create-walle 0.10.1 → 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

@@ -17,6 +17,12 @@ 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
@@ -34,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',
@@ -67,6 +86,14 @@ const STAGE_INDEX = new Map(STAGES.map((stage, index) => [stage, index]));
 // 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([
@@ -85,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);
@@ -172,6 +220,8 @@ function buildSlowInteractionRow(row, ktpMs, lastStage) {
     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'),
@@ -221,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();
@@ -320,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,
@@ -453,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 = '';
@@ -782,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,
@@ -811,4 +902,5 @@ function pendingInteractionIdsFor(byInputSeqMap, limit = 24) {
 
 module.exports = {
   createTypingInteractionTraceStore, STAGES, GATES, noteWorkerStageMessage, pendingInteractionIdsFor,
+  MAIN_SPANS_MIN_WINDOW_MS,
 };

package/template/coding-task-manager/lib/typing-worker-stages.js

@@ -25,6 +25,18 @@ function mergePendingInteractionIds(existing, incoming, limit = PENDING_IDS_LIMI
   return merged.slice(-limit);
 }
 
+// WP-4 (R-7, clock-free-tests-followups-r3-2026-10-24.html §5 R-7, §6 WP-4): keep the per-id
+// inputSeq map to exactly the ids `pending` still carries, oldest dropped first, capped at
+// `limit` -- the same "keep the most recent N" policy mergePendingInteractionIds applies to the
+// id list itself, so the two can never drift apart.
+function prunePendingInputSeqs(byId, pending, limit = PENDING_IDS_LIMIT) {
+  for (const id of Array.from(byId.keys())) {
+    if (!pending.includes(id)) byId.delete(id);
+  }
+  while (byId.size > limit) byId.delete(byId.keys().next().value);
+  return byId;
+}
+
 // Post ONE 'typing-stage' message covering every id currently pending for this session -- the
 // STAGES store's note() (lib/typing-interaction-trace.js) fans it out per-interactionId and is
 // idempotent per (interactionId, stage), so calling this more than once for the same boundary is
@@ -126,6 +138,22 @@ function armEchoPrediction(entry, msg) {
       entry.state.pendingTypingInteractionIds, msg.interactionIds,
     );
     entry.state.typingIdsAwaitingFeed = true;
+    // WP-4 (R-7): remember each pending id's OWN inputSeq here, so emitSettled can tell "the
+    // offered frame did not yet contain this key's echo" apart from "worker->main delivery or
+    // main-thread queueing" (the (i)/(ii) split design r3 §1.4 says today's stamps cannot make).
+    // Earliest seq wins for an id seen twice; the Math.max(0, ...) normalization is the same one
+    // headless-term-service.js's 'note-input' handler applies to msg.inputSeq.
+    const inputSeq = Math.max(0, Number(msg.inputSeq) || 0);
+    const seqById = entry.state.pendingTypingInputSeqById instanceof Map
+      ? entry.state.pendingTypingInputSeqById
+      : new Map();
+    for (const rawId of msg.interactionIds) {
+      const id = String(rawId);
+      if (!seqById.has(id) || inputSeq < seqById.get(id)) seqById.set(id, inputSeq);
+    }
+    entry.state.pendingTypingInputSeqById = prunePendingInputSeqs(
+      seqById, entry.state.pendingTypingInteractionIds,
+    );
   }
   const echo = msg.echo;
   if (!echo || !echo.interactionId || typeof echo.char !== 'string' || !echo.char) return;
@@ -177,9 +205,41 @@ function matchEchoPredictions(postTransport, sessionId, entry, data, now = Date.
   entry.state.echoPredictions = kept;
 }
 
+// WP-4 (R-7), called from headless-term-service.js's emitSettled ONLY after
+// _stateSyncEmitter.onMirrorUpdated returned `sent` -- the frame that just shipped is the first
+// one that could carry these keys' echoes, so stamp `frame-posted` for exactly the pending ids
+// the frame's `echoedThroughSeq` already covers (recorded inputSeq >= 1 AND <= offeredEchoSeq).
+// An id with NO recorded seq is treated as echoed, which preserves the pre-WP-4 blanket clear.
+// Returns the ids that remain un-echoed (recorded seq > offeredEchoSeq) so the caller can keep
+// only those pending -- that is what makes `emit-offered -> frame-posted` readable as "the
+// offered frame DID contain this key's echo" versus "the frame lacked it" instead of collapsing
+// both into one delivery gap.
+function noteFramePostedForEchoed(postTransport, sessionId, entry, offeredEchoSeq) {
+  const pending = Array.isArray(entry?.state?.pendingTypingInteractionIds)
+    ? entry.state.pendingTypingInteractionIds
+    : [];
+  const seqById = entry?.state?.pendingTypingInputSeqById;
+  const covering = Math.max(0, Number(offeredEchoSeq) || 0);
+  const echoedIds = [];
+  const remaining = [];
+  for (const rawId of pending) {
+    const id = String(rawId);
+    const seq = seqById instanceof Map && seqById.has(id) ? Number(seqById.get(id)) : 0;
+    if (seq > covering) remaining.push(id);
+    else echoedIds.push(id);
+  }
+  noteWorkerTypingStage(postTransport, sessionId, echoedIds, 'frame-posted', { offeredEchoSeq: covering });
+  // The echoed ids are delivered; only the un-echoed ones stay pending (and keep their seq).
+  if (seqById instanceof Map) {
+    for (const id of echoedIds) seqById.delete(id);
+  }
+  return remaining;
+}
+
 module.exports = {
   mergePendingInteractionIds,
   noteWorkerTypingStage,
+  noteFramePostedForEchoed,
   PENDING_IDS_LIMIT,
   isSingleGraphemeEcho,
   armEchoPrediction,