create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/fs-watcher-root-watch.js

@@ -0,0 +1,141 @@
+'use strict';
+/**
+ * WP-1 root-dir watch — design doc cross-machine-session-context-2026-10-31.html
+ * §1.3 C-6, §5 R-10/D-9, §8 WP-1, §9 S-4.
+ *
+ * The watcher watched each *project* directory but never a provider ROOT, so a brand-new
+ * project dir (a fresh worktree: ~/.claude/projects/<new-slug>/) stayed unreadable until the
+ * 60 s scan. This module owns the ONE extra non-recursive fs.watch per canonical root that
+ * closes that gap — a new dir is attached in ~one debounce window instead of a scan tick.
+ *
+ * Extracted out of lib/fs-watcher.js purely to keep that file inside its file-size ratchet
+ * (bin/file-size-lint.js). Behaviour is identical to the in-file version, including the
+ * per-layout rules, the symlink/containment refusals via the watcher's own
+ * `_warnRefusalOnce` + the caller's `isInside`, the error→reattach after `reattachDelayMs`,
+ * and the `closeHandles` contract. WP-3 (§9 S-5) moved the handle itself onto the caller's
+ * watch client (`watcher._watch`, the watch worker thread) so open/close never blocks the main
+ * loop; a sync attach failure now arrives as an `'error'` with `syncAttach` instead of a throw.
+ * The scan is untouched and stays the backstop: a dir
+ * created while this watch is closed/errored is still attached by `_scanAndWatchAsync`.
+ *
+ * createRootWatch(watcher, { isInside, reattachDelayMs }) →
+ *   { ensure(root), close(root), closeAll({ closeHandles }), handleChild(root, filename), handles,
+ *     events }
+ *
+ *   isInside        — the caller's canonical containment predicate (isInside in fs-watcher.js)
+ *   reattachDelayMs — the caller's REATTACH_DELAY_MS (same delay the per-dir watchers use)
+ *   watcher         — the JsonlWatcher this watch belongs to; this module reads `_stopped`
+ *                     and calls `emit`, `_warnRefusalOnce`, `_refreshRootAsync`,
+ *                     `_ensureWatchedDirAsync` and `_scanDatedRootStepsAsync` on it.
+ *   events          — read-only, monotonically increasing count of raw fs.watch callbacks
+ *                     (every event, before any filtering). It is the liveness probe for the
+ *                     tests: on macOS libuv keeps ONE FSEventStream per process and restarts it
+ *                     whenever a watcher is added or removed, so a test that wants to measure
+ *                     the root watch has to prove the stream is delivering — and proving it by
+ *                     attaching a probe directory would itself add a watcher and restart the
+ *                     stream. Reading this counter for a probe FILE under the root is watcher-free.
+ */
+const fs = require('fs');
+const path = require('path');
+
+function createRootWatch(watcher, { isInside, reattachDelayMs }) {
+  // root object → FSWatcher. Deliberately separate from the watcher's `_watchers`/
+  // `_watchedDirs`, so `watchedDirsSnapshot()`/`rootHealthSnapshot()` keep meaning
+  // "session dirs we read from".
+  const handles = new Map();
+  // Monotonic count of raw fs.watch callbacks, bumped BEFORE any filtering so it counts every
+  // event the OS stream delivered for any canonical root. Exposed read-only as `events`.
+  let events = 0;
+
+  function close(root) {
+    const handle = handles.get(root);
+    if (!handle) return;
+    handles.delete(root);
+    try { handle.close(); } catch { /* expected: the watcher may already be closed (its own 'error' handler) */ }
+  }
+
+  function ensure(root) {
+    if (watcher._stopped || !root.canonical || handles.has(root)) return;
+    // WP-3 §9 S-5: the handle comes from the caller's watch client (the watch worker), so its
+    // close() posts instead of blocking this loop on the libuv FSEvents semaphore.
+    const handle = watcher._watch(root.canonical, {}, (eventType, filename) => {
+      events += 1; // WP-1c: count first — the callback firing is the liveness signal itself.
+      if (!filename || watcher._stopped) return;
+      handleChild(root, filename).catch((e) => watcher.emit('error', e));
+    });
+    handle.on('error', (err) => {
+      // WP-3 §9 S-5: a sync attach failure (root vanished) now arrives here, not as a throw —
+      // report it with no reattach timer, exactly like the try/catch this replaced.
+      if (err && err.syncAttach) { watcher.emit('error', err); return; }
+      // Same shape as the per-dir watchers: drop the handle, then re-resolve the root (its
+      // canonical target may have moved while we were down) and reattach.
+      close(root);
+      if (watcher._stopped) return;
+      setTimeout(() => {
+        if (watcher._stopped) return;
+        watcher._refreshRootAsync(root).then(() => ensure(root)).catch((e) => watcher.emit('error', e));
+      }, reattachDelayMs);
+    });
+    handles.set(root, handle);
+  }
+
+  // A direct child of a canonical root appeared. Per layout (mirrors what `_scanTickSteps`
+  // derives for that layout — see `_scanProjectsRootStepsAsync`/`_scanDatedRootStepsAsync`):
+  //   - 'projects': attach it through the SAME path the scan and the fs.watch reattach use,
+  //     with the same watchKey/projectEntry (`entry`, prefixed by root name for non-claude
+  //     roots) and the same symlink + isInside containment refusals.
+  //   - 'dated': the immediate child of the root is a YEAR dir, never a leaf day dir, so
+  //     there is nothing to attach here; re-run the (idempotent) dated step for the root so
+  //     a brand-new year attaches its newest leaf dirs on this tick instead of 60 s later.
+  //     NOTE: a new day dir under an EXISTING year is not visible to a root watcher; it still
+  //     rides the 60 s scan.
+  //   - 'flat': the root itself is the watched dir and its *.jsonl files are already covered
+  //     by that per-dir watcher — a sub-directory is not a session location, so nothing to do
+  //     (and the non-directory early return above means no duplicate file events).
+  async function handleChild(root, filename) {
+    if (filename.includes(path.sep)) return; // direct children only
+    const child = path.join(root.canonical, filename);
+    let lstat;
+    try { lstat = await fs.promises.lstat(child); } catch { return; } // vanished again
+    if (lstat.isSymbolicLink()) {
+      watcher._warnRefusalOnce('project-symlink', child, `[jsonl-watcher] skipping symlinked project dir: ${filename}`);
+      return;
+    }
+    if (!lstat.isDirectory()) return;
+    let canonical;
+    try { canonical = await fs.promises.realpath(child); } catch { return; }
+    if (!isInside(root.canonical, canonical)) {
+      watcher._warnRefusalOnce('project-escape', canonical, `[jsonl-watcher] skipping project dir that escapes root: ${filename}`);
+      return;
+    }
+    if (root.layout === 'projects') {
+      const watchKey = root.name === 'claude' ? filename : `${root.name}:${filename}`;
+      await watcher._ensureWatchedDirAsync(root, child, watchKey, filename);
+    } else if (root.layout === 'dated' && /^\d{4}$/.test(filename)) {
+      // eslint-disable-next-line no-unused-vars
+      for await (const _step of watcher._scanDatedRootStepsAsync(root)) { /* no-op: drain without a tick budget */ }
+    }
+  }
+
+  // Rides the same closeHandles contract as the per-dir watchers: fast-exit callers leave the
+  // OS handles for the process to reclaim. The map is always cleared.
+  function closeAll({ closeHandles = true } = {}) {
+    if (closeHandles) {
+      for (const [root, handle] of handles) {
+        try { handle.close(); } catch (e) { console.error(`[jsonl-watcher] close error for root ${root.name}:`, e.message); }
+      }
+    }
+    handles.clear();
+  }
+
+  return {
+    ensure,
+    close,
+    closeAll,
+    handleChild,
+    handles,
+    get events() { return events; },
+  };
+}
+
+module.exports = { createRootWatch };

