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:

Non vengono nominati file né test. Inizia leggendo la proposta HarnessState e seguendo l’idratazione e la finalizzazione dell’orchestratore, quindi esamina come vengono rappresentati i record delle attività e i bundle di replay unificati. Il lavoro è considerato completato quando sono presenti uno schema concordato, la documentazione di progettazione e un popolamento minimo durante l’idratazione e la finalizzazione, senza aggiungere comportamenti runtime multi-agente.

Scritto dal modello di indicizzazione a partire dal testo della issue.