Repository navigation
Description
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
PR #1246 delivered verified resume after Codex CLI upgrades for held Sidekick conversations. It did not complete this issue's ordinary Session, Prompt, native resume, attachment, or incomplete replay contract.
The recurrence is an ordinary workflow role Session established on codex-cli 0.167.1. A desktop update selected 0.169.1, and XMD refused before the next prompt: the diagnostic said the conversation was created by the old version, would use the new version, and could not be confirmed. This is synthetic repository workflow evidence; private REPL histories are outside this issue's evidence scope.
At efb666c04304bf9080d24034863ed2a57f1e8588, packages/acp/src/provider.ts selects verifyChangedBuild only for Codex details with an established prepared.continuation. Other routes reach bindProviderNamed's version/digest refusal before live load. The workflow's components/Phase/Role.md uses ordinary <Session><Phase.Session><Prompt> and misses that narrower allowance.
The native-launch and attachment specifications still impose exact-build binding, while the ACP specification permits verified upgrade continuation for held Codex conversations. Design must reconcile the shared contract before implementation.
Accepted contract
The user explicitly confirmed one default for every session: resolve the executable selected by the current environment, resume the retained conversation, and require the provider to confirm the same conversation identity. Ordinary Session resumption and held continuation use this same policy. Version and digest are diagnostic metadata; their change alone never refuses resume. Refuse genuine resume failure, missing required confirmation, or a different identity. There is no opt-in flag or separate held-session policy. Pinning an old executable on PATH is only a temporary workaround.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- An ordinary workflow
<Session><Phase.Session><Prompt>resumes the same conversation with the upgraded executable selected by the current environment. Held conversation continuation has the same outcome and refusal rules. - A changed binary at the same path and an unchanged binary reached through a different path each resume the same retained conversation. Custom commands and environment selection follow the same policy; no old-binary PATH pinning is required.
- 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
Current design baseline: main at efb666c04304bf9080d24034863ed2a57f1e8588. Refresh the actual remote base and relevant stack heads before assigning the design. PR #1246 merged as 596d587cdeeca3813ed319fa884400d56ed3cc1a and is a delivered partial slice of this open issue.
packages/acp/src/provider.ts:observeBuild,bindProviderNamed,constructRoute, native preparation, and incomplete-launch reconciliation.packages/acp/src/native-launch.ts,packages/agent/src/launch.ts, andpackages/runtime/deno-executable-observer.ts: executable observation, version parsing, build comparison, and advertised integrations.packages/cli/src/agent-stack.tsandpackages/cli/src/repl-profile.ts: shared provider installation and REPL behavior.architecture.md,specs/acp-client-spec.md, andspecs/native-agent-session-launch-spec.md: update the existing build and compatibility contracts in the implementation PR. Reconcilespecs/decisions.mdand 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 fornative-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 local ACP agents with a reusable XMD example #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/agent/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.tsConfirm 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.
Design and delivery
Run a native Fable problem-solver design assessment through the latest repository workflow before implementation. The assessment compares existing ownership and API seams across ordinary Session, Prompt, held continuation, native resume, ACP attachment and incomplete replay, across supported providers and custom command/environment selection. It must explain provider-confirmed identity where capabilities differ without substituting a version gate for confirmation.
Preserve exact conversation identity, exclusive ownership, permissions, instruction handling, original history, cancellation and replay. A refused conversation is never silently replaced by a fresh one. Completed replay remains offline. The design names coherent amendments to authoritative architecture, specifications and regressions, with the Architect retaining ownership of the implementation contract.
Use public source and synthetic task evidence only. Keep private REPL history, private provider output and host paths out of published artifacts. Use finite workflow budgets and distinct original role conversations. Do not extend a special-case conditional or introduce callback/observer APIs without demonstrating why existing continuation-preserving operation/context seams cannot meet the contract.
#1399 currently blocks unrelated merges while main is red. Design can proceed independently; this issue grants no merge exception.
Assigned design pass
The owning lane, #891 — Unified session resume design, completed and joined the native Fable Problem Solver assessment through the documented standalone workflow at source/workflow revision efb666c04304bf9080d24034863ed2a57f1e8588 (Claude provider, model fable, high effort). Assignment, journal, provider-confirmed role identity, raw reply and validated design result are retained by that lane. The assessment and Architect handoff recommend unifying verified continuation at existing provider seams and identify unresolved native-confirmation, warning and executable-selection details. This is design advice, not an implementation-ready PASS; the Architect owns the next implementation contract. No production implementation or merge was performed. Restore Green Main's live CI and journal repairs remain separate.
Activity
taras commentedon Nov 18, 2026
Native Fable design assessment completed
The owning chat, #891 — Unified session resume design, ran and joined the documented standalone
phase.mdProblem Solver design route against clean source and workflow revisionefb666c04304bf9080d24034863ed2a57f1e8588. Native provider: Claude; selected model:fable; effort: high. The workflow returned validatedstatus: "design", with a confirmed provider-native role identity and retained assignment, journal, raw reply and result receipts. No production implementation or merge was performed.Fable recommends unifying continuation inside the existing ACP provider owners, rather than widening the held-Codex exception or importing #764's certification layer:
reopeningOf/ensureFromPreparedso established ordinary and held sessions use the exact retained loading target plus the retained provider-native identity through ACPX's existing verified-reopen path. Missing or different live assertions and real load refusal fail before a substitute receives a prompt.CODEX_PATH/CLAUDE_CODE_EXECUTABLE, while the current build observer searches the launcher on PATH and can override that selection. Its controlled two-launcher probe distinguished those files using production selection/observation functions; source remained clean.Contract questions the Architect must resolve before implementation:
The focused evidence matrix should cover both providers and ordinary workflow
Session/Phase.Session/Promptplus held continuation; original-only context recovery; missing/mismatched assertions and real refusal; same-path replacement, moved identical binary, digest-only changes, custom environment selection, unavailable/unfamiliar versions and legacy records; native/ACP/incomplete replay; and completed replay with zero observation, warning or provider work. Use controlled ACP/subprocess boundary doubles through production resume paths. Correct the stale core test reference topackages/agent/tests/agent-session-launch.test.ts. Existing live continuity documents remain evidence; no new paid certification probes were run.Amend the existing architecture, ACP/native-launch specifications, decision record 004 and a new decision record, plus REPL/Agent operation documentation where required. #764 is closed and unmerged: reuse its continuity behavior, not its admission layer or conflicting decision numbering. Preserve the identity/acceptance patches; #770/#639, patch retirement, #1393 and main-health work retain separate ownership.
This is completed design advice, not an implementation-ready PASS. The next role is Architect: settle the remaining implementation contract and then hand it to planning. The main-green merge gate remains unchanged.
taras commentedon Nov 18, 2026
Implementation is now authorized in the owning chat and running through the standard adversarial workflow at pinned source/runtime/workflow revision
b2bc6f1c6369bb93d92dd95ff71f0bc30a711fcf.The original Codex Planner completed and joined with
needs_discovery, a bounded proposal and focused evidence matrix. Its confirmed native role identity is retained locally. The same workflow has dispatched the original Architect to settle native confirmation, existing warning/operation/context transport, executable-selection ownership and legacy reconciliation. No production source changes or implementation commit exist yet. The starting boundary remains no new ACPX, Claude adapter/SDK, producer or dependency changes; a demonstrated missing capability must be surfaced before expansion.Recovery coordination: REPL Bench reports a synthetic #1397 ordinary-role continuation refused on Codex build drift after a human decision was recorded, leaving a nondispatchable execution-failure checkpoint. #891 owns current-executable/same-provider-conversation policy. Workflow Improvements' supported #1396 recovery owns how an already-held call becomes dispatchable again. A provider fix alone does not authorize rewriting the checkpoint, resetting its ticket or replacing its original role conversation. The final recovery/delivery pin is not available yet; #1393's model-selection repair remains separate.
Existing Fable design advice and the accepted one-default contract are unchanged.
taras commentedon Nov 18, 2026
The standard adversarial workflow has now joined both original discovery roles at
b2bc6f1c6369bb93d92dd95ff71f0bc30a711fcfand returned a confirmedneeds_decisionhold before implementation.The Architect selected positive native confirmation using the carried load/resume metadata, current selection before diagnostic observation, and immutable legacy reconciliation. It found no new ACPX, Claude adapter/SDK, Agent notice operation or exported observer-result change necessary. Established native resume uses confirmation before handoff; fresh client-native creation confirms after the native child joins and before successful completion. Exact first attachment without an ACP record is tested separately from strict existing-record reopening.
Existing contextual
Stdio.stderrserves warning transport. The production REPL transport check passed 4 tests/9 steps, and a focused scope experiment passed with joined tasks. Held work needs capture in its owning conversation task. These are design evidence, not proof of an implemented warning feature.One concrete API proposal awaits Product Owner review under the repository Architect boundary-interview rule:
The CLI owns one transient set across all provider installations in an invocation; providers claim private logical-placement keys before writing warnings. Omission gives an embedding host per-installation deduplication. The state is never serialized and grants no execution permission. This adds no callback or observer event.
The exact held continuation and original native role identities are retained. The supported next action is
resolve-decision.md, followed by ordinary continuation of the same Architect and Planner. No production code, implementation commit, adapter/dependency edits or merge occurred. #1397's nondispatchable failure still needs its separate supported #1396 recovery; this clean decision hold does not replace that mechanism.taras commentedon Nov 18, 2026
The Product Owner has approved
AcpxProviderDependencies.compatibilityWarnings?: Set<string>, including per-installation deduplication when an embedding host omits the shared set. The CLI will always share one transient set across the invocation. The supported decision-resolution operation accepted and retained the decision and provenance, and published a confirmed continuation for the same original Architect, followed by the retained Planner. The new call is being joined; no new role conversation, ACPX/adapter change, production implementation commit or merge is claimed.taras commentedon Nov 18, 2026
The approved boundary was closed by the same Architect, and the same Planner completed the decision-complete implementation plan and frozen E1–E11 evidence. Both joined with their original confirmed native identities.
The original Claude Opus Implementor then began work but hit the provider's usage limit after partial edits. The invocation has joined as a failure with no canonical implementation result, no feedback commit, and no completed focused-evidence claim. Four files currently contain partial changes: the ACP provider, its shared test helper, and runtime diagnostic helper/export. ACPX vendor/runtime, Claude adapter/SDK, producer inputs and dependency/lockfiles are unchanged.
The exact first failure, original native identity, source base, full patch and file fingerprints are preserved locally. The pinned workflow returned a confirmed
execution_failurecheckpoint withdispatchable=false. Ordinary continuation returns that hold; decision resolution does not cover it. No call was retried, no role/provider was replaced, and no ticket/history was reset or edited manually.Next: restore provider capacity and use supported recovery of the retained failed implementation call, preserving partial source and the original role identity. This is the same recovery boundary relevant to Workflow Improvements/#1396 and the separate #1397 held-call case. It does not authorize a competing recovery repair, an ACPX/adapter change, or merge. The implementation remains incomplete and unreviewed.
taras commentedon Nov 18, 2026
Resume check after the user indicated the Opus quota should have reset: the preserved partial patch and original native role identity still match their saved fingerprints. Current main was inspected at
5095bb36b72fd9dcbba998b7edf4575bd72e7f52without changing the assigned source or pinned workflow.The blocker is now the retained workflow state independently of quota: call 0004 failed mid-implementation with no canonical result, and the checkpoint remains
execution_failure/dispatchable=false. Current main still has no supported ordinary Ticket failed-call recovery entry; continuation returns the hold, and decision resolution excludes it.The Workflow Improvements proposal for reconciling a proven-completed #1400 reply is a different case. #891 needs supported continuation of the same failed Opus conversation with its partial source, keeping the original failure and budgets. It must not fabricate a completed result, substitute a new role, reset the ticket, or adopt a completed-reply extraction exception as proof of this failed call.
No provider call was sent in this check, so restored quota was not independently tested. No source, ticket, native identity, allocation or history changed. Implementation remains incomplete.
taras commentedon Nov 18, 2026
After the user explicitly directed proceeding, the documented same-session phase continuation reached the retained Claude conversation but failed before its implementation prompt on the separate #1393 resumed-model picker defect. #1393 remains an unmerged draft; no part of that adapter/runtime repair was copied into #891.
Implementation is now progressing through a separately recorded exact-session native Claude CLI continuation with the original Opus conversation, approved plan and E1–E11. The CLI result must report the original native identity and pass the existing workflow response contract. This is an explicit transport deviation, not a claim that the old nondispatchable managed Ticket recovered; its failure/history remain unchanged.
The continuation has made further source/test changes and retained the first focused failures. Latest native-launch and held-conversation selections pass, while CLI/workflow consumers, the complete frozen matrix, typing/docs and independent review remain outstanding. No feedback commit or delivery readiness is claimed. ACPX vendor, Claude adapter/SDK, producer and dependency/lockfile changes remain outside this implementation.
Continue sessions on the current agent executable (#891)
Stop a native replay whose reconfiguration release failed (#891)
Continue sessions quietly on the current executable (#891)
Reconcile proofs and specs with quiet unbound continuation (#891)
Continue sessions across agent CLI upgrades (#1413)