P0: preserve Codex MCP tool availability across deployment restart and OAuth rebind

[James3014]

Status

G0_EVIDENCE_BOUND / READY_FOR_BOUNDED_DIAGNOSIS

Owner-authorized public Issue. This Issue does not authorize merge, deployment, service restart, release, or production claims. AUTO_CHAIN=false.

Problem

An existing Codex conversation can lose the Dev MCP tool surface during or after a normal DevSpace deployment restart even though the replacement backend and public route are healthy. The failure occurs before agent_start, so it must not be classified as a provider/model failure.

Observed behavior:

• a normal server shutdown closes hundreds of active MCP sessions;
• the service launcher adds a fixed startup delay, creating an avoidable restart blackout;
• after replacement, codex-mcp-client can complete OAuth discovery but receive HTTP 400 from POST /token;
• no corresponding agent_start reaches the server;
• active session count grows quickly after restart, suggesting significant session churn;
• frequent deployment of a fast-moving main repeatedly interrupts active MCP clients.

This is a regression or remaining gap after #15, #31, #99, and #159. Those issues respectively cover general reliability, multi-session cutover, token request parsing, and missing snapshot rebind, but do not close this observed end-to-end failure chain.

Required invariant

normal deploy/restart
  -> bounded drain or explicit reconnect state
  -> replacement becomes ready without a fixed blackout
  -> same authenticated Codex client can refresh/rebind
  -> tools/list becomes callable again in the existing conversation
  -> a subsequent tool call reaches the handler exactly once

Server restart, OAuth recovery, MCP session recovery, tool-catalog exposure, and provider dispatch are separate evidence layers.

Gate sequence

G1 — Deterministic reproducer and classification

• Add a test/harness for server-generation restart followed by the Codex-client token/rebind request shape.
• Emit a safe structured OAuth failure class without logging credentials.
• Determine whether repeated initialize/list/call cycles reuse, close, or leak sessions.

G2 — Bounded restart behavior

• Replace unconditional startup delay with bounded readiness/backoff behavior.
• Deployment must drain, defer, or emit an explicit durable reconnect/rebind outcome instead of silently dropping active sessions.
• A failed build must not schedule or perform a restart.

G3 — OAuth and MCP rebind recovery

• The same authorized Codex client can recover after server replacement without creating a new conversation.
• Supported JSON and form token requests remain compatible.
• Stale, cross-client, replayed, or malformed credentials continue to fail closed.

G4 — Session lifecycle bound

• Repeated client operations do not create unbounded active sessions.
• Idle or abandoned sessions have a tested TTL or explicit close path.
• Health telemetry distinguishes normal concurrency from churn.

G5 — Host-level acceptance

• Run one controlled authenticated restart/rebind trial.
• Verify fresh tools/list and at least 10 consecutive safe calls after recovery.
• Verify one bounded agent_start obtains a durable dispatch receipt before making a provider-success claim.

Non-goals

