create-walle 0.10.0 → 0.10.2

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

@@ -22,6 +22,11 @@ function closedReceipt(stream) {
   return stream.closed ? Promise.resolve() : new Promise((resolve) => stream.once('close', resolve));
 }
 
+// A hit refreshes the entry's mtime (LRU order), but a shared 4 GiB cache does not need 5 s LRU
+// granularity: touching at most once per minute per file drops mtime-only writes by ~12x while keeping
+// 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 }) {
   const entries = new Map();
 
@@ -34,7 +39,12 @@ function createDecodedFrameCache({ withDecoder, cacheRoot, cacheMax, now, frameF
   }
 
   async function touch(handle, opts) {
-    const when = new Date(now(opts));
+    const st = await handle.stat();
+    const at = now(opts);
+    // The inode's mtime IS the last-touch record: entries are dropped from the map when their last
+    // lease closes, so anything in memory would reset on every acquisition cycle (model-sync, 5 s).
+    if (at - st.mtimeMs < TOUCH_MIN_INTERVAL_MS) return; // fresh enough: a touch this minute already happened
+    const when = new Date(at);
     await handle.utimes(when, when);
   }
 
@@ -241,4 +251,4 @@ function createDecodedFrameCache({ withDecoder, cacheRoot, cacheMax, now, frameF
   return { acquireDecodedFrame };
 }
 
-module.exports = { createDecodedFrameCache };
+module.exports = { createDecodedFrameCache, TOUCH_MIN_INTERVAL_MS };

package/template/coding-task-manager/lib/transcript-guard-job.js

@@ -24,12 +24,35 @@ const ARCHIVE_INTERVAL_MS = 60 * 60 * 1000;
 const SCRUB_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const ARCHIVE_TIMEOUT_MS = 60 * 60 * 1000; // a multi-GB compress + verify outlasts the 10 minute default
 
+// D-24/WP-6: the counters the `restoredOriginals` recovery result carries, flattened for the job result and
+// its log line. A cycle that skipped the phase (or a guard that never reported one) counts as all zeros.
+function _restoredCounts(restoredOriginals) {
+  const r = restoredOriginals || {};
+  const count = (v) => (Array.isArray(v) ? v.length : 0);
+  return {
+    units: Number(r.restoredUnits) || 0,
+    files: Number(r.restoredFiles) || 0,
+    linked: Number(r.linkedFromTrash) || 0,
+    decodedBytes: Number(r.decodedBytes) || 0,
+    deferredLowDisk: Number(r.deferredLowDisk) || 0,
+    targetExists: count(r.targetExists),
+    failed: count(r.failed),
+  };
+}
+
 // Scheduler job `transcript-archive` (D-16..D-19, D-23): archive idle transcripts, purge the trash after the
 // grace period, scrub archives once a day. `env` supplies what only the host knows:
 //   paths()            -> { projectsRoot, codexSessionsDir, walleSessionsDir, trashRoot, dataDir? }
 //   liveCtmSessionIds() -> ids of CTM sessions with a live PTY (a live session owns its transcript)
 //   hostShedding()     -> true while the load-pressure controller is shedding work
-function registerArchiveJob(scheduler, guard, env, shouldRun) {
+//   now()              -> (optional, test seam) ms clock; defaults to Date.now
+//   log(line)          -> (optional, test seam) one-line sink; defaults to console.log
+// WP-6 observability: a skipped cycle and an empty cycle used to look identical in the logs. Every primary run
+// now logs exactly one `ran` line, and a run that the `shouldRun` guard held back logs a `deferred` line at most
+// once per ARCHIVE_INTERVAL_MS -- with how long it has been waiting and why. A successful run resets the
+// deferral state. `deferReason` (5th argument, optional) is a function returning a short reason string ('' when
+// none); without it the reason is 'guard'.
+function registerArchiveJob(scheduler, guard, env, shouldRun, deferReason) {
   let first = true;
   let claudeAfter = '';
   let codexAfter = '';
@@ -37,6 +60,26 @@ function registerArchiveJob(scheduler, guard, env, shouldRun) {
   let claudeDigestAfter = '';
   let digestAfter = '';
   let lastScrubAt = 0;
+  const nowMs = () => (typeof env.now === 'function' ? Number(env.now()) : Date.now());
+  const log = typeof env.log === 'function' ? env.log : console.log;
+  // Deferral state (WP-6): startedAt = when the guard first held a cycle back, checks/reasons = what it saw,
+  // loggedAt = the last `deferred` line, so a long deferral is one line per interval, not one per tick.
+  const defer = { startedAt: 0, checks: 0, reasons: new Map(), loggedAt: 0 };
+  const resetDefer = () => { defer.startedAt = 0; defer.checks = 0; defer.reasons.clear(); defer.loggedAt = 0; };
+  const guardedShouldRun = typeof shouldRun === 'function' ? (...args) => {
+    if (shouldRun(...args)) return true;
+    const now = nowMs();
+    if (!defer.startedAt) defer.startedAt = now;
+    defer.checks += 1;
+    const reason = String((typeof deferReason === 'function' ? deferReason() : '') || 'guard');
+    defer.reasons.set(reason, (defer.reasons.get(reason) || 0) + 1);
+    if (!defer.loggedAt || now - defer.loggedAt >= ARCHIVE_INTERVAL_MS) {
+      defer.loggedAt = now;
+      const reasons = Array.from(defer.reasons, ([name, count]) => `${name}:${count}`).join(',');
+      log(`[transcript-archive] deferred ${Math.floor((now - defer.startedAt) / 60000)}m checks=${defer.checks} reasons=${reasons}`);
+    }
+    return false;
+  } : shouldRun;
   scheduler.register({
     name: 'transcript-archive',
     heavy: true,
@@ -44,10 +87,10 @@ function registerArchiveJob(scheduler, guard, env, shouldRun) {
     startDelayMs: 10 * 60 * 1000,
     priority: 9,
     pool: 'io',
-    shouldRun,
+    shouldRun: guardedShouldRun,
     run: async () => {
       if (typeof guard.isPrimary !== 'function' || !guard.isPrimary()) return { skipped: { not_primary: 1 } };
-      const now = Date.now();
+      const now = nowMs();
       const scrub = now - lastScrubAt >= SCRUB_INTERVAL_MS;
       const result = await guard.run('archive', {
         isPrimary: true,
@@ -77,9 +120,17 @@ function registerArchiveJob(scheduler, guard, env, shouldRun) {
         digestAfter = digest.nextCodexDigestAfter || '';
       }
       const { archived, bytesIn, bytesOut, trashed, purged, verified, corrupt, skipped } = result;
+      const restored = _restoredCounts(result.restoredOriginals);
+      const errors = (result.errors || []).length + (digest ? digest.errors.length : 0);
+      const waitedMs = defer.startedAt ? Math.max(0, nowMs() - defer.startedAt) : 0;
+      log(`[transcript-archive] ran archived=${Number(archived) || 0} restoredUnits=${restored.units} `
+        + `restoredFiles=${restored.files} linked=${restored.linked} decodedBytes=${restored.decodedBytes} `
+        + `deferredLowDisk=${restored.deferredLowDisk} targetExists=${restored.targetExists} `
+        + `restoreFailed=${restored.failed} errors=${errors} waitedMs=${waitedMs}`);
+      resetDefer();
       return {
         archived, bytesIn, bytesOut, trashed, purged, verified, corrupt, skipped, digested: digest ? digest.digested : 0,
-        errors: (result.errors || []).length + (digest ? digest.errors.length : 0),
+        errors, restored,
       };
     },
   });

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

@@ -0,0 +1,77 @@
+'use strict';
+
+// WP-2 (worker-transcript-link-derived-not-discovered-2026-10-25.html §5 D-4/D-7, §6, §8):
+// the resume preflight predicts a Claude worker's transcript path from (cwd, agent_session_id)
+// when agent_sessions.jsonl_path is empty, and must VERIFY the prediction before it links it --
+// a predicted path is not evidence. This module is the one place that verification happens.
+//
+// It is the only module besides lib/transcript-source.js that names a transcript path, and it
+// touches that path ONLY through transcript-source functions: `require('fs')` here would be a
+// new site for bin/transcript-open-lint.js (the read has to stay on the one sanctioned reader,
+// so archive/trash states, sibling `.zst` archives and the manifest all resolve identically).
+
+const transcriptSource = require('./transcript-source');
+
+// 64 KiB: enough to reach the session id in Claude Code's first record while never pulling a
+// multi-megabyte transcript into memory. It is NOT a bound on the first LINE: a measured 34 of
+// the 300 most recent real transcripts start with a single `queue-operation` record of 66 KB to
+// 387 KB, so the head routinely ends mid-record. Only the `sessionId` key is read out of it
+// (a bounded scan, never a JSON.parse of the whole record, which such a line would fail).
+const HEAD_BYTES = 65536;
+
+// Claude Code writes `"sessionId"` before any user content in the first record. Measured offset in
+// real transcripts: byte 87. The value is a session uuid, so no escapes are possible.
+const SESSION_ID_RE = /"sessionId"\s*:\s*"([^"]*)"/;
+
+/**
+ * Verify that `derivedPath` really is the transcript of `agentSessionId`.
+ *
+ * States (the caller reports them verbatim in a refusal, so the lead can tell "the file is not
+ * where Claude writes it" from "the file is there but belongs to someone else"):
+ *   plain       -- a local file whose first JSON line names this session (ok: true)
+ *   missing     -- nothing at the path (or the resolver itself threw)
+ *   archived    -- resolved to an archived/trashed source; resume restores those by path, so a
+ *                  predicted path that is not plain is never linked
+ *   unreadable  -- the head could not be read, or its first line names no sessionId at all
+ *                  (empty file, non-JSON bytes, a record without the key)
+ *   id-mismatch -- readable, but its sessionId is a different session
+ *
+ * @returns {Promise<{ok: boolean, state: string, headSessionId: string|null}>}
+ */
+async function verifyClaudeTranscriptAt(derivedPath, agentSessionId, {
+  resolveTranscriptSource = transcriptSource.resolveTranscriptSource,
+  readTranscriptHead = transcriptSource.readTranscriptHead,
+} = {}) {
+  let source = null;
+  try {
+    source = await resolveTranscriptSource(derivedPath);
+  } catch {
+    // expected: an unreadable/absent path is exactly the "no transcript there" answer
+    return { ok: false, state: 'missing', headSessionId: null };
+  }
+  if (!source || source.state === 'missing') return { ok: false, state: 'missing', headSessionId: null };
+  // Anything not plain (archived, trashed, ...) is reported as archived: the resolve path below
+  // restores an archived transcript at the LINKED path, and a derived path has no link yet.
+  if (source.state !== 'plain') return { ok: false, state: 'archived', headSessionId: null };
+
+  let head = '';
+  try {
+    head = String(await readTranscriptHead(derivedPath, HEAD_BYTES));
+  } catch {
+    // expected: an unreadable/absent file -- unverifiable, never a link
+    return { ok: false, state: 'unreadable', headSessionId: null };
+  }
+
+  // Scan the first line only (or the whole head when it is one unterminated line, i.e. the record
+  // is longer than HEAD_BYTES). Never parse the record: a first line over 64 KiB is normal and
+  // would throw. The key precedes user content, so the first match is the record's own session id.
+  const firstLine = head.split('\n')[0];
+  const match = SESSION_ID_RE.exec(firstLine);
+  if (!match) return { ok: false, state: 'unreadable', headSessionId: null };
+
+  const headSessionId = match[1];
+  if (headSessionId !== String(agentSessionId || '')) return { ok: false, state: 'id-mismatch', headSessionId };
+  return { ok: true, state: 'plain', headSessionId };
+}
+
+module.exports = { verifyClaudeTranscriptAt };

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

@@ -42,14 +42,18 @@ function _row(input) {
 const ALL_STATES = Object.freeze([...ARCHIVE_STATES, ...LEGACY_STATES]);
 
 // WP-9. Rows in any of `states`, optionally changed before `olderThanMs` (state_changed_at_ms) or with a source
-// mtime before `mtimeBeforeMs`. orderBy: 'mtime' (oldest source first) | 'verified' (least recently verified
-// first) | 'changed' (oldest state change first, the default). Bounded to 2000 rows.
+// mtime before `mtimeBeforeMs`. orderBy: 'mtime' (oldest source first) | 'mtime_desc' (newest source first, the
+// WP-2 recovery order) | 'verified' (least recently verified first) | 'changed' (oldest state change first, the
+// default). Bounded to 2000 rows.
 function listByState(db, { states = [], olderThanMs = 0, mtimeBeforeMs = 0, orderBy = 'changed', limit = 500 } = {}) {
   const wanted = (states || []).map(String).filter((s) => ALL_STATES.includes(s));
   if (!wanted.length) return [];
   const bounded = Math.max(1, Math.min(2000, Number(limit) || 500));
-  const order = { mtime: 'source_mtime_ms, source_path', verified: 'last_verified_at_ms, source_path' }[orderBy]
-    || 'state_changed_at_ms, source_path';
+  const order = {
+    mtime: 'source_mtime_ms, source_path',
+    mtime_desc: 'source_mtime_ms DESC, source_path',
+    verified: 'last_verified_at_ms, source_path',
+  }[orderBy] || 'state_changed_at_ms, source_path';
   const marks = wanted.map(() => '?').join(',');
   const where = [`state IN (${marks})`];
   const params = [...wanted];

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

@@ -22,7 +22,7 @@ const { finished } = require('node:stream/promises');
 const zlib = require('node:zlib');
 const { decodeFrame, waitForDecodedFrameClose, decompressParams } = require('./transcript-archive-codec');
 const { getDataDir } = require('./data-dir');
-const { createDecodedFrameCache } = require('./transcript-frame-cache');
+const { createDecodedFrameCache, TOUCH_MIN_INTERVAL_MS } = require('./transcript-frame-cache');
 
 const CACHE_DIR_NAME = 'transcript-archive-cache';
 const DEFAULT_CACHE_MAX_BYTES = 4 * 1024 * 1024 * 1024;
@@ -1109,8 +1109,13 @@ function _decodeFrameSync(archive, index, opts, learnLength) {
     // The cached bytes are this request's decoded bytes: charge them before returning, so a warm
     // cache hit is accounted for exactly like a cold decode would be.
     if (ledger && learnLength) _chargeLearnedDecoded(ledger, `${archive.cacheKey}:${index}`, hit.size);
-    const when = new Date(_now(opts));
-    fs.utimesSync(file, when, when);
+    // Same rule as the async cache's touch (D-10b): the hit's own mtime is the last-touch record, so a
+    // file touched in the last minute is left alone instead of paying a utimes write per read.
+    const at = _now(opts);
+    if (at - hit.mtimeMs >= TOUCH_MIN_INTERVAL_MS) {
+      const when = new Date(at);
+      fs.utimesSync(file, when, when);
+    }
     return file;
   }
   const max = _cacheMax(opts);

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

@@ -59,6 +59,11 @@ function setErrorSink(sink) {
 }
 const { shouldYieldAfterChunk } = require('./conversation-import/chunk-runner');
 const { createImportMetrics } = require('./conversation-import/import-metrics');
+// WP-2 (D-4): the ingest lane already parses every record, so the agent's own session name
+// (`ai-title` / `custom-title`) is captured here and applied at the ingestJsonlFile choke point.
+const { extractTitleSignalFromRecord } = require('./session-title-signals');
+const { getAgentCapabilities } = require('./agent-capabilities');
+const { applyAgentTitleSignals } = require('./agent-title-apply');
 
 const PARSER_VERSION = 3;
 const DEFAULT_INITIAL_TAIL_BYTES = 2 * 1024 * 1024;
@@ -1008,6 +1013,16 @@ function claudeMessagesFromEntry(entry, state = {}) {
   if (queued) entry = queued;
   if (shouldDropInheritedClaudeEntry(entry, state)) return [];
 
+  // WP-2 (D-4): a `custom-title`/`ai-title` record produces no rows, but CTM is already reading
+  // every record here — keep the last non-inherited one of each kind so ingestJsonlFile can apply
+  // it (lib/agent-title-apply.js). Last wins; an ai-title never clears a custom-title.
+  const titleSignal = extractTitleSignalFromRecord(entry);
+  if (titleSignal.userTitle || titleSignal.providerTitle) {
+    if (!state.agentTitleSignals) state.agentTitleSignals = {};
+    if (titleSignal.userTitle) state.agentTitleSignals.customTitle = titleSignal.userTitle;
+    else state.agentTitleSignals.aiTitle = titleSignal.providerTitle;
+  }
+
   if (entry.type === 'system' && entry.subtype === 'compact_boundary'
       && structuredCapture.structuredCaptureEnabled()) {
     const compactMeta = entry.compactMetadata || {};
@@ -1458,6 +1473,8 @@ function healSelfLinkedTranscriptRows(db, agentSessionId, ownerCtmSessionId) {
   try {
     const f = db.prepare('UPDATE transcript_files SET ctm_session_id=? WHERE agent_session_id=? AND ctm_session_id=?').run(owner, agentId, agentId);
     const e = db.prepare('UPDATE transcript_events SET ctm_session_id=? WHERE agent_session_id=? AND ctm_session_id=?').run(owner, agentId, agentId);
+    // Rows whose owner changed used to change silently. Ids only, truncated; never a path, never content.
+    if (f.changes || e.changes) console.log(`[transcript-owner] re-keyed self-link agent=${agentId.slice(0, 8)} -> owner=${owner.slice(0, 8)} files=${f.changes || 0} events=${e.changes || 0}`);
     return { files: f.changes || 0, events: e.changes || 0 };
   } catch { return { files: 0, events: 0 }; }
 }
@@ -1688,6 +1705,10 @@ function parseTranscriptTail(options = {}) {
   return {
     ...base,
     messages: projected.messages,
+    // WP-2 (D-4): the agent-name signal rides with the parsed window so both the inline ingest
+    // and the read-pool → preParsed apply path (workers/read-pool-worker.js parseTranscriptDelta)
+    // carry it without a second read.
+    agentTitleSignals: state.agentTitleSignals || null,
     metrics,
     read: { nextOffset: read.nextOffset, partialLine: read.partialLine || '', bytesRead: read.bytesRead },
   };
@@ -2034,6 +2055,8 @@ function _ingestJsonlFileV2(db, options = {}) {
     agentSessionId,
     generation: 1,
     fileSize: stat.size,
+    // WP-2 (D-4): the parsed window's agent-name signal (title records produce no rows).
+    agentTitleSignals: (preParsed || parsed).agentTitleSignals || null,
     oversizedNonRetainedRecordsSkipped,
     metrics: {
       ...(parsed.metrics || {}),
@@ -2466,6 +2489,8 @@ function _ingestJsonlFile(db, options = {}) {
 
   let read;
   let messages;
+  // WP-2 (D-4): the agent-name signal (title records produce no rows) from whichever parse ran.
+  let agentTitleSignals = null;
   if (preParsed) {
     // Off-thread parse already produced the delta (parseTranscriptTail) — apply is writes only.
     read = {
@@ -2474,6 +2499,7 @@ function _ingestJsonlFile(db, options = {}) {
       bytesRead: Number(preParsed.read?.bytesRead || 0),
     };
     messages = Array.isArray(preParsed.messages) ? preParsed.messages : [];
+    agentTitleSignals = preParsed.agentTitleSignals || null;
   } else {
     const maxBytes = Math.min(
       Math.max(0, readCeiling - cursor.offset),
@@ -2501,6 +2527,7 @@ function _ingestJsonlFile(db, options = {}) {
     });
     metrics.parseMs += Math.max(0, Date.now() - parseStartedAt);
     messages = projected.messages;
+    agentTitleSignals = state.agentTitleSignals || null;
     metrics.recordsParsed += projected.recordsParsed;
   }
   metrics.sourceBytesRead += Number(read.bytesRead || 0);
@@ -3266,6 +3293,7 @@ function _ingestJsonlFile(db, options = {}) {
       values: insertChunkStatementCounts,
     },
     overBudget: elapsedMs > IMPORT_SLICE_HARD_MAX_MS,
+    agentTitleSignals,
     messages: partial ? messages.slice(0, processedCount) : messages,
     rowCursorDelta: {
       ctmSessionId,
@@ -3367,6 +3395,18 @@ function ingestJsonlFile(db, options = {}) {
     result,
     coreDb: options.coreDb,
   });
+  // WP-2 (D-4/D-5/D-9, S-17): the single choke point for every ingest (event delta, targeted
+  // import, v13 migration) — apply the agent's own name to its CTM row. Gated on the provider
+  // declaring it reads ai-titles; a refused delta applied nothing, so it has no signal to apply.
+  // D-11: the caller publishes the outcome (titleApply) on the main thread.
+  if (result && !result.refused && result.agentTitleSignals && ownerCtmSessionId
+      && getAgentCapabilities(normalizeProvider(options.provider, filePath)).titleSpec?.readsAiTitle) {
+    result.titleApply = applyAgentTitleSignals(options.coreDb || db, {
+      ctmSessionId: ownerCtmSessionId,
+      provider: normalizeProvider(options.provider, filePath),
+      ...result.agentTitleSignals,
+    });
+  }
   return result;
 }
 function dryRunTranscriptByteBackfill(db, options = {}) {

package/template/coding-task-manager/lib/tunnel-lane-governor.js

@@ -65,10 +65,13 @@ function _socketBytesWritten(socket) {
 // The traffic class of a message, from the channel the caller already resolved (`opts.channel`
 // || the decoded `type`) plus the class `_wsSend` may have resolved explicitly (`opts.class` —
 // the live-status heartbeat sends `session-activity` as `{ class: 'stream', channel: 'heartbeat' }`).
-// `classifyWsPayload` stays the one authority for the class split.
+// T2 (docs/walle-turn-lifecycle-delivery-2026-10-26.html §3): the classification is delegated with
+// the ACTUAL payload plus the caller's class and channel — a synthetic `{ type: channel }` object
+// threw away the lifecycle fields (recordType/partType) that make a walle-transcript-append opener
+// a control notification rather than a replaceable sample, which in economy let progress replace a
+// queued opener. `classifyWsPayload` stays the one authority for the class split.
 function _channelClass(channel, payload, cls) {
-  const ch = String(channel || '');
-  return classifyWsPayload(ch ? { type: ch } : payload, cls);
+  return classifyWsPayload(payload, cls, channel);
 }
 
 function createTunnelLaneGovernor({ now = Date.now, setIntervalFn = setInterval, clearIntervalFn = clearInterval, send } = {}) {

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

@@ -1,5 +1,12 @@
 'use strict';
 
+// WP-3 (composer-freeze-followups-load-sigstop-attribution-2026-10-20.html §5 D-C1/D-C2):
+// READ THE STAGE NAMES HONESTLY. Every stage after `pty-written` EXCEPT `echo-bytes`/`echo-cell`
+// is stamped on the session's whole pending id set by the FIRST output/feed/frame after the key
+// -- "first X after the key", which is approximate, not causal (D-C1; the pty-output leg lands
+// 0-3 ms after pty-written in 14 of 18 retained slow rows, which no agent CLI can do).
+// `echo-bytes`/`echo-cell` are the only per-key matches today, and they are shadow-only
+// instrumentation for WP-4/WP-5's decision (D-C2) -- nothing reads them as truth yet.
 const STAGES = Object.freeze([
   'browser-keydown',
   'server-received',
@@ -10,7 +17,18 @@ const STAGES = Object.freeze([
   // echoed). Required (not in OPTIONAL_STAGES below), same as 'pty-written'.
   'host-posted',
   'pty-written',
+  // WP-4 (clock-free-tests-followups-r4-2026-10-24.html §5 R-9, §6.5): the host's OWN receipt
+  // of the PTY batch -- the instant its first byte entered the mirror-feed coalescer, carried on
+  // the 'feed' op as `hostReceivedAt`. `pty-output` below is the MAIN-thread arrival, which is a
+  // different clock hop; neither is causal for the other (every post-`pty-written` stage is
+  // "first X after the key"). Optional, like its neighbours.
+  'host-pty-data',
   'pty-output',
+  // WP-3 D-C2: the two shadow, per-key echo matchers -- VS Code typeahead's byte rule and
+  // mosh's cell rule (see lib/typing-worker-stages.js, which runs them in the mirror). Both are
+  // OPTIONAL (OPTIONAL_STAGES below), so neither can move lastCompletedBoundary.
+  'echo-bytes',
+  'echo-cell',
   // WP-0 (composer-freeze-stop-and-wait-emitter-2026-09-16.html §5 D-1, §6 API specs, §8 WP-0):
   // four stages stamped INSIDE the worker/pool-host, between `pty-output` and `mirror-revision`
   // -- the 16.1 s gap the census found with zero instrumentation coverage (§1.5). All four are
@@ -22,6 +40,19 @@ const STAGES = Object.freeze([
   'mirror-written',
   'emit-offered',
   'emit-refused',
+  // WP-4 (clock-free-tests-followups-r3-2026-10-24.html §5 R-7, §6 WP-4): stamped by the worker
+  // (lib/typing-worker-stages.js's noteFramePostedForEchoed, called from emitSettled) for exactly
+  // the pending ids the frame that just SHIPPED already covers (their own inputSeq <= that
+  // frame's echoedThroughSeq, carried as `offeredEchoSeq`). Optional, like its neighbours above:
+  // a key whose frame is refused, or that is delivered without ever being pending, never gets it.
+  'frame-posted',
+  // WP-4 (clock-free-tests-followups-r4-2026-10-24.html §5 R-7/R-8, §6.5): the FIRST main-thread
+  // touch of the frame that carries this key's echo (`session-host-manager.js`'s
+  // `_stampMainArrival`), split out from `mirror-revision` (where main stamped the interaction)
+  // to price the receiver-loop leg alone. Carries `mainSpans` (R-8) -- the top recent main-thread
+  // spans overlapping [frame-posted.at, frame-arrived.at]. Optional, same reason as
+  // `frame-posted`: a key whose frame was refused, or that never had a pending row, never gets it.
+  'frame-arrived',
   'mirror-revision',
   'frame-sent',
   'socket-received',
@@ -52,7 +83,19 @@ const STAGE_INDEX = new Map(STAGES.map((stage, index) => [stage, index]));
 // D-1: stages that may be absent from an otherwise-complete row without that absence meaning
 // "the interaction stalled here" -- the sequential boundary walk in note() skips these rather
 // than treating a miss as the end of the row's progress (see the walk below).
-const OPTIONAL_STAGES = new Set(['pty-output', 'worker-received', 'mirror-written', 'emit-offered', 'emit-refused']);
+// WP-3 D-C2: 'echo-bytes'/'echo-cell' join them -- they are shadow stamps most keys never get.
+const OPTIONAL_STAGES = new Set([
+  'pty-output', 'worker-received', 'mirror-written', 'emit-offered', 'emit-refused',
+  // WP-4 (R-7): 'frame-posted' joins them -- its absence must never move
+  // lastCompletedBoundary/missingBoundary for a row that shipped its frame before anything was
+  // pending (the common case).
+  'frame-posted',
+  // WP-4 r4 (R-7/R-8/R-9): 'frame-arrived' and 'host-pty-data' join for the same reason -- both
+  // are first-touch stamps on paths most interactions never take (a refused frame; a host whose
+  // coalescer delivered before any keystroke was pending), so neither may end the boundary walk.
+  'frame-arrived', 'host-pty-data',
+  'echo-bytes', 'echo-cell',
+]);
 const WORKLOAD_FIELDS = Object.freeze([
   'rawBatchClass', 'synchronizedFrameCount', 'mirrorChangedRows', 'frameKind',
   'frameBytes', 'queuedBytes', 'queueDepth', 'codexRepairActions',
@@ -69,6 +112,27 @@ function boundedText(value, max = 80) {
   return String(value || '').replace(/[^A-Za-z0-9_.:-]/g, '').slice(0, max);
 }
 
+// WP-4 r4 (R-8, §6.5): R-8's floor -- mainSpans are computed only for a frame-posted ->
+// frame-arrived window at or above this, so the fast path allocates nothing.
+const MAIN_SPANS_MIN_WINDOW_MS = 15;
+
+// The `frame-arrived` record's mainSpans shape: a malformed entry is DROPPED rather than repaired
+// into a plausible-looking 0 -- a reader may only ever see entries the sender actually produced.
+// Name is bounded to 120 chars and overlapMs floored to a non-negative integer, and the record is
+// the TOP 3 by overlapMs whatever order the sender used: the ranking is part of this record's
+// contract (§6.5), not of the sender's good manners.
+function sanitizeMainSpans(rawSpans) {
+  const mainSpans = [];
+  for (const entry of Array.isArray(rawSpans) ? rawSpans : []) {
+    if (!entry || typeof entry !== 'object') continue;
+    const name = String(entry.name == null ? '' : entry.name).slice(0, 120);
+    if (!name) continue;
+    mainSpans.push({ name, overlapMs: Math.max(0, Math.floor(finite(entry.overlapMs))) });
+  }
+  mainSpans.sort((a, b) => b.overlapMs - a.overlapMs);
+  return mainSpans.slice(0, 3);
+}
+
 function percentile(values, pct) {
   if (!values.length) return 0;
   const sorted = values.slice().sort((a, b) => a - b);
@@ -99,6 +163,23 @@ function stageMsFromKeydown(row, stage) {
   return stageDelta(row, stage, 'browser-keydown');
 }
 
+// WP-3 D-C3: an expired row must not report an OPTIONAL stage as "where it got to" -- the
+// reverse scan it used to do picked `pty-output` over `pty-written` for a key that stalled
+// after a stray output chunk (I-6 / R9). `lastObservedStage` is therefore the last observed
+// REQUIRED stage (fallback `browser-keydown`), and the last observed OPTIONAL stage is reported
+// separately as `lastOptionalStage` ('' when there is none) so the shadow echo stamps stay
+// readable without ever being mistaken for progress.
+function observedStageSplit(row) {
+  let lastObservedStage = 'browser-keydown';
+  let lastOptionalStage = '';
+  for (const stage of STAGES) {
+    if (!row.stages[stage]) continue;
+    if (OPTIONAL_STAGES.has(stage)) lastOptionalStage = stage;
+    else lastObservedStage = stage;
+  }
+  return { lastObservedStage, lastOptionalStage };
+}
+
 // D-7/S-14: builds the flat, ≤24-key `typing-interaction-slow` payload from the SAME stage
 // vector `note()`/`begin()` already maintain -- no second clock, no parallel bookkeeping.
 // `lastStage` is passed explicitly by the two callers below rather than read from
@@ -118,6 +199,10 @@ function buildSlowInteractionRow(row, ktpMs, lastStage) {
     printable: row.printable === true,
     ktpMs: Math.max(0, finite(ktpMs, 0)),
     lastStage: lastStage || row.lastCompletedBoundary || 'browser-keydown',
+    // WP-3 D-C3: the last OPTIONAL stage observed for this row ('' when none) -- carried on
+    // every slow/worst vector so `lastStage` can stay required-only without losing the shadow
+    // echo stamps.
+    lastOptionalStage: observedStageSplit(row).lastOptionalStage,
     dropReason: dropped ? boundedText(dropped.reason, 64) : '',
     gate: refused ? refused.gate : '',
     gateTop: refused ? refused.gate : '',
@@ -131,7 +216,12 @@ function buildSlowInteractionRow(row, ktpMs, lastStage) {
     serverReceivedMs: stageMsFromKeydown(row, 'server-received'),
     ptyWrittenMs: stageMsFromKeydown(row, 'pty-written'),
     ptyOutputMs: stageMsFromKeydown(row, 'pty-output'),
+    // WP-3 D-C2: the shadow per-key matchers' legs, same keydown rule as ptyOutputMs above.
+    echoBytesMs: stageMsFromKeydown(row, 'echo-bytes'),
+    echoCellMs: stageMsFromKeydown(row, 'echo-cell'),
     mirrorRevisionMs: stageMsFromKeydown(row, 'mirror-revision'),
+    // WP-4 (R-7): the shipped-frame leg, same keydown rule as mirrorRevisionMs above.
+    framePostedMs: stageMsFromKeydown(row, 'frame-posted'),
     frameSentMs: stageMsFromKeydown(row, 'frame-sent'),
     socketReceivedMs: stageMsFromKeydown(row, 'socket-received'),
     applyStartedMs: stageMsFromKeydown(row, 'apply-started'),
@@ -181,6 +271,9 @@ function createTypingInteractionTraceStore(options = {}) {
   // emitting workerLoopMaxMs: 0 / host: {0,0,0} exactly as before this WP.
   const getRollupExtras = typeof options.getRollupExtras === 'function' ? options.getRollupExtras : null;
   const rollupIntervalMs = Math.max(1000, finite(options.rollupIntervalMs, 60_000));
+  // WP-4 r4 (R-8): `(startMs, endMs) => [{ name, overlapMs }]`, a pure read of the caller's
+  // main-thread span ring (server.js `_mainSpansForWindow`). Absent -> no spans are computed.
+  const mainSpansForWindow = typeof options.mainSpansForWindow === 'function' ? options.mainSpansForWindow : null;
   const rows = new Map();
   const publicRows = new Map();
   const pendingClosed = new Map();
@@ -280,6 +373,8 @@ function createTypingInteractionTraceStore(options = {}) {
       workerReceivedMs: stageDelta(row, 'worker-received', 'browser-keydown'),
       mirrorWrittenMs: stageDelta(row, 'mirror-written', 'browser-keydown'),
       emitOfferedMs: stageDelta(row, 'emit-offered', 'browser-keydown'),
+      // WP-4 (R-7): the shipped-frame leg for the closed interaction, read the same way.
+      framePostedMs: stageMsFromKeydown(row, 'frame-posted'),
       gate,
       gateHoldMs,
       clientId: row.clientId,
@@ -302,12 +397,14 @@ function createTypingInteractionTraceStore(options = {}) {
 
   function captureExpiredInteraction(row, at) {
     if (row.stages.painted) return;
-    const lastObservedStage = STAGES.slice().reverse().find(stage => row.stages[stage]) || 'browser-keydown';
+    // WP-3 D-C3: required-only `lastObservedStage` + a separate `lastOptionalStage` (I-6/R9).
+    const { lastObservedStage, lastOptionalStage } = observedStageSplit(row);
     const ageMs = Math.max(0, at - row.startedAt);
     pushBounded(pendingExpired, rollupGroupKey(row.sessionId, row.agentType), {
       ageMs,
       clientId: row.clientId,
       lastObservedStage,
+      lastOptionalStage,
     });
     windowExpiredHistory.push({ at });
     if (windowExpiredHistory.length > WINDOW_HISTORY_CAP) windowExpiredHistory.shift();
@@ -411,10 +508,43 @@ function createTypingInteractionTraceStore(options = {}) {
           rejectedSurfaceEpoch: Math.max(0, finite(event.rejectedSurfaceEpoch)),
           sweepSkipReason: boundedText(event.sweepSkipReason, 24),
         };
+      } else if (stage === 'emit-offered' || stage === 'frame-posted') {
+        // WP-4 (R-7): these two stages carry the OFFERED/SHIPPED frame's echoedThroughSeq, so a
+        // reader can compare it against this row's own `inputSeq` (set once by begin(), above) --
+        // that comparison is what separates "the offered frame did not yet contain this key's
+        // echo" from "worker->main delivery / main-thread queueing". A sender that carries no seq
+        // records `{ at }` alone: an absent seq must never read as a real 0.
+        // First-wins like every other stage: the `!previous || at < previous.at` guard above owns
+        // idempotency, so a later note never rewrites this record.
+        const offeredEchoSeq = event.offeredEchoSeq;
+        row.stages[stage] = offeredEchoSeq == null
+          ? { at }
+          : { at, offeredEchoSeq: Math.max(0, Math.floor(finite(offeredEchoSeq))) };
+      } else if (stage === 'frame-arrived') {
+        // WP-4 r4 (R-8, §6.5): the arrival stamp may carry `mainSpans` -- the top ≤3 main-thread
+        // spans overlapping [frame-posted.at, frame-arrived.at], each `{ name, overlapMs }`.
+        // Same shape rule as `offeredEchoSeq` above: no array offered means `{ at }` alone (the
+        // store may still attach computed spans below, once both stamps are present).
+        row.stages[stage] = Array.isArray(event.mainSpans)
+          ? { at, mainSpans: sanitizeMainSpans(event.mainSpans) }
+          : { at };
       } else {
         row.stages[stage] = { at };
       }
     }
+    // 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
+    // the SECOND of the two lands, once per row; the window is in the past either way, and the
+    // span ring (lib/perf-tracker.js, 3 s+) still holds it.
+    if (mainSpansForWindow && (stage === 'frame-posted' || stage === 'frame-arrived')) {
+      const arrival = row.stages['frame-arrived'];
+      const postedAt = row.stages['frame-posted']?.at;
+      if (arrival && !arrival.mainSpans && Number.isFinite(postedAt)
+          && arrival.at - postedAt >= MAIN_SPANS_MIN_WINDOW_MS) {
+        arrival.mainSpans = sanitizeMainSpans(mainSpansForWindow(postedAt, arrival.at));
+      }
+    }
     if (stage === 'painted' && !previous) captureClosedInteraction(row);
     row.updatedAt = Math.max(row.updatedAt, at);
     row.lastCompletedBoundary = '';
@@ -740,6 +870,9 @@ function noteWorkerStageMessage(store, msg = {}) {
       sessionId: msg.sessionId,
       stage: msg.stage,
       at: msg.at,
+      // WP-4 (R-7): the offered/shipped frame's echoedThroughSeq rides the same worker message as
+      // the stage stamp, so emit-offered/frame-posted rows can be read against their inputSeq.
+      offeredEchoSeq: msg.offeredEchoSeq,
       gate: msg.gate,
       inFlightSeq: msg.inFlightSeq,
       inFlightKind: msg.inFlightKind,
@@ -769,4 +902,5 @@ function pendingInteractionIdsFor(byInputSeqMap, limit = 24) {
 
 module.exports = {
   createTypingInteractionTraceStore, STAGES, GATES, noteWorkerStageMessage, pendingInteractionIdsFor,
+  MAIN_SPANS_MIN_WINDOW_MS,
 };