create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/transcript-cache-temps.js

@@ -0,0 +1,171 @@
+'use strict';
+
+// Cache temp names and their reclaimer (design doc temp-file-leaks §5 D-1/D-3, §8 WP-1).
+//
+// A decoded frame is written to `<final>.tmp-<pid>-<threadId>-<hex>` and published with a rename, so a
+// crash between the two strands a temp. The pid+THREAD pair is what makes one attributable: the read
+// pool's worker threads share process.pid, and pool `worker.terminate()` stops a thread after its write
+// and before its rename -- a dead-pid sweep alone cannot see that (this is the 63 GB incident, §1 L-1).
+// Threads get their own module instance, so `threadId` here is this isolate's own id (0 = main thread).
+// CACHE_TEMP_RE also matches the legacy `<final>.tmp-<pid>-<hex>` shape, which has no thread to blame.
+//
+// Extracted from lib/transcript-source.js (which was over its 1500-line new-file ceiling) and kept
+// deliberately dependency-free: this module knows NOTHING about the data dir. Every entry point takes
+// the cache root in `opts.cacheDir`, and transcript-source -- the one owner of the default root -- passes
+// it. The only external dependency is the liveness probe, loaded lazily on first sweep.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { threadId } = require('node:worker_threads');
+
+const CACHE_TEMP_RE = /\.bin\.tmp-(\d+)-(?:(\d+)-)?[0-9a-f]{8,16}$/;
+const CACHE_TEMP_STALE_MS = 30 * 60_000;
+const CACHE_TEMP_SWEEP_INTERVAL_MS = 5 * 60_000;
+let _cacheTempSweptAt = 0; // per-isolate sweep throttle; 0 = never swept
+
+function cacheTempPath(finalPath) {
+  return `${finalPath}.tmp-${process.pid}-${threadId}-${crypto.randomBytes(8).toString('hex')}`;
+}
+
+/** The one cache-root rule here: the caller passes it. A missing root is a programming error, not a silent no-op. */
+function _cacheRootOf(opts) {
+  const root = opts && opts.cacheDir;
+  if (typeof root !== 'string' || root === '') throw new TypeError('transcript-cache-temps: opts.cacheDir is required');
+  return root;
+}
+
+function _cacheKeyDirPaths(root, dirs) {
+  return dirs.filter((d) => d.isDirectory()).map((d) => path.join(root, d.name));
+}
+
+/** The `<key>` subdirectories of a cache root, or [] when the root does not exist yet. */
+async function _cacheKeyDirsAsync(root) {
+  let dirs;
+  try {
+    dirs = await fs.promises.readdir(root, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return _cacheKeyDirPaths(root, dirs);
+}
+
+/** Every `*.bin.tmp-*` cache temp in `dir`: the one temp-shape rule (a published `.bin` never matches). */
+function _cacheTempEntry(dir, name, match, st) {
+  return {
+    file: path.join(dir, name), pid: Number(match[1]),
+    threadId: match[2] === undefined ? null : Number(match[2]), size: st.size, mtimeMs: st.mtimeMs,
+  };
+}
+
+async function _cacheTempsInDirAsync(dir) {
+  let names;
+  try {
+    names = await fs.promises.readdir(dir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return []; // expected: a concurrent prune took the whole key dir
+    throw err;
+  }
+  const temps = [];
+  for (const name of names) {
+    const match = CACHE_TEMP_RE.exec(name);
+    if (!match) continue;
+    let st;
+    try {
+      st = await fs.promises.stat(path.join(dir, name));
+    } catch (err) {
+      if (err && err.code === 'ENOENT') continue; // expected: another reclaimer unlinked this temp first
+      throw err;
+    }
+    temps.push(_cacheTempEntry(dir, name, match, st));
+  }
+  return temps;
+}
+
+async function _unlinkCacheTempAsync(file) {
+  try {
+    await fs.promises.unlink(file);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return false; // expected: a concurrent reclaimer won the race
+    throw err;
+  }
+}
+
+/** The per-temp sweep decision: a provably-gone OWNER, or simply age. The sweep calls only this. */
+function _cacheTempIsReclaimable(temp, now, isProcessAlive) {
+  const ownerGone = temp.pid !== process.pid && !isProcessAlive(temp.pid);
+  return ownerGone || now - temp.mtimeMs >= CACHE_TEMP_STALE_MS;
+}
+
+/** The per-temp thread claim (D-2): a legacy name has no threadId, so no thread can claim it. */
+function _cacheTempIsOwnedByThread(temp, pid, threadId_) {
+  return temp.pid === pid && temp.threadId === threadId_;
+}
+
+/** The sweep throttle + its inputs: null when this isolate already swept inside the interval. */
+function _cacheTempSweepState(opts) {
+  const now = typeof opts.now === 'function' ? Number(opts.now())
+    : (Number.isFinite(opts.now) ? Number(opts.now) : Date.now());
+  if (!opts.force && now - _cacheTempSweptAt < CACHE_TEMP_SWEEP_INTERVAL_MS) return null;
+  _cacheTempSweptAt = now;
+  return {
+    now,
+    root: _cacheRootOf(opts),
+    isProcessAlive: typeof opts.isProcessAlive === 'function'
+      ? opts.isProcessAlive
+      : require('./host-registry').isProcessAlive, // lazy: the probe is not needed on the decode path
+  };
+}
+
+/**
+ * The one reclaimer for stranded decode temps (design §5 D-3): a temp goes when its OWNER is provably
+ * gone (dead pid -- the only evidence a terminated worker thread leaves behind) or when it is simply
+ * old, whatever wrote it. Never touches a `.bin`; tolerates ENOENT races; throttled per isolate.
+ *
+ * ASYNC-only on purpose: a live cache holds thousands of `<key>` dirs (measured 479 ms for one walk),
+ * so a synchronous form would stall whatever loop called it. Every caller -- server.js's interval and
+ * the read pool's exit listener -- can await, so no sync twin exists to drift from these rules.
+ */
+async function sweepStaleCacheTempsAsync(opts = {}) {
+  const result = { removed: 0, bytes: 0 };
+  const state = _cacheTempSweepState(opts);
+  if (!state) return result;
+  for (const dir of await _cacheKeyDirsAsync(state.root)) {
+    for (const temp of await _cacheTempsInDirAsync(dir)) {
+      if (!_cacheTempIsReclaimable(temp, state.now, state.isProcessAlive)) continue;
+      if (await _unlinkCacheTempAsync(temp.file)) {
+        result.removed += 1;
+        result.bytes += temp.size;
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * D-2: reclaims what ONE dead thread left behind, by ownership (pid + threadId) instead of by age --
+ * the thread is gone, so no grace period is needed. Async for the same reason as the sweep above.
+ */
+async function removeCacheTempsForThreadAsync(pid, threadId_, opts = {}) {
+  const wantPid = Number(pid);
+  const wantThreadId = Number(threadId_);
+  let removed = 0;
+  for (const dir of await _cacheKeyDirsAsync(_cacheRootOf(opts))) {
+    for (const temp of await _cacheTempsInDirAsync(dir)) {
+      if (!_cacheTempIsOwnedByThread(temp, wantPid, wantThreadId)) continue;
+      if (await _unlinkCacheTempAsync(temp.file)) removed += 1;
+    }
+  }
+  return removed;
+}
+
+module.exports = {
+  CACHE_TEMP_RE,
+  CACHE_TEMP_STALE_MS,
+  CACHE_TEMP_SWEEP_INTERVAL_MS,
+  cacheTempPath,
+  sweepStaleCacheTempsAsync,
+  removeCacheTempsForThreadAsync,
+};

package/template/coding-task-manager/lib/transcript-frame-cache.js

@@ -3,7 +3,6 @@
 // Async full-frame cache ownership. A pathname is only the publication/eviction name: readers own
 // the opened inode through a refcounted lease, so a prune in another isolate cannot invalidate them.
 // Admission is injected by transcript-source, sharing its two slots with bounded prefix decoders.
-const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { Transform } = require('node:stream');
@@ -27,8 +26,12 @@ function closedReceipt(stream) {
 // the eviction order of multi-GB entries unchanged (fsevents-churn D-10b).
 const TOUCH_MIN_INTERVAL_MS = 60_000;
 
-function createDecodedFrameCache({ withDecoder, cacheRoot, cacheMax, now, frameFile, pruneCache, codeError }) {
+function createDecodedFrameCache({ withDecoder, cacheRoot, cacheMax, now, frameFile, pruneCache, codeError, cacheTempPath }) {
   const entries = new Map();
+  // D-1: the temp-naming rule lives in transcript-cache-temps.js (the sync writer in transcript-source
+  // shares it). It is injected at construction so the module graph stays acyclic; the lazy fallback is
+  // for direct constructors (tests) that call this factory without transcript-source in the loop.
+  const tempPathFor = cacheTempPath || require('./transcript-cache-temps').cacheTempPath;
 
   function removeEntry(entry) {
     if (entries.get(entry.key) === entry) entries.delete(entry.key);
@@ -96,7 +99,9 @@ function createDecodedFrameCache({ withDecoder, cacheRoot, cacheMax, now, frameF
     entry.state = 'filling';
     await fs.promises.mkdir(path.dirname(entry.file), { recursive: true });
     throwIfAborted(signal);
-    entry.tmp = `${entry.file}.tmp-${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+    // D-1: one naming rule for both writers, owned by transcript-cache-temps.js (pid + threadId), so a
+    // temp stranded by a terminated read-pool thread is attributable to the thread that wrote it.
+    entry.tmp = tempPathFor(entry.file);
     const decoder = (entry.opts.decoderFactory || decodeFrame)(entry.archive.path, entry.frame);
     const decoderClosed = closedReceipt(decoder);
     let total = 0;

package/template/coding-task-manager/lib/transcript-source.js

@@ -23,6 +23,7 @@ const zlib = require('node:zlib');
 const { decodeFrame, waitForDecodedFrameClose, decompressParams } = require('./transcript-archive-codec');
 const { getDataDir } = require('./data-dir');
 const { createDecodedFrameCache, TOUCH_MIN_INTERVAL_MS } = require('./transcript-frame-cache');
+const cacheTemps = require('./transcript-cache-temps');
 
 const CACHE_DIR_NAME = 'transcript-archive-cache';
 const DEFAULT_CACHE_MAX_BYTES = 4 * 1024 * 1024 * 1024;
@@ -91,6 +92,16 @@ function _frameFile(root, key, index) {
   return path.join(root, key, `${index}.bin`);
 }
 
+// The cache root is this module's to know (CACHE_DIR_NAME under getDataDir()); every reclaimer entry
+// point takes it as `cacheDir`. Delegated so the sweep's rules live in exactly one module.
+const _cacheTempsOpts = (opts) => ({ ...opts, cacheDir: (opts && opts.cacheDir) || _cacheRoot(opts) });
+const cacheTempPath = cacheTemps.cacheTempPath;
+const CACHE_TEMP_RE = cacheTemps.CACHE_TEMP_RE;
+const CACHE_TEMP_STALE_MS = cacheTemps.CACHE_TEMP_STALE_MS;
+const CACHE_TEMP_SWEEP_INTERVAL_MS = cacheTemps.CACHE_TEMP_SWEEP_INTERVAL_MS;
+const sweepStaleCacheTempsAsync = (opts = {}) => cacheTemps.sweepStaleCacheTempsAsync(_cacheTempsOpts(opts));
+const removeCacheTempsForThreadAsync = (pid, tid, opts = {}) => cacheTemps.removeCacheTempsForThreadAsync(pid, tid, _cacheTempsOpts(opts));
+
 // ---------------------------------------------------------------------------------------------
 // Manifest lookup (the db handle sees the base database; guarded like the identity guard).
 
@@ -336,6 +347,7 @@ function _evictionList(files, max, keepFile) {
 }
 
 async function _pruneCache(opts, keepFile) {
+  await sweepStaleCacheTempsAsync(opts);
   const doomed = _evictionList(await _listCache(_cacheRoot(opts)), _cacheMax(opts), keepFile);
   for (const file of doomed) {
     await fs.promises.unlink(file).catch((err) => {
@@ -391,7 +403,7 @@ async function _withDecoder(fn, signal) {
 
 const { acquireDecodedFrame } = createDecodedFrameCache({
   withDecoder: _withDecoder, cacheRoot: _cacheRoot, cacheMax: _cacheMax,
-  now: _now, frameFile: _frameFile, pruneCache: _pruneCache, codeError: _codeError,
+  now: _now, frameFile: _frameFile, pruneCache: _pruneCache, codeError: _codeError, cacheTempPath,
 });
 
 // ---------------------------------------------------------------------------------------------
@@ -1146,9 +1158,23 @@ function _decodeFrameSync(archive, index, opts, learnLength) {
   if (!learnLength && bytes.length !== uLen) throw _codeError('ARCHIVE_VERIFY_FAILED', `frame ${index} decoded to ${bytes.length} bytes, expected ${uLen}`);
   if (ledger && learnLength) _chargeLearnedDecoded(ledger, `${archive.cacheKey}:${index}`, bytes.length);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
-  fs.writeFileSync(tmp, bytes, { flag: 'wx' });
-  fs.renameSync(tmp, file);
+  const tmp = cacheTempPath(file);
+  try {
+    fs.writeFileSync(tmp, bytes, { flag: 'wx' });
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    // D-4: this write is synchronous inside whatever isolate called it, so nothing else can clean up
+    // after a failed publish -- and a caller killed right here (read pool terminate) never gets to.
+    // Unlink the temp, then rethrow the ORIGINAL error unchanged.
+    try {
+      fs.unlinkSync(tmp);
+    } catch (cleanupErr) {
+      if (!cleanupErr || cleanupErr.code !== 'ENOENT') {
+        console.warn(`[transcript-cache] temp cleanup failed for ${tmp}: ${cleanupErr?.message || cleanupErr}`);
+      } // else: the write failed before creating the temp -- nothing to remove
+    }
+    throw err;
+  }
   const when = new Date(_now(opts));
   fs.utimesSync(file, when, when);
   _pruneCacheSync(opts, file);
@@ -1423,4 +1449,10 @@ module.exports = {
   zstdContentSize,
   MAX_RANGE_BYTES,
   DEFAULT_CACHE_MAX_BYTES,
+  cacheTempPath,
+  CACHE_TEMP_RE,
+  CACHE_TEMP_STALE_MS,
+  CACHE_TEMP_SWEEP_INTERVAL_MS,
+  sweepStaleCacheTempsAsync,
+  removeCacheTempsForThreadAsync,
 };

package/template/coding-task-manager/lib/transcript-store.js

@@ -4314,6 +4314,11 @@ function catchUpTranscriptFiles(db, options = {}) {
     for (;;) {
       assertCatchUpLive();
       if (Date.now() - startedAt > catchUpBudgetMs) { budgetExceeded = true; break; }
+      // S-16 (D-11): a wall-clock budget alone lets this whole op (which blocks the serial
+      // writer) run to its 5 s slice while an interactive request waits. The caller's
+      // predicates are the same ones drainTranscriptByteBackfill already honours; a set
+      // predicate ends the run as a partial result, exactly like budget expiry.
+      if (options.shouldYieldToUrgent?.() || options.shouldYieldToPending?.()) { budgetExceeded = true; break; }
       const promoted = backfillSessionRowsFromTranscriptEvents(db, {
         limit: backfillLimit,
         ctmSessionId: sessionId,
@@ -4334,6 +4339,10 @@ function catchUpTranscriptFiles(db, options = {}) {
   for (const rawPath of filePaths) {
     assertCatchUpLive();
     if (Date.now() - startedAt > catchUpBudgetMs) { budgetExceeded = true; break; }
+    // S-16 (D-11): same yield contract as the backfill loop above — one file per check, so a
+    // pending interactive/urgent request is honoured within a single file's ingest here, not
+    // only at the 5 s op budget.
+    if (options.shouldYieldToUrgent?.() || options.shouldYieldToPending?.()) { budgetExceeded = true; break; }
     if (filesProcessed >= maxFilesPerRun) { budgetExceeded = true; break; }
     const filePath = path.resolve(String(rawPath || ''));
     if (!filePath || seenPaths.has(filePath)) continue;

package/template/coding-task-manager/lib/typing-interaction-trace.js

@@ -72,10 +72,13 @@ const STAGES = Object.freeze([
 // new gate -- Gate 1 (§7) pins it.
 // WP-2 (state-sync-delivery-path-reset-2026-09-18.html §5 D-9): the suppression/no-audience/
 // client-fault gates were deleted from the emitter along with their latches -- the emitter now
-// only refuses on an outstanding in-flight frame or the rate floor. `hidden`/`nudge`/`sync-hold`/
-// `settle` are stamped by headless-term-service.js itself, not by the emitter's onRefused.
+// only refuses on a full unacked window or the rate floor. `hidden`/`nudge`/`sync-hold`/`settle`
+// are stamped by headless-term-service.js itself, not by the emitter's onRefused.
+// WP-1 (docs/state-sync-pipelined-deltas-echo-never-waits-for-ack-2026-10-31.html §5 D-2, §6, §9
+// S-9): the one-slot gates are replaced by `window-full`; the OLD names are kept at the end so rows
+// written before WP-1 still parse.
 const GATES = Object.freeze([
-  'in-flight-keyframe', 'in-flight-delta', 'rate', 'hidden', 'nudge', 'sync-hold', 'settle',
+  'window-full', 'in-flight-keyframe', 'in-flight-delta', 'rate', 'hidden', 'nudge', 'sync-hold', 'settle',
 ]);
 const GATE_SET = new Set(GATES);
 
@@ -95,12 +98,23 @@ const OPTIONAL_STAGES = new Set([
   // coalescer delivered before any keystroke was pending), so neither may end the boundary walk.
   'frame-arrived', 'host-pty-data',
   'echo-bytes', 'echo-cell',
+  // WP-0 (docs/state-sync-pipelined-deltas-echo-never-waits-for-ack-2026-10-31.html §5 D-5,
+  // §9 S-9): 'inflight-acked' is a REPORT-ONLY stamp on the interaction a matched ack unblocked --
+  // it is not a step in any interaction's sequence (it is not in STAGES at all), so it must never
+  // move `lastCompletedBoundary`/`missingBoundary`. Its record carries the acked frame's seq and
+  // both measured legs (see note()'s branch below); the interaction itself gains `heldBehind`.
+  'inflight-acked',
 ]);
 const WORKLOAD_FIELDS = Object.freeze([
   'rawBatchClass', 'synchronizedFrameCount', 'mirrorChangedRows', 'frameKind',
   'frameBytes', 'queuedBytes', 'queueDepth', 'codexRepairActions',
   'statusRenderSource', 'visibility', 'focused', 'activeLoafMs', 'gridRevision',
   'frameSeq',
+  // WP-2 (docs/typing-delay-session-list-broadcast-storm-2026-11-01.html §6 WP-2, §5 OQ-3): the
+  // socket's bufferedAmount at the instant the frame carrying this key's echo was handed to it.
+  // Read on the `frame-sent` note (server.js's 'frame' fan-out); 0 at a slow frame is what rules
+  // socket backlog out and leaves browser task-queue time (OQ-3).
+  'socketBufferedBytes',
 ]);
 
 function finite(value, fallback = 0) {
@@ -139,6 +153,15 @@ function percentile(values, pct) {
   return sorted[Math.max(0, Math.ceil(sorted.length * pct) - 1)];
 }
 
+// WP-0 (S-9): one leg of an in-flight frame's round trip. A leg is a non-negative millisecond
+// count, or the explicit "no evidence" sentinel -1 -- never a silent 0, which would read as an
+// instant round trip and quietly flatter the very measurement this WP exists to make honest.
+function rttMs(value, fallback = -1) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0) return fallback;
+  return Math.floor(number);
+}
+
 function sanitizePublicContext(context = {}, fallback = {}) {
   const source = { ...fallback, ...context };
   return {
@@ -212,6 +235,10 @@ function buildSlowInteractionRow(row, ktpMs, lastStage) {
     inFlightAgeMs: refused ? refused.inFlightAgeMs : 0,
     rejectedSurfaceEpoch: refused ? refused.rejectedSurfaceEpoch : 0,
     sweepSkipReason: refused ? refused.sweepSkipReason : '',
+    // WP-0 (S-9, §6 API specs): the in-flight frame this keystroke was held behind, with both
+    // measured round-trip legs and the relay remainder -- null for a keystroke that was never
+    // refused, or whose held frame's ack never landed.
+    heldBehind: row.heldBehind || null,
     browserKeydownMs: stageMsFromKeydown(row, 'browser-keydown'),
     serverReceivedMs: stageMsFromKeydown(row, 'server-received'),
     ptyWrittenMs: stageMsFromKeydown(row, 'pty-written'),
@@ -310,6 +337,9 @@ function createTypingInteractionTraceStore(options = {}) {
   const slowThrottledBySession = new Map();
   const worstByGroup = new Map();
   const worstUnpaintedByGroup = new Map();
+  // WP-0 (S-9): the frame WINDOW size in force when the minute's acks landed (1 today, the gate's
+  // size after WP-1) -- keyed like the two maps above, last non-zero value wins, cleared per flush.
+  const windowFramesByGroup = new Map();
 
   // Both new per-key maps are bounded/evicted exactly like lastSlowEmitAtBySession above: re-set
   // an existing key at the tail, then drop the oldest keys past the shared cap.
@@ -378,6 +408,9 @@ function createTypingInteractionTraceStore(options = {}) {
       gate,
       gateHoldMs,
       clientId: row.clientId,
+      // WP-0 (S-9): this interaction's held-frame evidence (null when it was never refused, or the
+      // ack for its held seq never landed) -- flushRollups turns it into the three held*P95Ms fields.
+      heldBehind: row.heldBehind || null,
     });
     windowClosedHistory.push({ at: paintedAt, ktpMs, gate });
     if (windowClosedHistory.length > WINDOW_HISTORY_CAP) windowClosedHistory.shift();
@@ -468,6 +501,9 @@ function createTypingInteractionTraceStore(options = {}) {
       lastCompletedBoundary: 'browser-keydown',
       stages: Object.assign(Object.create(null), { 'browser-keydown': { at: startedAt } }),
       workload: Object.create(null),
+      // WP-0 (S-9): set by note()'s 'inflight-acked' branch when this interaction's own refusal
+      // named the seq that ack retired (see buildSlowInteractionRow / pendingClosed).
+      heldBehind: null,
     });
     prune(startedAt);
     return interactionId;
@@ -528,10 +564,46 @@ function createTypingInteractionTraceStore(options = {}) {
         row.stages[stage] = Array.isArray(event.mainSpans)
           ? { at, mainSpans: sanitizeMainSpans(event.mainSpans) }
           : { at };
+      } else if (stage === 'inflight-acked') {
+        // WP-0 (S-9): the acked frame's seq plus both measured legs (host = the emitter's own
+        // send->ack span; main = the server ledger's sentAt delta; windowFrames = the gate's window
+        // size when the ack landed). Report-only -- see OPTIONAL_STAGES above.
+        row.stages[stage] = {
+          at,
+          inFlightSeq: Math.max(0, Math.floor(finite(event.inFlightSeq))),
+          hostRttMs: rttMs(event.hostRttMs, 0),
+          mainRttMs: rttMs(event.mainRttMs, -1),
+          windowFrames: Math.max(0, Math.floor(finite(event.windowFrames))),
+        };
       } else {
         row.stages[stage] = { at };
       }
     }
+    // WP-0 (S-9, §5 D-5): if THIS interaction was refused behind the very seq this ack retired,
+    // remember the held frame's two round-trip legs on the interaction itself. FIRST match wins --
+    // a later ack, or one for another seq, never overwrites the evidence for the frame that
+    // actually held this keystroke, and a never-refused interaction keeps `heldBehind: null`.
+    if (stage === 'inflight-acked') {
+      const windowFrames = Math.max(0, Math.floor(finite(event.windowFrames)));
+      if (windowFrames > 0) {
+        setBoundedByKey(windowFramesByGroup, rollupGroupKey(row.sessionId, row.agentType), windowFrames);
+      }
+      if (!row.heldBehind) {
+        const refused = row.stages['emit-refused'];
+        const retiredSeq = Math.max(0, Math.floor(finite(event.inFlightSeq)));
+        if (refused && retiredSeq > 0 && Math.max(0, Math.floor(finite(refused.inFlightSeq))) === retiredSeq) {
+          const hostRttMs = rttMs(event.hostRttMs, 0);
+          const mainRttMs = rttMs(event.mainRttMs, -1);
+          row.heldBehind = {
+            seq: retiredSeq,
+            hostRttMs,
+            mainRttMs,
+            // The relay leg is the part of the host leg main's own measurement cannot see.
+            relayMs: mainRttMs >= 0 ? Math.max(0, hostRttMs - mainRttMs) : -1,
+          };
+        }
+      }
+    }
     // R-8, order-independent: the worker posts `frame-posted` as its own 'typing-stage' message
     // AFTER the frame shipped (headless-term-service.js emitSettled -> noteFramePostedForEchoed),
     // so main usually stamps `frame-arrived` BEFORE it knows `frame-posted`. Compute the spans when
@@ -724,6 +796,20 @@ function createTypingInteractionTraceStore(options = {}) {
     return values.length ? percentile(values, 0.95) : 0;
   }
 
+  // WP-0 (S-9, §6 API specs): nearest-rank p95 over the CLOSED interactions of the minute that
+  // carried held-frame evidence, for one leg (`hostRttMs` | `mainRttMs` | `relayMs`). The -1
+  // "no evidence" sentinel is not a sample: an all-unknown minute reports 0, not -1.
+  function heldPercentileMs(closedList, field) {
+    const values = [];
+    for (const entry of closedList) {
+      const held = entry.heldBehind;
+      if (!held) continue;
+      const value = Number(held[field]);
+      if (Number.isFinite(value) && value >= 0) values.push(value);
+    }
+    return values.length ? percentile(values, 0.95) : 0;
+  }
+
   // D-1: groups every interaction that CLOSED (reached `painted`) or EXPIRED (pruned by TTL
   // without `painted`) since the previous flush, by (sessionId, agentType||'unknown'), and
   // emits one flat rollup object per group via `onRollup`. Returns the number emitted.
@@ -793,6 +879,14 @@ function createTypingInteractionTraceStore(options = {}) {
         worstUnpainted: worstUnpaintedByGroup.get(key) || null,
         slowEmitted: slowEmittedBySession.get(sessionId) || 0,
         slowThrottled: slowThrottledBySession.get(sessionId) || 0,
+        // WP-0 (S-9, §6 API specs): the frame WINDOW size in force this minute (1 today -- the gate
+        // is still one frame in flight; WP-1 widens it) and the round trip of every keystroke this
+        // minute held behind an in-flight frame, split into its two measured legs plus the relay
+        // remainder (host - main). 0 = nothing held / no evidence in this minute.
+        windowFrames: windowFramesByGroup.get(key) || 1,
+        heldHostRttP95Ms: heldPercentileMs(closedList, 'hostRttMs'),
+        heldMainRttP95Ms: heldPercentileMs(closedList, 'mainRttMs'),
+        heldRelayP95Ms: heldPercentileMs(closedList, 'relayMs'),
         workerLoopMaxMs: Math.max(0, finite(extras.workerLoopMaxMs, 0)),
         host: {
           loadPerCore: Math.max(0, finite(extras.host?.loadPerCore, 0)),
@@ -810,6 +904,9 @@ function createTypingInteractionTraceStore(options = {}) {
     // minute starts from 0 rather than re-reporting the previous minute's worst).
     worstByGroup.clear();
     worstUnpaintedByGroup.clear();
+    // WP-0 (S-9): the minute's observed window size is per-flush-window state, cleared with the
+    // buckets it describes -- a later minute starts from "no evidence" (reported as 1) again.
+    windowFramesByGroup.clear();
     slowEmittedBySession.clear();
     slowThrottledBySession.clear();
     lastFlushAt = at;
@@ -880,6 +977,12 @@ function noteWorkerStageMessage(store, msg = {}) {
       inFlightAgeMs: msg.inFlightAgeMs,
       rejectedSurfaceEpoch: msg.rejectedSurfaceEpoch,
       sweepSkipReason: msg.sweepSkipReason,
+      // WP-0 (S-11): the matched ack's two measured round-trip legs and the gate's window size ride
+      // the same 'typing-stage' message as the `inflight-acked` stage stamp (the store bounds and
+      // validates each one itself -- see note()'s branch).
+      hostRttMs: msg.hostRttMs,
+      mainRttMs: msg.mainRttMs,
+      windowFrames: msg.windowFrames,
     });
   }
   return true;

package/template/coding-task-manager/lib/usage-ledger/backfill.js

@@ -22,9 +22,11 @@ const path = require('node:path');
 
 const { statTranscriptSync } = require('../transcript-source');
 const { claudeFileIdentity } = require('./claude-parse');
+const { DSH_USAGE_DIR_NAME } = require('./dsh-parse');
 
 const CODEX_ROLLOUT_RE = /^rollout-.*\.jsonl$/;
 const CLAUDE_TRANSCRIPT_RE = /\.jsonl(\.bak)?$/i;
+const DSH_USAGE_FILE_RE = /\.jsonl$/i;
 // Directories that hold no usage facts (memory notes, tool results).
 const SKIP_DIR_NAMES = new Set(['memory', 'tool-results']);
 
@@ -74,16 +76,39 @@ function codexCorpusFiles(root, { listDir, realpath, onError = (_path, error) =>
   return out;
 }
 
+// Every `*.jsonl` directly under the dsh usage directory (WP-9). FLAT on purpose: the directory
+// holds one file per CTM session, named by the session id, and nothing else -- no project nesting, no
+// `subagents/` tree, no `workflows/`. A missing directory is normal (no dsh session has been routed
+// through the proxy yet).
+function dshCorpusFiles(root, { listDir, onError = (_path, error) => { throw error; } }) {
+  const out = [];
+  if (!root) return out;
+  let entries;
+  try { entries = listDir(root); } catch (err) { onError(root, err); return out; }
+  for (const entry of entries) {
+    if (!entry || !entry.isFile) continue;
+    if (!DSH_USAGE_FILE_RE.test(entry.name)) continue;
+    out.push(path.join(root, entry.name));
+  }
+  return out;
+}
+
 /**
  * The whole local corpus, newest first.
  *
- * @param {{claudeProjectsDir?: string, codexSessionsDir?: string}} roots
+ * @param {{claudeProjectsDir?: string, codexSessionsDir?: string, dshUsageDir?: string}} roots
+ *   `dshUsageDir` is `<dataDir>/dsh-usage`; `createBackfill` derives it from the ledger's own
+ *   database file when the caller does not name it.
  * @param {{listDir: (dir: string) => Array<{name: string, isFile: boolean, isDirectory: boolean}>,
  *          realpath: (p: string) => string|null}} fsOps
  * @returns {Array<{path: string, size: number, mtimeMs: number}>}
  */
-function listCorpusFiles({ claudeProjectsDir, codexSessionsDir } = {}, fsOps) {
-  const paths = [...claudeCorpusFiles(claudeProjectsDir, fsOps), ...codexCorpusFiles(codexSessionsDir, fsOps)];
+function listCorpusFiles({ claudeProjectsDir, codexSessionsDir, dshUsageDir } = {}, fsOps) {
+  const paths = [
+    ...claudeCorpusFiles(claudeProjectsDir, fsOps),
+    ...codexCorpusFiles(codexSessionsDir, fsOps),
+    ...dshCorpusFiles(dshUsageDir, fsOps),
+  ];
   const out = [];
   for (const filePath of paths) {
     try {
@@ -105,6 +130,7 @@ function createBackfill({
   store,
   ingestor,
   roots,
+  dshUsageDir = null,
   parserVersion,
   isShedding = () => false,
   isLiveClaimed = () => false,
@@ -117,6 +143,15 @@ function createBackfill({
 } = {}) {
   const STEP = Math.max(1, Math.floor(Number(stepBytes) || DEFAULT_STEP_BYTES));
   const CHECKPOINT_EVERY = Math.max(1, Math.floor(Number(checkpointEveryCalls) || DEFAULT_CHECKPOINT_EVERY_CALLS));
+  // The dsh corpus root (WP-9). The Claude/Codex roots are HOME-derived and handed in by the worker;
+  // dsh's is NOT (it lives under the CTM data dir), and the ledger's own database file is the one
+  // thing in this process that already names that directory -- `<dataDir>/usage.db`. Deriving it here
+  // keeps the worker entrypoint free of a second path source, and a caller that knows better (a test)
+  // can still pass `dshUsageDir` explicitly.
+  const DSH_USAGE_DIR = dshUsageDir
+    || (store && store.db && typeof store.db.name === 'string' && store.db.name !== ''
+      ? path.join(path.dirname(store.db.name), DSH_USAGE_DIR_NAME)
+      : null);
   let callsSinceCheckpoint = 0;
   let lastError = null;
   // Calls upserted so far for a file that takes several steps, so the queue row is
@@ -138,7 +173,7 @@ function createBackfill({
       lastError = { path: sourcePath, message, at: now() };
       if (scanErrors.length < 20) scanErrors.push(message);
     };
-    const files = listCorpusFiles(roots, { listDir, realpath, onError, statTranscript }).map((f) => ({ path: f.path, size: f.size }));
+    const files = listCorpusFiles({ ...(roots || {}), dshUsageDir: DSH_USAGE_DIR }, { listDir, realpath, onError, statTranscript }).map((f) => ({ path: f.path, size: f.size }));
     const runId = store.createRun({ parserVersion, reason, files });
     if (scanErrors.length) store.setRunStatus(runId, 'queued', { error: `scan incomplete: ${scanErrors.join('; ')}`.slice(0, 500) });
     return runId;
@@ -244,4 +279,4 @@ function createBackfill({
   return { ensureRun, step, status, lastFailure };
 }
 
-module.exports = { listCorpusFiles, createBackfill };
+module.exports = { listCorpusFiles, dshCorpusFiles, createBackfill };

package/template/coding-task-manager/lib/usage-ledger/client.js

@@ -221,7 +221,10 @@ function startUsageLedger({
 
   function requestSources(sources) {
     if (stopping || !Array.isArray(sources) || sources.length > PRIORITY_REQUEST_LIMIT) return { accepted: false, backlog: priority.size };
-    const valid = sources.filter((s) => s && typeof s.path === 'string' && path.isAbsolute(s.path) && ['claude', 'codex'].includes(s.provider));
+    // The main thread is the FIRST gate on a source batch; the live lane re-checks the same set
+    // (lib/usage-ledger/live.js `LIVE_PROVIDERS`). dsh was added by WP-9: its roots are the
+    // `<dataDir>/dsh-usage/<ctmSessionId>.jsonl` files the model proxy writes.
+    const valid = sources.filter((s) => s && typeof s.path === 'string' && path.isAbsolute(s.path) && ['claude', 'codex', 'dsh'].includes(s.provider));
     if (valid.length !== sources.length || priority.size + valid.filter((s) => !priority.has(s.path)).length > PRIORITY_QUEUE_CAP) return { accepted: false, backlog: priority.size };
     for (const source of valid) priority.set(source.path, { provider: source.provider, path: source.path });
     deliverSources();