Skip to content

Make Codex and Claude sessions continue across CLI upgrades #891

Closed

Description

@taras

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.

  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

  • 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.

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.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.

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

  1. added
    enhancementNew feature or request
    UXUser-facing usability and interaction improvements
    on Oct 11, 2026
  2. taras commented on Nov 18, 2026

    @taras
    OwnerAuthor

    Native Fable design assessment completed

    The owning chat, #891 — Unified session resume design, ran and joined the documented standalone phase.md Problem Solver design route against clean source and workflow revision efb666c04304bf9080d24034863ed2a57f1e8588. Native provider: Claude; selected model: fable; effort: high. The workflow returned validated status: "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:

    • Generalize reopeningOf / ensureFromPrepared so 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.
    • Remove live build equality as an admission condition across ordinary Session/Prompt, native preparation, attachment and incomplete-launch reconciliation. Preserve immutable route/journal history and agreement between their original records; accept missing historical build observations without inventing them.
    • Observe and execute the file selected by the current environment. Fable found that host selection honors 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.
    • Keep warning deduplication for one logical session across the invocation in the host. Fable proposes a small provider-originated Agent operation composed through existing middleware, because prompt events, error-only diagnostics, usage and durable launch records do not cover pre-work Session/launch/replay warnings. This proposed API still requires Architect review of existing operation/context seams; no callback dependency is accepted by this assessment.

    Contract questions the Architect must resolve before implementation:

    1. Native UI processes expose exit status rather than a positive identity assertion. Fable identifies exact-ID native resume versus an ACP confirmation step as alternatives. Exit status alone has not been accepted as satisfying this issue's provider-confirmed-identity requirement.
    2. Establish when confirmation occurs and bound observation/load cost without using build equality to weaken it. The accepted one-default policy and refusal of missing required confirmation are settled, not new product questions.
    3. Cover ordinary Claude observation/warnings and custom executable commands without overriding their selected environment or suppressing required warnings. Separate executable availability failures from diagnostic version failures.
    4. The proposed same-ID/empty-history test must demonstrate original-context continuity. An identity-only client cannot independently detect a provider falsely asserting an old ID for replacement history; do not claim that mutation is rejected before prompting without a supported witness.

    The focused evidence matrix should cover both providers and ordinary workflow Session/Phase.Session/Prompt plus 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 to packages/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.

  3. taras commented on Nov 18, 2026

    @taras
    OwnerAuthor

    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.

  4. taras commented on Nov 18, 2026

    @taras
    OwnerAuthor

    The standard adversarial workflow has now joined both original discovery roles at b2bc6f1c6369bb93d92dd95ff71f0bc30a711fcf and returned a confirmed needs_decision hold 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.stderr serves 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:

    compatibilityWarnings?: Set<string>;

    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.

  5. taras commented on Nov 18, 2026

    @taras
    OwnerAuthor

    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.

  6. taras commented on Nov 18, 2026

    @taras
    OwnerAuthor

    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_failure checkpoint with dispatchable=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.

  7. taras commented on Nov 18, 2026

    @taras
    OwnerAuthor

    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 5095bb36b72fd9dcbba998b7edf4575bd72e7f52 without 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.

  8. taras commented on Nov 18, 2026

    @taras
    OwnerAuthor

    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.

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

    UXUser-facing usability and interaction improvementsenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions