mixdog 0.9.87 → 0.9.89

package/src/runtime/agent/orchestrator/session/store-summary-reader.mjs

@@ -1,15 +1,24 @@
 /**
  * Read-only session summary catalog for cold desktop startup.
  *
- * This module intentionally avoids store.mjs, config/provider loading, workers,
- * and atomic-lock writers. The full runtime remains authoritative after it is
- * loaded; cold startup only needs enough metadata to paint the session list.
+ * The summary path intentionally avoids store.mjs, config/provider loading,
+ * workers, and atomic-lock writers. A transcript read stays lightweight too
+ * unless a durable turn checkpoint exists; only then does it lazily enter the
+ * reconnect recovery boundary so restored panes never paint a stale prompt.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { readFileSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+// Leaf helpers only (no store.mjs, no workers, no config): the three-way
+// present/absent/unreadable classification and the strict record parser the
+// authoritative store uses, so the cold catalog cannot disagree with it.
+import { probePath, readTextFile, PROBE_PRESENT, PROBE_ABSENT } from './store/fs-probe.mjs';
+import { readTopLevelLifecycleRecord, isLifecycleUnreadable } from './lifecycle-scan.mjs';
 
 const SESSION_SUMMARY_INDEX_VERSION = 2;
+const TERMINAL_AGENT_STATUS = /idle|done|complete|success|closed|error|fail|cancel|killed|timeout/i;
+const ACTIVE_AGENT_STATUS = /^(?:connecting|requesting|streaming|tool[-_\s]?running|running|queued|pending|starting|cancelling)$/i;
+const AGENT_POOL_HEARTBEAT_FRESH_MS = 2 * 60 * 1000;
 
 // Mirror of lifecycle-api.mjs listLeadSessions visibility: the cold catalog
 // must never surface worker/agent dispatches (memory ingest chunks, judges,
@@ -46,6 +55,125 @@ function positiveNumber(value, fallback = 0) {
     return Number.isFinite(number) && number > 0 ? number : fallback;
 }
 
+function cleanValue(value) {
+    return String(value || '').trim();
+}
+
+function activeAgentWorker(row) {
+    const statuses = [row?.stage, row?.status]
+        .map(cleanValue)
+        .filter((status, index, values) => Boolean(status) && values.indexOf(status) === index);
+    return statuses.length > 0
+        && !statuses.some((status) => TERMINAL_AGENT_STATUS.test(status))
+        && statuses.some((status) => ACTIVE_AGENT_STATUS.test(status));
+}
+
+export function storedAgentWorkerIndexPath() {
+    return join(dataDir(), 'agent-workers.json');
+}
+
+/** Process-global active agent pool. Fresh child heartbeat sidecars are the
+ * cross-process running source even when their durable session is detached
+ * (`closed`) and a terminal reaper has already removed the worker-index row.
+ * The index remains additive for active rows published before the heartbeat or
+ * by runtimes without a sidecar. No runtime starts. */
+export function listStoredAgentWorkers() {
+    let parsed = null;
+    try {
+        parsed = JSON.parse(readFileSync(storedAgentWorkerIndexPath(), 'utf8'));
+    } catch { /* heartbeat-backed rows remain authoritative without the index */ }
+    const source = Array.isArray(parsed?.workers)
+        ? parsed.workers
+        : parsed?.workers && typeof parsed.workers === 'object'
+            ? Object.values(parsed.workers)
+            : [];
+    const bySessionId = new Map();
+    for (const row of source) {
+        if (!row || typeof row !== 'object' || !activeAgentWorker(row)) continue;
+        const sessionId = cleanValue(row.sessionId);
+        const tag = cleanValue(row.tag);
+        if (!sessionId || !tag || !/^[A-Za-z0-9_-]+$/.test(sessionId)) continue;
+        let session = null;
+        if (!cleanValue(row.ownerSessionId || row.parentSessionId)) {
+            try {
+                session = JSON.parse(readFileSync(
+                    join(dataDir(), 'sessions', `${sessionId}.json`),
+                    'utf8',
+                ));
+            } catch { /* a new row may precede its first session save */ }
+        }
+        bySessionId.set(sessionId, {
+            tag,
+            sessionId,
+            ownerSessionId: cleanValue(
+                row.ownerSessionId || row.parentSessionId
+                || session?.ownerSessionId || session?.parentSessionId,
+            ) || null,
+            agent: cleanValue(row.agent || session?.agent) || null,
+            provider: cleanValue(row.provider || session?.provider) || null,
+            model: cleanValue(row.model || session?.model) || null,
+            status: cleanValue(row.status) || 'running',
+            stage: cleanValue(row.stage || row.status) || 'running',
+            startedAt: row.startedAt || row.createdAt || session?.createdAt || null,
+            turnStartedAt: row.turnStartedAt || null,
+            createdAt: row.createdAt || session?.createdAt || null,
+            updatedAt: row.updatedAt || session?.updatedAt || null,
+            cwd: cleanValue(row.cwd || session?.cwd) || null,
+            clientHostPid: positiveNumber(row.clientHostPid || session?.clientHostPid, 0) || null,
+            taskId: cleanValue(row.task_id || row.taskId) || null,
+        });
+    }
+    const now = Date.now();
+    for (const [sessionId, heartbeatAt] of sessionHeartbeatMtimes()) {
+        if (now - heartbeatAt > AGENT_POOL_HEARTBEAT_FRESH_MS) continue;
+        let session;
+        try {
+            session = JSON.parse(readFileSync(
+                join(dataDir(), 'sessions', `${sessionId}.json`),
+                'utf8',
+            ));
+        } catch {
+            continue;
+        }
+        const ownerSessionId = cleanValue(
+            session?.ownerSessionId || session?.parentSessionId,
+        );
+        const owner = cleanValue(session?.owner).toLowerCase();
+        const agent = cleanValue(session?.agent);
+        if (!ownerSessionId || (owner !== 'agent' && (!agent || agent === 'lead'))) continue;
+        const current = bySessionId.get(sessionId) || {};
+        bySessionId.set(sessionId, {
+            ...current,
+            tag: cleanValue(session?.agentTag) || cleanValue(current.tag)
+                || `${agent || 'agent'}:${sessionId}`,
+            sessionId,
+            ownerSessionId,
+            agent: agent || current.agent || null,
+            provider: cleanValue(session?.provider) || current.provider || null,
+            model: cleanValue(session?.model) || current.model || null,
+            // The sidecar is the live lease. Durable child sessions are
+            // intentionally detached/closed while their external owner runs.
+            status: 'running',
+            stage: 'running',
+            startedAt: session?.createdAt || current.startedAt || heartbeatAt,
+            turnStartedAt: current.turnStartedAt || null,
+            createdAt: session?.createdAt || current.createdAt || null,
+            updatedAt: heartbeatAt,
+            cwd: cleanValue(session?.cwd) || current.cwd || null,
+            clientHostPid: positiveNumber(session?.clientHostPid, 0)
+                || current.clientHostPid || null,
+            taskId: cleanValue(session?.task_id || session?.taskId)
+                || current.taskId || null,
+        });
+    }
+    const rows = [...bySessionId.values()];
+    return rows.sort((left, right) => {
+        const leftTime = Date.parse(String(left.startedAt || '')) || 0;
+        const rightTime = Date.parse(String(right.startedAt || '')) || 0;
+        return leftTime - rightTime || left.tag.localeCompare(right.tag);
+    });
+}
+
 function cleanText(value, maximum = 240) {
     return String(value || '')
         .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, ' ')
