aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

Agent: Repo tip belief-state divergence detection at finalization

Open
#513 0 comments 0 reactions 0 assignees View on GitHub
agent-runtime enhancement
Dominant language
TypeScript
Stars
143
Forks
46
Avg merge
3d 9h
Merged PRs (30d)
20

Description

> **Roadmap:** Agent swarm (foundation); Shared program state RFC
> **Priority:** P3

## Component

Agent (Python runtime)

## Describe the feature

At task finalization (and optionally on long-running checkpoint), compare the **base SHA recorded at plan/hydration time** to the current branch tip. Emit a `state_divergence` TaskEvent when the branch advanced unexpectedly (new commits, force-push, concurrent human edits).

Implements a lightweight version of SyncMind-style belief-state divergence (arXiv:2605.18747 §4.4, §5.1.1) without full multi-agent coordination.

## Use case

- **Operators** see warnings when verification ran against a different commit than planned.
- **HarnessState RFC** uses divergence events as the first consumer of `base_sha`.
- **Evaluation** categorizes "verified stale tree" failures separately from agent errors.

## Proposed solution

1. Record `base_sha` at clone/setup in task record (or HarnessState when RFC lands).

2. At finalization in `agent/src/post_hooks.py` or pipeline:
- `git rev-parse HEAD` vs stored `base_sha`
- If differ: emit `state_divergence` event with `{ base_sha, head_sha, commits_ahead }`

3. Blueprint policy:
- `divergence_policy: warn` (default) | `fail`

4. Surface in `bgagent status`, verification report, and replay bundle.

### Acceptance criteria

- [ ] `base_sha` captured at repo setup for coding workflows
- [ ] `state_divergence` event type documented in TaskEvents schema
- [ ] Configurable warn vs fail; default warn
- [ ] Unit tests with mocked git SHAs
- [ ] Documented in `ORCHESTRATOR.md` or observability docs

## Other information

- **Companion:** Shared program state RFC
- **Paper:** arXiv:2605.18747 SyncMind, transactional shared state §5.2.4
- **Not in scope:** Auto-rebase or merge conflict resolution

## Acknowledgements

- [ ] I may be able to implement this feature
- [ ] This might be a breaking change

Contributor guide

Open the contributing guide

Research direction

Start by tracing repository setup and finalization in agent/src/post_hooks.py, including how the task record or HarnessState stores base_sha and how TaskEvents are defined. Check the bgagent status and verification-report entry points, then use mocked git SHAs to verify warn and fail behavior; done means all listed acceptance criteria are covered and the behavior is documented in ORCHESTRATOR.md or observability docs.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, python
Domain
devtools, observability-sre
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.