Make Codex and Claude sessions continue across CLI upgrades #891

Story

As an XMD user working with Codex or Claude through ACPX, I want CLI upgrades to leave my conversations usable, so I can update my agent without waiting for XMD to certify the new release or starting a replacement conversation.

ACPX is the client XMD uses to communicate with coding agents through their ACP adapters. XMD confirms that each integration works and relies on that integration across releases. Version observations inform the user; they do not grant permission to use a session.

Common path

In xmd repl, submit:

<Prompt agent="codex" session="implementer">
Review the implementation.
</Prompt>

After upgrading Codex, submit another prompt with the same agent and session. XMD warns once for that session in the current invocation and attempts to continue the same provider conversation:

Codex has changed from 0.153.2 to 0.162.1 since this session was established. Continuing the existing conversation.

No confirmation, override flag, downgrade, or recertification is required. The same policy applies to Claude and to native launch and subsequent ACP continuation where the host supports those operations.

Current gap

The inspected main source records an executable version and SHA-256 digest in a session's construction route and rejects later use when the observed build differs. It also rejects version output outside a narrow format. Ordinary session and prompt paths reach these checks, so this is broader than native launch.

The specifications tie advertised capabilities to elaborate live proofs against particular CLI, adapter, and host combinations. That makes tested combinations look like an admission policy and creates an ongoing maintenance obligation whenever dependencies change.

There is already overlapping work: PR #764 replaces the same-build lock with audit evidence and independent protocol, CLI-shape, capability, and host admission. Its description still restricts the admitted real-provider host envelope to macOS arm64. Plan against its latest contract rather than assuming the inspected main implementation is the only design to change.

The REPL screenshot discussed during investigation was a separate prop-validation error: <Session agent="codex" /> is unsupported. Explicit agent and session props on <Prompt> work. This issue does not claim that screenshot reproduces a version refusal.

Accepted contract

1. Compatibility belongs to the integration. Confirm the Codex and Claude integrations work through the production ACPX route. Do not require XMD certification for every CLI version, executable digest, adapter release, or host combination merely because that combination has not been tested. Actual runtime support and required operation capabilities still apply.
2. Version changes warn and continue. An observed change produces one warning per logical session per invocation, before the affected live work. Further prompts in that invocation do not repeat it. The warning appears in the REPL's visible execution output and in ordinary CLI diagnostics without corrupting machine-readable output. It requires no answer and changes no permission policy.
3. Observation is diagnostic. A digest difference alone never blocks use or requires recertification. An unfamiliar version format or an unavailable version observation also does not block an otherwise usable integration; report that the version could not be determined once under the same warning scope. A missing or unlaunchable executable remains an ordinary availability failure.
4. Continuation keeps its identity. Attempt to open the exact retained provider conversation. A missing conversation, missing required identity assertion, or a different returned identity remains a failure. Never create a replacement, infer identity from a request echo, reconstruct history, or silently route to another provider.
5. Existing sessions remain usable. Read released routes and journals, including records with executable bindings and records without a historical build observation. The absence of historical version or digest evidence alone does not prevent continuation. Preserve established conversation identity and original durable records; do not rewrite old history to claim it was established by the current executable. Missing information required to locate or confirm the conversation remains a separate failure.
6. Verification follows changes to XMD's integration. Keep a small, repeatable integration regression covering initial use, conversation continuity, and native handoff where supported. Run live checks when changing the integration or investigating breakage, with existing explicit authorization for model spending. Record tested versions as evidence. Do not create a recurring per-release certification obligation or turn the recorded evidence into a runtime allowlist.

Architecture amendment and preserved boundaries

This issue explicitly replaces the requirement that the live executable match a session's original version and digest. It also replaces certification-derived admission restrictions whose only basis is that a particular release, probe profile, or host combination has not been proven. A successful required operation through the supported integration determines usability.

Preserve actual ACP protocol and capability requirements, provider-native identity checks, exclusive session ownership, construction-route identity, instruction and permission handling, and cancellation and teardown. Keep live paths and private provider output out of durable records and public diagnostics. Completed replay performs no executable observation, warning, provider call, or launch; incomplete replay attempts the same retained conversation under the revised compatibility policy.

This amendment does not resolve missing provider identity signals. It does not remove patched adapter metadata contracts for turn identity, acceptance, or native session identity. A dependency pin or vendored snapshot needed to supply those contracts is a different concern from certifying every installed agent release.

Acceptance and discriminating evidence

