create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/hosted-input-dispatch.js

@@ -0,0 +1,203 @@
+'use strict';
+
+// A1 (override-preserving dispatch observation): the ONE leaf every hosted input frame
+// travels through when it is put on a wire. These helpers DO perform that existing wire leaf --
+// they are the real dispatch, not a bystander -- but they add NO independent or parallel route, no
+// override bypass, no no-post witness and no durable/protocol authority. The frozen
+// {posted, disposition} result is DATA: an uncertain route is never reported as proof, and a
+// caller's legacy Boolean is never upgraded by a guess.
+//
+// Scope model -- two PRIVATE WeakMaps, read and written only here:
+//   _adapterScopes  adapter  -> the collector for ONE observeAdapterWrite invocation
+//   _messageScopes  message  -> the collector of the invocation that built that frame
+// The message binding is what carries one observation across the EXISTING routing seams -- a
+// selected `write` override, a selected `_post` override, the manager's pooled COPY of the
+// frame, and a selected `_postToPool` override -- so no parallel dispatch path is added and
+// an uninstrumented override still wins (it simply leaves the invocation uncertain).
+//
+// Requires ONLY the encoder on purpose: the session-host manager requires this module, so
+// requiring it back would be a cycle.
+const { encodeFrame } = require('./host-control-protocol');
+
+// Fixed vocabulary, ordered by join rank. A later refusal must not erase an endpoint that was
+// entered, and a later success must not launder an earlier uncertainty of the SAME invocation;
+// a genuinely separate successful dispatch is simply observed as its own asserted result.
+const PREFLIGHT_REFUSED = 'preflight-refused';
+const DISPATCH_ASSERTED = 'dispatch-asserted';
+const DISPATCH_UNCERTAIN = 'dispatch-uncertain';
+const JOIN_RANK = new Map([[PREFLIGHT_REFUSED, 1], [DISPATCH_ASSERTED, 2], [DISPATCH_UNCERTAIN, 3]]);
+
+const _adapterScopes = new WeakMap();
+const _messageScopes = new WeakMap();
+
+function _observation(posted, disposition) {
+  return Object.freeze({ posted: posted === true, disposition });
+}
+
+function _createCollector() {
+  let disposition = '';
+  return {
+    record(next) {
+      if ((JOIN_RANK.get(next) || 0) > (JOIN_RANK.get(disposition) || 0)) disposition = next;
+    },
+    disposition() { return disposition; },
+  };
+}
+
+function _collectorFor(message) {
+  return message && typeof message === 'object' ? _messageScopes.get(message) || null : null;
+}
+
+// Record one leaf outcome in the exact frame collector, if this frame is inside an observed
+// invocation at all. Outside one, this is a no-op: observation never creates state of its own.
+function _record(message, disposition) {
+  const collector = _collectorFor(message);
+  if (collector) collector.record(disposition);
+}
+
+// A refusal is a fact about THIS call taking no transport action; it is recorded so a later
+// successful dispatch of the same invocation can still be joined above it. `posted` is explicit
+// per leaf: only the SELECTED SOCKET inner refusal keeps the legacy `true` (the pre-observation
+// owner returned true even when its inner write did nothing); an absent/disconnected IPC child is
+// `false`, exactly as the legacy `return false` it replaces.
+function _refuse(message, posted) {
+  _record(message, PREFLIGHT_REFUSED);
+  return _observation(posted, PREFLIGHT_REFUSED);
+}
+
+// Note that an EXPLICIT no-transport preflight branch refused to dispatch this frame at all
+// (missing/disconnected transport, closed adapter/pool, absent manager). Call it only from such a
+// preflighted refusal branch -- never from an arbitrary branch after a dispatch was attempted,
+// where the honest record is uncertainty, not a refusal that would understate what happened.
+function notePostRefusal(message) {
+  _record(message, PREFLIGHT_REFUSED);
+}
+
+// The ONE socket leaf. The legacy boundary swallowed an encoding/write failure and reported the
+// frame as posted, so that result is preserved -- the failure is recorded as uncertainty instead
+// (never a new host-error, never fabricated as asserted). The caller owns the `destroyed`
+// preflight it has always owned; a connection that dies between the two checks refuses here.
+function postSocketFrameObserved(conn, message) {
+  if (!conn || conn.destroyed) return _refuse(message, true);
+  let outcome = DISPATCH_ASSERTED;
+  try {
+    conn.write(encodeFrame(message));
+  } catch {
+    outcome = DISPATCH_UNCERTAIN; // expected: the connection may already be gone
+  }
+  _record(message, outcome);
+  return _observation(true, outcome);
+}
+
+// The ONE IPC leaf. A normal return -- including the false a full send backlog produces -- is a
+// completed dispatch of this frame and is asserted; only a thrown send is uncertain, and it is
+// recorded BEFORE the original error callback runs, so a throwing callback cannot lose it.
+function postIpcFrameObserved(child, message, onError) {
+  if (!child || !child.connected) return _refuse(message, false);
+  try {
+    child.send(message);
+  } catch (err) {
+    _record(message, DISPATCH_UNCERTAIN);
+    if (typeof onError === 'function') onError(err);
+    return _observation(false, DISPATCH_UNCERTAIN);
+  }
+  _record(message, DISPATCH_ASSERTED);
+  return _observation(true, DISPATCH_ASSERTED);
+}
+
+// The WHOLE selected-socket boundary, extracted rather than re-implemented. The caller keeps its
+// own selection check exactly where it was (that `destroyed` read is lookup #1); the connection
+// thunk is evaluated INSIDE this try, so lookup #2 happens in the leaf. This catch is for failures
+// that ESCAPE the inner helper -- the connection lookup/preflight itself -- which become one
+// uncertainty record on the exact frame, the original error callback, and the legacy `false`
+// only if that callback returns. An encoding or write exception is NOT an outer failure: the
+// inner helper swallows it and returns `true`/`dispatch-uncertain` with no host-error, so this
+// boundary never converts it into a `false`. A throwing callback propagates; it is never swallowed.
+// The `true` return is the legacy result of a selected socket dispatch that completed, or of a leaf
+// refusal that never touched the wire.
+function postSelectedSocket(getConnection, message, onError) {
+  try {
+    postSocketFrameObserved(getConnection(), message);
+    return true;
+  } catch (error) {
+    _record(message, DISPATCH_UNCERTAIN);
+    if (typeof onError === 'function') onError(error);
+    return false;
+  }
+}
+
+// Run the ACTUAL selected `_post` for a frame built by the selected `write`, associating the
+// frame with this invocation's collector while it runs. The raw callback result is returned
+// unchanged so the legacy `=== true` Boolean keeps its exact meaning.
+function withAdapterPostObservation(adapter, message, invoke) {
+  const collector = _adapterScopes.get(adapter);
+  if (!collector || !message || typeof message !== 'object') return invoke();
+  const previous = _messageScopes.get(message);
+  _messageScopes.set(message, collector);
+  try {
+    return invoke();
+  } finally {
+    if (previous === undefined) _messageScopes.delete(message);
+    else _messageScopes.set(message, previous);
+  }
+}
+
+// Carry the source frame's collector onto the COPY the selected `_post` hands to `_postToPool`,
+// for the synchronous actual `_postToPool` callback only. The previous binding is restored even
+// when that callback throws, so a nested forwarded scope cannot leak into a later dispatch.
+function forwardPostObservation(sourceMessage, forwardedMessage, invoke) {
+  const collector = _collectorFor(sourceMessage);
+  if (!collector || !forwardedMessage || typeof forwardedMessage !== 'object') return invoke();
+  const previous = _messageScopes.get(forwardedMessage);
+  _messageScopes.set(forwardedMessage, collector);
+  try {
+    return invoke();
+  } finally {
+    if (previous === undefined) _messageScopes.delete(forwardedMessage);
+    else _messageScopes.set(forwardedMessage, previous);
+  }
+}
+
+// Observe ONE actual dispatch through the ACTUAL selected writer -- `write` here is whatever the
+// caller selected, never a prototype bypass. Nested/reentrant calls see their own scope restored
+// on the way out, and a throw from the selected writer propagates with every binding cleaned.
+function observeAdapterWrite(adapter, invoke) {
+  const previous = _adapterScopes.get(adapter);
+  const collector = _createCollector();
+  _adapterScopes.set(adapter, collector);
+  try {
+    const result = invoke();
+    return _observation(result !== false, collector.disposition() || DISPATCH_UNCERTAIN);
+  } finally {
+    if (previous === undefined) _adapterScopes.delete(adapter);
+    else _adapterScopes.set(adapter, previous);
+  }
+}
+
+// Observe a write to a PTY-like object. An instrumented handle reports its own real route; a
+// malformed report is NEVER retried and never trusted -- it is frozen false/uncertain, because
+// this leaf has no transport of its own to check. An opaque handle keeps its exact legacy result
+// (`!== false`) and is ALWAYS uncertain: a normal return proves only that write() returned. An
+// invalid/unavailable opaque writer is NOT swallowed into a fabricated refusal -- the original
+// TypeError propagates, because the caller already owns its own missing-PTY preflight.
+function observePtyWrite(pty, data, meta) {
+  if (typeof pty?.writeObserved === 'function') {
+    const observed = pty.writeObserved(data, meta);
+    if (observed && typeof observed.posted === 'boolean' && JOIN_RANK.has(observed.disposition)) {
+      return _observation(observed.posted, observed.disposition);
+    }
+    return _observation(false, DISPATCH_UNCERTAIN);
+  }
+  return _observation(pty.write(data, meta) !== false, DISPATCH_UNCERTAIN);
+}
+
+module.exports = {
+  postSocketFrameObserved,
+  postIpcFrameObserved,
+  postSelectedSocket,
+  notePostRefusal,
+  withAdapterPostObservation,
+  forwardPostObservation,
+  observeAdapterWrite,
+  observePtyWrite,
+};

