Skip to content

Add the trusted Agent bundle lifecycle with Codex exact-prefix support #624

Description

@taras

Part of #599. Frozen by plan commit b42339b3d6df869d65e4b34a8ba89f60728f8a58 after independent Architect PASS.

Outcome

Add a provider-neutral trusted Agent bundle lifecycle available only to sealed-artifact export and artifact-backed fork orchestration. It captures a detached frontier bundle, restores into deterministic private provider staging, exact-prefix-forks at one journaled token, optionally accepts caller-allocated identity, enumerates complete-root identity claimants, and verifies bundle/source identity and the exact ordered token prefix.

Capture, restore, verification, and fork execute no Agent Prompt and append no provider turn. Live Prompt execution remains ACP-only. The lifecycle is absent from authored Markdown, the live ACP Prompt chain, and the existing retained-run fork. A retained-run checkpoint after an Agent Prompt remains agent-state-unavailable with zero lifecycle calls and no provider/run mutation.

The first qualified provider is Codex App Server:

  • Transport the source rollout closure as opaque confidential bytes.
  • Record length/hash and qualify bundle/App Server compatibility.
  • Recover ordered turns with thread/read.
  • Fork with no turn using thread/fork(lastTurnId).
  • Verify forkedFromId when available and always verify the exact token prefix.
  • Treat identity as provider-allocated and reconcile lost responses by pristine candidate cardinality: zero creates, one exact candidate adopts, multiple refuse.
  • Enumerate raw duplicate thread IDs across the complete destination CODEX_HOME; ACPX records and newest-file selection are insufficient.

Claude is not declared. The proven claude -p form executes a Prompt and cannot qualify.

Ownership

The namespaced provider-neutral lifecycle API, artifact-management host wiring for the sealed exporter and artifact-backed fork orchestrator, and provider-private Codex implementation under packages/acp. Export orchestration and the artifact-backed SQLite fork transaction remain separate issues.

Acceptance and evidence

  • C1: Only sealed-artifact export and artifact-backed fork receive the lifecycle. Authored Markdown, live ACP Prompt, and retained-run fork cannot resolve it.
  • C2: Codex captures one frontier-aligned bundle and exact ordered token list without changing source bytes or turns.
  • C3: Restoring in another private root and calling thread/fork(lastTurnId) produces exactly the selected prefix, no later token, and no added Prompt/turn.
  • C4: Unsupported compatibility, malformed bytes, hash/token/source/prefix mismatch, or missing evidence refuses without published provider state.
  • C5: Complete-root claimant enumeration implements zero, one matching, one different, and multiple-even-equal refusal rules, including raw duplicate Codex thread IDs missed by ACPX.
  • C6: Provider-allocated retry reconciliation is 0 → create, 1 → adopt, ≥2 → refuse; no blind duplicate retry.
  • C7: The capability set includes qualified Codex and no Claude; neither ACP session/fork nor claude -p is invoked.
  • C8: A retained-run checkpoint after an Agent Prompt remains agent-state-unavailable; a lifecycle spy records zero capture/restore/fork calls and provider/run/journal inventories remain unchanged.

Focused feedback

Run the provider-neutral lifecycle test, Codex App Server lifecycle integration, packages/acp/tests/provider.test.ts, raw provider-state conflict regression, and retained-run cases in:

  • packages/workflow/tests/workflow-fork.test.ts
  • packages/cli/tests/workflow-fork.test.ts

Dependencies

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions