aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
Agent: Repo tip belief-state divergence detection at finalization
- 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
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