create-walle 0.9.28 → 0.9.30

package/template/claude-task-manager/lib/desktop-fork.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/*
+ * desktop-fork.js — server-side orchestrator for converting a read-only Claude Desktop
+ * conversation into a resumable Claude Code session (snapshot-and-fork).
+ *
+ * It is the meat behind POST /api/claude-desktop/convert, factored out of the HTTP handler
+ * so it can be unit-tested against a real DB without a live server. It composes the two
+ * lower layers:
+ *   - lib/claude-desktop-sessions.materializeForkTranscript — writes a valid, resumable
+ *     `.jsonl` from the conversation's cached text (Step 1), and
+ *   - db.getForkForDesktopUuid / db.upsertAgentSessionIdentity — the dedup link keyed on the
+ *     originating Desktop uuid (Step 2).
+ *
+ * Conversion is explicit and one-way: only text carries over (Desktop never recorded tool
+ * calls / working dir), and continuing the fork never syncs back to Desktop. Dedup makes it
+ * idempotent — the same conversation is never forked twice; a fork whose transcript was
+ * deleted self-heals by re-materializing under the same fork id.
+ */
+
+const fs = require('fs');
+const crypto = require('crypto');
+
+const claudeDesktopSessions = require('./claude-desktop-sessions');
+
+function _firstUserText(session) {
+  const m = (Array.isArray(session.messages) ? session.messages : []).find((x) => x.role === 'user');
+  return m ? String(m.text || '').trim().slice(0, 200) : '';
+}
+
+function _userMsgCount(session) {
+  return (Array.isArray(session.messages) ? session.messages : []).filter((m) => m.role === 'user').length;
+}
+
+function convertDesktopConversation(opts = {}) {
+  const session = opts.session;
+  const cwd = opts.cwd;
+  const db = opts.db || require('../db');
+  if (!session || !session.uuid) throw new Error('desktop-fork: session with uuid is required');
+  if (!cwd) throw new Error('desktop-fork: cwd is required');
+
+  const desktopUuid = session.uuid;
+
+  // Idempotency / self-heal: a conversation already linked to a fork is never re-forked. If
+  // that fork's transcript is still on disk, return it untouched. If the transcript was
+  // deleted, re-materialize under the SAME fork id (the link stays valid).
+  const existing = db.getForkForDesktopUuid(desktopUuid);
+  if (existing && existing.jsonl_path && fs.existsSync(existing.jsonl_path)) {
+    return { forkSessionId: existing.agent_session_id, jsonlPath: existing.jsonl_path, cwd, existing: true };
+  }
+
+  const forkSessionId = (existing && existing.agent_session_id)
+    || (typeof opts.forkUuidFn === 'function' ? opts.forkUuidFn() : crypto.randomUUID());
+
+  const { jsonlPath, lineCount } = claudeDesktopSessions.materializeForkTranscript(session, {
+    forkSessionId,
+    cwd,
+    desktopUuid,
+    version: opts.version,
+    homeDir: opts.homeDir,
+    claudeConfigDir: opts.claudeConfigDir,
+    uuidFn: opts.lineUuidFn,
+    now: opts.now,
+  });
+
+  // Record (or re-affirm) the dedup link. COALESCE on the upsert preserves any ctm_session_id
+  // the importer may have attached if the JsonlWatcher raced us to the new transcript.
+  db.upsertAgentSessionIdentity(forkSessionId, {
+    provider: 'claude',
+    jsonlPath,
+    projectPath: cwd,
+    model: session.model || '',
+    firstMessage: _firstUserText(session),
+    userMsgCount: _userMsgCount(session),
+    forkedFromDesktopUuid: desktopUuid,
+  });
+
+  return { forkSessionId, jsonlPath, cwd, lineCount, existing: false };
+}
+
+module.exports = { convertDesktopConversation };

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

@@ -35,6 +35,9 @@ const {
   MAX_SNAPSHOT_SCROLLBACK_ROWS,
   normalizeSnapshotScrollbackRows,
 } = require('./terminal-snapshot-options');
+const { createFrameEmitter } = require('./state-sync/frame-emitter');
+const { noteOutput: _stateSyncNoteOutput, isFlooding: _stateSyncIsFlooding, settleDelay: _stateSyncSettleDelay } = require('./state-sync/frame-rate');
+const { serializeRow } = require('./state-sync/row-serializer');
 
 let postMessage = () => {};
 