package/template/coding-task-manager/lib/hosted-sync-worker.js

@@ -3,6 +3,9 @@
 const crypto = require('crypto');
 const { dispatchOwnerMutation } = require('./owner-mutation-disposition');
 const { MAX_BATCH_BYTES, jsonByteLength, batchEntriesByBytes } = require('./sync-push');
+// WP-0 (remote-machine-hub-sessions-2026-10-22.html D-4): the machine registry's liveness probe
+// rides THIS tick rather than owning a timer, so the hub keeps exactly one outbound cadence.
+const machineRegistry = require('./machine-registry');
 
 const DEFAULT_INTERVAL_MS = 15000;
 const DEFAULT_GAP_BACKOFF_MS = 5 * 60 * 1000;
@@ -32,6 +35,24 @@ function _authHeaders(env) {
   };
 }
 
+// The machine probe's credential (lib/machine-registry.js): the same headers as a sync leg, or
+// none when this host has no peer token configured (a same-host box answers over loopback).
+//
+// S-12 / P-8: this is only the FALLBACK now. A pool member must dial a pool member with the shared
+// pool secret and a legacy env-token box with the env bearer, and that split needs the target's
+// instance id — which is why the caller injects `peerHeadersFor(instanceId)`. It is injected and not
+// required here because lib/remote-machine-create.js (which owns buildPeerControlHeaders) requires
+// THIS module for parseSyncPeers: requiring it back would close a lib/** cycle (dependency-lint
+// ceiling 0).
+function _probeHeaders(env = process.env) {
+  try {
+    return _authHeaders(env);
+  } catch {
+    // expected: no peer token configured — the probe goes out without a credential.
+    return {};
+  }
+}
+
 function _parsePeerTokenMap(raw = '') {
   const value = _string(raw, 10000);
   const map = new Map();
@@ -695,15 +716,91 @@ function _failureDelayMs(env, options, intervalMs, attempt) {
   return Math.min(max, exp + jitter);
 }
 
+// WP-0 (remote-machine-hub-sessions-2026-10-22.html §8): the machine-registry sweep, plus the WP-6
+// live-catalog refresh riding it. Shared by the sync tick and the machines-only loop below; a
+// probe failure is reported, never thrown, and never folded into a sync verdict.
+async function _sweepMachines({ db, fetchImpl, env, peerHeadersFor, selfInstanceId }) {
+  try {
+    const machineProbe = await machineRegistry.probeMachinesOnce({ fetchImpl }, {
+      db,
+      // P-8: the per-target credential the server injects (pool secret vs env bearer). The fixed
+      // env-token object stays as the fallback for a caller that has not been wired yet.
+      ...(typeof peerHeadersFor === 'function' ? { peerHeadersFor } : { peerHeaders: _probeHeaders(env) }),
+      // P-5: this machine's own id, so the roster pull never writes its own row. Injected by
+      // server.js (which owns the identity accessor) — requiring it here would close a lib/** cycle.
+      ...(selfInstanceId ? { selfInstanceId } : {}),
+    });
+    // WP-6 (AC-6a): deliberately NOT awaited — the catalog talks to the boxes' WS links (a dial
+    // plus a reply), and the tick's cadence must not be held hostage by a slow box. A machine the
+    // sweep judged unreachable keeps its previous catalog, which degrades its rows to the
+    // sync-mirror look.
+    try {
+      require('./remote-machine-catalog').refreshAll({ db }).catch(() => { /* expected: refreshAll resolves its own per-machine failures */ });
+    } catch { /* expected: a catalog fault must never fail a machine probe sweep */ }
+    return machineProbe;
+  } catch (probeErr) {
+    // REPORT: surfaced as status().machines / lastResult.machineProbe; the next tick retries.
+    return { ok: false, error: probeErr.message || String(probeErr) };
+  }
+}
+
+// A hub may register machines (Settings -> Machines) without configuring any sync peer: the box
+// authorises it through the peer TOKEN map alone. Sync stays off (`started:false`, the status
+// surfaces read that as "sync off"), but the registered machines are still probed on the same
+// cadence — otherwise a machine's health would freeze at whatever registration recorded and a
+// stopped box would read "reachable" forever. Zero registered machines => zero fetches (AC-0d).
+function _startMachinesOnlyLoop({ db, fetchImpl, intervalMs, env, peerHeadersFor, selfInstanceId }) {
+  let running = false;
+  let stopped = false;
+  let machineProbe = null;
+  const tick = async () => {
+    if (running || stopped) return;
+    running = true;
+    try {
+      machineProbe = await _sweepMachines({ db, fetchImpl, env, peerHeadersFor, selfInstanceId });
+    } finally {
+      running = false;
+    }
+  };
+  const timer = setInterval(tick, intervalMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  tick();
+  return {
+    started: false,
+    reason: 'no_peers',
+    peers: [],
+    intervalMs,
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+    },
+    status() {
+      return { started: false, reason: 'no_peers', intervalMs, machines: machineProbe };
+    },
+  };
+}
+
 function startHostedSyncWorker(options = {}) {
   const env = options.env || process.env;
-  // R-12: "peers configured" is the gate (there is no separate enable flag any more).
-  if (!syncEnabledByConfig(env)) return { started: false, reason: 'no_peers' };
-  const peers = options.peers || parseSyncPeers(env);
-  if (!peers.length) return { started: false, reason: 'no_peers' };
   const db = options.db;
   const fetchImpl = options.fetch || global.fetch;
   const intervalMs = Math.max(1000, Number(env.CTM_SYNC_POLL_INTERVAL_MS || options.intervalMs || DEFAULT_INTERVAL_MS) || DEFAULT_INTERVAL_MS);
+  // R-12: "peers configured" is the gate (there is no separate enable flag any more).
+  if (!syncEnabledByConfig(env)) return _startMachinesOnlyLoop({ db, fetchImpl, intervalMs, env, peerHeadersFor: options.peerHeadersFor, selfInstanceId: options.selfInstanceId });
+  const peers = options.peers || parseSyncPeers(env);
+  if (!peers.length) return _startMachinesOnlyLoop({ db, fetchImpl, intervalMs, env, peerHeadersFor: options.peerHeadersFor, selfInstanceId: options.selfInstanceId });
+  // WP-0 (§8 "seed-from-CTM_SYNC_PEERS"): this worker starts exactly once per boot, which makes
+  // it the hub's seeding hook. Every configured peer that is not yet in the registry becomes a
+  // DISABLED machines row — env is a seed, never an authority, so nothing is auto-enabled or
+  // auto-probed (D-11: no flag, no auto-enable). Idempotent: a restart re-seeds nothing.
+  let machineSeed = null;
+  try {
+    machineSeed = machineRegistry.seedMachinesFromSyncPeers({ db, env, peers });
+  } catch (seedErr) {
+    // REPORT: surfaced as status().machineSeed; an unseeded machine is a missing card, not a
+    // failed boot, and the next boot retries.
+    machineSeed = { seeded: 0, skipped: 0, error: seedErr.message || String(seedErr) };
+  }
   let running = false;
   let stopped = false;
   let lastResult = null;
@@ -725,6 +822,9 @@ function startHostedSyncWorker(options = {}) {
   };
   // Follow-up #17: the last local outbox prune (null until one is attempted).
   let brainPrune = null;
+  // WP-0: the last machine-registry sweep (null until one is attempted). Reported, never folded
+  // into the sync verdict.
+  let machineProbe = null;
   const tick = async () => {
     if (running || stopped) return;
     running = true;
@@ -818,7 +918,13 @@ function startHostedSyncWorker(options = {}) {
         }
         brainPrune = { ...pruneReport, lastAttemptAt: new Date().toISOString() };
       }
-      lastResult = { ok: results.every((r) => r.ok !== false), checkedAt: new Date().toISOString(), results, brainPrune: pruneReport };
+      // WP-0 (remote-machine-hub-sessions-2026-10-22.html §8): the machine-registry sweep rides
+      // this tick, AFTER the peer legs and independent of them — it shares the cadence (D-4) but
+      // not the verdict, so a probe failure never marks a sync leg failed. Zero registered
+      // machines ⇒ zero fetches (AC-0d), so an instance with no machines performs no extra
+      // network work per tick.
+      machineProbe = await _sweepMachines({ db, fetchImpl, env, peerHeadersFor: options.peerHeadersFor, selfInstanceId: options.selfInstanceId });
+      lastResult = { ok: results.every((r) => r.ok !== false), checkedAt: new Date().toISOString(), results, brainPrune: pruneReport, machineProbe };
     } catch (err) {
       lastResult = { ok: false, checkedAt: new Date().toISOString(), error: err.message || String(err) };
     } finally {
@@ -846,6 +952,8 @@ function startHostedSyncWorker(options = {}) {
         push: [...pushState.values()],
         brain: [...brainState.values()],
         brainPrune,
+        machines: machineProbe,
+        machineSeed,
       };
     },
   };

