create-walle 0.9.29 → 0.9.30

package/template/claude-task-manager/db.js

@@ -813,6 +813,10 @@ function runtimeKernelSchemaSql() {
       ON ctm_runtime_events(ctm_session_id, turn_id, created_at_ms, id);
     CREATE INDEX IF NOT EXISTS idx_ctm_runtime_events_type
       ON ctm_runtime_events(event_type, created_at_ms);
+    -- Serves "latest event of a type for a session" (latestContextTruth's per-session token/compact
+    -- lookup) as an O(1) index seek instead of fetching+parsing the oldest 1000 events per poll.
+    CREATE INDEX IF NOT EXISTS idx_ctm_runtime_events_session_type
+      ON ctm_runtime_events(ctm_session_id, event_type, id);
 
     CREATE TABLE IF NOT EXISTS ctm_runtime_turns (
       ctm_session_id TEXT NOT NULL,
@@ -2505,6 +2509,34 @@ function migrateSchemaIfNeeded() {
       // Non-fatal: dropping a dormant cache table; the app runs fine if it lingers.
     }
   }
+  if (getSchemaVersion() < 11) {
+    try {
+      migrateToV11();
+    } catch (e) {
+      console.error('[db] Schema migration to v11 FAILED:', e.message);
+      console.error('[db] Stack:', e.stack);
+      // Non-fatal: the column only enables Claude Desktop → Code fork dedup; absent it,
+      // getForkForDesktopUuid simply returns null and conversion stays available.
+    }
+  }
+}
+
+/**
+ * Schema v11: link a converted Claude Desktop conversation to its resumable Claude Code
+ * fork. A read-only Desktop conversation can be snapshot-and-forked into a real Code session
+ * (see lib/claude-desktop-sessions.js materializeForkTranscript); we record the originating
+ * Desktop uuid on the fork's agent_sessions row so the same conversation is never offered for
+ * conversion twice — the sidebar shows "Resume fork" instead. Idempotent via PRAGMA pre-check.
+ */
+function migrateToV11() {
+  const d = getDb();
+  const cols = d.prepare('PRAGMA table_info(agent_sessions)').all();
+  if (!cols.find((c) => c.name === 'forked_from_desktop_uuid')) {
+    d.prepare("ALTER TABLE agent_sessions ADD COLUMN forked_from_desktop_uuid TEXT DEFAULT ''").run();
+  }
+  d.exec("CREATE INDEX IF NOT EXISTS idx_agent_forked_desktop ON agent_sessions(forked_from_desktop_uuid) WHERE forked_from_desktop_uuid != ''");
+  setSchemaVersion(11);
+  console.log('[db] Schema migrated to v11 (Claude Desktop fork linkage)');
 }
 
 /**
@@ -3168,6 +3200,7 @@ function createV1Tables() {
       parent_agent_session_id TEXT DEFAULT '',
       agent_nickname TEXT DEFAULT '',
       agent_role TEXT DEFAULT '',
+      forked_from_desktop_uuid TEXT DEFAULT '',
       created_at TEXT DEFAULT (datetime('now')),
       updated_at TEXT DEFAULT (datetime('now')),
       FOREIGN KEY (ctm_session_id) REFERENCES ctm_sessions(id) ON DELETE CASCADE
@@ -3189,6 +3222,7 @@ function createV1Tables() {
   d.exec('CREATE INDEX IF NOT EXISTS idx_agent_slug ON agent_sessions(slug)');
   d.exec('CREATE INDEX IF NOT EXISTS idx_agent_parent_session ON agent_sessions(parent_agent_session_id)');
   d.exec('CREATE INDEX IF NOT EXISTS idx_agent_thread_source ON agent_sessions(thread_source)');
+  d.exec("CREATE INDEX IF NOT EXISTS idx_agent_forked_desktop ON agent_sessions(forked_from_desktop_uuid) WHERE forked_from_desktop_uuid != ''");
 }
 
 // --- Settings CRUD ---
@@ -3596,6 +3630,32 @@ function listRuntimeEvents(ctmSessionId, { sinceId = 0, turnId = '', limit = 100
   return rows.map(_parseRuntimeEvent).filter(Boolean);
 }
 
+// Latest event whose event_type is one of `eventTypes` for a session — the highest id wins.
+// Backs latestContextTruth, which previously fetched + JSON-parsed the oldest 1000 events per
+// session per poll just to find the latest token_usage + latest compact (a 3.98s/4min on-main cost
+// in the live CPU profile, and wrong once a session exceeds 1000 events). One indexed DESC LIMIT 1
+// seek per type (idx_ctm_runtime_events_session_type) → O(1), parses at most one row per type.
+function latestRuntimeEventOfTypes(ctmSessionId, eventTypes, { turnId = '' } = {}) {
+  const cleanSessionId = String(ctmSessionId || '').trim();
+  if (!cleanSessionId || !Array.isArray(eventTypes) || eventTypes.length === 0) return null;
+  const cleanTurnId = String(turnId || '').trim();
+  const d = getDb();
+  let best = null;
+  for (const t of eventTypes) {
+    const et = String(t || '').trim();
+    if (!et) continue;
+    const row = cleanTurnId
+      ? d.prepare(
+          'SELECT * FROM ctm_runtime_events WHERE ctm_session_id = ? AND turn_id = ? AND event_type = ? ORDER BY id DESC LIMIT 1'
+        ).get(cleanSessionId, cleanTurnId, et)
+      : d.prepare(
+          'SELECT * FROM ctm_runtime_events WHERE ctm_session_id = ? AND event_type = ? ORDER BY id DESC LIMIT 1'
+        ).get(cleanSessionId, et);
+    if (row && (!best || Number(row.id) > Number(best.id))) best = row;
+  }
+  return best ? _parseRuntimeEvent(best) : null;
+}
+
 function _parseRuntimeTurn(row) {
   if (!row) return null;
   return {
@@ -4983,6 +5043,10 @@ function importSessionConversation({
   // render shape differs from `messages` (Wall-E persists review-shaped rows, not the raw transcript
   // blob shape). The metadata upsert + blob still happen so the freshness gate + legacy reads work.
   skipMessageRows,
+  // When true, write the real blob even under blob retirement so the session renders from the blob
+  // while content-rows-backfill fills rows across slices (chunked/cold-import route). Over-cap still
+  // wins — a multi-GB stringify is never safe regardless of this flag.
+  forceBlobWrite,
 }) {
   // Attribution: the whole import is one synchronous span — a JSON.stringify of
   // the full message array (multi-MB for 2000+ prompt sessions) + an upsert + a
@@ -5010,7 +5074,10 @@ function importSessionConversation({
   // the default), otherwise nulling the blob would blind every read; and the row
   // write below restores the real blob if it fails, so a session is never empty.
   const _retireBlob = _blobRetirementActive();
-  const _skipBlobWrite = _overParseCap || _retireBlob;
+  // forceBlobWrite (cold/large chunked-import route) writes the real blob even under retirement so
+  // the session renders from blob while content-rows-backfill fills rows across slices. Over-cap
+  // still wins (a multi-GB stringify is never safe).
+  const _skipBlobWrite = _overParseCap || (_retireBlob && !forceBlobWrite);
   if (_overParseCap && !_overCapImportLogged.has(session_id)) {
     _overCapImportLogged.add(session_id);
     console.warn(`[db] session_conversations import over parse cap (file_size=${file_size}) for ${String(session_id || '').slice(0, 8)} — storing empty blob, skipping full stringify/row-rewrite.`);
@@ -5032,7 +5099,8 @@ function importSessionConversation({
   const _prevEst = _importTokenEstimateLen.get(session_id);
   const _modelChanged = !_prevEst || _prevEst.model !== (model_id || '');
   const _grewEnough = !_prevEst || _reestimateDelta === 0 || (_msgLen - _prevEst.len) >= _reestimateDelta;
-  if (!_overParseCap && (_modelChanged || _grewEnough)) {
+  const _chunkedRoute = !!forceBlobWrite && !!skipMessageRows && !_overParseCap;
+  if (!_overParseCap && !_chunkedRoute && (_modelChanged || _grewEnough)) {
     try {
       const summary = require('./lib/session-token-usage').estimateFromMessages(messages || [], model_id || '');
       if (summary && summary.total > 0) {
@@ -5087,6 +5155,14 @@ function importSessionConversation({
       _tokTotal, _tokCtx, _tokWindow, _tokExact, _tokBreakdown
     );
 
+    // Chunked-import route: rows are written later by content-rows-backfill (in windows). Stamp the
+    // render-gate HWM now so findUnbackfilledSessions (extracted_source_len>0 AND rows<len) adopts
+    // this session; appendSessionMessageRowsChunk re-stamps the same value idempotently on completion.
+    if (_chunkedRoute) {
+      try { _setExtractedSourceLen(getDb(), session_id, _msgLen, _lastMessageAt); }
+      catch (e) { console.error('[db] chunked-import source-len stamp failed:', e.message); }
+    }
+
     // Keep message-level search/review surfaces in lockstep with the durable
     // conversation cache. The older one-shot backfill path intentionally skips
     // sessions that already have rows, which made long-running imported Codex
@@ -7886,6 +7962,9 @@ function replaceSessionMessages(sessionId, messages) {
 // transcript timestamp is available, advance last_message_at without allowing
 // partial rewrites or compacted sources to move activity backward.
 function _setExtractedSourceLen(d, ctmSessionId, sourceLen, lastMessageAt = '') {
+  // Any row write reaches here to advance the watermark — drop the cached rows-available verdict so
+  // sessionContentRowsAvailable re-COUNTs once against the new state (covers same-watermark mutations).
+  _invalidateRowsAvailCache(ctmSessionId);
   try {
     d.prepare('UPDATE session_conversations SET extracted_source_len = ? WHERE ctm_session_id = ?')
       .run(Number(sourceLen) || 0, ctmSessionId);
@@ -8221,8 +8300,10 @@ function appendSessionConversation({
 function getSessionMessagesArray(sessionId, { fallbackToBlob = true } = {}) {
   const d = getDb();
   if (_tableExists('session_message_rows')) {
-    const rows = d.prepare('SELECT role, text, timestamp, meta FROM session_message_rows WHERE ctm_session_id = ? ORDER BY message_index ASC').all(sessionId);
-    if (rows.length) return rows.map(_messageRowToObject);
+    // Delegate the SELECT + row→object map to the shared lib so this row read is byte-identical
+    // to the read-pool worker's off-thread getSessionMessagesArray op (parity by construction).
+    const rows = require('./lib/session-messages-page').getMessagesArray(d, { sessionId });
+    if (rows.length) return rows;
   }
   if (fallbackToBlob) {
     try {
@@ -8236,16 +8317,40 @@ function getSessionMessagesArray(sessionId, { fallbackToBlob = true } = {}) {
 // True only when the faithful rows can serve this session: present AND fully backfilled
 // (row count covers the conversation's extracted length). A half-migrated session returns
 // false → the caller uses the complete blob/JSONL path.
+// Watermark-keyed cache of the "rows fully cover the conversation" verdict. sessionContentRowsAvailable
+// is on MANY hot/periodic main-loop paths — most heavily the per-codex-session snapshot serialize
+// (_serializeSessionSnapshot → _codexRolloutHistoryActive → _codexRowLookupId), plus the
+// apiSessionMessages gate, attach, and exit — and each call ran an O(rows) COUNT(*) that cold-page
+// faults for seconds (the `(unknown)` cpu-low apiSessionMessages/snapshot freeze on the primary).
+// The gate is `cnt >= expected` where expected = extracted_source_len (the import high-water mark).
+// Rows only grow and `expected` advances only as import progresses, so a TRUE verdict stays true
+// while `expected` is unchanged. Cache ONLY true verdicts keyed on `expected`: a key match means
+// cnt was already ≥ this watermark and (rows-only-grow) still is — skip the COUNT(*). A false/
+// half-migrated verdict is NOT cached (it must be re-checked so a just-completed migration is
+// picked up). Row writes invalidate the entry (belt-and-suspenders for a same-watermark row
+// mutation). CTM_ROWS_AVAIL_CACHE=0 disables.
+const _rowsAvailCache = new Map(); // ctm_session_id -> expected (watermark at which it was TRUE)
+function _invalidateRowsAvailCache(sessionId) { _rowsAvailCache.delete(String(sessionId || '')); }
 function sessionContentRowsAvailable(sessionId) {
   try {
     const d = getDb();
     if (!_tableExists('session_message_rows')) return false;
-    const cnt = Number(d.prepare('SELECT COUNT(*) AS n FROM session_message_rows WHERE ctm_session_id = ?').get(sessionId).n);
-    if (cnt === 0) return false;
+    // Cheap watermark read first (single non-blob column); also lets us skip the COUNT entirely for
+    // sessions with no HWM (always false under the old logic too).
     const conv = d.prepare('SELECT extracted_source_len FROM session_conversations WHERE ctm_session_id = ?').get(sessionId);
     const expected = conv ? Number(conv.extracted_source_len) : 0;
-    if (!(expected > 0) || cnt < expected) return false; // unknown HWM or half-migrated → blob path
-    return true;
+    if (!(expected > 0)) { _invalidateRowsAvailCache(sessionId); return false; } // unknown HWM → blob path
+    const cacheOn = process.env.CTM_ROWS_AVAIL_CACHE !== '0';
+    if (cacheOn && _rowsAvailCache.get(sessionId) === expected) return true; // TRUE@expected still holds (rows only grow)
+    const cnt = Number(d.prepare('SELECT COUNT(*) AS n FROM session_message_rows WHERE ctm_session_id = ?').get(sessionId).n);
+    const available = cnt > 0 && cnt >= expected; // unknown HWM or half-migrated → blob path
+    if (available && cacheOn) {
+      _rowsAvailCache.set(sessionId, expected);
+      if (_rowsAvailCache.size > 1024) { const k = _rowsAvailCache.keys().next().value; _rowsAvailCache.delete(k); }
+    } else {
+      _invalidateRowsAvailCache(sessionId);
+    }
+    return available;
   } catch { return false; }
 }
 
@@ -8403,9 +8508,28 @@ function _messageFreshnessStatsForId(id, { userOnly = false } = {}) {
   const d = getDb();
   const bindId = String(id);
   const whereRole = userOnly ? " AND role = 'user'" : '';
-  const readStats = (table) => d.prepare(
+  // The all-message session_message_rows store is DENSE — every message is a row at its array index
+  // (replaceSessionMessageRows / appendSessionMessageRowsChunk write message_index = i contiguously
+  // from 0, an invariant the row write paths already rely on), so COUNT(*) === MAX(message_index)+1.
+  // The per-poll COUNT(*) over a giant (14k-19k-row) session was a 5.25s/4min on-main cost in the
+  // live CPU profile; the query already computes MAX (an O(1) index seek), so deriving rows from it
+  // drops the only O(rows) term with NO schema or write-path change — strictly better than a
+  // maintained counter (no cross-thread drift). Equivalent as a change-detector: maxIndex moves on
+  // every append, and the store is append-only / full-replace (no mid-array deletes), so maxIndex+1
+  // changes exactly when the message set does. User-only rows are SPARSE (no density) and the legacy
+  // session_messages store isn't guaranteed dense, so both keep the exact COUNT(*).
+  const countStats = (table) => d.prepare(
     `SELECT COALESCE(MAX(message_index), -1) AS maxIndex, COUNT(*) AS rows FROM ${table} WHERE ctm_session_id = ?${whereRole}`
   ).get(bindId);
+  const denseStats = (table) => {
+    const r = d.prepare(
+      `SELECT COALESCE(MAX(message_index), -1) AS maxIndex FROM ${table} WHERE ctm_session_id = ?`
+    ).get(bindId);
+    const maxIndex = Number(r && r.maxIndex != null ? r.maxIndex : -1);
+    return { maxIndex, rows: maxIndex + 1 };
+  };
+  const readStats = (table) =>
+    (!userOnly && table === 'session_message_rows') ? denseStats(table) : countStats(table);
 
   // The row store is the default read source, but migration and tests can leave
   // some sessions present only in the legacy filtered index. Pick per session
@@ -9383,14 +9507,15 @@ function upsertAgentSessionIdentity(agentSessionId, data = {}) {
     parent_agent_session_id: lineage.parent_agent_session_id,
     agent_nickname: lineage.agent_nickname,
     agent_role: lineage.agent_role,
+    forked_from_desktop_uuid: data.forkedFromDesktopUuid || data.forked_from_desktop_uuid || '',
   };
   d.prepare(`
     INSERT INTO agent_sessions (agent_session_id, ctm_session_id, provider, provider_resume_id, project_path, jsonl_path,
       first_message, file_size, modified_at, hostname, model, git_branch, user_msg_count, slug,
-      thread_source, parent_agent_session_id, agent_nickname, agent_role)
+      thread_source, parent_agent_session_id, agent_nickname, agent_role, forked_from_desktop_uuid)
     VALUES (@agent_session_id, @ctm_session_id, @provider, @provider_resume_id, @project_path, @jsonl_path,
       @first_message, @file_size, @modified_at, @hostname, @model, @git_branch, @user_msg_count, @slug,
-      @thread_source, @parent_agent_session_id, @agent_nickname, @agent_role)
+      @thread_source, @parent_agent_session_id, @agent_nickname, @agent_role, @forked_from_desktop_uuid)
     ON CONFLICT(agent_session_id) DO UPDATE SET
       ctm_session_id = COALESCE(agent_sessions.ctm_session_id, excluded.ctm_session_id),
       provider = COALESCE(NULLIF(excluded.provider, ''), agent_sessions.provider),
@@ -9409,10 +9534,40 @@ function upsertAgentSessionIdentity(agentSessionId, data = {}) {
       parent_agent_session_id = COALESCE(NULLIF(excluded.parent_agent_session_id, ''), agent_sessions.parent_agent_session_id),
       agent_nickname = COALESCE(NULLIF(excluded.agent_nickname, ''), agent_sessions.agent_nickname),
       agent_role = COALESCE(NULLIF(excluded.agent_role, ''), agent_sessions.agent_role),
+      forked_from_desktop_uuid = COALESCE(NULLIF(excluded.forked_from_desktop_uuid, ''), agent_sessions.forked_from_desktop_uuid),
       updated_at = datetime('now')
   `).run(params);
 }
 
+/**
+ * Look up the Claude Code fork that was created from a given Claude Desktop conversation.
+ * Returns the fork's agent_sessions row ({ agent_session_id, jsonl_path, ctm_session_id })
+ * or null when the conversation has never been converted. Callers verify the fork still
+ * exists (row + jsonl file) before treating the conversation as already-converted; a deleted
+ * fork should re-offer conversion. Anchored on the stable Desktop uuid so a re-scan of the
+ * Desktop cache never mints a duplicate fork.
+ */
+function getForkForDesktopUuid(desktopUuid) {
+  const id = String(desktopUuid || '').trim();
+  if (!id) return null;
+  return getDb().prepare(
+    'SELECT agent_session_id, jsonl_path, ctm_session_id FROM agent_sessions WHERE forked_from_desktop_uuid = ? LIMIT 1'
+  ).get(id) || null;
+}
+
+/**
+ * List every Claude Code fork created from a Claude Desktop conversation, keyed by the
+ * originating Desktop uuid. The client fetches this to decide, per Desktop conversation,
+ * whether to offer "Convert" or "Resume fork". Callers verify the transcript still exists
+ * before trusting the link (a deleted fork should re-offer conversion).
+ */
+function listDesktopForks() {
+  return getDb().prepare(
+    "SELECT forked_from_desktop_uuid AS desktopUuid, agent_session_id AS forkSessionId, jsonl_path AS jsonlPath, project_path AS projectPath " +
+    "FROM agent_sessions WHERE forked_from_desktop_uuid != ''"
+  ).all();
+}
+
 function setSessionStar(id, starred) {
   // Try ctm_sessions first
   const result = getDb().prepare("UPDATE ctm_sessions SET starred = ?, updated_at = datetime('now') WHERE id = ?")
@@ -10249,7 +10404,7 @@ module.exports = {
   getStorageRisk,
   getSqliteDriverStatus,
   ensureRuntimeKernelTables,
-  appendRuntimeEvent, listRuntimeEvents,
+  appendRuntimeEvent, listRuntimeEvents, latestRuntimeEventOfTypes,
   upsertRuntimeTurn, getRuntimeTurn, listRuntimeTurns,
   upsertRuntimeInputEnvelope, updateRuntimeInputEnvelope, getRuntimeInputEnvelope, listRuntimeInputEnvelopes,
   upsertRuntimeRouteSnapshot, getLatestRuntimeRouteSnapshot,
@@ -10318,7 +10473,7 @@ module.exports = {
   setSessionTitleNew, setSessionTitleStatusNew, getSessionTitleNew, getSessionTitlesByIds, getSessionDisplayTitleInfo, isUserSessionTitleCandidate, promoteStartupTaskTitleIfUserNamed, repairSessionTitlesFromStartupTasks, getAllSessionsData,
   repairCodexSessionMetadataFromConversations, repairCodexRolloutAgentIdentities, detachPromotedProviderChildSessions,
   listProviderChildAgentOwnerMappings,
-  getAgentSessions, getAgentSession, deleteCtmSession,
+  getAgentSessions, getAgentSession, getForkForDesktopUuid, listDesktopForks, deleteCtmSession,
   // Schema version
   getSchemaVersion,
 };

package/template/claude-task-manager/docs/session-title-authority.md

@@ -8,8 +8,10 @@ CTM has one product-facing session name: `title`.
 
 1. Explicit user title wins.
 2. A user-looking active `startup_tasks.label` is promoted into `ctm_sessions.title` with `user_renamed=1`.
-3. AI-generated titles may fill `ctm_sessions.title` only when no user title exists.
-4. Runtime generated titles such as `Codex: ~/repo`, `Claude Code: ~/repo`, `Shell: /path`, branch/worktree leaf names, and `Wall-E session` are not user titles.
+3. Provider-native session titles may fill `ctm_sessions.title` only when no user title exists. Examples: Claude Code `summary` records and Codex `ai-title` records.
+4. CTM AI-generated titles may fill `ctm_sessions.title` only when no user/provider title exists.
+5. Runtime generated titles such as `Codex: ~/repo`, `Claude Code: ~/repo`, `Shell: /path`, branch/worktree leaf names, and `Wall-E session` are not user titles.
+6. First prompts are display fallbacks, not titles. They belong in `agent_sessions.first_message` / conversation cache fields and must not be written to `ctm_sessions.title` unless the user explicitly renamed the session to that text.
 
 ## Why
 
@@ -26,7 +28,10 @@ The fix is architectural: promote the user runtime title into the durable title
 
 - Session create/rename should send `title`; `label` may be included only as a compatibility mirror.
 - Rename writes must update both `ctm_sessions.title` and `startup_tasks.label`.
-- Non-user title writers must call through `setSessionTitleNew`; it protects active user startup titles before accepting an AI title.
+- Non-user title writers must call through `setSessionTitleNew`; it protects active user startup titles before accepting a provider/AI title.
+- Provider-native imports write `title_source='provider_title'`, `title_status='imported'`, and the raw provider title. Live UI chrome can add branding such as `Codex:`, but durable `ctm_sessions.title` stores only the product-facing session name.
+- Codex `first_user_message` and rollout user events are never title authority. Only explicit title records (`ai-title`, `custom-title`) or trusted provider state titles tied to the same canonical rollout id can become titles.
+- Claude Code `summary` records are provider-native titles. They can fill an unnamed session title, but they must not overwrite `user_renamed=1`.
 - Browser active-session chrome should prefer `meta.title`/user-looking runtime title before recent-session AI fields.
 - Branch-only runtime labels are not user titles unless `userRenamed=1` is explicit. A worktree branch named `evaluation` should render as `Codex session` with an `evaluation` branch badge, not as a user title.
 - New uses of `startup_tasks.label` should be commented as legacy schema compatibility.

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

@@ -4,6 +4,8 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const zlib = require('zlib');
+const crypto = require('crypto');
+const resumeCwd = require('./resume-cwd');
 
 const DESKTOP_PROJECT_ENTRY = 'claude-desktop';
 const DESKTOP_PROJECT_PATH = 'Claude Desktop';
@@ -213,6 +215,66 @@ function toClaudeCodeEntries(sessionOrId, options = {}) {
   }));
 }
 
