RFC: Shared program state contract for multi-agent workflows

> **Roadmap:** Agent swarm (deferred); Pure decision function orchestrator refactor
> **Priority:** P3

## Primary area

API or orchestration

## Related issue or feature request

Roadmap: Agent swarm; Unified task replay API (draft)

## Summary

Define a **HarnessState** contract: task-scoped record of repo snapshot, assumed invariants, verification obligations, and declared read/write sets. Single-agent coding workflows populate it as a foundation; multi-agent swarm (deferred) requires transactional shared program state (arXiv:2605.18747 §4.3, §5.2.4).

RFC delivers schema + design doc + minimal population at hydration/finalization — no multi-agent runtime.

## Use case and motivation

- **Agent swarm** roadmap warns of coordination without shared substrate — this RFC is the prerequisite.
- **Stale snapshot bugs:** planner assumptions diverge from branch tip during long tasks (SyncMind belief divergence).
- **Replay API** consumers need structured state, not only event streams.

## Proposal

### HarnessState schema (illustrative)

```typescript
interface HarnessState {
task_id: string;
base_sha: string; // repo HEAD at plan time
branch: string;
workflow_ref: string;
invariants: string[]; // e.g. "do not modify cdk/cdk.json"
verification_obligations: string[]; // e.g. "mise //cdk:test must pass"
read_set: string[]; // glob paths agent may read
write_set: string[]; // glob paths agent may edit
captured_at: string;
}
```

### Population points

- **Plan phase:** Orchestrator sets `base_sha`, read/write sets from workflow + blueprint pack
- **Verify phase:** Finalization compares `base_sha` to current tip (see belief-state divergence issue)

### Storage

- DynamoDB field on task record or separate item keyed by `task_id`
- Included in unified replay bundle

### Before / after

**Before:** Repo state implied from git clone + chat history.

**After:** Explicit, API-visible harness state for audit and future multi-agent merge.

## Out of scope

- Multi-agent DAG, planner-worker topology, merge orchestrator
- Distributed locking or CRDT merge semantics (follow-up)
- Automatic conflict resolution

## Potential challenges

- **Write set enforcement:** Cedar/tool policy must align with declared write_set
- **Size limits:** Large read_set globs — store patterns not expanded file lists
- **Repo-less workflows:** HarnessState optional when `requires_repo: false`

## Dependencies and integrations

- Orchestrator hydration and finalization
- Unified task replay API
- Belief-state divergence detection (companion feature issue)
- Agent swarm (future consumer)

## Alternative solutions

- **Git-only truth:** Rely on branch state — no explicit contract (status quo; insufficient for MAS).
- **Blackboard in agent session:** Not durable across workers without S3 session store.

---
**Note:** Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.

* RFC PR:
* Approved by:
* Reviewed by:

No files or tests are named. Start by reading the HarnessState proposal and tracing orchestrator hydration and finalization, then inspect how task records and unified replay bundles are represented. Done means an agreed schema, design documentation, and minimal population at hydration and finalization without adding multi-agent runtime behavior.

Written by the indexing model from the issue text.