create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/resume-cwd.js

@@ -85,6 +85,18 @@ function claudeProjectDirForCwd(cwd, opts = {}) {
   return path.join(configDir, 'projects', encodeClaudeProjectEntry(cwd, opts));
 }
 
+// WP-2 (worker-transcript-link-derived-not-discovered-2026-10-25.html §5 D-4/D-7): the path
+// Claude Code writes a session's transcript to, derived from (cwd, session id) alone -- no fs
+// read, no directory scan. A resume preflight that finds an empty agent_sessions.jsonl_path
+// uses this to look where the file deterministically is before refusing, then verifies it
+// through lib/transcript-source.js (lib/transcript-link.js) rather than trusting the guess.
+function deriveClaudeTranscriptPath({ cwd, agentSessionId, homeDir = process.env.HOME, claudeConfigDir = '' } = {}) {
+  const dir = String(cwd || '').trim();
+  const id = String(agentSessionId || '').trim();
+  if (!dir || !id) throw new TypeError('deriveClaudeTranscriptPath requires cwd and agentSessionId');
+  return path.join(claudeProjectDirForCwd(dir, { homeDir, claudeConfigDir }), `${id}.jsonl`);
+}
+
 // D-3 (main-loop-sync-io doc §5 D-3, §8 WP-0): decodeClaudeProjectEntry used to duplicate
 // session-utils.js's own backtracking search AND add the authoritative-transcript-cwd fallback
 // session-utils.js lacked, with no memo at all (R-2's 439,403-calls-in-88-min hot path). The full