package/template/coding-task-manager/lib/fs-watcher.js

@@ -5,6 +5,8 @@ const EventEmitter = require('events');
 const { namedInterval, runSync, wrap } = require('./perf-tracker');
 const envFlags = require('./env-flags');
 const { isWritableOnlyByOwner } = require('../../shared/owner-write-safety');
+const { createRootWatch } = require('./fs-watcher-root-watch');
+const { getDefaultWatchClient } = require('./watch-worker-client');
 
 // Design doc mainloop-composer-freeze-2026-08-20.html §5 D-1, §6, §9 S-1/S-4. The 60s
 // scan tick and the attach/reattach directory walk ran completely unwrapped, so the
@@ -228,8 +230,12 @@ class JsonlWatcher extends EventEmitter {
     extraRoots = [],
     scanBudgetMs = DEFAULT_SCAN_BUDGET_MS,
     scanContinuationJitterMs = DEFAULT_SCAN_CONTINUATION_JITTER_MS,
+    watch = null,
   } = {}) {
     super();
+    // WP-3 (§5 D-4, §9 S-3): directory watchers are created in ONE worker thread
+    // (./watch-worker-client.js); `watch` is the injection seam (tests needing a real fs.watch).
+    this._watch = typeof watch === 'function' ? watch : getDefaultWatchClient().watch;
     this._rescanDirsPerTick = Math.max(1, Number(rescanDirsPerTick) || DEFAULT_RESCAN_DIRS_PER_TICK);
     this._rescanCursor = 0;
     // WP-1 async scan budget/continuation state (§9 S-1..S-4). `_scanBudgetMs` is
@@ -277,6 +283,7 @@ class JsonlWatcher extends EventEmitter {
         configuredPath: r.configuredPath || r.dir,
         enrolled: r.enrolled === true,
         allowRootSymlink: r.allowRootSymlink === true,
+        ensureDir: r.ensureDir === true, // a CTM-owned root its writer creates lazily (dsh): the scan tick mkdirs it
         dev: 0,
         ino: 0,
         validationStatus: r.validationStatus || 'missing',
@@ -288,6 +295,10 @@ class JsonlWatcher extends EventEmitter {
     ];
     this._watchers = new Map(); // watchKey → FSWatcher
     this._watchedDirs = new Map(); // watchKey → { dir, root, projectEntry }
+    // WP-1 root-dir watch: one extra fs.watch per canonical root (./fs-watcher-root-watch.js).
+    this._rootWatch = createRootWatch(this, { isInside, reattachDelayMs: REATTACH_DELAY_MS });
+    // WP-1b: watchKeys with an attach in flight — reserved before the first await (see below).
+    this._attaching = new Set();
     this._debounceTimers = new Map(); // filePath → timer
     this._knownFiles = new Map(); // filePath → { size, mtimeMs }
     this._refusalWarnings = new Set();
@@ -323,6 +334,7 @@ class JsonlWatcher extends EventEmitter {
   }
 
   _detachRoot(root, previousCanonical = root.canonical) {
+    this._rootWatch.close(root);
     for (const [watchKey, rec] of this._watchedDirs) {
       if (rec.root !== root) continue;
       const watcher = this._watchers.get(watchKey);
@@ -354,6 +366,7 @@ class JsonlWatcher extends EventEmitter {
       || previousDev !== root.dev
       || previousIno !== root.ino
     )) this._detachRoot(root, previousCanonical);
+    this._rootWatch.ensure(root); // WP-1: (re)attach the root-dir watcher for this canonical root
     return !!root.canonical;
   }
 
@@ -395,10 +408,10 @@ class JsonlWatcher extends EventEmitter {
   /**
    * Stop scanning and event delivery.
    * @param {{ closeHandles?: boolean }} [options]
-   *   closeHandles (default true): close every fs.watch handle.
-   *   false: leave the OS handles open for the process to reclaim at exit. ONLY for callers that
-   *   are about to exit the process (libuv fsevents.c:888: each close() blocks on a semaphore while
-   *   the shared FSEventStream is rebuilt; 417 closes took 41-360 s). _watchers/_watchedDirs are
+   *   closeHandles (default true): close every directory watch handle. WP-3 posts those closes to
+   *   the watch worker, so the libuv FSEvents semaphore wait no longer blocks this loop.
+   *   false: leave the OS handles open for the process to reclaim at exit. ONLY for callers about to
+   *   exit (each close rebuilds the shared FSEventStream; 417 closes took 41-360 s). The maps are
    *   still cleared so getKnownFiles()/introspection stay consistent.
    */
   stop({ closeHandles = true } = {}) {
@@ -412,6 +425,7 @@ class JsonlWatcher extends EventEmitter {
         try { watcher.close(); } catch (e) { console.error(`[jsonl-watcher] close error for ${entry}:`, e.message); }
       }
     }
+    this._rootWatch.closeAll({ closeHandles }); // WP-1 root watchers: same closeHandles contract
     this._watchers.clear();
     this._watchedDirs.clear();
   }
@@ -542,6 +556,7 @@ class JsonlWatcher extends EventEmitter {
       if (this._stopped) return;
       // Late canonicalization mirrors the sync path: a root whose directory
       // didn't exist at start() attaches on the first tick that sees it.
+      if (root.ensureDir && !root.canonical) await fs.promises.mkdir(root.dir, { recursive: true }).catch((e) => this.emit('error', e));
       const attached = await this._refreshRootAsync(root);
       if (!attached) {
         await this._refuseRootOnceAsync(root);
@@ -577,6 +592,7 @@ class JsonlWatcher extends EventEmitter {
       || previousDev !== root.dev
       || previousIno !== root.ino
     )) this._detachRoot(root, previousCanonical);
+    this._rootWatch.ensure(root); // WP-1: covers roots that appear/retarget after start()
     return !!root.canonical;
   }
 
@@ -712,28 +728,32 @@ class JsonlWatcher extends EventEmitter {
   // are NOT on the budgeted periodic path (the fs.watch reattach-on-error handler
   // below) drain it to completion via `_ensureWatchedDirAsync`.
   async *_ensureWatchedDirAsyncSteps(root, dir, watchKey, projectEntry) {
-    if (this._stopped || this._watchers.has(watchKey)) return;
-    const rec = { dir, root, projectEntry };
+    if (this._stopped || this._watchers.has(watchKey) || this._attaching.has(watchKey)) return;
+    this._attaching.add(watchKey); // reserve synchronously: the walk below awaits before fs.watch
+    try {
+      const rec = { dir, root, projectEntry };
 
-    // Reconcile against prior _knownFiles entries for this dir (fresh attach: none;
-    // reattach: catches files that appeared/grew/vanished while unwatched).
-    yield* this._attachWalkStepsAsync(dir, root, projectEntry);
+      // Reconcile against prior _knownFiles entries for this dir (fresh attach: none;
+      // reattach: catches files that appeared/grew/vanished while unwatched).
+      yield* this._attachWalkStepsAsync(dir, root, projectEntry);
 
-    // Set up fs.watch (non-recursive). Symlink checks happen in _handleFileEvent.
-    try {
+      // Set up the watcher (non-recursive). Symlink checks happen in _handleFileEvent.
       this._watchedDirs.set(watchKey, rec);
-      const watcher = fs.watch(dir, (eventType, filename) => {
+      const watcher = this._watch(dir, {}, (eventType, filename) => {
         if (!filename || this._stopped) return;
         if (!filename.endsWith('.jsonl') && !filename.endsWith('.jsonl.bak')) return;
         const filePath = path.join(dir, filename);
         this._debouncedHandle(filePath, dir, watchKey);
       });
 
-      watcher.on('error', () => {
-        // Reattach on error with delay — same delay/shape as the sync path, but
-        // resumes via the async attach so it never touches sync fs.
+      watcher.on('error', (err) => {
         this._watchers.delete(watchKey);
         this._watchedDirs.set(watchKey, rec);
+        // WP-3 §9 S-3: the sync attach throw (missing dir) is now this async 'error' — same shape
+        // as the catch it replaced: keep the dir recorded and report, with NO reattach timer.
+        if (err && err.syncAttach) { this.emit('error', err); return; }
+        // Reattach on error with delay — same delay/shape as the sync path, but
+        // resumes via the async attach so it never touches sync fs.
         try { watcher.close(); } catch { /* expected: the watcher already errored, close() may throw again harmlessly */ }
         if (!this._stopped) {
           setTimeout(() => {
@@ -743,9 +763,8 @@ class JsonlWatcher extends EventEmitter {
       });
 
       this._watchers.set(watchKey, watcher);
-    } catch (e) {
-      this._watchedDirs.set(watchKey, rec);
-      this.emit('error', e);
+    } finally {
+      this._attaching.delete(watchKey);
     }
   }
 
@@ -832,7 +851,7 @@ class JsonlWatcher extends EventEmitter {
   }
 
   _ensureWatchedDir(root, dir, watchKey, projectEntry) {
-    if (this._stopped || this._watchers.has(watchKey)) return;
+    if (this._stopped || this._watchers.has(watchKey) || this._attaching.has(watchKey)) return; // WP-1b: an async attach owns it
     const rec = { dir, root, projectEntry };
 
     // Reconcile against any prior _knownFiles entries for this dir. On a
@@ -899,33 +918,30 @@ class JsonlWatcher extends EventEmitter {
     if (MAINLOOP_JOB_SPANS_ENABLED) runSync('fs-watcher:attach-walk', attachWalk);
     else attachWalk();
 
-    // Set up fs.watch (non-recursive — one watcher per directory). The
+    // Set up the watcher (non-recursive — one watcher per directory). The
     // actual symlink check happens in _handleFileEvent so that a file that
     // is later replaced by a symlink is still filtered.
-    try {
-      this._watchedDirs.set(watchKey, rec);
-      const watcher = fs.watch(dir, (eventType, filename) => {
-        if (!filename || this._stopped) return;
-        if (!filename.endsWith('.jsonl') && !filename.endsWith('.jsonl.bak')) return;
-        const filePath = path.join(dir, filename);
-        this._debouncedHandle(filePath, dir, watchKey);
-      });
-
-      watcher.on('error', (err) => {
-        // Reattach on error with delay
-        this._watchers.delete(watchKey);
-        this._watchedDirs.set(watchKey, rec);
-        try { watcher.close(); } catch {}
-        if (!this._stopped) {
-          setTimeout(() => this._ensureWatchedDir(root, dir, watchKey, projectEntry), REATTACH_DELAY_MS);
-        }
-      });
+    this._watchedDirs.set(watchKey, rec);
+    const watcher = this._watch(dir, {}, (eventType, filename) => {
+      if (!filename || this._stopped) return;
+      if (!filename.endsWith('.jsonl') && !filename.endsWith('.jsonl.bak')) return;
+      const filePath = path.join(dir, filename);
+      this._debouncedHandle(filePath, dir, watchKey);
+    });
 
-      this._watchers.set(watchKey, watcher);
-    } catch (e) {
+    watcher.on('error', (err) => {
+      this._watchers.delete(watchKey);
       this._watchedDirs.set(watchKey, rec);
-      this.emit('error', e);
-    }
+      // WP-3 §9 S-4: the sync attach throw arrives here now — the try/catch it replaced, no timer.
+      if (err && err.syncAttach) { this.emit('error', err); return; }
+      // Reattach on error with delay
+      try { watcher.close(); } catch { /* expected: the watcher already errored, close() may throw again harmlessly */ }
+      if (!this._stopped) {
+        setTimeout(() => this._ensureWatchedDir(root, dir, watchKey, projectEntry), REATTACH_DELAY_MS);
+      }
+    });
+
+    this._watchers.set(watchKey, watcher);
   }
 
   // Async so the readdir/lstat run on libuv's threadpool, NOT the main event loop. On a primary

package/template/coding-task-manager/lib/harness-history-transition.js

@@ -2,12 +2,28 @@
 
 const NATIVE_ORIGINS = new Set(['native-codex', 'native-claude', 'native-opencode', 'native-gemini']);
 const KNOWN_ORIGINS = new Set([...NATIVE_ORIGINS, 'routed-proxy', 'portable-transcript']);
-// S-3: the adapter/schema ids and the version membership test come from the one qualified table.
+// S-3: the adapter/schema ids and the non-elevated cyber program set come from the one table. A
+// Codex version is recorded provenance only (WP-0): the gates below refuse a missing/blank version
+// string but never compare it against a qualified-version table, range or floor.
 const { CODEX_CONTROL_ADAPTER, CODEX_COMPACTION_SCHEMA_RECEIPT, CODEX_PRE_TURN_COMPACTION_SCHEMA,
-  isQualifiedCodexVersion, isNonElevatedCyberAccessProgram } = require('./codex-harness-qualification');
+  isNonElevatedCyberAccessProgram } = require('./codex-harness-qualification');
+// D-4 (docs/codex-0164-historical-tools-safe-handoff-2026-10-27.html §5): the ONE versioned
+// proxy-filter receipt. A cross-provider Codex target may carry historical tool declarations only
+// when its durable recipe proves the local authenticated proxy launch path issued this exact receipt.
+const { CODEX_HISTORICAL_TOOLS_FILTER_RECEIPT } = require('./model-proxy/historical-tool-declarations');
 // S-4: the ONE portable-kind set. `native-media` is a message whose only non-text content parts are
 // input_image parts (D-2); it is portable only to a Codex target, which is the planner's job below.
-const PORTABLE_HISTORY_KINDS = new Set(['text', 'tool-pair', 'native-world-state', 'native-lifecycle', 'native-media']);
+// `native-tool-declarations` is listed because its portability is CONDITIONAL, and the condition is
+// evaluated below (routed Codex target plus the exact durable receipt); membership here only stops
+// the generic `history_kind_unsupported` refusal from firing first.
+// D-7 (docs/codex-upgrades-without-version-approval-2026-10-28.html §configuration-followup):
+// `native-configuration-update` is the harness-authored reasoning-configuration control record.
+// Codex keeps it for the native OpenAI models that advertise support and drops it from the outgoing
+// request copy for non-OpenAI / unsupported-override targets -- not for all targets -- so it travels
+// only to a Codex target; membership here keeps the generic refusal from firing first and the
+// condition is evaluated below, exactly like `native-media`.
+const PORTABLE_HISTORY_KINDS = new Set(['text', 'tool-pair', 'native-world-state', 'native-lifecycle',
+  'native-media', 'native-tool-declarations', 'native-configuration-update']);
 // D-5/D-6 (docs/codex-lead-routed-switch-history-handoff-2026-10-21.html §6.2): the plaintext handoff
 // the source model writes is injected into the forked target, so it consumes target context that the
 // source estimate does not count. 32 KiB of summary text is 8_192 tokens at four characters each.
@@ -23,9 +39,10 @@ function inspectTransition({ sourceRecipe, targetRecipe, snapshot, signal } = {}
   const targetProviderId = nonempty(targetRecipe.providerId);
   const origin = nonempty(sourceRecipe.origin);
   const codexHistorySource = origin === 'native-codex' || sourceRecipe.harness === 'codex-cli';
-  // D-3: qualification is per record (D-1) plus the installed binary that performs the fork. The
-  // rollout's CREATOR version (session_meta.cli_version, written once at creation) is not the writer
-  // of its later records, so it is not a gate here.
+  // D-3/WP-0: admission is per record (D-1) plus the adapter identity of the binary that performs
+  // the fork. The rollout's CREATOR version (session_meta.cli_version, written once at creation) is
+  // not the writer of its later records, so it is never a gate; the target wire version below is
+  // required provenance only, not membership in a qualified-version table.
   const qualifiedCodexHistorySource = codexHistorySource
     && sourceRecipe.controlAdapterVersion === CODEX_CONTROL_ADAPTER;
   if (!origin) return refuse('source_origin_unknown');
@@ -50,7 +67,7 @@ function inspectTransition({ sourceRecipe, targetRecipe, snapshot, signal } = {}
       && (!qualifiedCodexHistorySource
         || !isNonElevatedCyberAccessProgram(sourceRecipe.cyberAccessProgram)
         || !isNonElevatedCyberAccessProgram(snapshot.previousSettings?.cyberAccessProgram)
-        || targetRecipe.harness !== 'codex-cli' || !isQualifiedCodexVersion(targetRecipe.harnessVersion))) {
+        || targetRecipe.harness !== 'codex-cli' || !nonempty(targetRecipe.harnessVersion))) {
     return refuse('native_fork_adapter_unqualified', { sourceCheckpoint });
   }
   if (qualifiedCodexHistorySource) {
@@ -75,12 +92,36 @@ function inspectTransition({ sourceRecipe, targetRecipe, snapshot, signal } = {}
     }
   }
   if (snapshot.opaque === true || has(snapshot.historyKinds, 'opaque')) return refuse('opaque_history_not_portable', { sourceCheckpoint });
+  // D-4: a persisted AdditionalTools declaration is its own kind and is portable ONLY to the local
+  // authenticated proxy Codex target whose durable recipe carries the exact versioned filter receipt
+  // (the target that proved it strips the source declaration before the upstream request). Anything
+  // else -- a non-Codex target, a route-less native target, or a missing/foreign receipt -- keeps a
+  // fixed refusal instead of forwarding an unexamined tool schema across providers. Same-provider
+  // native reuse was already decided above, and this never widens the generic opaque allowance.
+  // The name is deliberately in the `target_` refusal family so the existing user-facing sentence map
+  // (lib/session-model-action-preconditions.js, out of this package's file list) already names it.
+  if (has(snapshot.historyKinds, 'native-tool-declarations')
+      && !(targetRecipe.harness === 'codex-cli' && nonempty(targetRecipe.routeId)
+        && targetRecipe.historyToolFilterReceipt === CODEX_HISTORICAL_TOOLS_FILTER_RECEIPT)) {
+    return refuse('target_tool_declarations_filter_unqualified', { sourceCheckpoint });
+  }
   // D-2: native media is portable exactly when the target is Codex, which strips images the target
   // cannot accept (core/src/context_manager/normalize.rs:346 @ rust-v0.163.0). A non-Codex target
   // gets a plain refusal instead of a silent rewrite of the source history.
   if (has(snapshot.historyKinds, 'native-media') && targetRecipe.harness !== 'codex-cli') {
     return refuse('history_media_not_portable', { sourceCheckpoint });
   }
+  // D-7: the harness-authored reasoning-configuration control record is portable exactly when the
+  // target is Codex: the only harness that produced it, and the one whose request copy drops this
+  // item before the provider on non-OpenAI / unsupported-override targets
+  // (core/src/client.rs:596-599,935-939 @ rust-v0.165.0), so a routed Codex target never forwards
+  // it upstream. Any other target keeps a named refusal rather than a silent rewrite of the source
+  // history, and no replacement-history form of this record is accepted: no producer of one has been
+  // observed. The same-provider native reuse above already decided the matching case, and the
+  // earlier source/harness gates are untouched, so they can still refuse first.
+  if (has(snapshot.historyKinds, 'native-configuration-update') && targetRecipe.harness !== 'codex-cli') {
+    return refuse('history_configuration_not_portable', { sourceCheckpoint });
+  }
   // D-5/D-6: a sealed `compaction` item is carried by a plaintext handoff the SOURCE model writes
   // before the switch. Exactly one sealed digest can be covered, and only the native openai source
   // (whose own model can be asked to write it) can produce one; everything else keeps a named refusal.
@@ -114,12 +155,12 @@ function inspectTransition({ sourceRecipe, targetRecipe, snapshot, signal } = {}
     && targetRecipe.compactHashStatus === 'known-absent-with-native-schema-receipt'
     && targetRecipe.compactHashSchemaReceipt === CODEX_COMPACTION_SCHEMA_RECEIPT
     && /^[a-f0-9]{64}$/.test(String(targetRecipe.catalogSha256 || ''))
-    && targetRecipe.harness === 'codex-cli' && isQualifiedCodexVersion(targetRecipe.harnessVersion);
+    && targetRecipe.harness === 'codex-cli' && !!nonempty(targetRecipe.harnessVersion);
   const targetHashKnownPresent = targetHash !== ''
     && targetRecipe.compactHashStatus === 'known-present-with-native-schema-receipt'
     && targetRecipe.compactHashSchemaReceipt === CODEX_COMPACTION_SCHEMA_RECEIPT
     && /^[a-f0-9]{64}$/.test(String(targetRecipe.catalogSha256 || ''))
-    && targetRecipe.harness === 'codex-cli' && isQualifiedCodexVersion(targetRecipe.harnessVersion);
+    && targetRecipe.harness === 'codex-cli' && !!nonempty(targetRecipe.harnessVersion);
   if (!targetHashKnownAbsent && !targetHashKnownPresent) return refuse('target_compaction_hash_unknown', { sourceCheckpoint });
   // In pinned Codex 0.162.1, compaction for a hash change is triggered only
   // when both turns declare hashes and those hashes differ. A qualified

package/template/coding-task-manager/lib/headless-term-service.js

@@ -54,7 +54,7 @@ const {
   MIRROR_RIGHTSIZE_ENABLED,
   normalizeSnapshotScrollbackRows,
 } = require('./terminal-snapshot-options');
-const { createFrameEmitter, EMPTY_GRID } = require('./state-sync/frame-emitter'); const { computeAnsiPatch } = require('./state-sync/cell-diff');
+const { createFrameEmitter } = require('./state-sync/frame-emitter'); // WP-1: EMPTY_GRID/computeAnsiPatch moved into terminal-bootstrap.js's keyframeBootstrapAnsi (one diff core, one empty grid)
 const HEADLESS_VIEWPORT_CONTRACT_VERSION = 2; // WP-1/D-1: getViewportText wire-contract version
 const { noteOutput: _stateSyncNoteOutput, isFlooding: _stateSyncIsFlooding, settleDelay: _stateSyncSettleDelay } = require('./state-sync/frame-rate');
 const { serializeRow, serializeRowState, wrapRowAnsi, ROW_DIGEST_ALGORITHM } = require('./state-sync/row-serializer');
@@ -75,7 +75,7 @@ const { composerSnapshotFromTerm, boundedBufferTokens } = require('./image-compo
 const { createErrorSink } = require('./error-sink');
 const { createPendingClientRegistry } = require('./state-sync/pending-client-registry');
 const { createApprovalTrailingRecheck } = require('./approval-trailing-recheck');
-const { composeTerminalBootstrapResult, truncateBootstrapAnsi } = require('./terminal-bootstrap');
+const { composeTerminalBootstrapResult, truncateBootstrapAnsi, keyframeBootstrapAnsi } = require('./terminal-bootstrap');
 const { createInFlightOps } = require('./headless-inflight-ops'); // WP-0 (D-6): per-session in-flight op table
 
 let postMessage = () => {};
@@ -214,6 +214,10 @@ function _deliverKeyframeRequest(msg) {
     requestToken: String(msg.requestToken || '').slice(0, 128),
     contentRecoveryEpoch: Math.max(0, Number(msg.contentRecoveryEpoch || 0)),
     ...(serverHealAttempt >= 1 ? { serverHealAttempt } : {}),
+    // WP-2 (D-6, §9 S-8): thread the client's committed baseline seq to the emitter when the relay
+    // carried a valid one; an absent haveSeq stays absent (the emitter then serves every request,
+    // exactly as before this WP).
+    ...(Number.isSafeInteger(msg.haveSeq) && msg.haveSeq >= 0 ? { haveSeq: msg.haveSeq } : {}),
   };
   const delivered = _stateSyncEmitter.onKeyframeReq(msg.sessionId, reqCtx);
   // WP-2 (state-sync-delivery-path-reset-2026-09-18.html §5): onKeyframeReq never refuses and
@@ -438,6 +442,19 @@ const _stateSyncEmitter = createFrameEmitter({
     if (!ids) return;
     _noteWorkerTypingStage(id, ids, 'emit-refused', { gate, ...fields });
   },
+  // WP-0 (S-11, docs/state-sync-pipelined-deltas-echo-never-waits-for-ack-2026-10-31.html §5 D-5,
+  // §9 S-11): report ONE matched ack's in-flight round trip -- the host leg measured in the emitter,
+  // the main leg passed through from the server's ledger lookup -- against whichever interactions
+  // are still pending on this session's mirror. `inflight-acked` is an OPTIONAL trace stage, so it
+  // can never move an interaction's completed boundary (lib/typing-interaction-trace.js).
+  onAcked: (id, info) => {
+    const ids = _pendingTypingInteractionIds(terminals.get(id));
+    if (!ids) return;
+    _noteWorkerTypingStage(id, ids, 'inflight-acked', {
+      inFlightSeq: info.seq, hostRttMs: info.hostRttMs, mainRttMs: info.mainRttMs,
+      windowFrames: info.windowFrames,
+    });
+  },
   // WP-5 (§9 S-8/S-9): surface the no-audience stand-down latch in ctm.log the same way the W5c
   // ack-stall warning below does (console.warn from this worker is captured like any other log line).
   log: (event, data) => {
@@ -477,25 +494,81 @@ const _stateSyncPendingClearScrollback = new Set(); // sessionIds whose next fra
 // Lost-ack watchdog: the emitter's diff base only advances on a client ACK, so a frame whose ACK never
 // reaches the worker would pin the session in-flight forever and freeze its terminal. Periodically sweep
 // for frames stuck in flight past STATE_SYNC_INFLIGHT_STALL_MS and force a fresh keyframe (full repaint).
+// WP-2 (D-5, docs/remote-relay-ack-rate-limit-typing-delay-2026-10-28.html §5 D-5, §9 S-10): the stall
+// is now PER DELIVERY — each delivery's own measured ack RTT sizes its own watchdog (`stallMsFor`,
+// RFC 6298 §2 SRTT/RTTVAR). This constant is now the CEILING (unchanged value, unchanged env
+// override), and the floor is the private-low-RTT-path bound below (mosh MIN_RTO intuition).
 const STATE_SYNC_INFLIGHT_STALL_MS = Math.max(
   STATE_SYNC_FRAME_MAX_MS * 4,
   Number(process.env.CTM_STATE_SYNC_INFLIGHT_STALL_MS) || 3000,
 );
-const STATE_SYNC_INFLIGHT_SWEEP_MS = Math.max(250, Math.floor(STATE_SYNC_INFLIGHT_STALL_MS / 3));
+const STATE_SYNC_INFLIGHT_STALL_FLOOR_MS = Math.max(50, Number(require('./env-flags').intFlag('CTM_STATE_SYNC_INFLIGHT_STALL_FLOOR_MS', 250)));
+// The recovery sweep runs every 100 ms (was max(250, stall/3) = 1000 ms), so an adaptive stall at the
+// 250 ms floor still recovers within 350 ms of the send instead of 3–4 s.
+const STATE_SYNC_INFLIGHT_SWEEP_MS = 100;
 // W5c: a session whose client ack stream is dead gets NO benefit from sweepStalledInFlight's
 // per-frame recovery (it keeps re-arming inFlightAt every sweep, forever masking the stall) — the
 // browser mirror can freeze for minutes with zero console output (production incident 2026-07-12).
-// Query listStalledSessions alongside the recovery sweep and surface a throttled warning.
+// Query listStalledSessions on its own (unchanged) 1000 ms cadence and surface a throttled warning.
+const STATE_SYNC_STALL_LIST_MS = 1000;
 const _stalledSessionWarnings = createStallWarningRegistry();
 const STATE_SYNC_STALL_WARN_THROTTLE_MS = 60000;
+
+// WP-0 (D-4c, docs/remote-relay-ack-rate-limit-typing-delay-2026-10-28.html §5 D-4c, §9 S-10):
+// every lost-ack recovery the sweep performs is reported to main, throttled per session per 30 s
+// with the count accumulated in the window (the first recovery reports immediately, mirroring
+// lib/remote-machine-link.js's _noteUndelivered). Diagnostics only — the recovery itself has
+// already happened when this runs.
+const STATE_SYNC_INFLIGHT_RECOVERED_THROTTLE_MS = 30000;
+const _inflightRecovered = new Map(); // sessionId -> { count, hiddenCount, inFlightKind, lastInFlightAgeMs, stallMs, lastReportMs }
+function _noteInflightRecovered(sessionId, info) {
+  if (!sessionId) return;
+  const now = Date.now();
+  let entry = _inflightRecovered.get(sessionId);
+  if (!entry) {
+    entry = { count: 0, hiddenCount: 0, inFlightKind: '', lastInFlightAgeMs: 0, stallMs: 0, lastReportMs: null };
+    _inflightRecovered.set(sessionId, entry);
+  }
+  entry.count += 1;
+  entry.hiddenCount += info && info.hidden ? 1 : 0;
+  entry.inFlightKind = String((info && info.inFlightKind) || '');
+  entry.lastInFlightAgeMs = Number((info && info.inFlightAgeMs) || 0);
+  entry.stallMs = Number((info && info.stallMs) || 0);
+  if (entry.lastReportMs != null && now - entry.lastReportMs < STATE_SYNC_INFLIGHT_RECOVERED_THROTTLE_MS) return;
+  postMessage({
+    type: 'state-sync-inflight-recovered',
+    sessionId,
+    count: entry.count,
+    inFlightKind: entry.inFlightKind,
+    lastInFlightAgeMs: entry.lastInFlightAgeMs,
+    stallMs: entry.stallMs,
+    hiddenCount: entry.hiddenCount,
+  });
+  entry.count = 0;
+  entry.hiddenCount = 0;
+  entry.lastReportMs = now;
+}
+
 if (_stateSyncEmitter) {
-  const _stalledSweep = setInterval(() => {
+  // WP-2 (D-5, §9 S-10): the recovery sweep runs on its own 100 ms cadence so a per-delivery stall at
+  // the 250 ms floor is noticed within one sweep of elapsing (recovered ≤ 350 ms after send), not on
+  // the old 1000 ms tick. `stallMs` is the ceiling; `floorMs` bounds a fast delivery from below.
+  const _recoverySweep = setInterval(() => {
     try {
       _stateSyncEmitter.sweepStalledInFlight(Date.now(), {
         stallMs: STATE_SYNC_INFLIGHT_STALL_MS,
+        floorMs: STATE_SYNC_INFLIGHT_STALL_FLOOR_MS,
         hasViewers: (id) => _mirrorVisibility(id) === 'visible',
+        onRecovered: (id, info) => _noteInflightRecovered(id, info),
       });
     } catch {}
+  }, STATE_SYNC_INFLIGHT_SWEEP_MS);
+  if (typeof _recoverySweep.unref === 'function') _recoverySweep.unref();
+
+  // W5c: listStalledSessions keeps its own (unchanged) 1000 ms cadence and 3×-ceiling warning
+  // semantics. A dead ack stream gets no benefit from the recovery sweep above (it keeps re-arming
+  // inFlightAt every sweep, forever masking the stall) — this is the separate, louder signal.
+  const _stalledList = setInterval(() => {
     try {
       const stalls = _stateSyncEmitter.listStalledSessions(Date.now(), { stallMs: STATE_SYNC_INFLIGHT_STALL_MS });
       const now = Date.now();
@@ -540,8 +613,8 @@ if (_stateSyncEmitter) {
       }
       _stalledSessionWarnings.reconcile(activeWarningKeys);
     } catch {}
-  }, STATE_SYNC_INFLIGHT_SWEEP_MS);
-  if (typeof _stalledSweep.unref === 'function') _stalledSweep.unref();
+  }, STATE_SYNC_STALL_LIST_MS);
+  if (typeof _stalledList.unref === 'function') _stalledList.unref();
 }
 
 // Sessions mid-"repaint nudge": the server resizes the PTY+mirror to cols-1 (to force a SIGWINCH so a
@@ -1630,6 +1703,9 @@ async function handleMessage(msg) {
         _stateSyncEmitter.onAck(msg.sessionId, Number(msg.seq || 0), {
           clientId: msg.clientId || '', socketGeneration: Number(msg.socketGeneration || 0),
           holdCatchUp,
+          // WP-0 (S-11): the main process measured this ack's main-side round trip on the ledger's
+          // own sentAt; -1 when it had no evidence. Report-only, forwarded to the typing trace.
+          mainRttMs: Number.isFinite(Number(msg.mainRttMs)) ? Number(msg.mainRttMs) : -1,
         });
         if (holdCatchUp) _stateSyncScheduleHeldEmit(msg.sessionId);
       }
@@ -1895,7 +1971,7 @@ async function handleMessage(msg) {
         const keyframe = Number(msg.clientBufferLength || 0) > Number(entry.term.rows || 0);
         if (keyframe) bootstrapMode = 'keyframe';
         const sourceAnsi = keyframe
-          ? computeAnsiPatch(EMPTY_GRID, extractGrid(msg.sessionId, { scrollbackRows: STATE_SYNC_SCROLLBACK_ROWS }), { keyframe: true }).ansi
+          ? keyframeBootstrapAnsi(extractGrid(msg.sessionId, { scrollbackRows: STATE_SYNC_SCROLLBACK_ROWS }))
           : data;
         // WP-3: byte-budget probe only (server.js builds the wire result from `bootstrap` below);
         // gridRevision/surfaceEpoch are required by the schema, so 0 placeholders satisfy it.