create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/lib/session-create/codex-native-provider-gate.js

@@ -0,0 +1,218 @@
+'use strict';
+
+// WP-1 — docs/codex-routed-fork-cold-restore-guard-2026-10-22.html §5 D-1..D-4, §6.
+//
+// The incident this closes: a Codex LEAD is launched natively with startup args `["resume", T]` and
+// NO `session_lead_route` row. Codex 0.163's `thread/resume` injects the thread's own stored
+// provider (`$CODEX_HOME/state_5.sqlite` -> threads.model_provider, e.g. `ctm-lead`) into its config
+// load, which then fails "Model provider `ctm-lead` not found" -> exit 1 -> the 3-restart budget
+// burns 50 s and the session ends blocked with a message that says nothing about the cause.
+//
+// D-1: the provider a spawned Codex process loads is CTM's decision (the route row), never the
+// string in the thread. D-2: that string is read ONLY to decide whether a NATIVE launch can
+// succeed. So before a native spawn this gate asks: is the thread's stored provider one a native
+// `codex` config load resolves (its built-ins ∪ the user `[model_providers]` table)? If not, the
+// launch is either repaired from CTM's own transition journal (D-3, the same row the commit would
+// have written) or refused deterministically before any PTY exists (D-4) — never spawned to die.
+//
+// Nothing here is flag-gated, and nothing here spawns a process: reading the state row is a single
+// readonly SQLite lookup and the rollout fallback only reads the file's first line.
+
+const path = require('node:path');
+const { getCodexStateThreadById, readCodexRolloutMetadata } = require('../session-history');
+const codexConfigGuard = require('../codex-config-guard');
+
+// codex-rs/core/src/config/mod.rs built_in_model_providers(); `openai` is the default when unset.
+const NATIVE_BUILTIN_PROVIDERS = Object.freeze(['openai', 'ollama', 'lmstudio', 'amazon-bedrock']);
+
+// The route/model columns `session_lead_route` accepts (lib/storage/session-lead-route-store.js).
+const MAX_ROUTE_FIELD_LENGTH = 200;
+
+/**
+ * Read the provider a native `codex resume <threadId>` would load for this thread.
+ *
+ * Order is the authority order Codex itself uses (D-2 decision table): the state DB row wins — it
+ * is what `thread/resume` reads — then the rollout's own `session_meta.model_provider`, then the
+ * built-in default. `codexHome` is the CODEX_HOME directory the launch uses; the state DB lookup
+ * takes the HOME it derives `<HOME>/.codex` from, so `homeDir` may be passed explicitly and is
+ * otherwise taken to be `codexHome`'s parent.
+ *
+ * @returns {{ provider: string, source: 'state_db'|'rollout'|'default', rolloutPath: string|null }}
+ */
+function readCodexThreadProvider({ threadId, codexHome = null, homeDir, rolloutPath = null,
+  getStateThread = getCodexStateThreadById, readRolloutMeta = readCodexRolloutMetadata } = {}) {
+  const id = String(threadId || '').trim();
+  const fallbackPath = rolloutPath ? String(rolloutPath) : null;
+  if (!id) return { provider: 'openai', source: 'default', rolloutPath: fallbackPath };
+  const resolvedHome = homeDir !== undefined && homeDir !== null
+    ? homeDir
+    : (codexHome ? path.dirname(String(codexHome)) : undefined);
+  let row = null;
+  try {
+    row = getStateThread(id, resolvedHome) || null;
+  } catch {
+    row = null; /* expected: a corrupt/unreadable state DB degrades to the rollout fallback (D-2) */
+  }
+  const stateProvider = String(row?.model_provider || '').trim();
+  const stateRolloutPath = String(row?.rollout_path || '').trim();
+  if (stateProvider) {
+    return { provider: stateProvider, source: 'state_db', rolloutPath: stateRolloutPath || fallbackPath };
+  }
+  const file = stateRolloutPath || fallbackPath;
+  if (file) {
+    let meta = null;
+    try {
+      meta = readRolloutMeta(file) || null;
+    } catch {
+      meta = null; /* expected: a missing/malformed rollout is not a provider source (D-2) */
+    }
+    const rolloutProvider = String(meta?.model_provider || '').trim();
+    if (rolloutProvider) return { provider: rolloutProvider, source: 'rollout', rolloutPath: file };
+  }
+  return { provider: 'openai', source: 'default', rolloutPath: file || null };
+}
+
+/**
+ * Decide whether a NATIVE spawn can serve this thread (D-2).
+ * native === true iff provider ∈ NATIVE_BUILTIN_PROVIDERS ∪ keys(config.toml[model_providers]).
+ *
+ * @returns {{ native: boolean, provider: string, source: string, configProviders: string[] }}
+ */
+function classifyCodexThreadProvider({ provider, source = '', codexHome = null,
+  readConfigToml = codexConfigGuard.readModelProviderKeys } = {}) {
+  const id = String(provider || '').trim();
+  let configProviders = [];
+  try {
+    const listed = readConfigToml(codexHome);
+    if (Array.isArray(listed)) configProviders = listed.map((key) => String(key));
+  } catch {
+    configProviders = []; /* expected: an unreadable config.toml declares no user providers (S-5) */
+  }
+  const native = !!id && (NATIVE_BUILTIN_PROVIDERS.includes(id) || configProviders.includes(id));
+  return { native, provider: id, source, configProviders };
+}
+
+/**
+ * D-3. Find the newest `coding_model_transitions` row for `ctmSessionId` whose parsed target recipe
+ * names this thread on the Codex harness with a route, and write `session_lead_route` from it.
+ *
+ * The journal is CTM's own record of the fork it launched, so this never guesses: no matching row
+ * means no repair (`{ ok: false, reason: 'no_journal_route' }`) and D-4 refuses the launch. An
+ * EXISTING route row wins byte-for-byte: the read below short-circuits, and the store's write is
+ * INSERT … ON CONFLICT DO NOTHING through the DB-owner mutation lane (awaited), so two concurrent
+ * cold restores converge on one row (meta-test M-1).
+ *
+ * @returns {{ ok: true, route: { route_id: string, model: string, context_window: null, transition_id: string }, written: boolean }
+ *        | { ok: false, reason: 'no_journal_route' }}
+ */
+async function reconcileLeadRouteFromJournal({ ctmSessionId, threadId, dbModule, recordSessionDiagnostic } = {}) {
+  const id = String(ctmSessionId || '').trim();
+  const thread = String(threadId || '').trim();
+  if (!id || !thread) return { ok: false, reason: 'no_journal_route' };
+  let rows = [];
+  try {
+    rows = typeof dbModule?.getCodingModelTransitionsForThread === 'function'
+      ? (dbModule.getCodingModelTransitionsForThread(id, thread) || [])
+      : [];
+  } catch {
+    rows = []; /* expected: an unreadable journal is not a route source — refuse, never guess (D-3) */
+  }
+  const row = rows.find((candidate) => {
+    const recipe = candidate?.target_recipe || {};
+    return String(recipe.providerThreadId || '') === thread
+      && String(recipe.harness || '') === 'codex-cli'
+      && String(recipe.routeId || '').trim().length > 0;
+  }) || null;
+  if (!row) return { ok: false, reason: 'no_journal_route' };
+  const routeId = String(row.target_recipe.routeId || '').trim();
+  const model = String(row.target_recipe.wireModelId || '').trim();
+  const transitionId = String(row.transition_id || '').trim();
+  if (!routeId || !model || !transitionId
+      || routeId.length > MAX_ROUTE_FIELD_LENGTH || model.length > MAX_ROUTE_FIELD_LENGTH) {
+    return { ok: false, reason: 'no_journal_route' };
+  }
+  let existing = null;
+  try {
+    existing = typeof dbModule?.getSessionLeadRoute === 'function' ? dbModule.getSessionLeadRoute(id) : null;
+  } catch {
+    existing = null; /* expected: an unreadable route row is treated as absent — the store's write is idempotent */
+  }
+  let written = false;
+  let route;
+  if (existing) {
+    route = {
+      route_id: existing.route_id, model: existing.model,
+      context_window: existing.context_window == null ? null : existing.context_window,
+      transition_id: existing.transition_id || null,
+    };
+  } else {
+    let stored = null;
+    if (typeof dbModule?.setSessionLeadRoute === 'function') {
+      stored = await dbModule.setSessionLeadRoute({
+        ctmSessionId: id, agent: 'codex', routeId, model, display: model,
+        contextWindow: null, transitionId,
+      });
+    }
+    written = !!stored;
+    route = { route_id: routeId, model, context_window: null, transition_id: transitionId };
+  }
+  if (typeof recordSessionDiagnostic === 'function') {
+    recordSessionDiagnostic(id, 'lead-route-reconciled-from-journal', {
+      transition_id: route.transition_id, route_id: route.route_id, model: route.model,
+      provider_thread_id: thread, written,
+    });
+  }
+  return { ok: true, route, written };
+}
+
+/**
+ * The D-4 refusal message. ONE sentence, and the picker is the way out (server.js's
+ * RESUME_BLOCK_MESSAGES and the client's error map both render this same provider id).
+ */
+function codexProviderMissingMessage(provider) {
+  return `This Codex thread was created on gateway provider \`${String(provider || '')}\`; pick a model for this session to relaunch it.`;
+}
+
+/**
+ * The launch-time hook (§9 S-3), called by provider-process.js when a Codex lead is about to be
+ * spawned natively on a resume thread (no `_launchLeadRoute` object and no route row). Returns
+ * `{ native: true }` when the thread's stored provider is servable natively, `{ target }` when
+ * the journal repaired a route (the caller runs its routed branch unchanged), or `{ refused: true }`
+ * after the deterministic resume block was recorded and the client told (D-4).
+ */
+async function gateNativeCodexLaunch({ sessionId, threadId, env = {}, preparedLaunchPlan = null, dbModule,
+  recordSessionDiagnostic, markSessionResumeBlocked, ws = null, wsSend = null } = {}) {
+  const codexHome = env.CODEX_HOME || (env.HOME ? path.join(env.HOME, '.codex') : null);
+  const threadRead = readCodexThreadProvider({
+    threadId, codexHome, homeDir: env.HOME || null,
+    rolloutPath: preparedLaunchPlan?.resume?.rolloutInfo?.rolloutPath
+      || preparedLaunchPlan?.resume?.preflight?.transcriptPath || null,
+  });
+  const threadClass = classifyCodexThreadProvider({ ...threadRead, codexHome });
+  if (threadClass.native) return { native: true };
+  const reconciled = await reconcileLeadRouteFromJournal({ ctmSessionId: sessionId, threadId, dbModule, recordSessionDiagnostic });
+  if (reconciled.ok) {
+    return { target: { routeId: reconciled.route.route_id, model: reconciled.route.model, contextWindow: null } };
+  }
+  if (typeof recordSessionDiagnostic === 'function') {
+    recordSessionDiagnostic(sessionId, 'codex-thread-provider-unservable', {
+      provider_thread_id: threadId, provider: threadClass.provider, source: threadRead.source,
+      config_providers: threadClass.configProviders.length,
+    });
+  }
+  const message = codexProviderMissingMessage(threadClass.provider);
+  if (typeof markSessionResumeBlocked === 'function') {
+    markSessionResumeBlocked(sessionId, { code: 'codex_provider_missing', message, agentType: 'codex', deterministic: true }, 'codex-provider-gate');
+  }
+  if (ws && typeof wsSend === 'function') wsSend(ws, JSON.stringify({ type: 'error', code: 'codex_provider_missing', message }));
+  return { refused: true };
+}
+
+module.exports = {
+  NATIVE_BUILTIN_PROVIDERS,
+  readCodexThreadProvider,
+  classifyCodexThreadProvider,
+  reconcileLeadRouteFromJournal,
+  codexProviderMissingMessage,
+  gateNativeCodexLaunch,
+};