@@ -53,6 +56,125 @@ const VERIFY_FAIL_COOLDOWN_MS = 30 * 1000;
 // Per-session headless terminal instances + state
 const terminals = new Map(); // sessionId -> { term, serialize, state }
 
+// --- Option B state-sync (DEFAULT-ON; opt out with CTM_STATE_SYNC=0 ⇒ this is entirely inert and the
+// byte-stream path runs unchanged). The worker process inherits CTM_STATE_SYNC from the server's env, so
+// this default MUST match the server's STATE_SYNC_ENABLED default (server.js) — a mismatch desyncs the
+// frame contract between the two processes. ---
+const STATE_SYNC_ENABLED = process.env.CTM_STATE_SYNC !== '0';
+// VIEWPORT-ONLY (mosh model: sync the visible screen, NOT scrollback). The cell-diff positions every
+// row by absolute CUP (\x1b[r;1H), and the client xterm is only viewport-height — so any synced row past
+// the viewport height clamps to the bottom row, smashing scrollback + viewport into garble and misplacing
+// the composer cursor (the real-Claude/Codex "unusable, can't type" bug). The grid MUST equal the viewport.
+// Live client scrollback accumulation is a separate concern (handled by snapshot/restore + the byte path);
+// re-enabling a positive value here re-introduces the clamp garble, so default 0 and treat >0 as experimental.
+const STATE_SYNC_SCROLLBACK_ROWS = Math.max(0, Number(process.env.CTM_STATE_SYNC_SCROLLBACK_ROWS) || 0);
+const STATE_SYNC_FRAME_MIN_MS = Math.max(8, Number(process.env.CTM_STATE_SYNC_FRAME_INTERVAL_MS) || 16);
+const STATE_SYNC_FRAME_MAX_MS = Math.max(STATE_SYNC_FRAME_MIN_MS, Number(process.env.CTM_STATE_SYNC_FRAME_MAX_MS) || 50);
+// Trailing-debounce settle: emit the SETTLED frame this long after the last write goes quiet (interactive
+// path). Small ⇒ a keystroke's multi-read repaint coalesces into ONE frame in ~10-16ms instead of being
+// emitted half-painted then delayed to the slow ceiling. Capped by the min/max interval (see settleDelay).
+const STATE_SYNC_SETTLE_MS = Math.max(0, Number(process.env.CTM_STATE_SYNC_SETTLE_MS) || 8);
+// Background (non-VISIBLE) sessions still ingest every byte into their headless mirrors, but default to
+// ZERO frame extraction. Serializing grids for hidden busy sessions burns the same worker needed for the
+// focused tab's typing echo; nobody can see those pixels. A tab-switch forces a keyframe from the current
+// mirror, so the selected session catches up immediately. Set CTM_STATE_SYNC_BG_MS>0 only for experiments.
+function parseStateSyncBgMs(value) {
+  if (value === undefined || value === null || value === '') return 0;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return Math.max(STATE_SYNC_FRAME_MAX_MS, Math.floor(n));
+}
+const STATE_SYNC_BG_MS = parseStateSyncBgMs(process.env.CTM_STATE_SYNC_BG_MS);
+let _stateSyncVisibleKnown = false;          // has the client reported a visible set yet?
+const _stateSyncVisibleSessions = new Set(); // sessionIds the user is actually looking at (fast path)
+const _stateSyncEmitter = STATE_SYNC_ENABLED ? createFrameEmitter({
+  send: (id, msg) => { try { postMessage({ ...msg, sessionId: id }); } catch {} }, // sessionId for server routing; id for the client
+  extractGrid: (id) => extractGrid(id, { scrollbackRows: STATE_SYNC_SCROLLBACK_ROWS }),
+  now: Date.now,
+  frameOpts: { minIntervalMs: STATE_SYNC_FRAME_MIN_MS, maxIntervalMs: STATE_SYNC_FRAME_MAX_MS },
+}) : null;
+const _stateSyncFlushTimers = new Map(); // sessionId -> trailing-flush timer
+const _stateSyncFlood = new Map();       // sessionId -> output-rate flood state
+const _stateSyncHiddenDirtySessions = new Set();
+
+// Lost-ack watchdog: the emitter's diff base only advances on a client ACK, so a frame whose ACK never
+// reaches the worker would pin the session in-flight forever and freeze its terminal. Periodically sweep
+// for frames stuck in flight past STATE_SYNC_INFLIGHT_STALL_MS and force a fresh keyframe (full repaint).
+const STATE_SYNC_INFLIGHT_STALL_MS = Math.max(
+  STATE_SYNC_FRAME_MAX_MS * 4,
+  Number(process.env.CTM_STATE_SYNC_INFLIGHT_STALL_MS) || 3000,
+);
+const STATE_SYNC_INFLIGHT_SWEEP_MS = Math.max(250, Math.floor(STATE_SYNC_INFLIGHT_STALL_MS / 3));
+if (_stateSyncEmitter) {
+  const _stalledSweep = setInterval(() => {
+    try { _stateSyncEmitter.sweepStalledInFlight(Date.now(), { stallMs: STATE_SYNC_INFLIGHT_STALL_MS }); } catch {}
+  }, STATE_SYNC_INFLIGHT_SWEEP_MS);
+  if (typeof _stalledSweep.unref === 'function') _stalledSweep.unref();
+}
+
+function _stateSyncFramesSuppressed(sessionId) {
+  return _stateSyncVisibleKnown && !_stateSyncVisibleSessions.has(sessionId) && STATE_SYNC_BG_MS <= 0;
+}
+
+function _stateSyncMarkHiddenDirty(sessionId) {
+  if (sessionId) _stateSyncHiddenDirtySessions.add(sessionId);
+}
+
+// Called after output has been applied to the mirror. We emit on the TRAILING edge of a write burst:
+// a single keystroke makes a TUI repaint that arrives as several PTY reads, so emitting on the FIRST read
+// captures a half-painted screen and the rate floor then delays the read that carries the new char (the
+// measured ~70ms typing lag). Instead we (re)schedule a settle-emit a few ms after writes go quiet —
+// capped by settleDelay's max-wait so continuous output still streams at the ceiling rather than starving.
+// `bypassRate` lets the settled frame through the emitter's floor (this debounce IS the rate limiter).
+function _stateSyncOnMirrorWrite(sessionId, bytes) {
+  if (!_stateSyncEmitter) return;
+  let flood = _stateSyncFlood.get(sessionId);
+  if (!flood) { flood = {}; _stateSyncFlood.set(sessionId, flood); }
+  const now = Date.now();
+  _stateSyncNoteOutput(flood, bytes, now);
+  const flooding = _stateSyncIsFlooding(flood, now, {});
+  _stateSyncEmitter.setFlooding(sessionId, flooding);
+  if (!flood.firstPendingAt) flood.firstPendingAt = now; // first un-emitted write (max-wait anchor)
+  // Not visible (and the client has told us what IS visible) ⇒ no frames by default, so hidden busy
+  // sessions can't starve the focused tab's typing. Unknown visibility (pre-handshake) ⇒ treat as visible.
+  const background = _stateSyncVisibleKnown && !_stateSyncVisibleSessions.has(sessionId);
+  if (_stateSyncFramesSuppressed(sessionId)) {
+    _stateSyncMarkHiddenDirty(sessionId);
+    clearTimeout(_stateSyncFlushTimers.get(sessionId));
+    _stateSyncFlushTimers.delete(sessionId);
+    flood.firstPendingAt = 0;
+    return;
+  }
+  const delay = _stateSyncSettleDelay(flood, now, {
+    settleMs: STATE_SYNC_SETTLE_MS, minIntervalMs: STATE_SYNC_FRAME_MIN_MS, maxIntervalMs: STATE_SYNC_FRAME_MAX_MS,
+    bgIntervalMs: STATE_SYNC_BG_MS, flooding, background,
+  });
+  if (!Number.isFinite(delay)) {
+    _stateSyncMarkHiddenDirty(sessionId);
+    clearTimeout(_stateSyncFlushTimers.get(sessionId));
+    _stateSyncFlushTimers.delete(sessionId);
+    flood.firstPendingAt = 0;
+    return;
+  }
+  clearTimeout(_stateSyncFlushTimers.get(sessionId));
+  _stateSyncFlushTimers.set(sessionId, setTimeout(() => {
+    _stateSyncFlushTimers.delete(sessionId);
+    flood.firstPendingAt = 0; // this emit clears the pending window
+    if (terminals.has(sessionId)) {
+      _stateSyncEmitter.setFlooding(sessionId, _stateSyncIsFlooding(flood, Date.now(), {}));
+      _stateSyncEmitter.onMirrorUpdated(sessionId, { bypassRate: true });
+    }
+  }, delay));
+}
+function _stateSyncReset(sessionId) {
+  if (!_stateSyncEmitter) return;
+  clearTimeout(_stateSyncFlushTimers.get(sessionId));
+  _stateSyncFlushTimers.delete(sessionId);
+  _stateSyncFlood.delete(sessionId);
+  _stateSyncHiddenDirtySessions.delete(sessionId);
+  _stateSyncEmitter.reset(sessionId);
+}
+
 function getOrCreate(sessionId, cols = 120, rows = 30) {
   let entry = terminals.get(sessionId);
   if (!entry) {
@@ -197,6 +319,10 @@ function _approvalOutputHasHint(text) {
 // 80 rows = ~2 viewports of headroom on a typical 30-row terminal. Wider
 // than any Codex prompt observed in production while bounding the scan cost.
 const APPROVAL_SCROLLBACK_ROWS = 80;
+// Bounded window of recent scrollback rows folded into the content fingerprint so an in-place
+// stranded fragment baked into history is detected (the viewport + row count stay unchanged).
+// MUST match the client mirror (public/js/terminal-reconciler.js SCROLLBACK_FP_TAIL_ROWS).
+const SCROLLBACK_FP_TAIL_ROWS = 256;
 function getVisibleText(term) {
   const buf = term.buffer.active;
   const lines = [];
@@ -234,7 +360,16 @@ function viewportFingerprint(term) {
     rowStrings.push(line ? line.translateToString(true) : '');
   }
   const scrollbackLen = Math.max(0, buf.length - rows);
-  return fingerprintRows(rowStrings, { cols: term.cols, rows, scrollbackLen });
+  // Bounded recent-scrollback CONTENT tail (the rows just above the viewport) so an in-place
+  // stranded fragment baked into history is detected even when the viewport + row count match.
+  // Bounded to keep the cost low; MUST match the client's window (terminal-reconciler.js).
+  const tail = [];
+  const tailStart = Math.max(0, start - SCROLLBACK_FP_TAIL_ROWS);
+  for (let i = tailStart; i < start; i++) {
+    const line = buf.getLine(i);
+    tail.push(line ? line.translateToString(true) : '');
+  }
+  return fingerprintRows(rowStrings, { cols: term.cols, rows, scrollbackLen, scrollbackTail: tail });
 }
 
 function getVisibleRows(term) {
@@ -271,10 +406,28 @@ const WRITE_TIMEOUT_MS = 5000;
 // badge rather than leaving the user guessing why auto-approve is silent.
 const _writeStallCounts = new Map(); // sessionId -> count
 
+function _writeHeadlessSync(entry, data) {
+  const core = entry && entry.term && entry.term._core;
+  if (!core || typeof core.writeSync !== 'function') return false;
+  try {
+    // @xterm/headless exposes this only on the internal core object. Option B needs the mirror updated
+    // before the next 16ms frame deadline; the public async write callback can lag far behind that.
+    core.writeSync(data);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function enqueueWrite(sessionId, data) {
   const entry = getOrCreate(sessionId);
   const prev = writeQueues.get(sessionId) || Promise.resolve();
   const next = prev.then(() => new Promise(resolve => {
+    if (STATE_SYNC_ENABLED && _writeHeadlessSync(entry, data)) {
+      _stateSyncOnMirrorWrite(sessionId, (data && data.length) || 0);
+      resolve();
+      return;
+    }
     let settled = false;
     const timer = setTimeout(() => {
       if (settled) return;
@@ -291,6 +444,7 @@ function enqueueWrite(sessionId, data) {
       settled = true;
       clearTimeout(timer);
       resolve();
+      _stateSyncOnMirrorWrite(sessionId, (data && data.length) || 0); // Option B: emit frame (inert when off)
     });
   }));
   // Periodically reset the promise chain to prevent unbounded growth.
@@ -353,6 +507,13 @@ async function handleMessage(msg) {
   switch (msg.type) {
     case 'create': {
       getOrCreate(msg.sessionId, msg.cols, msg.rows);
+      // Option B: seed this session's visibility (sent in the create message because the host wasn't
+      // registered yet when the server knew it). undefined ⇒ state-sync off ⇒ leave visibility unknown.
+      if (typeof msg.visible === 'boolean') {
+        _stateSyncVisibleKnown = true;
+        if (msg.visible) _stateSyncVisibleSessions.add(msg.sessionId);
+        else _stateSyncVisibleSessions.delete(msg.sessionId);
+      }
       break;
     }
 
@@ -507,6 +668,58 @@ async function handleMessage(msg) {
     case 'resize': {
       const entry = terminals.get(msg.sessionId);
       if (entry) entry.term.resize(msg.cols, msg.rows);
+      // Option B: dims changed → the grid reflows → force a keyframe at the new dims (inert when off).
+      if (_stateSyncEmitter && entry) {
+        if (_stateSyncFramesSuppressed(msg.sessionId)) _stateSyncMarkHiddenDirty(msg.sessionId);
+        else _stateSyncEmitter.onKeyframeReq(msg.sessionId, {});
+      }
+      break;
+    }
+
+    // Option B: client confirmed it applied frame `seq` (no-op when state-sync is off).
+    case 'ack': {
+      if (_stateSyncEmitter) _stateSyncEmitter.onAck(msg.sessionId, Number(msg.seq || 0));
+      break;
+    }
+
+    // Option B: client is missing the diff base (desync / cold attach / scroll-up) → send a keyframe.
+    // msg.deferIfBlank (restore-hold release): defer the keyframe while the mirror is a blank cleared
+    // screen so the client never paints a blank frame with the cursor parked at row 1 mid-resume.
+    case 'keyframe-req': {
+      if (_stateSyncEmitter) {
+        if (_stateSyncFramesSuppressed(msg.sessionId)) _stateSyncMarkHiddenDirty(msg.sessionId);
+        else _stateSyncEmitter.onKeyframeReq(msg.sessionId, { deferIfBlank: !!msg.deferIfBlank });
+      }
+      break;
+    }
+
+    // Option B: the server reports ONE session's visibility (routed by sessionId so it reaches the right
+    // session-host process — sessions run in per-session hosts, so a global broadcast wouldn't arrive).
+    // Non-visible sessions default to NO frame extraction so a hidden busy session can't starve the
+    // focused tab. A session that just BECAME visible gets an immediate keyframe so the switch paints fresh.
+    case 'set-visibility': {
+      if (!_stateSyncEmitter || !msg.sessionId) break;
+      _stateSyncVisibleKnown = true;
+      const wasVisible = _stateSyncVisibleSessions.has(msg.sessionId);
+      if (msg.visible) {
+        _stateSyncVisibleSessions.add(msg.sessionId);
+      } else {
+        _stateSyncVisibleSessions.delete(msg.sessionId);
+        if (_stateSyncFlushTimers.has(msg.sessionId)) {
+          clearTimeout(_stateSyncFlushTimers.get(msg.sessionId));
+          _stateSyncFlushTimers.delete(msg.sessionId);
+          const flood = _stateSyncFlood.get(msg.sessionId);
+          if (flood) flood.firstPendingAt = 0;
+          _stateSyncMarkHiddenDirty(msg.sessionId);
+        }
+      }
+      const wasHiddenDirty = msg.visible && _stateSyncHiddenDirtySessions.delete(msg.sessionId);
+      if (msg.visible && terminals.has(msg.sessionId) && (!wasVisible || wasHiddenDirty)) {
+        // deferIfBlank: switching TO a still-resuming session whose mirror is a blank cleared screen
+        // (cursor at home) must not paint a blank frame with the caret at row 1 — defer until the
+        // redraw lands. A settled session is non-blank, so it keyframes immediately (no behavior change).
+        _stateSyncEmitter.onKeyframeReq(msg.sessionId, { deferIfBlank: true });
+      }
       break;
     }
 
@@ -619,6 +832,7 @@ async function handleMessage(msg) {
       if (entry) {
         entry.term.reset();
         writeQueues.delete(msg.sessionId);
+        _stateSyncReset(msg.sessionId);
       }
       break;
     }
@@ -630,6 +844,7 @@ async function handleMessage(msg) {
         entry.term.dispose();
         terminals.delete(msg.sessionId);
         writeQueues.delete(msg.sessionId);
+        _stateSyncReset(msg.sessionId);
       }
       break;
     }
@@ -639,7 +854,7 @@ async function handleMessage(msg) {
 function dispatchHeadlessMessage(msg) {
   const sessionId = msg && msg.sessionId;
   if (!sessionId) {
-    handleMessage(msg).catch((err) => {
+    return handleMessage(msg).catch((err) => {
       try {
         postMessage({
           type: 'worker-error',
@@ -648,9 +863,8 @@ function dispatchHeadlessMessage(msg) {
         });
       } catch {}
     });
-    return;
   }
-  enqueueSessionOp(sessionId, () => handleMessage(msg));
+  return enqueueSessionOp(sessionId, () => handleMessage(msg));
 }
 
 function bindHeadlessTerminalService(options = {}) {
@@ -672,7 +886,40 @@ function bindHeadlessTerminalService(options = {}) {
   };
 }
 
+// Extract the live viewport + a bounded recent-scrollback window as a row-serialized grid for
+// state-sync (Option B). Each row is SELF-CONTAINED ANSI — SerializeAddon's per-row `range` resets its
+// own SGR — so the cell-diff can rewrite any single row independently. Absolute buffer indexing keyed
+// off buf.baseY (the LIVE viewport top; NOT viewportY — client-side scroll is local and must not move
+// the synced region). Returns { cols, rows, rowAnsi: string[], baseRow }.
+function extractGrid(sessionId, opts) {
+  const entry = terminals.get(sessionId);
+  if (!entry || !entry.term) return { cols: 0, rows: 0, rowAnsi: [], baseRow: 0 };
+  const term = entry.term;
+  const buf = term.buffer.active;
+  const length = Number(buf.length || 0);
+  const viewportRows = Number(term.rows || 0);
+  if (!length || !viewportRows) return { cols: Number(term.cols || 0), rows: 0, rowAnsi: [], baseRow: 0 };
+  const scrollbackRows = Math.max(0, Number(opts && opts.scrollbackRows) || 0);
+  const baseY = Math.max(0, Number(buf.baseY || 0));
+  const start = Math.max(0, baseY - scrollbackRows);
+  const end = Math.min(length - 1, baseY + viewportRows - 1);
+  const rowAnsi = [];
+  for (let r = start; r <= end; r++) {
+    rowAnsi.push(serializeRow(buf.getLine(r), term.cols));
+  }
+  // Cursor position relative to the grid (1-based), so the client can place the TUI composer cursor.
+  const cursorAbs = baseY + Number(buf.cursorY || 0);
+  const cursor = { row: Math.max(1, (cursorAbs - start) + 1), col: Math.max(1, Number(buf.cursorX || 0) + 1) };
+  return { cols: Number(term.cols || 0), rows: rowAnsi.length, rowAnsi, baseRow: start, cursor };
+}
+
 module.exports = {
   bindHeadlessTerminalService,
   handleMessage: dispatchHeadlessMessage,
+  viewportFingerprint, // exported for fingerprint unit tests (scrollback-fingerprint.test.js)
+  extractGrid,
+  getOrCreate, // exported for state-sync unit tests
+  STATE_SYNC_SCROLLBACK_ROWS, // exported so the regression test can pin the live window to viewport-only
+  STATE_SYNC_BG_MS,
+  parseStateSyncBgMs,
 };

package/template/claude-task-manager/lib/message-identity.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// Canonical, stable per-message identity for the conversation log.
+//
+// The server merge (conversation-tail-merge.js) already collapses the two
+// delivery-path copies of one turn (durable rows + live stream tail) into a
+// single message, using a 3-tier heuristic (parentUuid / timestamp / content).
+// This module produces ONE deterministic `id` for that final message so the
+// CLIENT can dedup and apply append/replace-by-id instead of re-deriving the
+// same heuristics a second time (_parentUuidSeen / _messageFingerprintSeen).
+//
+// Design rules:
+// - The id must stay STABLE while a streaming turn's text grows (so the client
+//   replaces in place) — hence it keys off uuid/parentUuid, never the live text,
+//   when those are present.
+// - The id must MATCH across the row-store copy and the stream-ring copy of one
+//   turn — hence text is dedup-normalized (image tokens stripped) before hashing,
+//   mirroring conversation-tail-merge.dedupText.
+// - tool_call and tool_result share a callId but are distinct messages — hence
+//   the structured kind is part of the id.
+
+const crypto = require('crypto');
+const { timestampValue } = require('./conversation-tail-merge');
+
+// `[Image #N]` placeholder tokens — mirror conversation-tail-merge.dedupText so a
+// turn's two copies (richer row-store label vs raw stream-ring prompt) hash alike.
+const IMAGE_TOKEN_RE = /\[Image #\d+\]/gi;
+
+// The weak tier hashes only this many chars of the normalized text. It MUST stay
+// below the live stream's text cap (session-stream.js MAX_TEXT_LEN = 50KB): a live
+// event truncates long prompts to 50KB + `...truncated(...)` while the durable row
+// keeps the full text, so hashing only a sub-50KB prefix makes the two copies of a
+// giant prompt converge to one id. 32KB is well under 50KB and above any realistic
+// prompt, so for normal messages the cap is a no-op (id unchanged).
+const WEAK_HASH_TEXT_CAP = 32 * 1024;
+
+function dedupText(text) {
+  return String(text || '')
+    .replace(IMAGE_TOKEN_RE, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function textHash(text) {
+  return crypto.createHash('sha1').update(String(text || '')).digest('hex').slice(0, 16);
+}
+
+// Text from either a durable message ({text}) or a live stream event ({data:{text}}).
+function messageText(message) {
+  return String(
+    message?.text ?? message?.content ?? message?.message ?? message?.data?.text ?? ''
+  ).trim();
+}
+
+// Derive the canonical id for a single message. Works on BOTH shapes — a durable
+// message ({role, parentUuid, text}) and a live stream event ({role, data:{parentUuid,
+// text}}) — so the same turn hashes to one id across the durable and live paths.
+// Returns '' for a message with no role or no text (callers stamp a positional fallback).
+function messageStableId(message) {
+  const role = String(message?.role || '').trim();
+  const text = messageText(message);
+  if (!role || !text) return '';
+
+  const kind = String(message?.metadata?.kind || message?.data?.metadata?.kind || '').trim();
+  if (kind) {
+    // Structured rows never carry uuid/parentUuid (structured-capture contract).
+    // A callId pairs a tool_call with its tool_result but does not identify the
+    // message — the kind does. Without a callId, fall back to the row's content.
+    const callId = String(message?.metadata?.callId || message?.data?.metadata?.callId || '').trim();
+    return `s:${kind}:${callId || textHash(dedupText(text))}`;
+  }
+
+  // parentUuid FIRST (before uuid): it is the only identity key the live stream
+  // event carries (data.parentUuid) AND the durable row keeps, so it is the one
+  // that survives the live↔durable boundary. The row store does not persist the
+  // message's own uuid, so preferring uuid here would split a turn's two copies.
+  const parentUuid = String(
+    message?.parentUuid || message?.data?.parentUuid || message?.metadata?.parentUuid || ''
+  ).trim();
+  if (parentUuid) return `p:${role}:${parentUuid}`;
+
+  const uuid = String(message?.uuid || '').trim();
+  if (uuid) return `u:${role}:${uuid}`;
+
+  // No stable provider id (Codex / Wall-E / resume-rewritten). Key off the
+  // normalized text + normalized timestamp — the same signals the merge's weak
+  // tiers use, so two copies that survived the merge hash identically here.
+  const ts = timestampValue(message?.timestamp);
+  const norm = dedupText(text);
+  const capped = norm.length > WEAK_HASH_TEXT_CAP ? norm.slice(0, WEAK_HASH_TEXT_CAP) : norm;
+  return `w:${role}:${ts}:${textHash(capped)}`;
+}
+
+// Stamp a unique, deterministic `id` on every message in a list. Two messages
+// that derive the same base id (e.g. two identical structured rows at the same
+// timestamp) are disambiguated by appended occurrence count, stable by order.
+// Returns NEW message objects; the input list is not mutated.
+function assignStableIds(messages) {
+  const list = Array.isArray(messages) ? messages : [];
+  const counts = new Map();
+  return list.map((message, index) => {
+    let base = messageStableId(message);
+    if (!base) base = `x:${index}`; // positional fallback for role/text-less rows
+    const n = counts.get(base) || 0;
+    counts.set(base, n + 1);
+    const id = n === 0 ? base : `${base}#${n}`;
+    return { ...message, id };
+  });
+}
+
+module.exports = {
+  messageStableId,
+  assignStableIds,
+  dedupText,
+};

package/template/claude-task-manager/lib/mirror-feed-guards.js

@@ -0,0 +1,25 @@
+'use strict';
+// Pure guards for the server-side headless-mirror feed + snapshot paths. Extracted so the byte-drop
+// fixes are unit-testable (server.js itself isn't requireable in tests). See the 285f93c8 torn-Codex
+// investigation: bytes were lost feeding the mirror under load, and a partial mirror was serialized
+// over the good scrollback file so it re-served torn forever.
+
+// The per-session feed flush (`_flushHeadlessFeed`) must consult these guards BEFORE consuming its
+// pending buffer. A miss means "can't deliver to this (legacy) mirror right now" — the caller keeps
+// the buffer instead of the old clear-then-return that silently dropped a 16ms batch whenever a
+// resume replaced the session object (`sameSession` false) or session-host ownership flipped.
+function headlessFeedShouldDeliver({ hasSession, sameSession, hostOwnsLiveHeadless } = {}) {
+  return !!hasSession && !!sameSession && !hostOwnsLiveHeadless;
+}
+
+// A session scrollback snapshot may be persisted to its file ONLY when the mirror is fully populated.
+// On restore the mirror is re-fed in chunks (status 'queued' → 'hydrating' → 'ready'); a periodic or
+// shutdown snapshot firing mid-hydration serializes a PARTIAL frame and overwrites the good file,
+// which then re-serves torn on every subsequent restore. A never-restored live session has no
+// hydration status (undefined) and is always snapshot-able. A failed/aborted hydration
+// ('missing'/'timeout') left a partial mirror too, so it must not be persisted either.
+function snapshotHydrationReady(status) {
+  return !status || status === 'ready';
+}
+
+module.exports = { headlessFeedShouldDeliver, snapshotHydrationReady };

package/template/claude-task-manager/lib/mirror-feed-sanitize.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// Option B (state-sync) scroll-up fidelity — hosted mirror feed sanitizer.
+//
+// Under state-sync the client renders VIEWPORT-ONLY frames; its scrollback comes solely from
+// the byte-path snapshot, which is serialized from the session's headless MIRROR. If that mirror
+// honors an erase-saved-lines (ESC[3J) that the agent emits on resume/redraw, the mirror's seeded
+// scrollback is wiped, every snapshot becomes viewport-only, and the user cannot scroll up.
+//
+// The primary process already strips ESC[3J for non-Codex agents before feeding ITS in-process
+// headless worker (server.js `shouldStripEraseScrollback`, kept because "older shell/Claude replay
+// paths rely on scrollback not being wiped"). But hosted PTYs (the default) feed their EMBEDDED
+// mirror directly in the session-host process, raw — so that protection never reached them. This
+// helper ports the exact rule to the hosted feed: strip ESC[3J for everyone except Codex, which
+// deliberately pairs ESC[2J+ESC[3J and carries its own rollout-history scrollback.
+//
+// Only the live PTY->mirror feed is sanitized; the raw byte stream sent to the client is unchanged,
+// and the restore seed (initialHeadlessData) is never passed through here.
+
+const { detectAgentType } = require('./agent-capabilities');
+
+const ERASE_SCROLLBACK = '\x1b[3J';
+const ERASE_SCROLLBACK_RE = /\x1b\[3J/g;
+
+// Codex is the lone agent that wants ESC[3J honored by the mirror; everyone else (Claude, shells,
+// gemini, etc.) relies on scrollback NOT being wiped. Null/unknown cmd defaults to stripping.
+function shouldStripEraseScrollbackForMirror(cmd) {
+  return detectAgentType(cmd || '') !== 'codex';
+}
+
+// Pure: returns `data` with ESC[3J removed when the agent is non-Codex, else `data` unchanged.
+// Non-string input and ESC[3J-free input are returned as-is (fast path).
+function sanitizeHostedMirrorFeed(data, cmd) {
+  if (!data || typeof data !== 'string') return data;
+  if (!shouldStripEraseScrollbackForMirror(cmd)) return data;
+  if (data.indexOf(ERASE_SCROLLBACK) < 0) return data;
+  return data.replace(ERASE_SCROLLBACK_RE, '');
+}
+
+module.exports = {
+  sanitizeHostedMirrorFeed,
+  shouldStripEraseScrollbackForMirror,
+  ERASE_SCROLLBACK,
+  ERASE_SCROLLBACK_RE,
+};