• A fresh Codex session works with a compatible release that was absent from recorded live-test evidence. An unfamiliar version string also permits a successful operation. Equivalent coverage applies to Claude.
• A session established under one version resumes under another, emits one warning, and retrieves information supplied only in the original conversation. Equal IDs with empty replacement history do not pass.
• A changed digest with the same reported version is accepted. Missing historical build evidence and unavailable version observation do not independently refuse continuation.
• Repeated prompts for one session in an invocation do not repeat the warning. A second affected session receives its own warning. The warning is visible in the REPL and ordinary command output without requesting input.
• A provider that cannot open the retained session, reports no required identity assertion, or reports another identity fails without a prompt reaching a substitute conversation. Permission, ownership, and cleanup failures retain their existing behavior.
• Native resume, ACP reattachment, and incomplete replay apply the same policy. Completed replay remains entirely offline and emits no new compatibility warning.
• The implementation, normative specifications, decision records, and integration documentation agree that tested versions are evidence rather than release-certification gates. Existing live documents remain usable as opt-in regressions without requiring the installed CLI to equal an old recorded test version.

Use deterministic production-provider and command/REPL tests to distinguish warning-and-continue behavior from merely replacing an error with a warning while still skipping the operation. Reuse existing live continuity evidence where applicable; a new upstream version alone does not demand another paid proof. The Planner selects and freezes the smallest sufficient evidence matrix before implementation.

Planning references and overlapping work

Investigation baseline: local main at e61d6ce072735b5d0cf683eeaca0f2eefddc2d59. Refresh the actual base and relevant stack heads before planning.

• packages/acp/src/provider.ts: observeBuild, bindProviderNamed, constructRoute, native preparation, and incomplete-launch reconciliation.
• packages/acp/src/native-launch.ts, packages/core/src/agent/launch.ts, and packages/runtime/deno-executable-observer.ts: executable observation, version parsing, build comparison, and advertised integrations.
• packages/cli/src/agent-stack.ts and packages/cli/src/repl-profile.ts: shared provider installation and REPL behavior.
• architecture.md, specs/acp-client-spec.md, and specs/native-agent-session-launch-spec.md: update the existing build and compatibility contracts in the implementation PR. Reconcile specs/decisions.md and the executable-language spec where the selected base contains overlapping amendments.
• Launch Codex sessions with <Session.Launch> #755 / PR ✨ Launch Codex sessions with <Session.Launch> (#755) #764: Codex launch and cross-release continuation. Inspected PR head: ba9047f8102a1cd8cafdf7a9f403d85c3be1d03c. Account for native-capability.ts, capability admissions, and DEC-017/DEC-018 on that stack. Reuse its cross-release behavior; remove remaining certification-derived restrictions within this issue's scope.
• Certify ACP agents against real backends through xmd run #743: shared live-backend certification proposal. This issue establishes the compatibility policy; coordinate the overlapping verification contract without building that certification framework as a prerequisite.
• Make Claude native-to-ACP continuation preserve the exact conversation #770 and Real Codex and Claude adapters assert no durable session identity, so #302 reattachment cannot hold #639: independent provider-identity defects. Preserve their identity guarantees; this issue does not bypass or depend on repairing those missing assertions.
• Return each embedded ACP adapter to a qualifying upstream release #636, Remove the vendored ACPX checkpoint-metadata patch after a released runtime carries response _meta #629, and Remove the vendored ACPX transient-environment patch after a released scoped seam passes continuity #566: removal of vendored adapter/runtime patches stays separate and is not a prerequisite.
• Add an interactive Sidekick to xmd repl #883 / PR ✨ Evaluate, preview and converse as a trusted host (#883, PR 1 of 2) #890: host-held conversations for the REPL Sidekick consume the same provider; apply the policy there if present in the implementation base without expanding into Sidekick delivery.

Existing focused entrypoints include:

deno task test packages/acp/tests/native-launch.test.ts packages/acp/tests/provider.test.ts packages/acp/tests/session-route.test.ts packages/core/tests/agent-session-launch.test.ts
deno task test packages/cli/tests/repl-agent-interface.test.ts packages/cli/tests/repl-agent-execution.test.ts packages/cli/tests/repl-agent-journey.test.ts

Confirm exact files on the selected base and add the focused REPL warning and continuation regressions the plan identifies. native-capability.test.ts and native-reconnect.test.ts belong in the selection if planning on the #764 implementation. Follow the repository feedback-commit procedure after the frozen focused evidence passes; ordinary delivery checks retain their own scope.

Out of scope

New agent providers, persistent agent-selection syntax in the REPL, changes to <Session> props, automatic dependency upgrades, removal of necessary adapter patches, weakened provider identity, and a new compatibility or certification framework.