package/template/coding-task-manager/lib/session-create/codex-resume-exit-classify.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// WP-2 — docs/codex-routed-fork-cold-restore-guard-2026-10-22.html §5 D-5, §9 S-9/S-10, §8 WP-2.
+//
+// The belt to WP-1's braces. WP-1 refuses a native Codex launch *before* it spawns when the
+// thread's stored provider is not one a native config load resolves. This module covers the exits
+// that get past any such gate: a thread whose provider changes between the decision and the spawn,
+// and the D-8 paths that never consult the gate at all.
+//
+// Codex reports "Model provider `x` not found" as a plain anyhow error with exit 1 — the SAME exit
+// code as a transient startup fault — so the exit code alone cannot discriminate: only the captured
+// output text can. CTM already buffers that text per attempt (`session._resumeAttemptOutput`, 8 KiB,
+// reset at the start of every attempt), which is what this classifier reads.
+//
+// A config-load failure is a precondition failure: no amount of retrying resolves it, so the
+// caller blocks deterministically instead of spending the 3-restart budget (50 s) to reach the same
+// state with a message that names nothing. Nothing here is flag-gated and nothing here spawns a
+// process: the whole decision is one regex over the caller's string.
+
+// The one Codex phrase this classifies, pinned deliberately narrow (§11: "do not widen the exit
+// classifier beyond the one Codex phrase"; every other startup fault keeps the restart budget).
+// The provider id is the backtick-quoted run Codex echoes back from the thread's stored
+// `model_provider`.
+const CODEX_PROVIDER_MISSING_RE = /Model provider `([^`]+)` not found/;
+
+/**
+ * Classify one attempt's captured Codex output (the caller passes `session._resumeAttemptOutput`).
+ *
+ * @param {string} output the attempt buffer — never scrollback; a non-string degrades to ''
+ * @returns {{ code: 'codex_provider_missing', provider: string, line: string } | null}
+ *   `null` for any output that does not carry the phrase, and for a phrase with no usable provider
+ *   id (e.g. "Model provider `` not found"), so a malformed line can only ever fail OPEN into
+ *   today's restart budget rather than blocking a thread it cannot name.
+ */
+function classifyCodexResumeExit(output) {
+  const text = typeof output === 'string' ? output : '';
+  if (!text) return null;
+  const match = CODEX_PROVIDER_MISSING_RE.exec(text);
+  if (!match) return null;
+  const provider = String(match[1] || '').trim();
+  if (!provider) return null;
+  // `detail` is the whole line the phrase landed on (Codex wraps the anyhow error across the
+  // "thread/resume failed: ..." prefix and the "(code -32600)" suffix); the line is the unit a
+  // human reads, and the provider id alone would drop the surrounding failure context.
+  const lineStart = text.lastIndexOf('\n', Math.max(0, match.index - 1)) + 1;
+  const lineEndRaw = text.indexOf('\n', match.index);
+  const lineEnd = lineEndRaw === -1 ? text.length : lineEndRaw;
+  const line = text.slice(lineStart, lineEnd).replace(/\r$/, '').trim();
+  return { code: 'codex_provider_missing', provider, line: line || match[0] };
+}
+
+module.exports = { CODEX_PROVIDER_MISSING_RE, classifyCodexResumeExit };

package/template/coding-task-manager/lib/session-create/delegate-worker.js

@@ -23,7 +23,7 @@ const { armAt } = require('./clamped-timer');
 const admission = require('../worker-admission');
 const { createWorkerAdmissionExit } = require('./worker-admission-exit');
 const { createWorkerContinuation, validCallerToolUseId } = require('./worker-continuation');
-const { createWorkerObservability, safeToolCounts, progressForGeneration, baselineChanged, statusProgress, currentGenerationReceipts, currentReceiptState, computeExitFailure, boundedWorkerText, isColdDeferredSession, workerHideLogLine, probeCachedFileState, THROTTLED_WINDOW_MS, EVENT_RECEIPT_LIMIT } = require('./worker-observability');
+const { createWorkerObservability, safeToolCounts, progressForGeneration, baselineChanged, statusProgress, currentGenerationReceipts, currentReceiptState, computeExitFailure, boundedWorkerText, isColdDeferredSession, workerHideLogLine, probeCachedFileState, THROTTLED_WINDOW_MS, EVENT_RECEIPT_LIMIT, WORKER_REPORT_TEXT_CAP_BYTES } = require('./worker-observability');
 const { killSessionProcess } = require('../session-class'); // worker-session-tree WP-2: the one kill authority
 const { loadWorkerBrief, validateWorkerCwd, validateBriefPath, validateBriefRealpathInsideCwd, renderedBriefPathForSession, renderedBriefWithBudget, ownedPaths: parseOwnedPaths, findScopeOverlap } = require('./worker-brief');
 const { checkCallerAuthority } = require('./worker-launch-sandbox');
@@ -49,10 +49,27 @@ const EFFORT_VALUES = new Set(['low', 'medium', 'high', 'xhigh']);
 const { createProxyRouteReadiness, DelegateError, setLeadRouteReadiness, DEFAULT_ROUTE_ALIAS, DEFAULT_MODEL, READINESS_BUDGET_MS } = require('./proxy-route-readiness');
 const DEFAULT_TOKEN_TTL_MS = 24 * 60 * 60 * 1000 + 10 * 60 * 1000; // session lifetime + 10 min (D-4)
 
+// D-3 (lead-cost-routing-round2-2026-10-24.html §5 D-3, §6.1/§6.2): the ONE citation counter,
+// shared with wall-e/lib/helper-rules/label.js so the counter and the labeller cannot drift.
+const { countReportCitations } = require('../../../shared/report-citations');
+
 // Only generated UUIDs are accepted before report paths are constructed, preventing encoded
 // path traversal through GET /api/sessions/:id/worker-status?include_report=1.
 const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+// The statuses whose payload carries a citation count; every other status reports null/null
+// because no text has been selected yet (D-3's §6.2 table).
+const WORKER_TERMINAL_STATUSES = new Set(['report_ready', 'exited', 'failed']);
+
+// D-3: read at most WORKER_REPORT_TEXT_CAP_BYTES of a report/last-message file, decode as UTF-8
+// and drop a trailing U+FFFD left by a split multi-byte sequence -- byte-for-byte the semantics
+// lib/api/sessions.js:931 applies to an ?include_report=1 read. A throw (ENOENT/EACCES/EISDIR)
+// is the caller's to classify: getWorkerStatus turns it into report_read_error, never a failure.
+function _readBoundedReportText(filePath) {
+  const bytes = fs.readFileSync(filePath);
+  return bytes.subarray(0, WORKER_REPORT_TEXT_CAP_BYTES).toString('utf8').replace(/\uFFFD$/, '');
+}
+
 function _assertValidSessionId(id) {
   if (!SESSION_ID_RE.test(String(id || ''))) {
     throw new DelegateError('session_invalid', 400, 'ctm_session_id is not a valid session id');
@@ -791,6 +808,31 @@ function getWorkerStatus(ctmSessionId, { now = Date.now } = {}) {
     status = 'starting';
   }
 
+  // D-3 (lead-cost-routing-round2-2026-10-24.html §5 D-3, §6.2): CTM is the ONLY counter of a
+  // report's distinct `file:line` citations. Count whichever text the row's OWN report_source
+  // names -- the report file, the last-message fallback, or the final provider result -- on
+  // every read, independent of ?include_report=1, so the whole-set wait's nested `worker`
+  // payload (which never carries report_text) still answers with a row count. Non-terminal
+  // statuses have selected no text yet and answer null/null; a read failure degrades to 0/0
+  // plus report_read_error and never fails the status read (same posture as report_present).
+  const terminalStatus = WORKER_TERMINAL_STATUSES.has(status);
+  let citationText = '';
+  let reportReadError = null;
+  if (terminalStatus) {
+    if (reportSource === 'report' || reportSource === 'last_message') {
+      try {
+        citationText = _readBoundedReportText(reportSource === 'report' ? reportPath : lastMessagePath);
+      } catch (error) {
+        // expected: report/last-message file missing, unreadable or a directory -- the count
+        // degrades to 0 with the error code exposed, exactly like the include_report=1 reader.
+        reportReadError = (error && error.code) || 'read_failed';
+        citationText = '';
+      }
+    } else if (reportSource === 'final_result') {
+      citationText = typeof successfulFinalText === 'string' ? successfulFinalText : '';
+    }
+  }
+
   const identity = workerRow ? 'marked' : 'unmarked';
 
   return {
@@ -799,6 +841,12 @@ function getWorkerStatus(ctmSessionId, { now = Date.now } = {}) {
     report_present: reportPresent,
     report_source: reportSource,
     report_text: reportText,
+    // D-3 (§6.2): the citation count and the character count of the text report_source names,
+    // never gated by include_report. report_read_error rides along ONLY when the file read
+    // threw (its error code, or 'read_failed'), in which case both counts are 0.
+    report_citation_rows: terminalStatus ? countReportCitations(citationText) : null,
+    report_chars: terminalStatus ? citationText.length : null,
+    ...(reportReadError ? { report_read_error: reportReadError } : {}),
     report_provisional: !!reportPresent && alive,
     last_message_path: lastMessagePath,
     turns: observer ? Number(observer.count || 0) : (Number.isInteger(runtime?.turns) ? runtime.turns : (Number.isInteger(session?._workerTurnCount) ? session._workerTurnCount : null)),
@@ -961,6 +1009,13 @@ function cancelRetirement(ctmSessionId) {
 // that never exits doesn't spam the log every 60s forever.
 const HIDE_LIVE_PROCESS_RETRY_MS = 60_000;
 
+// WP-1 (durable terminal stamp, worker-terminal-stamp-durable-2026-10-26): the ceiling for
+// markWorkerTerminal's transient-lock retry backoff. The write lock is held by the db-owner core
+// writer's transactions (observed 259-1210 ms back-to-back for 19 s on 2026-10-26), so
+// the retry has NO attempt ceiling -- it re-arms until the stamp lands or the row is already
+// terminal / hidden / gone -- and the geometric backoff stops growing here.
+const TERMINAL_STAMP_RETRY_CAP_MS = 5000;
+
 async function _hideWorker(ctmSessionId, { now = Date.now } = {}) {
   const deps = _requireDeps();
   _retentionTimers.delete(ctmSessionId);
@@ -1074,11 +1129,13 @@ function _invalidateWorkerFailureCache(deps, ctmSessionId) {
   session._workerFailure = null;
 }
 
-function markWorkerTerminal(ctmSessionId, { terminalStatus, failure = null, runtime = null, now = Date.now, retry = 0 } = {}) {
+function markWorkerTerminal(ctmSessionId, { terminalStatus, failure = null, runtime = null, now = Date.now, retry = 0, firstAttemptMs = null } = {}) {
   const deps = _requireDeps();
   let row;
   try { row = deps.dbModule.getWorkerSession(ctmSessionId); } catch { row = null; /* expected: an unreadable row is treated as no worker row, so nothing is stamped or scheduled -- a later exit-path call or the boot reload retries */ }
-  if (!row) return;
+  // WP-1: a row that no longer exists, or that another path already hid (hidden_at stamped =
+  // the worker is retired and its row is out of every listing), ends the retry chain here.
+  if (!row || row.hidden_at) return;
   const nowMs = typeof now === 'function' ? now() : Number(now);
   const nowIso = new Date(nowMs).toISOString();
   const patch = {};
@@ -1113,12 +1170,23 @@ function markWorkerTerminal(ctmSessionId, { terminalStatus, failure = null, runt
     try {
       deps.dbModule.updateWorkerSession(ctmSessionId, patch);
     } catch (err) {
-      // WP-7 live finding: a busy write lock fails FAST and the old early return also dropped the wait wake + terminal sentinel -- disposition is now REPORT + bounded retry of the whole stamp.
+      // WP-7 live finding: a busy write lock fails FAST and the old early return also dropped the wait wake + terminal sentinel -- disposition is now REPORT + retry of the whole stamp.
+      // WP-1: that retry has NO attempt ceiling -- a transient lock error is not the stamp's
+      // failure, it is contention on the main-thread writer (2026-10-26: 19 s of back-to-back
+      // 259-1210 ms transactions outlived the old 5-attempt / 1.5 s budget and two finished
+      // workers stayed listed as live for 9 h and 6 h). The chain ends at the top of the
+      // re-entered call: row gone / hidden_at set, or the patch finding terminal_at already
+      // written -- and, of course, when this write lands.
       // The retry's terminal writes start only when it fires, so the pending retry is tracked by the terminal settle.
-      if (['SQLITE_WRITE_LOCK_BUSY', 'SQLITE_BUSY', 'SQLITE_LOCKED'].includes(err && err.code) && retry < 5) return void workerLedger.trackTerminalWork(new Promise((resolve) => setTimeout(() => { try { markWorkerTerminal(ctmSessionId, { terminalStatus, failure, runtime, now, retry: retry + 1 }); } finally { resolve(); } }, 100 * (retry + 1)).unref?.()));
+      if (['SQLITE_WRITE_LOCK_BUSY', 'SQLITE_BUSY', 'SQLITE_LOCKED'].includes(err && err.code)) {
+        const firstAtMs = firstAttemptMs ?? nowMs;
+        if (retry === 5) console.warn(`[delegate-worker] terminal stamp still busy after 6 attempts (${String((err && err.code) || 'write_failed').slice(0, 48)}); retrying every ${TERMINAL_STAMP_RETRY_CAP_MS} ms`);
+        return void workerLedger.trackTerminalWork(new Promise((resolve) => setTimeout(() => { try { markWorkerTerminal(ctmSessionId, { terminalStatus, failure, runtime, now, retry: retry + 1, firstAttemptMs: firstAtMs }); } finally { resolve(); } }, Math.min(100 * (retry + 1), TERMINAL_STAMP_RETRY_CAP_MS)).unref?.()));
+      }
       console.warn(`[delegate-worker] terminal stamp failed (${String((err && err.code) || "write_failed").slice(0, 48)})`); return;
     }
     row = { ...row, ...patch };
+    if (retry > 0) console.log(`[delegate-worker] terminal stamp landed for ${ctmSessionId} after ${retry + 1} attempts in ${nowMs - (firstAttemptMs ?? nowMs)} ms`);
     _invalidateWorkerFailureCache(deps, ctmSessionId);
   }
   const hideAtMs = _computeHideAtMs(row, _retainMsForSession(deps, ctmSessionId));
@@ -1195,6 +1263,25 @@ function retireNow(session, now) {
   markWorkerTerminal(session.id, { terminalStatus: result.status, failure: result.failure, runtime, now });
 }
 
+// WP-2 (worker-terminal-stamp-durable-2026-10-26 D-2/D-3): one idempotent read repair for a
+// worker that EXITED but whose row never got its exit-time stamp (the write-lock loss WP-1 now
+// retries). Every lead-facing reader calls this FIRST, so a dead-but-unstamped worker is never
+// listed live and the stop verb never answers 'stopping' on a process that no longer exists.
+// Returns 'retired' | 'lost' | null. Idempotent: a stamped or hidden row is a no-op.
+// retireWorkerOnExit is deliberately NOT awaited -- a proxied worker's stamp is deferred by one
+// async read and tracked by workerLedger.trackTerminalWork, so callers must not assume the
+// stamp is synchronous (the next read retries anyway).
+function repairExitedWorkerRow(ctmSessionId, { now = Date.now } = {}) {
+  const deps = _requireDeps();
+  let row = null;
+  try { row = deps.dbModule.getWorkerSession(ctmSessionId); } catch { row = null; /* expected: an unreadable row cannot be repaired now; the next read retries */ }
+  if (!row || row.terminal_at || row.hidden_at) return null;
+  const session = typeof deps.getSession === 'function' ? deps.getSession(ctmSessionId) : null;
+  if (session && session.agentRole === 'worker' && (session._exitCode != null || session._exited)) { retireWorkerOnExit(session, { now }); return 'retired'; }
+  if (!session) { retireLostWorker(row, { now }); return 'lost'; }
+  return null; // a live process: nothing to repair
+}
+
 // Lifecycle WP-5 (§5 D-10, R-3, §9 S-8, AC-5c): boot re-arm -- every live (hidden_at === '')
 // worker_sessions row that already has a persisted hide_at gets its retirement timer
 // re-armed at that EXACT value (never recomputed off the current retainMs, so a config
@@ -1263,7 +1350,7 @@ const retireLostWorker = bootRetire.retireLostWorker, retireSurvivingWorker = bo
 module.exports = {
   configure, _terminalJournalSettled: workerLedger.terminalJournalSettled,
   resumeWorkerSession: workerContinuation.resumeWorkerSession,
-  stopWorkerSession: (id, opts) => require('./worker-stop').stopWorkerSession(id, opts, _requireDeps(), { resolveParent: resolveParentCtmSessionId }),
+  stopWorkerSession: (id, opts) => require('./worker-stop').stopWorkerSession(id, opts, _requireDeps(), { resolveParent: resolveParentCtmSessionId, repairExitedWorkerRow }),
   probeWorkerRoute: workerContinuation.probeWorkerRoute,
   restoreQuotaHoldsAtBoot: workerContinuation.restoreQuotaHoldsAtBoot,
   markAgentConsumed: workerContinuation.markAgentConsumed,
@@ -1290,6 +1377,8 @@ module.exports = {
   markAcknowledged,
   markWorkerTerminal,
   retireWorkerOnExit,
+  // WP-2 (D-2): the idempotent read repair both lead-facing readers call before answering.
+  repairExitedWorkerRow,
   reloadRetirementsAtBoot,
   listPendingRetirements,
   _resetRetentionTimersForTest,

package/template/coding-task-manager/lib/session-create/identity.js

@@ -7,6 +7,25 @@ function configure(getDeps) {
   _getDeps = getDeps;
 }
 
+// WP-4 (docs/remote-hub-followups-credential-projects-rows-idempotency-2026-10-23.html §5 D-11):
+// the create fingerprint an Idempotency-Key retry is compared against -- the JSON of these nine
+// launch-shaping fields, IN THIS ORDER, with a missing field read as ''. Geometry (cols/rows) and
+// label/title are deliberately EXCLUDED: a retry may differ in window size or naming and is still
+// the same create. Pure: reads nothing but `msg`, allocates nothing, touches no socket.
+const CREATE_FINGERPRINT_FIELDS = Object.freeze([
+  'cmd', 'args', 'cwd', 'createCwd', 'model_id', 'model_provider', 'mcp_profile', 'agentType', 'chatSessionId',
+]);
+
+function createFingerprint(msg) {
+  const source = msg && typeof msg === 'object' ? msg : {};
+  return JSON.stringify(CREATE_FINGERPRINT_FIELDS.map((field) => {
+    const value = source[field];
+    // `args` is compared AS GIVEN (an argv array serializes element by element); every other
+    // field is a scalar. Absent and null both read as ''.
+    return value === undefined || value === null ? '' : value;
+  }));
+}
+
 function prepareCreate(ws, msg) {
   const deps = _getDeps();
   const handleCreateStartedAt = deps.now();
@@ -67,4 +86,4 @@ function prepareCreate(ws, msg) {
   };
 }
 
-module.exports = { configure, prepareCreate };
+module.exports = { configure, prepareCreate, createFingerprint };

package/template/coding-task-manager/lib/session-create/prepared.js

@@ -1,5 +1,10 @@
 'use strict';
 
+// WP-4 (docs/remote-hub-followups-credential-projects-rows-idempotency-2026-10-23.html §5 D-11):
+// the ONE fingerprint definition lives in lib/session-create/identity.js; this module stamps it on a
+// session it fully owned and compares it on the next same-id create.
+const { createFingerprint } = require('./identity');
+
 // WP-2b (docs/session-model-authority-and-display-2026-10-15.html §9): the COMPLETE prepared-create
 // orchestration, moved verbatim out of server.js's `handleCreatePrepared`. It owns one whole
 // responsibility -- admitted request -> durable generation -> prepared current plan -> trusted
@@ -26,11 +31,23 @@
 //      argv, token or raw send-error text is ever echoed into the report. Every other `_wsSend` in
 //      the handler (mcp_profile_invalid, launch-generation-refused, cwd-create-failed,
 //      launch_transcript_restore_failed, the folder toast) keeps its original throwing behavior.
+// WP-4 (docs/remote-hub-followups-credential-projects-rows-idempotency-2026-10-23.html §5 D-13):
+// the per-id IN-FLIGHT create ledger -- id -> { fingerprint } (D-11). One entry per create that has
+// passed owner/MCP admission and has not yet left handleCreatePrepared; a second create with the
+// SAME id AND the same fingerprint while the first is in flight is refused `create_in_progress`
+// before it reserves a generation, plans, or spawns anything. The entry is deleted in the handler's
+// `finally`, which covers every exit (success, typed refusal, early null return, throw). A DIFFERENT
+// fingerprint never refuses and never overwrites the first entry (D-14: a model-switch relaunch
+// stays the generation runtime's business).
+const _inflightCreates = new Map();
+
 function createPreparedSessionCreate(host) {
   const {
     // Admission / identity
     crypto, _sessionMcpProfileSetting, _wsSend, _codingSessionGenerationRuntime,
     recordSessionDiagnostic, isSessionResumeBlocked, clearSessionResumeBlocked, getSession,
+    // WP-4 (§5 D-12): the one `created` frame a duplicate create is re-answered with.
+    sendNativeSessionCreated,
     // Input / local path
     serverConfig, path, fs, detectAgentType, extractResumeTarget,
     // Metadata / planning
@@ -61,6 +78,9 @@ function createPreparedSessionCreate(host) {
     }
   }
 
+  // WP-4 (§5 D-13): admission, then the in-flight claim, then the unchanged orchestration. The
+  // claim's `finally` wraps the WHOLE body, so every exit of the orchestration releases it -- and no
+  // line of the orchestration itself had to move to make that true.
   async function handleCreatePrepared(ws, msg) {
     if (host._ownerRecovery.rejectRequest(ws, msg)) return null; const id = msg?.id || crypto.randomUUID();
     const preparedMsg = { ...(msg || {}), id };
@@ -70,6 +90,44 @@ function createPreparedSessionCreate(host) {
       if (ws?.readyState === 1) _wsSend(ws, JSON.stringify({ type: 'error', code: 'mcp_profile_invalid', message: `Unknown mcp_profile: ${JSON.stringify(_rawMcpProfile)}` }));
       return null;
     }
+    // WP-4 (§5 D-12/D-13): a client-supplied id is the Idempotency-Key, and both duplicate answers
+    // are decided HERE, before any generation reservation, plan, markSpawning or markLive:
+    //   - the id names a LIVE session spawned by an identical create => re-answer ONE `created`
+    //     frame (same builder a fresh create uses) and return it; nothing is attached or rolled back;
+    //   - an identical create is still in flight => one typed `create_in_progress` refusal.
+    // A DIFFERENT fingerprint is NOT a duplicate (D-14): it walks today's path (attach, or the
+    // generation runtime's model-switch relaunch) and leaves the other fingerprint's entry alone.
+    let _claimedInflight = false;
+    const fingerprint = msg?.id ? createFingerprint(preparedMsg) : '';
+    if (fingerprint) {
+      const live = getSession(id);
+      if (ws && live?.ptyProcess && live._createFingerprint === fingerprint) {
+        sendNativeSessionCreated(ws, live);
+        return live;
+      }
+      const inFlight = _inflightCreates.get(id);
+      if (inFlight && inFlight.fingerprint === fingerprint) {
+        sendPreparedError(ws, {
+          type: 'error',
+          code: 'create_in_progress',
+          id,
+          message: 'A create for this session is already in progress',
+        });
+        return null;
+      }
+      if (!inFlight) { _inflightCreates.set(id, { fingerprint }); _claimedInflight = true; }
+    }
+    try {
+      return await _prepareCreateAdmitted(ws, msg, preparedMsg, id, fingerprint);
+    } finally {
+      if (_claimedInflight) _inflightCreates.delete(id);
+    }
+  }
+
+  // The orchestration itself: byte-for-byte the body that used to be handleCreatePrepared's, from
+  // the generation reservation on, plus the one D-11 fingerprint stamp on the owned success path.
+  // Split out ONLY so the D-13 claim above can wrap every exit.
+  async function _prepareCreateAdmitted(ws, msg, preparedMsg, id, fingerprint) {
     const reserved = _codingSessionGenerationRuntime.revalidateReservation(await _codingSessionGenerationRuntime.reserveSessionGeneration(id));
     if (!reserved.ok) { recordSessionDiagnostic(id, 'launch-generation-refused', { code: reserved.code, message: reserved.message }); if (ws?.readyState === 1) _wsSend(ws, JSON.stringify({ type: 'error', code: reserved.code, message: `Launch refused: ${reserved.message}` })); return null; }
     const generation = reserved.generation;
@@ -274,6 +332,10 @@ function createPreparedSessionCreate(host) {
       });
       return null;
     }
+    // WP-4 (§5 D-11): only a create this handler fully owned, keyed by a client id, can be re-answered
+    // later. A retry landing between the `created` frame and this line still finds the in-flight
+    // entry above and gets `create_in_progress`.
+    if (fingerprint && created && created.type !== 'walle') created._createFingerprint = fingerprint;
     _launchPlanCoordinator.markLive(id, generation, result.plan);
     return created || null;
   }
@@ -281,4 +343,10 @@ function createPreparedSessionCreate(host) {
   return handleCreatePrepared;
 }
 
-module.exports = { createPreparedSessionCreate };
+module.exports = {
+  createPreparedSessionCreate,
+  // WP-4 test seam (AC-4a/§10 abuse case): the in-flight ledger is process-local, so a test that
+  // drives the real factory in-process asserts it drains through this accessor rather than reaching
+  // into the module's internals.
+  inflightCreateCount: () => _inflightCreates.size,
+};