• Changing Muse/OpenCode model behavior.
• Repairing PR feat(delivery): G4 controller-visible PR delivery lifecycle projection (#115) #161 projection semantics.
• Weakening OAuth client/resource binding.
• Automatically merging, deploying, restarting production, or claiming unattended reliability from source tests alone.

Claim ceiling

REPRODUCED_HOST_RESTART_AND_OAUTH_REBIND_FAILURE / SOURCE_REPAIR_NOT_YET_ACCEPTED

[James3014]

G1 direct-delegated implementation contract

Status: READY_FOR_DIRECT_DELEGATED_IMPLEMENTATION

Identity:

• repository: James3014/devspace
• base/head at dispatch: 735c07d3a8853c58cb643f7f449da4eb48178035
• branch: codex/issue-163-mcp-restart-rebind
• isolated worktree: controller-bound local worktree
• worker: gpt-5.6-luna, reasoning effort xhigh
• authority mode: Owner-authorized DIRECT_DELEGATED
• AUTO_CHAIN=false

Objective:

Implement only G1: a deterministic restart/token-replay reproducer plus redaction-safe structured OAuth token failure classification. Preserve current OAuth acceptance and denial semantics.

Allowed writes:

• src/server.ts
• src/server.test.ts
• src/oauth-provider.ts
• src/oauth-store.test.ts

Required behavior:

1. Exercise the request shape that can produce post-restart POST /token -> 400, including durable refresh-token restart behavior and stale/replayed token denial.
2. Emit a bounded machine-readable failure class sufficient to distinguish invalid refresh token, invalid authorization code, invalid resource/redirect, and request-shape/validation failures when observable at the server boundary.
3. Never log or return token/code values, authorization headers, client secrets, owner password, redirect query contents, or credential-derived hashes.
4. Keep JSON and form token requests compatible.
5. Do not weaken one-time refresh rotation, PKCE, resource/client binding, expiry, replay denial, or any other authentication/authorization behavior.

Required verification:

• focused OAuth/restart tests;
• npx tsx src/server.test.ts;
• npm run typecheck;
• git diff --check;
• physical scope/deletion/status readback.

Forbidden:

• deployment, service/tunnel restart, production mutation;
• edits outside the four allowed files;
• PR creation, push, merge, release, or Issue closure;
• PR feat(delivery): G4 controller-visible PR delivery lifecycle projection (#115) #161 changes;
• session TTL/capacity changes;
• authentication semantic changes.

Claim ceiling:

G1_SOURCE_CANDIDATE_ONLY / AUTH_SEMANTICS_UNCHANGED / HOST_RECONNECT_NOT_YET_PROVEN

[James3014]

G1 source Candidate — independently verified

Status: G1_SOURCE_CANDIDATE_VERIFIED

Identity:

• base and current remote main: 735c07d3a8853c58cb643f7f449da4eb48178035
• local branch: codex/issue-163-mcp-restart-rebind
• patch SHA-256: c637bfcd6737005c38239aa7136502872d2a161ead0e14e4fdab75d119620fa0
• worker runtime: gpt-5.6-luna, reasoning effort xhigh
• controller independently inspected the physical diff and reran verification

Changed paths:

• src/oauth-provider.ts
• src/server.ts
• src/server.test.ts

Behavior:

• adds bounded OAuth token failure classes for invalid refresh token, invalid authorization code, invalid resource, invalid redirect, and request-shape validation;
• keeps JSON and form token requests compatible;
• preserves durable successor refresh-token redemption across server replacement;
• preserves stale/replayed refresh-token denial before and after restart;
• normalizes token error descriptions and omits credentials, tokens, authorization codes, owner password, credential hashes, origin/referer values, and redirect query contents from the new failure log/response path;
• adds safe handling for malformed JSON token bodies.

TDD evidence:

• RED: the new Issue P0: preserve Codex MCP tool availability across deployment restart and OAuth rebind #163 test executed and failed because failure_class was absent.
• GREEN: the same focused test passed after implementation.

Independent controller verification:

• focused Issue P0: preserve Codex MCP tool availability across deployment restart and OAuth rebind #163 test: PASS, 1/1;
• OAuth store test: PASS;
• OAuth JSON/token compatibility test: PASS;
• full src/server.test.ts: PASS, 51/51;
• npm run typecheck: PASS;
• npm run build: PASS (existing Vite chunk-size warning only);
• git diff --check: PASS;
• scope/deletion audit: PASS, three allowed files changed, zero deletions.

Boundary:

• OAuth acceptance/denial, one-time refresh rotation, PKCE, expiry, and client/resource binding were not weakened.
• No commit, push, PR, merge, deployment, tunnel/service restart, production mutation, or Issue closure occurred.
• G2-G5 and real Codex-host reconnect remain open.
• Any future change to refresh-token replay/rotation semantics crosses the authentication boundary and requires the applicable governed authority.

Claim ceiling:

G1_SOURCE_CANDIDATE_ONLY / AUTH_ACCEPTANCE_SEMANTICS_UNCHANGED / HOST_RECONNECT_NOT_YET_PROVEN

[James3014]

Handoff update: G1-G4 source work is merged through PRs #166, #167, and #168; both follow-up PRs passed all 12 checks and independent review. No runtime restart or live acceptance claim is made. Remaining gate: separately authorize and execute the bounded runtime activation, then verify same-generation catalog continuity, ten safe existing-conversation calls, one read-only chat_swarm_runtime_status call, and one bounded agent_start receipt with reconcile-before-retry semantics. Claim ceiling: SOURCE_MERGED_RELEASE_STAGED_RUNTIME_ACCEPTANCE_PENDING.