@@ -166,6 +178,7 @@ module.exports = {
   canonicalizeClaudeProjectPath,
   resetCanonicalizeClaudeProjectPathMemo,
   claudeProjectDirForCwd,
+  deriveClaudeTranscriptPath,
   encodeClaudeProjectEntry,
   encodeClaudeProjectSegment,
   decodeClaudeProjectEntry,

package/template/coding-task-manager/lib/resume-from-store.js

@@ -372,7 +372,18 @@ function resolveResumeRung(input = {}, probes = {}) {
   if (_RESTORE_STATES.has(state)) return done('restore');
   const fileName = plainPath ? plainPath.split(/[\\/]/).pop() : '';
   const trashed = fileName ? probes.trashEntry(fileName) : null;
-  if (trashed) return done('trash', { detail: { trashPath: trashed.trashPath, originalPath: trashed.originalPath } });
+  // WP-3 (D-13): the trash rung rides the SAME two recorded facts as the preflight path, so the
+  // card's "why" sentence is identical whichever route found the copy.
+  if (trashed) {
+    return done('trash', {
+      detail: {
+        trashPath: trashed.trashPath,
+        originalPath: trashed.originalPath,
+        trashReason: trashed.reason || '',
+        trashedAt: trashed.trashedAt || '',
+      },
+    });
+  }
   if (probes.storeHasHuman(ctmSessionId)) return done('store');
   return done('fresh');
 }

package/template/coding-task-manager/lib/resume-origin-facts.js

@@ -43,7 +43,7 @@ function _peerInstanceIds(syncPeers) {
 }
 
 function resumeOriginFacts(db, ctmSessionId, options = {}) {
-  const facts = { origin: 'unknown', originHostname: '', originIsPeer: false };
+  const facts = { origin: 'unknown', originHostname: '', originInstanceId: '', originIsPeer: false };
   try {
     const id = String(ctmSessionId || '').trim();
     if (!id) return facts;
@@ -57,13 +57,46 @@ function resumeOriginFacts(db, ctmSessionId, options = {}) {
     const originId = _originIdOf(handle.prepare('SELECT origin_instance_id FROM ctm_sessions WHERE id = ?').get(id));
     facts.origin = resumeOriginFor({ origin_instance_id: originId }, identity);
     facts.originHostname = String(birth?.hostname || '').trim();
+    // WP-6 (S-8/S-25, AC-6d): the raw MINTED origin id travels too, because it — never the hostname
+    // (S-5) — is the key a machine registration is pinned by (lib/machine-registry.js, D-3). It is
+    // what lets the resume-blocked card offer "open on <machine>" and what routes the resume itself.
+    facts.originInstanceId = originId;
     facts.originIsPeer = !!originId && _peerInstanceIds(options.syncPeers).has(originId);
+    // WP-6 (S-8, AC-6d): when the origin is a REGISTERED, REACHABLE machine, the card can act on it
+    // instead of dead-ending at `on_other_machine`. Additive, and absent (not null) otherwise, so
+    // every existing payload keeps its exact shape. `displayName` is the registry's user label; a
+    // hostname is never used here.
+    const openOnMachine = _openOnMachineFor(originId, facts.origin);
+    if (openOnMachine) facts.openOnMachine = openOnMachine;
     return facts;
   } catch {
     return facts; // expected: pre-boot / a test harness with no database -> the card says what it knows, which is nothing
   }
 }
 
+// A machine that is not registered, is disabled, or is not reachable is NOT an actionable origin:
+// the 60 s health walk (P3) means a reachable verdict is the only one worth offering an action on.
+function _openOnMachineFor(originId, origin) {
+  const id = String(originId || '').trim();
+  if (!id || origin !== 'other_instance') return null;
+  try {
+    const registry = require('./machine-registry');
+    const db = require('../db-owner-client');
+    const { machines } = registry.listMachines({ db }) || {};
+    return _openOnMachineIn(Array.isArray(machines) ? machines : [], id);
+  } catch {
+    return null; // expected: pre-boot / no machines table -> today's card copy, byte-for-byte
+  }
+}
+
+function _openOnMachineIn(machines, originId) {
+  const row = (Array.isArray(machines) ? machines : [])
+    .find((machine) => machine && String(machine.instanceId || '') === originId);
+  if (!row || row.enabled === false) return null;
+  if (String(row.health || '') !== 'reachable') return null;
+  return { instanceId: String(row.instanceId || ''), displayName: String(row.displayName || '') };
+}
+
 // WP-3 (§6.4): the three sync-table facts the resume-blocked card needs to distinguish "the copy is
 // here and gone", "the copy is on its way" and "everything is on the other machine". Every read is
 // best-effort: a missing sync_transcript_replicas table (a pre-WP-3 database) or a pre-boot harness
@@ -152,7 +185,11 @@ function resumeOriginRecordFields(sessionId, info = {}) {
   return {
     origin,
     originHostname: String(i.originHostname || facts.originHostname || ''),
+    originInstanceId: String(i.originInstanceId || facts.originInstanceId || ''),
     originIsPeer: i.originIsPeer === true || facts.originIsPeer === true,
+    // WP-6 (S-8/AC-6d): the actionable-origin fact survives the record round-trip, so a caller that
+    // re-derives the wire object from the record still offers "open on <machine>".
+    ...(i.openOnMachine || facts.openOnMachine ? { openOnMachine: i.openOnMachine || facts.openOnMachine } : {}),
     ...syncFacts,
     transcriptState: i.transcriptState || deriveTranscriptState({
       origin, localHistory: normalizeLocalHistory(i), ...syncFacts,

package/template/coding-task-manager/lib/resume-preflight.js

@@ -122,26 +122,21 @@ async function recheckResumeBlockedRecord(record, deps = {}) {
 }
 
 // Builds the human-readable "removed" sentence shared by both the Claude and Codex missing-
-// transcript messages (R10): says the file was removed from this machine (with size + last-seen
-// date), that CTM still has the conversation, and — when a trash copy was found — where it is
-// and that moving it back makes Retry work.
+// transcript messages (R10, D-15): says the file was removed from this machine (with size +
+// last-seen date) and whether CTM kept a copy it can put back. No path, no "move it back", no
+// "Retry will work" — the user never handles a file, and the card's Details row carries paths.
 function _removedTranscriptSentence(fields) {
   const dateText = fields.lastSeenAt ? fields.lastSeenAt.slice(0, 10) : 'an earlier session';
-  let sentence = `was removed from this machine (${_formatBytes(fields.lastSeenBytes)}, last seen ${dateText}). `
-    + `CTM still has the cached conversation history.`;
-  if (fields.trashPath) {
-    sentence += ` A copy is in CTM's transcript trash at ${fields.trashPath} — move it back to `
-      + `${fields.originalPath || 'its original location'} and Retry will work.`;
-  } else {
-    sentence += ' Start a new session from the cached history, or restore the missing transcript from backup.';
-  }
-  return sentence;
+  return `was removed from this machine (${_formatBytes(fields.lastSeenBytes)}, last seen ${dateText}). `
+    + (fields.trashPath
+      ? 'CTM kept a copy and can put it back.'
+      : 'CTM still has the cached conversation history.');
 }
 
 // Pure (no fs/DB): given a `localHistory === 'removed'` preflight result and a WP-1
-// findTrashedTranscript() lookup result (`{ trashPath, originalPath, trashedAt } | null`, found by
-// the CALLER -- this module never runs that async fs read itself), returns a new result with
-// `trashPath`/`originalPath` set and `message` rebuilt to name the trash location. `trashed ===
+// findTrashedTranscript() lookup result (`{ trashPath, originalPath, trashedAt, reason } | null`,
+// found by the CALLER -- this module never runs that async fs read itself), returns a new result
+// with `trashPath`/`originalPath`/`trashReason`/`trashedAt` set and `message` rebuilt. `trashed ===
 // null` (nothing found, or no trashRoot configured) returns `result` unchanged -- same message as
 // before. Never mutates its input.
 function withTrashLocation(result, trashed) {
@@ -151,7 +146,14 @@ function withTrashLocation(result, trashed) {
   const isCodex = result.code === 'missing_codex_rollout';
   const message = `Cannot resume ${isCodex ? 'Codex' : 'Claude'} session ${shortId}: `
     + `${isCodex ? 'the local Codex rollout file' : 'the local Claude transcript file'} ${_removedTranscriptSentence(fields)}`;
-  return { ...result, trashPath: trashed.trashPath, originalPath: trashed.originalPath, message };
+  return {
+    ...result,
+    trashPath: trashed.trashPath,
+    originalPath: trashed.originalPath,
+    trashReason: trashed.reason || '',
+    trashedAt: trashed.trashedAt || '',
+    message,
+  };
 }
 
 // A Claude transcript is "real" only if it carries at least one conversation
@@ -676,6 +678,9 @@ module.exports = {
   claudeLiveTranscriptShouldRestore,
   restoreClaudeLiveTranscriptFromBak,
   withTrashLocation,
+  // WP-3 (D-15, AC-3c): exported so the exact sentence is pinned by a unit test instead of only by the
+  // message it is embedded in.
+  _removedTranscriptSentence,
   withResumeRung,
   recheckResumeBlockedRecord,
   MISSING_TRANSCRIPT_CODES,

package/template/coding-task-manager/lib/review-repo-admission.js

@@ -14,9 +14,19 @@ const os = require('os');
 const path = require('path');
 
 const REJECT_SEGMENTS = new Set(['node_modules', '.cache']);
-// bin/pre-commit-hook.sh mktemps `<root>/.worktrees/precommit-staged.XXXXXX` per commit and
-// deletes it after; admitting one leaves a registry row whose cwd vanishes (`spawn git ENOENT`).
-const REJECT_BASENAME_PATTERNS = [/^precommit-staged\./];
+// Every scratch checkout the repo's own tooling mktemps under `<repo>/.worktrees/` and deletes
+// when it is done. Admitting one leaves a registry row (or a /api/projects picker row, WP-2 of
+// docs/remote-hub-followups-credential-projects-rows-idempotency-2026-10-23.html) whose cwd
+// vanishes (`spawn git ENOENT`) or that the user never asked for. Widened from the single
+// pre-commit template (S-10) to all four; each one is pinned by name in
+// tests-integration/api-projects-rows.test.js (AC-2e), which reads the templates back out of the
+// gate scripts themselves.
+const GATE_SCRATCH_BASENAME_PATTERNS = Object.freeze([
+  /^test-gate-merged\./,   // bin/test-gate.sh (merged-tree gate worktree)
+  /^precommit-staged\./,   // bin/pre-commit-hook.sh
+  /^nightly-gate\./,       // bin/nightly-gate.sh
+  /^deflake-snapshot-/,    // bin/deflake-source-snapshot.js
+]);
 const WORKTREE_PARENT_SEGMENTS = ['.claude/worktrees', '.walle/worktrees', '.worktrees'];
 
 function _segments(p) {
@@ -44,12 +54,28 @@ function _rejectReason(candidatePath, env) {
     if (REJECT_SEGMENTS.has(seg)) return 'dependency-dir';
   }
   for (const seg of _segments(candidatePath)) {
-    if (REJECT_BASENAME_PATTERNS.some((re) => re.test(seg))) return 'temp';
+    if (GATE_SCRATCH_BASENAME_PATTERNS.some((re) => re.test(seg))) return 'temp';
   }
   if (env.hidden && env.hidden.has(candidatePath)) return 'hidden';
   return null;
 }
 
+/**
+ * True iff `p` is a gate scratch checkout: its PARENT directory is named `.worktrees` and its
+ * basename matches one of the gate's own mktemp templates (GATE_SCRATCH_BASENAME_PATTERNS).
+ * A real worktree the user created (e.g. `<repo>/.worktrees/feature-x`) is NOT gate scratch and
+ * stays visible; the four tooling templates never do. Used by the worktree worker's `projectRows`
+ * op (WP-2) — the Review Hub admission filter below keeps its own segment scan over the same list.
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isGateScratchPath(p) {
+  const value = String(p || '');
+  const name = path.basename(value);
+  if (path.basename(path.dirname(value)) !== '.worktrees') return false;
+  return GATE_SCRATCH_BASENAME_PATTERNS.some((re) => re.test(name));
+}
+
 /**
  * @returns {{ok:true, realpath, kind:'primary'|'worktree', repoRoot, gitDir, viaSubdir?:true}
  *         | {ok:false, reason:'missing'|'outside-home'|'temp'|'scratch'|'dependency-dir'|'not-git'|'hidden'}}
@@ -97,7 +123,7 @@ function admitReviewRepo(candidatePath, env) {
   }
 
   for (const seg of _segments(realpath)) {
-    if (REJECT_BASENAME_PATTERNS.some((re) => re.test(seg))) return { ok: false, reason: 'temp' };
+    if (GATE_SCRATCH_BASENAME_PATTERNS.some((re) => re.test(seg))) return { ok: false, reason: 'temp' };
   }
 
   if (env.hidden && env.hidden.has(realpath)) return { ok: false, reason: 'hidden' };
@@ -145,4 +171,11 @@ function defaultAdmissionEnv({ home = os.homedir(), scratchRoot = null } = {}) {
   };
 }
 
-module.exports = { admitReviewRepo, defaultAdmissionEnv, REJECT_SEGMENTS, WORKTREE_PARENT_SEGMENTS };
+module.exports = {
+  admitReviewRepo,
+  defaultAdmissionEnv,
+  isGateScratchPath,
+  GATE_SCRATCH_BASENAME_PATTERNS,
+  REJECT_SEGMENTS,
+  WORKTREE_PARENT_SEGMENTS,
+};

package/template/coding-task-manager/lib/review-repo-registry.js

@@ -665,6 +665,23 @@ function createReviewRepoRegistry({ db, gitRead, sessionFeed, readSources, broad
       next.watcher = watchFn(dir, { persistent: false }, () => {
         for (const p of next.repoPaths) _scheduleWatchRefresh(p);
       });
+      // F-2 (clock-free follow-ups r3): a synchronous try/catch is NOT an 'error' listener.
+      // On macOS libuv broadcasts one FSEventStreamStart failure (UV_EMFILE) to EVERY
+      // directory watcher in the loop (src/unix/fsevents.c), asynchronously — so without
+      // this listener the EventEmitter throws and the whole CTM process exits (observed:
+      // "EMFILE: too many open files, watch" 13 s after a dev restart).
+      next.watcher.on('error', (error) => {
+        // REPORT once per dir; the next discover() pass (boot, a new transcript, or the client
+        // Refresh) re-watches it via _watchRepo. Until then the 60 s sweep keeps status correct.
+        // No timer and no immediate re-attach: a re-attach rebuilds the one shared FSEvents
+        // stream, which would just re-fail every handle (D-2).
+        if (watchedDirs.get(dir) === next) watchedDirs.delete(dir);
+        try { next.watcher.close(); } catch { /* expected: an errored FSWatcher may throw on close */ }
+        if (!warnedWatchDirs.has(dir)) {
+          warnedWatchDirs.add(dir);
+          console.warn('[review-registry] watch error', dir, error && error.code);
+        }
+      });
     } catch (error) {
       // REPORT once per dir: the 60s sweep is the fallback for a dir this process can't
       // watch (e.g. an fs.watch fd/inotify-limit failure), not a hard failure.

package/template/coding-task-manager/lib/root-delivery-runtime.js

@@ -51,6 +51,7 @@ function createRootDeliveryRuntime(deps = {}) {
   const {
     coordinator, readLatestDelivery, readJobText, preflight, buildWritePayload,
     deliverTerminal, isDeliveryCurrent = () => true, now = Date.now,
+    reportDiagnostic = () => {},
   } = deps;
   const required = { 'coordinator.execute': coordinator?.execute, readLatestDelivery, readJobText,
     preflight, buildWritePayload, deliverTerminal };
@@ -58,10 +59,23 @@ function createRootDeliveryRuntime(deps = {}) {
     if (typeof callback !== 'function') throw new TypeError(`Root delivery runtime requires ${name}`);
   }
 
+  // WP-0: one bounded diagnostic per rejected handoff stage. `phase` is the exact
+  // stage the driver gave up at and `code` is a static, non-parameterized token --
+  // no prompt text, attachment, auth fact, path, receipt id, or raw exception text
+  // ever rides along, and a throwing sink can never change an outcome.
+  const report = (phase, code) => {
+    if (typeof reportDiagnostic !== 'function') return;
+    try { reportDiagnostic(Object.freeze({ phase, code })); return true; }
+    catch { return false; } // Diagnostics are advisory; their failure cannot change delivery.
+  };
+
   async function drive(admissionHandle, { automatic = false, nowMs = now() } = {}) {
     const committed = getCommittedRootAdmission(admissionHandle);
     if (!committed || typeof committed.isCurrent !== 'function' || !committed.selector
-        || !committed.metadata || !committed.target || typeof committed.target.isCurrent !== 'function') return unavailable();
+        || !committed.metadata || !committed.target || typeof committed.target.isCurrent !== 'function') {
+      report('admission_metadata', 'root_admission_metadata_unavailable');
+      return unavailable();
+    }
     const intent = rootPromptIntent.getCapturedRootPromptIntent(committed.intentHandle);
     const parent = committed.metadata;
     const deliveryCurrent = () => {
@@ -70,6 +84,7 @@ function createRootDeliveryRuntime(deps = {}) {
     if (!intent || intent.sessionId !== parent.sessionId || intent.source !== parent.source
         || !committed.isCurrent()) {
       retiredJobs.add(admissionHandle);
+      report('admission_metadata', 'root_admission_metadata_unavailable');
       return unavailable();
     }
     if (!deliveryCurrent()) return unavailable('root_delivery_expired');
@@ -98,22 +113,37 @@ function createRootDeliveryRuntime(deps = {}) {
     };
     const selector = committed.selector;
     let snapshot;
-    try { snapshot = await readLatestDelivery(selector); } catch { return unavailable(); }
+    try { snapshot = await readLatestDelivery(selector); } catch {
+      report('delivery_snapshot', 'root_delivery_snapshot_unavailable');
+      return unavailable();
+    }
     if (!stillJobCurrent()) return unavailable();
     if (!deliveryCurrent()) return unavailable('root_delivery_expired');
-    if (!snapshot || !snapshot.parent || !sameMetadata(snapshot.parent, parent)) return unavailable();
+    if (!snapshot || !snapshot.parent || !sameMetadata(snapshot.parent, parent)) {
+      report('delivery_snapshot', 'root_delivery_snapshot_unavailable');
+      return unavailable();
+    }
     const selected = selectRootDeliveryAttempt(snapshot, { automatic, nowMs });
-    if (!selected?.ok) return selected || unavailable();
+    if (!selected?.ok) {
+      report('delivery_selection', 'root_delivery_selection_refused');
+      return selected || unavailable();
+    }
 
     let workerResult;
-    try { workerResult = await readJobText(selector, parent.textBytes); } catch { return unavailable(); }
+    try { workerResult = await readJobText(selector, parent.textBytes); } catch {
+      report('delivery_text', 'root_delivery_text_unavailable');
+      return unavailable();
+    }
     if (!stillJobCurrent()) return unavailable();
     if (!deliveryCurrent()) return unavailable('root_delivery_expired');
     const buffer = workerResult?.__resultBuffer;
     const metadata = workerResult?.__resultMetadata;
     if (!Buffer.isBuffer(buffer) || !sameMetadata(metadata, parent) || buffer.byteLength !== parent.textBytes
         || crypto.createHash('sha256').update(buffer).digest('hex') !== parent.textHash
-        || !buffer.equals(Buffer.from(intent.text, 'utf8'))) return unavailable();
+        || !buffer.equals(Buffer.from(intent.text, 'utf8'))) {
+      report('delivery_text', 'root_delivery_text_unavailable');
+      return unavailable();
+    }
     const text = buffer.toString('utf8');
 
     const expectedChildId = remoteCommandStore.remoteCommandReceiptId(selector.namespaceHash, selected.commandId);
@@ -128,18 +158,26 @@ function createRootDeliveryRuntime(deps = {}) {
         authorize,
         dispatch: async (message) => {
           if (message?.id !== expectedChildId || message?.type !== ROOT_DELIVERY_ACTION || message?.version !== 1
-              || !message.body || JSON.stringify(message.body) !== JSON.stringify(selected.body)
-              || !stillJobCurrent()) return unavailable();
+              || !message.body || JSON.stringify(message.body) !== JSON.stringify(selected.body)) {
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
+            return unavailable();
+          }
+          if (!stillJobCurrent()) return unavailable();
           let blocker;
-          try { blocker = preflight(parent.sessionId, committed.target.session, text); } catch { return unavailable('root_delivery_preflight_unavailable'); }
+          try { blocker = preflight(parent.sessionId, committed.target.session, text); } catch {
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
+            return unavailable('root_delivery_preflight_unavailable');
+          }
           if (blocker && typeof blocker?.then === 'function') {
             // A promise violates the synchronous preflight contract; consume either settlement without exposing it.
             void Promise.resolve(blocker).then(() => false, () => false);
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
             return unavailable('root_delivery_preflight_unavailable');
           }
           if (blocker !== null) {
             if (!blocker || typeof blocker !== 'object' || Array.isArray(blocker)
                 || blocker.ok !== false || !PREFLIGHT.has(blocker.error)) {
+              report('delivery_dispatch', 'root_delivery_dispatch_failed');
               return unavailable('root_delivery_preflight_unavailable');
             }
             const blockerCode = blocker.error;
@@ -150,16 +188,29 @@ function createRootDeliveryRuntime(deps = {}) {
             } };
           }
           if (!deliveryCurrent()) return unavailable('root_delivery_expired');
-          if (!stillTargetCurrent()) return unavailable('terminal_target_replaced');
+          if (!stillTargetCurrent()) {
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
+            return unavailable('terminal_target_replaced');
+          }
           let payload;
-          try { payload = buildWritePayload(committed.target.session, text); } catch { return unavailable('root_delivery_payload_unavailable'); }
+          try { payload = buildWritePayload(committed.target.session, text); } catch {
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
+            return unavailable('root_delivery_payload_unavailable');
+          }
           if (payload && typeof payload?.then === 'function') {
             // Payload construction is synchronous by contract; consume async contract violations safely.
             void Promise.resolve(payload).then(() => false, () => false);
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
+            return unavailable('root_delivery_payload_unavailable');
+          }
+          if (typeof payload !== 'string' || !payload || !stillJobCurrent()) {
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
             return unavailable('root_delivery_payload_unavailable');
           }
-          if (typeof payload !== 'string' || !payload || !stillJobCurrent()) return unavailable('root_delivery_payload_unavailable');
-          if (!stillTargetCurrent()) return unavailable('terminal_target_replaced');
+          if (!stillTargetCurrent()) {
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
+            return unavailable('terminal_target_replaced');
+          }
           const permit = Object.freeze({});
           const permitState = { admissionHandle, committed, target: committed.target, parent, deliveryCurrent,
             text, payload, active: true, phase: 'text', pending: null };
@@ -174,12 +225,18 @@ function createRootDeliveryRuntime(deps = {}) {
             delivered = await deliverTerminal({ permit, target: committed.target, sessionId: parent.sessionId,
               text, submissionId: parent.receiptId, source: intent.source,
               attachments: intent.attachments });
-          } catch { return { ok: false, error: 'root_delivery_failed', retryable: false }; }
+          } catch {
+            report('delivery_dispatch', 'root_delivery_dispatch_failed');
+            return { ok: false, error: 'root_delivery_failed', retryable: false };
+          }
           if (!deliveryCurrent()) return unavailable('root_delivery_expired');
           return cleanDeliveryResult(delivered);
         },
       });
-    } catch { result = unavailable('remote_command_unresolved'); }
+    } catch {
+      report('delivery_dispatch', 'root_delivery_dispatch_failed');
+      result = unavailable('remote_command_unresolved');
+    }
     finally {
       if (issuedPermit) retirePermit(issuedPermit);
     }

package/template/coding-task-manager/lib/root-delivery-selection.js

@@ -16,6 +16,21 @@ const AUTOMATIC_BLOCKERS = new Set([
 ]);
 const AUTO_LIMIT = 5;
 const AUTO_AGE_MS = 30 * 60 * 1000;
+// A parent row that reached one of these statuses is itself the recorded proof
+// that the prompt reached the terminal (see prompt-submission-contract's
+// TERMINAL_STATUS_MAP). Nothing to recover: the client is told "sent".
+const SENT_PARENT_STATUSES = new Set([
+  'sent', 'accepted_by_terminal', 'durable_user_message_seen', 'response_started', 'queued_by_agent',
+]);
+
+// WP-0 (queue-delivery-recovery): the ONLY three verdicts the recovery classifier
+// may return. `recoveryAction` is the action a client should offer; `deliveryState`
+// is what CTM can prove about the prompt. Each is a frozen singleton so a caller can
+// never mutate a verdict, and none carries a permit, proof, or receipt id -- this
+// classifier never grants delivery authority.
+const RECOVERY_SENT = Object.freeze({ recoveryAction: 'none', deliveryState: 'sent' });
+const RECOVERY_NOT_STARTED = Object.freeze({ recoveryAction: 'resend', deliveryState: 'not_started' });
+const RECOVERY_UNKNOWN = Object.freeze({ recoveryAction: 'review', deliveryState: 'unknown' });
 
 function unavailable() {
   return Object.freeze({ ok: false, code: 'root_job_unavailable', retryable: false });
@@ -119,4 +134,25 @@ function selectRootDeliveryAttempt(snapshot, { automatic = false, nowMs = Date.n
   });
 }
 
-module.exports = { selectRootDeliveryAttempt };
+// Truthful recovery classification for a parent whose local delivery job is gone
+// (process restart, replayed id, lost registry). It answers one question only:
+// may the user resend the SAME text, or must a human review first?
+//
+//   confirmed sent parent status                     -> sent / none
+//   valid no-child or valid certified no-effect child -> not_started / resend
+//   everything else (invalid, read-failed, reserved,
+//   unknown, ambiguous, exhausted)                    -> unknown / review
+//
+// `sent` requires the durable parent row itself to say so. A proven no-child
+// snapshot (`latest: null`) and a certified preflight_no_effect child both permit
+// `resend`; a snapshot whose `latest` field is absent or malformed proves nothing
+// and stays `review`.
+function selectRootDeliveryRecovery(snapshot) {
+  const parent = validParent(snapshot);
+  if (!parent) return RECOVERY_UNKNOWN;
+  if (SENT_PARENT_STATUSES.has(parent.status)) return RECOVERY_SENT;
+  const selected = selectRootDeliveryAttempt(snapshot, { automatic: false });
+  return selected?.ok === true ? RECOVERY_NOT_STARTED : RECOVERY_UNKNOWN;
+}
+
+module.exports = { selectRootDeliveryAttempt, selectRootDeliveryRecovery };

package/template/coding-task-manager/lib/root-prompt-admission.js

@@ -315,6 +315,7 @@ function createRootPromptAdmission(deps = {}) {
     });
     const expected = Object.freeze({ ...expectedJob });
     let metadata = null;