package/template/coding-task-manager/lib/instance-id-ownership-manifest.js

@@ -120,6 +120,10 @@ const INSTANCE_ID_COLUMN_MANIFEST = [
   },
 
   // --- live-peer: peer-sync owned, deliberately out of scope for local restamping ---
+  {
+    table: 'machines', column: 'instance_id', classification: 'live-peer',
+    note: 'WP-0 remote-machine-hub (docs/remote-machine-hub-sessions-2026-10-22.html D-3): the REMOTE box\'s minted identity, pinned from its GET /api/sync/manifest at registration. It names another machine, never this one — a local re-mint changes nothing about which box the row points at, so restamping it would corrupt the pin.',
+  },
   {
     table: 'sync_outbox', column: 'source_instance_id', classification: 'live-peer',
     note: 'Peer sync bookkeeping. Restamping locally could trigger re-delivery storms on the peer side. Deferred per S-14/S-15.',

package/template/coding-task-manager/lib/instance-manifest-runtime.js

@@ -68,6 +68,9 @@ function buildServerInstanceManifest(options = {}) {
     backupStatus,
     port: options.port,
     wallePort: options.wallePort,
+    // WP-2a D-4: the machine-owned settings cache (lib/machine-self.js) rides through to the pure
+    // builder, which reads it and never the DB. `options.machineSelf` is `current()` from server.js.
+    machineSelf: options.machineSelf,
     pid: options.pid,
     uptimeSeconds: options.uptimeSeconds,
     walleStatus: options.walleStatus,

package/template/coding-task-manager/lib/instance-manifest.js

@@ -102,7 +102,13 @@ function buildInstanceManifest(options = {}) {
     EXECUTION_HOST_KINDS,
     'local'
   );
-  const displayName = _limitedString(
+  // WP-2a (machine-pool-picker-pairing-dashboard-2026-10-24.html §5 D-4 rev 2, §9 S-25): the
+  // machine-owned settings, passed IN through `options.machineSelf` (lib/machine-self.js's cache) so
+  // the builder stays pure and never reads the DB. A non-empty displayName overrides the env/default
+  // name; favorite/hidden ride the manifest as booleans so every primary reads the same values.
+  const machineSelf = options.machineSelf && typeof options.machineSelf === 'object' ? options.machineSelf : null;
+  const selfDisplayName = _limitedString(machineSelf && machineSelf.displayName, '');
+  const displayName = selfDisplayName || _limitedString(
     env.CTM_EXECUTION_HOST_DISPLAY_NAME || env.CTM_INSTANCE_DISPLAY_NAME,
     executionHostKind === 'hosted' ? hostname : 'Local CTM'
   );
@@ -158,8 +164,14 @@ function buildInstanceManifest(options = {}) {
     executionHost: {
       kind: executionHostKind,
       displayName,
+      // D-4 rev 2: machine-owned booleans. `favorite` is the picker star; `hidden` is "hide from
+      // picker". NEVER `pinned` — that word already means the identity pin (lib/machine-registry.js).
+      favorite: !!(machineSelf && machineSelf.favorite),
+      hidden: !!(machineSelf && machineSelf.hidden),
       hostname,
       os: _platform(options, env),
+      // Machine pool D-2/D-10: os/arch name the box in the picker search and the Machines card.
+      arch: _limitedString(options.arch || process.arch || '', ''),
       hostLabel: _limitedString(env.CTM_SERVER_HOST_LABEL || env.CTM_HOST_LABEL, ''),
       bindHost: host,
       publicOrigin: _limitedString(

package/template/coding-task-manager/lib/instance-sync-status.js

@@ -76,6 +76,8 @@ function buildInstanceSyncStatus(options = {}) {
   const hasDurableSyncSchema = _phaseEnabledBySchema(hybridEnabled, hasOwnership, hasOutbox);
   const outboxStats = schema.outbox || {};
   const worker = schema.worker || {};
+  // S-30: supplied by the caller (see the `machines` key in the return below).
+  const machinesInput = options.machines && typeof options.machines === 'object' ? options.machines : {};
 
   const warnings = [];
   if (mode !== 'none' && !hybridEnabled) warnings.push('sync_mode_configured_but_hybrid_sync_disabled');
@@ -141,6 +143,19 @@ function buildInstanceSyncStatus(options = {}) {
       brain: Array.isArray(worker.brain) ? worker.brain : [],
       brainPrune: worker.brainPrune && typeof worker.brainPrune === 'object' ? worker.brainPrune : null,
     },
+    // S-30 (WP-0, remote-machine-hub-sessions-2026-10-22.html): the machine registry's rollup —
+    // how many boxes this hub knows and where they stand. The CALLER supplies it
+    // (options.machines, built by lib/machine-registry.js summarizeMachines) because this builder
+    // is pure: it opens no handle and probes nothing. Absent input reads as "no machines known",
+    // which is the truth for a hub with no registry rows.
+    machines: {
+      count: Number(machinesInput.count || 0) || 0,
+      reachable: Number(machinesInput.reachable || 0) || 0,
+      unknown: Number(machinesInput.unknown || 0) || 0,
+      unreachable: Number(machinesInput.unreachable || 0) || 0,
+      unhealthy: Number(machinesInput.unhealthy || 0) || 0,
+      hubNetworkSuspect: machinesInput.hubNetworkSuspect === true,
+    },
     exchange: {
       workspaceBindingsReady: !!workspaceBindings.enabled,
       workspaceBindingCount: Array.isArray(workspaceBindings.bindings) ? workspaceBindings.bindings.length : 0,

package/template/coding-task-manager/lib/launch-model-override.js

@@ -19,6 +19,10 @@
 //
 // Pure: never mutates `args`, never reads the DB or the environment.
 
+const {
+  CLAUDE_OPTION_SIGNATURES, CLAUDE_SHORT_OPTIONS, locateClaudeSettingsArg,
+} = require('./native-lead-settings-argv');
+
 const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:/@+\-[\]]*$/;
 const MAX_MODEL_ID_LENGTH = 200;
 
@@ -204,6 +208,160 @@ function ensureCodexResumeTarget(argv, providerThreadId) {
   return { ok: true, args };
 }
 
+// --- Claude native same-thread resume normalization (D-2) ----------------------------------------
+// docs/claude-routed-native-history-resume-2026-10-24.html §5 D-2, §6. A Claude lead whose model or
+// route changes continues the SAME native thread: the canonical source owner's provider thread is
+// the authority, never a stale startup/parent selector in the recorded argv. This normalizer turns
+// every conversation selector the installed CLI accepts (`--resume`/`-r`, `--continue`/`-c`,
+// `--session-id`, `--from-pr`) into exactly one explicit `--resume <canonical>` placed FIRST, drops a
+// fork (which would mint a different identity), and removes the original positional startup prompt so
+// it cannot execute a second time. Every other option keeps its token and its operand boundary.
+//
+// Pure: no fs, no clock, never mutates `argv`, never reads a file, never changes model/auth.
+const CLAUDE_THREAD_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const CLAUDE_LONG_ARITY = new Map(CLAUDE_OPTION_SIGNATURES);
+// Every option token that SELECTS which conversation the CLI opens, including the ones that would
+// start a DIFFERENT one. Each is replaced by the canonical owner's own explicit resume: an old
+// `--session-id` would START that id again (colliding with the recorded transcript), `--continue`/`-c`
+// would not even name a thread, and `--from-pr` names a conversation that is not this one at all.
+const CLAUDE_CONVERSATION_SELECTORS = new Set(['--resume', '--session-id', '--continue', '--from-pr']);
+const CLAUDE_CONVERSATION_SELECTOR_SHORTS = new Set(['r', 'c']);
+// A recorded thread is continued IN PLACE: a fork would mint a new session identity, which is not what
+// this operation does, so it is dropped. `--replay-user-messages` is deliberately NOT here -- it only
+// changes how output is streamed and names no conversation identity, so it is preserved untouched.
+const CLAUDE_FORK_MODIFIERS = new Set(['--fork-session']);
+
+// Commander's own option-likeness rule: a lone `-` is an OPERAND, `--` is the terminator.
+function _isClaudeOptionLike(token) {
+  return typeof token === 'string' && token.length > 1 && token[0] === '-';
+}
+
+// One pass over an installed-CLI Claude argv, modelling Commander's operand consumption exactly
+// (`combineFlagAndOptionalValue` = true, so a short option's attached remainder is its value; a
+// required operand is consumed unconditionally; an optional one only when the next token is not
+// option-like; a variadic one takes its first operand plus every following non-option token). An
+// operand that merely SPELLS `--resume`/`--session-id` is therefore never read as a selector.
+//
+// Selector tokens are dropped and every OTHER token is returned untouched, in its original order, with
+// its own operand. A mixed short cluster keeps its non-selector members (rebuilt, with any attached
+// value) instead of losing flags: `-pc` becomes `-p`, `-cd value` becomes `-d value`, `-dp` is left
+// alone (`d` takes `p` as its value, so there is no selector in it at all).
+function _claudeResumeKeptTokens(args) {
+  const kept = [];
+  let index = 0;
+  while (index < args.length) {
+    const token = String(args[index]);
+    // A real terminator: every remaining token is positional, i.e. this launch's own prompt.
+    if (token === '--') break;
+    if (token.startsWith('--') && token.length > 2) {
+      const equalsAt = token.indexOf('=');
+      const name = equalsAt === -1 ? token : token.slice(0, equalsAt);
+      const inlineValue = equalsAt === -1 ? null : token.slice(equalsAt + 1);
+      const arity = CLAUDE_LONG_ARITY.get(name);
+      if (!arity) return { ok: false };
+      if (arity === 'boolean') {
+        if (inlineValue !== null) return { ok: false };
+        if (!CLAUDE_CONVERSATION_SELECTORS.has(name) && !CLAUDE_FORK_MODIFIERS.has(name)) kept.push(args[index]);
+        index += 1;
+        continue;
+      }
+      let end = index + 1;
+      if (inlineValue === null) {
+        if (arity === 'required') {
+          if (index + 1 >= args.length) return { ok: false };
+          end = index + 2;
+        } else if (arity === 'optional') {
+          if (args[index + 1] !== undefined && !_isClaudeOptionLike(args[index + 1])) end = index + 2;
+        } else { // variadic
+          if (index + 1 >= args.length) return { ok: false };
+          end = index + 2;
+          while (end < args.length && args[end] !== '--' && !_isClaudeOptionLike(args[end])) end += 1;
+        }
+      }
+      if (!CLAUDE_CONVERSATION_SELECTORS.has(name)) for (let i = index; i < end; i += 1) kept.push(args[i]);
+      index = end;
+      continue;
+    }
+    if (token.startsWith('-') && token.length > 1) {
+      const cluster = token.slice(1);
+      let position = 0;
+      let consumed = 1;
+      let rebuilt = '';
+      let selector = false;
+      let keepsOperand = false;
+      while (position < cluster.length) {
+        const character = cluster[position];
+        const spec = CLAUDE_SHORT_OPTIONS[character];
+        if (!spec) return { ok: false };
+        const isSelector = CLAUDE_CONVERSATION_SELECTOR_SHORTS.has(character);
+        const arity = spec[1];
+        if (arity === 'boolean') {
+          if (isSelector) selector = true; else rebuilt += character;
+          position += 1;
+          continue;
+        }
+        // `optional`/`required`: the whole attached remainder is this option's value, so the cluster
+        // has no further members.
+        const attached = cluster.slice(position + 1);
+        if (attached) {
+          if (isSelector) selector = true; else rebuilt += character + attached;
+          break;
+        }
+        if (arity === 'required') {
+          if (index + 1 >= args.length) return { ok: false };
+          consumed = 2;
+        } else {
+          consumed = args[index + 1] !== undefined && !_isClaudeOptionLike(args[index + 1]) ? 2 : 1;
+        }
+        if (isSelector) selector = true; else { rebuilt += character; keepsOperand = consumed === 2; }
+        break;
+      }
+      if (selector) {
+        // The non-selector members survive; a non-selector member that consumed the next token keeps
+        // that operand too.
+        if (rebuilt) kept.push(`-${rebuilt}`);
+        if (keepsOperand) kept.push(args[index + 1]);
+        index += consumed;
+        continue;
+      }
+      for (let i = index; i < index + consumed; i += 1) kept.push(args[i]);
+      index += consumed;
+      continue;
+    }
+    index += 1; // a positional token is this launch's own startup prompt: it is never replayed
+  }
+  return { ok: true, kept };
+}
+
+/**
+ * Normalize an installed-CLI Claude argv to resume exactly the canonical source thread.
+ *
+ * @param {string[]} argv the recorded startup/restore arguments (never mutated)
+ * @param {string} providerThreadId the canonical source owner's provider thread (a UUID)
+ * @returns {{ok:true,args:string[]}|{ok:false,reason:string}}
+ *   `claude_resume_target_invalid` — no canonical UUID was supplied;
+ *   `claude_resume_argv_unsupported` — malformed/ambiguous argv, an unknown option, a subcommand, or
+ *   the two installed parsers disagreeing about an operand span.
+ */
+function ensureClaudeResumeTarget(argv, providerThreadId) {
+  const args = Array.isArray(argv) ? argv : null;
+  const threadId = String(providerThreadId == null ? '' : providerThreadId).trim();
+  if (!args || !CLAUDE_THREAD_ID_RE.test(threadId)) return { ok: false, reason: 'claude_resume_target_invalid' };
+  for (const token of args) if (typeof token !== 'string') return { ok: false, reason: 'claude_resume_argv_unsupported' };
+  // The EXISTING settings/source adapter is the agreed-parse guard: a subcommand launch, an unknown
+  // option, or the two installed parsers disagreeing about a `--settings`/`--setting-sources` span
+  // is refused here instead of being reinterpreted as a conversation selector.
+  try { locateClaudeSettingsArg(args); }
+  catch { return { ok: false, reason: 'claude_resume_argv_unsupported' }; }
+  const scanned = _claudeResumeKeptTokens(args);
+  if (!scanned.ok) return { ok: false, reason: 'claude_resume_argv_unsupported' };
+  // The canonical resume goes FIRST, ahead of every preserved option token. That is what makes the
+  // result readable by the EXISTING `indexOf('--resume')` extractor even when another option's own
+  // operand spells `--resume`/`--session-id` (e.g. `--append-system-prompt --resume`): the first
+  // `--resume` in the produced argv is always this launch's canonical thread.
+  return { ok: true, args: ['--resume', threadId, ...scanned.kept] };
+}
+
 // --- Lead-model pin replay (claude-resume-managed-model-pin-2026-10-16.html §6 D-4/D-7) -----------
 // A managed policy (`model=opusplan`) makes a plain `claude --resume` restart an Opus session on
 // Sonnet, so the model the user explicitly chose is stored per session (WP-0 storage, WP-1 native
@@ -324,4 +482,5 @@ function applyLaunchEffortOverride(argv, agent, effort) {
 }
 
 module.exports = { applyLaunchModelOverride, isValidOverrideModel, applyLaunchEffortOverride, isValidEffort,
-  applyLaunchModelPin, stripModelFlags, insertBeforeCodexResume, rebindCodexForkLaunchPlan, ensureCodexResumeTarget };
+  applyLaunchModelPin, stripModelFlags, insertBeforeCodexResume, rebindCodexForkLaunchPlan, ensureCodexResumeTarget,
+  ensureClaudeResumeTarget };