@@ -113,6 +241,7 @@ function normalizedRow(row, heartbeatAt = 0) {
         permission: row.permission || null,
         toolPermission: row.toolPermission || null,
         messageCount: Math.max(0, Math.floor(Number(row.messageCount) || 0)),
+        title: cleanText(row.title, 100),
         preview: cleanText(row.preview),
         generation: typeof row.generation === 'number' ? row.generation : 0,
         implicitBashSessionId: row.implicitBashSessionId || null,
@@ -120,6 +249,28 @@ function normalizedRow(row, heartbeatAt = 0) {
     };
 }
 
+function leadRowsWithAgentHeartbeat(rows) {
+    const agentHeartbeatByOwner = new Map();
+    for (const row of rows) {
+        const heartbeatAt = positiveNumber(row?.heartbeatAt, 0);
+        const ownerSessionId = String(row?.ownerSessionId || '').trim();
+        const owner = String(row?.owner || '').trim().toLowerCase();
+        const agent = String(row?.agent || '').trim().toLowerCase();
+        if (!heartbeatAt || !ownerSessionId
+            || (owner !== 'agent' && (!agent || agent === 'lead'))) continue;
+        agentHeartbeatByOwner.set(
+            ownerSessionId,
+            Math.max(agentHeartbeatByOwner.get(ownerSessionId) || 0, heartbeatAt),
+        );
+    }
+    return rows
+        .filter((row) => row && isLeadVisibleRow(row))
+        .map((row) => {
+            const agentHeartbeatAt = agentHeartbeatByOwner.get(row.id) || 0;
+            return agentHeartbeatAt > 0 ? { ...row, agentHeartbeatAt } : row;
+        });
+}
+
 function rowFromSession(session, heartbeatAt = 0) {
     const messages = Array.isArray(session?.messages) ? session.messages : [];
     const preview = messages
@@ -141,80 +292,353 @@ function rowFromSession(session, heartbeatAt = 0) {
 function sessionHeartbeatMtimes() {
     const directory = join(dataDir(), 'sessions');
     const result = new Map();
-    if (!existsSync(directory)) return result;
-    for (const filename of readdirSync(directory)) {
+    if (probePath(directory).state !== PROBE_PRESENT) return result;
+    let entries = [];
+    try { entries = readdirSync(directory); } catch { return result; }
+    for (const filename of entries) {
         if (!filename.endsWith('.hb')) continue;
         const id = filename.slice(0, -3);
         if (!/^[A-Za-z0-9_-]+$/.test(id)) continue;
-        try {
-            const mtime = statSync(join(directory, filename)).mtimeMs || 0;
-            if (mtime > 0) result.set(id, mtime);
-        } catch { /* sidecar disappeared after readdir */ }
+        // Liveness is additive: a sidecar that is absent OR unreadable simply
+        // contributes nothing, and can never remove a row.
+        const probe = probePath(join(directory, filename));
+        if (probe.state === PROBE_PRESENT && probe.mtimeMs > 0) result.set(id, probe.mtimeMs);
     }
     return result;
 }
 
-function scanSessionFiles(heartbeatMtimes = sessionHeartbeatMtimes()) {
+/**
+ * Read-only scan of the authoritative session files.
+ * Returns `null` when the directory itself is NOT enumerable (unreadable
+ * stat / readdir): that is not "no sessions", and the caller must keep the
+ * authority it already has (the index rows) instead of publishing an empty
+ * catalog. `indexRowsById` carries those rows so a single UNREADABLE session
+ * file also retains its last known row instead of vanishing.
+ */
+function scanSessionFiles(heartbeatMtimes = sessionHeartbeatMtimes(), indexRowsById = new Map()) {
     const directory = join(dataDir(), 'sessions');
-    if (!existsSync(directory)) return [];
+    const dirProbe = probePath(directory);
+    if (dirProbe.state === PROBE_ABSENT) return [];
+    if (dirProbe.state !== PROBE_PRESENT) return null;
+    let entries;
+    try { entries = readdirSync(directory); } catch { return null; }
     const rows = [];
-    for (const filename of readdirSync(directory)) {
+    for (const filename of entries) {
         if (!filename.endsWith('.json')) continue;
-        try {
-            const session = JSON.parse(readFileSync(join(directory, filename), 'utf8'));
-            const row = rowFromSession(session, heartbeatMtimes.get(session?.id) || 0);
-            if (row && isLeadVisibleRow(row)) rows.push(row);
-        } catch {
-            // A corrupt or concurrently replaced session is omitted from the
-            // cold catalog; the authoritative runtime can reconcile it later.
+        const storageId = filename.slice(0, -5);
+        const read = readTextFile(join(directory, filename));
+        // Provably gone: the row legitimately disappears with the file.
+        if (read.state === PROBE_ABSENT) continue;
+        if (read.state !== PROBE_PRESENT) {
+            // Exists and could not be read (EACCES/EIO): retain the last known
+            // row rather than let a transient IO error delete it from view.
+            const retained = indexRowsById.get(storageId);
+            if (retained) rows.push(retained);
+            continue;
         }
+        // Same strict authority as the store: a duplicate/ambiguous top-level
+        // record or a foreign identity is not this file's session.
+        const record = readTopLevelLifecycleRecord(read.text);
+        if (isLifecycleUnreadable(record) || record.id !== storageId) continue;
+        const row = rowFromSession(record.doc, heartbeatMtimes.get(record.id) || 0);
+        if (row) rows.push(row);
     }
-    return rows.sort((left, right) =>
+    return leadRowsWithAgentHeartbeat(rows).sort((left, right) =>
         (right.lastUsedAt || right.updatedAt || 0) - (left.lastUsedAt || left.updatedAt || 0));
 }
 
 function sessionFilesAreNewerThan(indexPath) {
     const directory = join(dataDir(), 'sessions');
-    if (!existsSync(directory)) return false;
-    let indexMtime = 0;
-    try { indexMtime = statSync(indexPath).mtimeMs || 0; }
-    catch { return true; }
-    try {
-        for (const filename of readdirSync(directory)) {
-            if (!filename.endsWith('.json')) continue;
-            try {
-                if ((statSync(join(directory, filename)).mtimeMs || 0) > indexMtime) return true;
-            } catch { /* session disappeared after readdir */ }
-        }
-    } catch {
-        return true;
+    if (probePath(directory).state !== PROBE_PRESENT) return false;
+    const indexProbe = probePath(indexPath);
+    // Only a PROVABLY absent index makes the files newer by definition. An
+    // index that exists but cannot be stat'ed (EACCES/EIO) is still the
+    // authority we failed to consult — claiming "files are newer" there would
+    // replace the whole catalog on the strength of an IO error.
+    if (indexProbe.state === PROBE_ABSENT) return true;
+    if (indexProbe.state !== PROBE_PRESENT) return false;
+    const indexMtime = indexProbe.mtimeMs || 0;
+    let entries;
+    try { entries = readdirSync(directory); } catch { return false; }
+    for (const filename of entries) {
+        if (!filename.endsWith('.json')) continue;
+        // Absent (raced unlink) and unreadable both prove nothing about
+        // freshness: only an observed newer mtime does.
+        const probe = probePath(join(directory, filename));
+        if (probe.state === PROBE_PRESENT && (probe.mtimeMs || 0) > indexMtime) return true;
     }
     return false;
 }
 
 export function listStoredSessionSummaries(options = {}) {
     const heartbeatMtimes = sessionHeartbeatMtimes();
-    if (options.refreshFromStorage === true) return scanSessionFiles(heartbeatMtimes);
     const indexPath = join(dataDir(), 'session-summaries.json');
-    try {
-        const index = JSON.parse(readFileSync(indexPath, 'utf8'));
-        if (Number(index?.version) === SESSION_SUMMARY_INDEX_VERSION) {
-            const rows = (Array.isArray(index.rows) ? index.rows : [])
-                .map((row) => normalizedRow(row, heartbeatMtimes.get(row?.id) || 0))
-                .filter((row) => row && isLeadVisibleRow(row))
-                .sort((left, right) =>
-                    (right.lastUsedAt || right.updatedAt || 0) - (left.lastUsedAt || left.updatedAt || 0));
-            // A crashed/non-blocking sidecar writer can leave a valid but old,
-            // non-empty index indefinitely. Detect only newer session JSONs
-            // (heartbeat churn does not count), then recover read-only from the
-            // authoritative files without trying to rewrite the stuck index.
-            if (options.rebuildIfMissing !== false && sessionFilesAreNewerThan(indexPath)) {
-                return scanSessionFiles(heartbeatMtimes);
+    // The index is read on EVERY path (it is one small file): its rows are the
+    // authority that must be retained whenever storage cannot be enumerated or
+    // an individual session file cannot be read.
+    const indexRowsById = new Map();
+    let indexRows = null;
+    const indexRead = readTextFile(indexPath);
+    if (indexRead.state === PROBE_PRESENT) {
+        try {
+            const index = JSON.parse(indexRead.text);
+            if (Number(index?.version) === SESSION_SUMMARY_INDEX_VERSION) {
+                const normalizedRows = (Array.isArray(index.rows) ? index.rows : [])
+                    .map((row) => normalizedRow(row, heartbeatMtimes.get(row?.id) || 0))
+                    .filter(Boolean);
+                for (const row of normalizedRows) indexRowsById.set(row.id, row);
+                indexRows = leadRowsWithAgentHeartbeat(normalizedRows)
+                    .sort((left, right) =>
+                        (right.lastUsedAt || right.updatedAt || 0) - (left.lastUsedAt || left.updatedAt || 0));
+            }
+        } catch { /* malformed sidecar: the files below are the authority */ }
+    }
+    // An index that EXISTS but is unreadable (EACCES/EIO) is neither missing
+    // nor empty: the scan below still runs, and when IT cannot enumerate
+    // either, the catalog reports nothing rather than inventing an empty truth.
+    const scan = () => scanSessionFiles(heartbeatMtimes, indexRowsById);
+    if (options.refreshFromStorage === true) return scan() ?? indexRows ?? [];
+    if (indexRows) {
+        // A crashed/non-blocking sidecar writer can leave a valid but old,
+        // non-empty index indefinitely. Detect only newer session JSONs
+        // (heartbeat churn does not count), then recover read-only from the
+        // authoritative files without trying to rewrite the stuck index.
+        if (options.rebuildIfMissing !== false && sessionFilesAreNewerThan(indexPath)) {
+            return scan() ?? indexRows;
+        }
+        if (indexRows.length > 0 || options.rebuildIfMissing === false) return indexRows;
+    }
+    return options.rebuildIfMissing === false ? [] : (scan() ?? indexRows ?? []);
+}
+
+/** Read exactly one persisted session for a visible desktop pane. This never
+ * enumerates siblings. Normal reads stay independent of runtime ownership;
+ * interrupted turns conditionally use the same durable reconnect recovery as
+ * resumeSession before projecting the transcript. */
+export async function readStoredSessionTranscript(id, options = {}) {
+    const sessionId = String(id || '').trim();
+    if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) return null;
+    // Same strict authority as the store, and the same fail-closed rule: an
+    // absent, unreadable, ambiguous or foreign record yields no transcript.
+    const read = readTextFile(join(dataDir(), 'sessions', `${sessionId}.json`));
+    if (read.state !== PROBE_PRESENT) return null;
+    const record = readTopLevelLifecycleRecord(read.text);
+    if (isLifecycleUnreadable(record) || record.id !== sessionId) return null;
+    let session = record.doc;
+    const owner = cleanValue(session.owner).toLowerCase();
+    const agent = cleanValue(session.agent).toLowerCase();
+    const liveDetachedAgent = session.closed === true
+        && (owner === 'agent' || (agent && agent !== 'lead'))
+        && Boolean(cleanValue(session.ownerSessionId || session.parentSessionId));
+    // Only a PROVABLY absent checkpoint skips recovery: an unreadable probe
+    // must not silently downgrade an interrupted turn to a plain cold read.
+    if (probePath(join(dataDir(), 'turn-checkpoints', `${sessionId}.json`)).state !== PROBE_ABSENT) {
+        if (liveDetachedAgent) {
+            const {
+                projectTurnCheckpointMessages,
+                readTurnCheckpoint,
+            } = await import('./manager/turn-checkpoint.mjs');
+            const checkpoint = readTurnCheckpoint(sessionId);
+            if (checkpoint) {
+                session = {
+                    ...session,
+                    messages: projectTurnCheckpointMessages(session, checkpoint),
+                };
             }
-            if (rows.length > 0 || options.rebuildIfMissing === false) return rows;
+        } else {
+            const { recoverSessionAfterProcessRestart } = await import('./manager.mjs');
+            session = recoverSessionAfterProcessRestart(sessionId) || session;
         }
+    }
+    const {
+        restoreTranscriptItems,
+        sessionContextSnapshotProjection,
+    } = await import(
+        '../../../../tui/engine/session-api-ext.mjs'
+    );
+    let preparedContextProjection = null;
+    try {
+        const [
+            { prepareSessionProjection },
+            { createContextStatus },
+        ] = await Promise.all([
+            import('./manager.mjs'),
+            import('../../../../session-runtime/context-status.mjs'),
+        ]);
+        const prepared = prepareSessionProjection(session, 'full');
+        if (prepared) session = prepared;
+        const { contextStatus } = createContextStatus({
+            getSession: () => session,
+            getRoute: () => ({
+                provider: session.provider || '',
+                model: session.model || '',
+                contextWindow: session.contextWindow || null,
+            }),
+            getCurrentCwd: () => session.cwd || '',
+            getMode: () => 'full',
+        });
+        preparedContextProjection = sessionContextSnapshotProjection(session, contextStatus());
     } catch {
-        // Missing/malformed sidecars fall through to the read-only scan.
+        // Cold context projection is presentation-only. The transcript and
+        // legacy estimator below remain available if provider/tool prep fails.
     }
-    return options.rebuildIfMissing === false ? [] : scanSessionFiles(heartbeatMtimes);
+    const messages = Array.isArray(session.messages) ? session.messages : [];
+    const hasConversationActivity = messages.some((message) => message?.role === 'user');
+    let currentEstimatedContextTokens = 0;
+    if (hasConversationActivity) {
+        try {
+            const { estimateTranscriptContextUsage } = await import('./context-utils.mjs');
+            currentEstimatedContextTokens = estimateTranscriptContextUsage(
+                messages,
+                Array.isArray(session.tools) ? session.tools : [],
+                { provider: session.provider },
+            );
+        } catch {
+            // Context metering is presentation-only. A cold transcript remains
+            // readable even if its optional estimator cannot be loaded.
+        }
+    }
+    const contextWindow = positiveNumber(session.contextWindow);
+    const rawContextWindow = positiveNumber(session.rawContextWindow, contextWindow);
+    const displayContextWindow = positiveNumber(session.compactBoundaryTokens, contextWindow);
+    const rawAutoCompactTokenLimit = positiveNumber(session.autoCompactTokenLimit);
+    const autoCompactTokenLimit = rawAutoCompactTokenLimit
+        && (!displayContextWindow || rawAutoCompactTokenLimit < displayContextWindow)
+        ? rawAutoCompactTokenLimit
+        : 0;
+    const requestedLimit = Number(options.transcriptItemLimit);
+    return {
+        sessionId,
+        items: restoreTranscriptItems(messages, {
+            sessionId,
+            itemLimit: Number.isFinite(requestedLimit) && requestedLimit > 0
+                ? requestedLimit
+                : Number.POSITIVE_INFINITY,
+        }),
+        provider: session.provider || '',
+        model: session.model || '',
+        effort: session.effort || '',
+        fast: session.fast === true,
+        cwd: session.cwd || '',
+        desktopSession: desktopSession(session.desktopSession, session.cwd),
+        workflow: session.workflow || null,
+        ...(preparedContextProjection ? {
+            ...preparedContextProjection,
+            preparedContextProjection: true,
+        } : {
+            stats: {
+                currentContextTokens: 0,
+                currentEstimatedContextTokens,
+                currentContextSource: currentEstimatedContextTokens > 0 ? 'estimated' : null,
+            },
+            contextWindow: contextWindow || null,
+            rawContextWindow: rawContextWindow || null,
+            displayContextWindow: displayContextWindow || null,
+            autoCompactTokenLimit: autoCompactTokenLimit || null,
+        }),
+        // Desktop must not ask its unrelated active engine to recover/peek an
+        // externally owned child: that runtime can only return the detached
+        // Task row and masks this checkpoint projection.
+        readOnlyDetachedAgent: liveDetachedAgent,
+    };
+}
+
+/**
+ * Lightweight desktop background viewer. It reuses the owner's existing
+ * live-share pipe without creating a second engine/runtime or claiming session
+ * ownership. The caller has already published the cold disk snapshot; the
+ * owner's first full frame atomically replaces it, then deltas keep the pane
+ * current while it remains visible.
+ */
+export async function createStoredSessionLiveViewer(id, options = {}) {
+    const sessionId = String(id || '').trim();
+    if (!/^[A-Za-z0-9_-]+$/.test(sessionId)
+        || typeof options.onSnapshot !== 'function') return null;
+    const initial = options.initialSnapshot && typeof options.initialSnapshot === 'object'
+        ? options.initialSnapshot
+        : {};
+    let state = {
+        ...initial,
+        sessionId,
+        items: Array.isArray(initial.items) ? initial.items : [],
+        queued: Array.isArray(initial.queued) ? initial.queued : [],
+        streamingTail: initial.streamingTail || null,
+        spinner: initial.spinner || null,
+    };
+    let disposed = false;
+    let publishQueued = false;
+    const publish = () => {
+        if (disposed || publishQueued) return;
+        publishQueued = true;
+        queueMicrotask(() => {
+            publishQueued = false;
+            if (disposed) return;
+            try { options.onSnapshot(state); } catch { /* host lane isolation */ }
+        });
+    };
+    const commit = (patch) => {
+        state = { ...state, ...patch, sessionId };
+        publish();
+    };
+    const viewerApply = {
+        getState: () => state,
+        set: (patch) => commit(patch && typeof patch === 'object' ? patch : {}),
+        replaceItems: (items, replaceOptions = {}) => commit({
+            items: Array.isArray(items) ? [...items] : [],
+            ...(replaceOptions.preserveStreamingTail === true
+                ? {}
+                : { streamingTail: null }),
+        }),
+        patchItem: (itemId, patch) => {
+            const index = state.items.findIndex((item) => item?.id === itemId);
+            if (index < 0) return false;
+            const items = [...state.items];
+            items[index] = { ...items[index], ...patch };
+            commit({ items });
+            return true;
+        },
+        appendItems: (items) => {
+            if (!Array.isArray(items) || items.length === 0) return;
+            commit({ items: [...state.items, ...items] });
+        },
+        updateStreamingTail: (itemId, patch, _unused = {}, updateOptions = {}) => {
+            const current = updateOptions.resetText !== true
+                && state.streamingTail?.id === itemId
+                ? state.streamingTail
+                : { id: itemId, text: '' };
+            commit({ streamingTail: { ...current, ...patch, id: itemId } });
+        },
+        clearStreamingTail: () => commit({ streamingTail: null }),
+    };
+    const { createLiveShare, liveSharePipePath } = await import(
+        '../../../../tui/engine/live-share.mjs'
+    );
+    const share = createLiveShare({
+        ownerSessionId: () => '',
+        viewerSessionId: () => disposed ? '' : sessionId,
+        socketPathFor: (targetId) => liveSharePipePath(
+            targetId,
+            join(dataDir(), 'sessions', `${targetId}.json`),
+        ),
+        getPublishedState: () => state,
+        listeners: new Set(),
+        onRemoteSubmit: () => {},
+        onRemoteAbort: () => {},
+        onOwnerClosed: () => {
+            if (!disposed) options.onOwnerClosed?.();
+        },
+        viewerApply,
+        // A visible desktop pane may remain open before its external owner
+        // starts. Keep one bounded retry per pane instead of the TUI's
+        // latency-first 160ms retry ceiling.
+        viewerRetryMaxMs: 1_000,
+    });
+    share.ensure();
+    return {
+        dispose() {
+            if (disposed) return;
+            disposed = true;
+            share.dispose();
+        },
+    };
 }