+    let metadataReadDiagnostic = null;
     try {
       if (currentIdentity(getDb, getInstanceId, originalDb, instanceId)) {
         const candidate = await promptAdmissionTrace.time('metadata.read', () => readAcceptedMetadata(selector));
@@ -322,8 +323,38 @@ function createRootPromptAdmission(deps = {}) {
           metadata = validateMetadata(candidate, selector, expected);
         }
       }
-    } catch { metadata = null; }
-    if (!metadata) return { response, admission: null };
+    } catch (error) {
+      metadata = null;
+      metadataReadDiagnostic = canonicalReadError(error, originalDb);
+    }
+    if (!metadata) {
+      // WP-0 criterion 5: this admission dispatched a FRESH parent and confirmed
+      // its durable record, but the bounded metadata read did not reproduce the
+      // committed descriptor. That is a typed handoff failure -- the caller must
+      // never see the cached acceptance without a committed in-memory handle. The
+      // committed historical record is left untouched: no permission is recreated
+      // from the database, and nothing is written back. A plain cached replay
+      // never reaches here (it does not dispatch), so it is not mislabelled.
+      if (didDispatch && confirmed && expectedJob) {
+        reportDiagnosticSafely(reportDiagnostic, {
+          phase: 'admission_metadata',
+          code: 'root_admission_metadata_unavailable',
+          ...(metadataReadDiagnostic ? {
+            errorKind: metadataReadDiagnostic.errorKind,
+            nativeHandleOpen: metadataReadDiagnostic.nativeHandleOpen,
+            nativeHandleClosed: metadataReadDiagnostic.nativeHandleClosed,
+            ...(metadataReadDiagnostic.failureClass ? { failureClass: metadataReadDiagnostic.failureClass } : {}),
+            ...(metadataReadDiagnostic.sourceFile ? { sourceFile: metadataReadDiagnostic.sourceFile } : {}),
+            ...(metadataReadDiagnostic.sourceLine ? { sourceLine: metadataReadDiagnostic.sourceLine } : {}),
+          } : {}),
+        });
+        return { response: { ...blocked('root_admission_metadata_unavailable', 503),
+          recoveryAction: 'resend',
+          message: 'CTM saved your prompt but could not start delivery. Resend to try again.',
+        }, admission: null };
+      }
+      return { response, admission: null };
+    }
     const handle = Object.freeze({});
     const record = Object.freeze({
       selector, metadata, intentHandle, target: target || null,