+// Snapshot-and-fork: turn a read-only Claude Desktop conversation (cached text only) into a
+// valid, resumable Claude Code `.jsonl` so it can be continued in a terminal. Only text
+// carries over — Desktop never recorded tool calls, thinking, working dir, or usage. The
+// file is written into claudeProjectDirForCwd(cwd) so `path.dirname` matches the launch cwd
+// (Claude Code's resume contract; see lib/resume-preflight.js), with an unbroken parentUuid
+// chain and a first-line sentinel that records the originating Desktop uuid for dedup/recovery.
+function materializeForkTranscript(session, opts = {}) {
+  const forkSessionId = opts.forkSessionId;
+  if (!forkSessionId) throw new Error('claude-desktop: forkSessionId is required');
+  if (!opts.cwd) throw new Error('claude-desktop: cwd is required');
+
+  const usable = (Array.isArray(session && session.messages) ? session.messages : [])
+    .filter(m => (m.role === 'user' || m.role === 'assistant') && String(m.text || '').trim());
+  if (usable.length === 0) {
+    throw new Error('claude-desktop: no usable cached messages to materialize');
+  }
+
+  const projectOpts = { homeDir: opts.homeDir, claudeConfigDir: opts.claudeConfigDir };
+  const dir = resumeCwd.claudeProjectDirForCwd(opts.cwd, projectOpts);
+  const jsonlPath = path.join(dir, `${forkSessionId}.jsonl`);
+  if (fs.existsSync(jsonlPath)) {
+    throw new Error(`claude-desktop: transcript already exists at ${jsonlPath}`);
+  }
+
+  const cwd = resumeCwd.canonicalizeClaudeProjectPath(opts.cwd, projectOpts);
+  const version = opts.version || '';
+  const nextUuid = typeof opts.uuidFn === 'function' ? opts.uuidFn : () => crypto.randomUUID();
+  const fallbackTs = opts.now || new Date().toISOString();
+
+  let parentUuid = null;
+  const lines = usable.map((msg, index) => {
+    const uuid = nextUuid();
+    const role = msg.role === 'assistant' ? 'assistant' : 'user';
+    const text = String(msg.text || '');
+    const line = {
+      parentUuid,
+      isSidechain: false,
+      userType: 'external',
+      cwd,
+      sessionId: forkSessionId,
+      version,
+      gitBranch: '',
+      type: role,
+      message: {
+        role,
+        content: role === 'assistant' ? [{ type: 'text', text }] : text,
+      },
+      uuid,
+      timestamp: msg.timestamp || fallbackTs,
+    };
+    if (index === 0 && opts.desktopUuid) line._ctmForkedFromDesktop = opts.desktopUuid;
+    parentUuid = uuid;
+    return JSON.stringify(line);
+  });
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(jsonlPath, lines.join('\n') + '\n');
+  return { jsonlPath, sessionId: forkSessionId, lineCount: lines.length };
+}
+
 function readReactQueryCacheTexts(appDir) {
   const levelDir = path.join(appDir, 'Local Storage', 'leveldb');
   let files;
@@ -690,6 +752,7 @@ module.exports = {
   parseSessionFile,
   getMessages,
   toClaudeCodeEntries,
+  materializeForkTranscript,
   virtualSessionPath,
   parseVirtualSessionPath,
   isVirtualSessionPath,

package/template/claude-task-manager/lib/codex-config-guard.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// Codex MCP transport guard.
+//
+// The Codex desktop app periodically regenerates ~/.codex/config.toml and sometimes writes
+// app-only MCP servers (e.g. `codex_apps`, `xcodebuildmcp`) as TABLES WITH NO TRANSPORT — only
+// `startup_timeout_sec`, no `command` (stdio) and no `url` (http). The desktop app wires their
+// transport up internally, but the standalone `codex` CLI that CTM spawns to resume a session
+// validates transports at config-load time and ABORTS on the first offender:
+//
+//     Error: failed to load configuration
+//       Caused by: invalid transport in `mcp_servers.codex_apps`
+//
+// Every Codex session then fails to resume, surfacing that error in the tab. `enabled = false`
+// does NOT help — the CLI validates the transport BEFORE it honors `enabled`. The only thing that
+// loads is supplying a transport. So this guard hands each transport-less server an INERT, DISABLED
+// stdio transport via `-c` overrides: `command="/usr/bin/true"` satisfies the validator and
+// `enabled=false` guarantees the CLI never actually spawns it. The override leaves ~/.codex
+// untouched (no fighting the desktop app over a shared, Dropbox-synced file) and is a no-op on a
+// healthy config (no transport-less servers → no args).
+
+const fs = require('fs');
+const path = require('path');
+
+const INERT_COMMAND = '/usr/bin/true';
+
+// Split a TOML table header's inner text on top-level dots (dots inside double quotes are literal).
+function _splitDotted(inside) {
+  const segs = [];
+  let cur = '';
+  let inQ = false;
+  for (let i = 0; i < inside.length; i++) {
+    const ch = inside[i];
+    if (ch === '"') { inQ = !inQ; cur += ch; continue; }
+    if (ch === '.' && !inQ) { segs.push(cur); cur = ''; continue; }
+    cur += ch;
+  }
+  segs.push(cur);
+  return segs.map(s => s.trim());
+}
+
+function _unquote(seg) {
+  const t = String(seg || '').trim();
+  if (t.length >= 2 && t[0] === '"' && t[t.length - 1] === '"') return t.slice(1, -1);
+  return t;
+}
+
+// Parse a line as a TOML table header `[ ... ]`, returning its dotted segments, else null.
+function _tableHeaderSegments(line) {
+  const m = String(line).match(/^\s*\[([^\]]+)\]\s*(#.*)?$/);
+  if (!m) return null;
+  return _splitDotted(m[1]);
+}
+
+// Find every `[mcp_servers.<name>]` table (exactly two segments — sub-tables like
+// `[mcp_servers.<name>.env]` have three and are ignored) whose own body declares neither
+// `command` nor `url`. Returns the unquoted server names, in file order, de-duplicated.
+function findTransportlessMcpServers(configText) {
+  const lines = String(configText || '').split(/\r?\n/);
+  const out = [];
+  let cur = null; // { name, hasTransport } for the server table we're currently inside
+
+  const finalize = () => {
+    if (cur && !cur.hasTransport) out.push(cur.name);
+    cur = null;
+  };
+
+  for (const line of lines) {
+    const segs = _tableHeaderSegments(line);
+    if (segs) {
+      finalize(); // a new header ends the previous server table's body
+      if (segs.length === 2 && _unquote(segs[0]) === 'mcp_servers') {
+        cur = { name: _unquote(segs[1]), hasTransport: false };
+      }
+      continue;
+    }
+    if (cur && !cur.hasTransport) {
+      const km = line.match(/^\s*("[^"]*"|[A-Za-z0-9_-]+)\s*=/);
+      if (km) {
+        const key = _unquote(km[1]);
+        if (key === 'command' || key === 'url') cur.hasTransport = true;
+      }
+    }
+  }
+  finalize();
+
+  return [...new Set(out)];
+}
+
+// A TOML `-c` key segment is left bare when it's a valid bare key; otherwise double-quoted so the
+// dotted override path (mcp_servers.<seg>.command) keeps parsing as three segments.
+function _keySegment(name) {
+  return /^[A-Za-z0-9_-]+$/.test(name) ? name : `"${name}"`;
+}
+
+// Build `codex -c ...` override args that neutralize each transport-less server.
+function buildCodexTransportOverrideArgs(names, opts = {}) {
+  const inert = opts.command || INERT_COMMAND;
+  const out = [];
+  for (const name of names || []) {
+    const seg = _keySegment(name);
+    out.push('-c', `mcp_servers.${seg}.command="${inert}"`);
+    out.push('-c', `mcp_servers.${seg}.enabled=false`);
+  }
+  return out;
+}
+
+// Read CODEX_HOME/config.toml and return the override args (best-effort: unreadable/missing → []).
+function codexMcpTransportGuardArgs(codexHome, opts = {}) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(codexHome || '', 'config.toml'), 'utf8');
+  } catch {
+    return [];
+  }
+  return buildCodexTransportOverrideArgs(findTransportlessMcpServers(text), opts);
+}
+
+module.exports = {
+  INERT_COMMAND,
+  findTransportlessMcpServers,
+  buildCodexTransportOverrideArgs,
+  codexMcpTransportGuardArgs,
+};

package/template/claude-task-manager/lib/codex-rollout-snapshot.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { looksLikeCodexTranscriptPagerSnapshot } = require('./codex-transcript-pager');
+
 // Codex rollout-backed snapshot composition (the "seam").
 //
 // A Codex Term snapshot becomes:  [synthesized settled history]  +  [live region]
@@ -161,6 +163,11 @@ function composeCodexHistorySnapshot(input = {}) {
   const historyAnsi = String(input.historyAnsi || '');
   const viewportAnsi = String(input.viewportAnsi || '');
   const opts = input.opts || {};
+  // durable: this compose feeds a snapshot PERSISTED to file for cold resume, not a
+  // live send to a connected client. The interactive transcript pager is kept for
+  // live sends (so the user sees the screen they're driving) but must be dropped for
+  // durable persistence — else a cold resume restores into a dead pager forever.
+  const durable = !!input.durable;
 
   if (!historyAnsi) {
     return { data: viewportAnsi, trimmed: 0, composed: false };
@@ -173,9 +180,25 @@ function composeCodexHistorySnapshot(input = {}) {
   // \x1b[?1049h would flip the browser xterm to the alt buffer and hide the clean
   // history + composer. Drop it and serve history-only — the synthesized history
   // already ends with the composer, so the input box stays visible.
+  //
+  // EXCEPTION: the Codex transcript / backtrack pager (opened by `/status` then
+  // Esc) is ALSO an alt-screen frame, but it is a legitimate, persistent overlay
+  // the user is actively reading and navigating. Dropping it makes every
+  // snapshot/reflow serve stale history-only while the live PTY keeps painting the
+  // pager → the browser never settles and the session wedges (observed live:
+  // droppedAltViewport for 2+ min after `/status`+Esc). On a LIVE send, keep it:
+  // it is the authoritative live screen. On a DURABLE persist, still drop it (see
+  // the `durable` note above) so a cold resume never restores into a dead pager.
   if (viewportEntersAltScreen(viewportAnsi)) {
-    const histOnly = historyAnsi.endsWith(CRLF) || historyAnsi.endsWith('\n') ? historyAnsi : historyAnsi + CRLF;
-    return { data: histOnly, trimmed: 0, composed: true, droppedAltViewport: true };
+    // Keep the recognized interactive pager on a LIVE send (it's the screen the user
+    // is driving); drop transient full-screen frames, and — for durable persistence —
+    // the pager too. The detector's normalize pass only runs on the rare alt-screen
+    // frame, never on the common main-buffer compose.
+    const keepInteractivePager = !durable && looksLikeCodexTranscriptPagerSnapshot('codex', viewportAnsi);
+    if (!keepInteractivePager) {
+      const histOnly = historyAnsi.endsWith(CRLF) || historyAnsi.endsWith('\n') ? historyAnsi : historyAnsi + CRLF;
+      return { data: histOnly, trimmed: 0, composed: true, droppedAltViewport: true };
+    }
   }
 
   const { viewport, trimmed } = trimViewportOverlap(historyAnsi, viewportAnsi, opts);
@@ -206,12 +229,29 @@ function codexComposerTail(viewportAnsi) {
   return '\x1b[0m' + lines.slice(start, lastNB + 1).join(CRLF) + CRLF;
 }
 
+// Should a mid-stream restore PUSH be suppressed because the codex compose is mid-turn?
+// A flap/divergence-driven reflow that RIS-restores a fresh [synthesized history + live
+// viewport] snapshot while the turn is still streaming makes the client reset + replay
+// over codex's live inline repaint — under load this scatters the "Working…" status line
+// into the middle of the transcript. When mid-turn (no composer ⇒ settled === false),
+// keep the client's live render; the settle-time reconcile applies the clean snapshot.
+//   deferrableSource : the push is a flap/divergence reflow (the caller opts in); a cold
+//                      attach / activation / keyframe always renders, so passes false.
+//   settled          : compose saw a composer tail (turn settled). Only `=== false`
+//                      (a confirmed mid-turn frame) suppresses; undefined fails open.
+// Pure + total: any non-deferrable source, or a settled/undefined frame, returns false.
+function shouldSuppressMidTurnRestore(input) {
+  const view = input || {};
+  return view.deferrableSource === true && view.settled === false;
+}
+
 module.exports = {
   composeCodexHistorySnapshot,
   trimViewportOverlap,
   codexComposerTail,
   capHistoryAnsiLines,
   viewportEntersAltScreen,
+  shouldSuppressMidTurnRestore,
   // exported for tests
   _internal: { stripAnsi, normalizeLine, historyTailAnchor, findOverlapEnd, splitLines },
 };