spexcode 0.6.8 → 0.7.0-next.0

package/node_modules/@spexcode/spec-cli/dist/harness.js

@@ -1,4 +1,5 @@
 import { closeSync, openSync, readSync, writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { parse as parseToml } from 'smol-toml';
 import { join, dirname, basename } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import { createHash, randomBytes } from 'node:crypto';
@@ -12,15 +13,14 @@ import { piExtensionSource, writePiTrust, removePiTrust } from './pi-harness.js'
 import { claudeHeadlessColdRuntime, claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js';
 import { codexHeadlessLaunchCommand } from './codex-headless.js';
 import { opencodeHeadlessColdRuntime, opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js';
-import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless, piHeadlessColdRuntime } from './pi-headless.js';
+import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless, interruptPiHeadless, piHeadlessColdRuntime } from './pi-headless.js';
 import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath, spexcodeHome } from '@spexcode/spec-core';
 import { git } from '@spexcode/spec-core';
 import { shQuote } from './sh.js';
 import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, processStartToken, verifyDetachedRuntime } from '@spexcode/spec-core';
 import { codexGenerationEndpoints, codexGenerationSocketPath, currentCodexGeneration, legacyCodexGenerationEndpoint, readCodexGenerationLedger, resolveCodexGenerationForSession } from './codex-runtime-generations.js';
 import { writeFileIfChanged } from './file-write.js';
-import { codexRolloutPath, noExecutionTrace, readCodexExecutionTrace, readLocalStoreExecutionTrace, readProjectJsonlExecutionTrace, readSessionJsonlExecutionTrace } from './execution-trace.js';
-import { readClaudeTranscript, readCodexTranscript, unsupportedTranscriptReader } from './transcript-reader.js';
+import { claudeTranscript, codexRolloutPath, codexTranscript, opencodeTranscript, piTranscript, unsupportedTranscript } from '@spexcode/transcript';
 import { harnessIdentity, HARNESS_IDENTITIES } from '@spexcode/spec-core';
 // One project-wide resident-reference census for read projections. A shared app-server descriptor is probed
 // once per call, then its result is joined to every record that names that adapter/thread. Product readers must
@@ -409,6 +409,83 @@ export async function deliverViaSocketOrWake(id, text, mid, coldWake, unprovenEr
         return { ok: false, error: unprovenError };
     return coldWake();
 }
+const RENDEZVOUS_INTERRUPT_WALL_MS = 10_000;
+const RENDEZVOUS_INTERRUPT_SETTLE_MS = 15_000;
+// @@@ interruptViaRendezvous - one `interrupt` line to the session's LIVE rendezvous listener, confirmed by the
+// shim's own answer ([[shim-runtime]] runs the host's native abort — pi's ctx.abort(), opencode's
+// session.abort — and writes interrupt-done / interrupt-rejected). Unlike a reply poke, whose durable copy is
+// the timeline, an interrupt has nothing to fall back on: silence is a loud failure, never an optimistic ok.
+// A generative shim serves its socket only while a turn process is alive, so a dead listener means no turn
+// is running — nothing to interrupt — and an unproven probe sends nothing. `settle` additionally waits for
+// that listener to go dead: for a one-turn-per-process adapter the abort ends the process, and confirming
+// only then means a delivery that follows the interrupt wakes cold instead of poking an exiting agent.
+export async function interruptViaRendezvous(id, harness, opts = {}) {
+    const probe = await rendezvousListening(id);
+    if (probe === 'dead')
+        return { ok: false, error: `no ${harness} turn is running for session ${id} - nothing to interrupt` };
+    if (probe === 'unproven')
+        return { ok: false, error: `${harness} rendezvous listener for session ${id} is unproven - interrupt NOT sent` };
+    const answered = await sendRendezvousInterrupt(id, harness);
+    if (!answered.ok || !opts.settle)
+        return answered;
+    const deadline = Date.now() + RENDEZVOUS_INTERRUPT_SETTLE_MS;
+    for (;;) {
+        const state = await rendezvousListening(id);
+        if (state === 'dead')
+            return { ok: true };
+        if (Date.now() >= deadline)
+            return { ok: false, error: `${harness} confirmed the interrupt but its turn process for session ${id} is still ${state === 'live' ? 'serving' : 'unproven'} after ${RENDEZVOUS_INTERRUPT_SETTLE_MS}ms` };
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+}
+function sendRendezvousInterrupt(id, harness) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let c;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(wall);
+            try {
+                c?.destroy();
+            }
+            catch { /* */ }
+            resolve(r);
+        };
+        const wall = setTimeout(() => done({ ok: false, error: `${harness} did not confirm the interrupt for session ${id} within ${RENDEZVOUS_INTERRUPT_WALL_MS}ms (a shim materialized before interrupt support never answers - rerun spex materialize)` }), RENDEZVOUS_INTERRUPT_WALL_MS);
+        try {
+            c = createConnection({ path: rvSock(id) });
+        }
+        catch (e) {
+            done({ ok: false, error: `rendezvous socket connect threw: ${String(e)} - interrupt NOT sent` });
+            return;
+        }
+        c.on('error', (e) => done({ ok: false, error: `rendezvous socket error: ${e?.code || String(e)} - interrupt NOT confirmed` }));
+        c.on('close', () => done({ ok: false, error: `rendezvous connection closed before ${harness} answered the interrupt` }));
+        c.on('connect', () => c.write(`${JSON.stringify({ type: 'interrupt' })}\n`));
+        let buf = '';
+        c.on('data', (chunk) => {
+            buf += chunk.toString('utf8');
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                let msg = {};
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (msg.type === 'interrupt-done')
+                    return done({ ok: true });
+                if (msg.type === 'interrupt-rejected')
+                    return done({ ok: false, error: `${harness} rejected the interrupt: ${msg.error || 'no reason given'}` });
+            }
+        });
+    });
+}
 // The JSON-RPC the delivery handshake speaks, in send order. Method names + param shapes are pinned to codex
 // 0.142.3 (`codex app-server generate-ts` → ClientRequest.ts / v2/*Params.ts): the visible TUI is launched with
 // `codex --remote unix://<sock>`, so its thread is ALREADY loaded in this server — we must NOT `thread/resume`
@@ -592,8 +669,13 @@ export function codexLaunchCommand(id, codexCmd = 'codex', serverCmd, dir = runt
         `if [ "$1" = "--resume" ]; then`,
         `  tid=$2`,
         ...(attachTui ? [] : [
-            // A headless forced reopen has no TUI to attach and the shared app-server already owns the thread. Keep it
-            // a no-op instead of calling codex-launch without a prompt (which would mint an unrelated empty thread).
+            // A headless resume has no TUI to reload the thread. The shared app-server evicts an idle thread from its
+            // loaded set, and headless readiness proves online only for a RESIDENT thread, so resume must reopen it
+            // here — the load the visible TUI's `resume "$tid"` would have done — or readiness times out for a thread
+            // that is fine on disk. codex-generation-session above already ensured the app-server, so `$sock` is live.
+            `  ${SPEX} internal codex-reopen "$sock" "$tid" || exit 1`,
+            // A headless forced reopen with NO thread id and no prompt has nothing to attach and nothing to launch.
+            // Keep it a no-op instead of calling codex-launch without a prompt (which would mint an unrelated thread).
             `elif [ "$#" -eq 0 ]; then`,
             `  exit 0`,
         ]),
@@ -946,6 +1028,69 @@ const CODEX_MUTATION_CENSUS_MS = 15_000;
 const CODEX_MUTATION_BASE_MS = 15_000;
 const CODEX_ARCHIVE_FLUSH_FLOOR_BYTES_PER_MS = 1000;
 const codexArchiveBudgetMs = (bytes) => CODEX_MUTATION_BASE_MS + Math.ceil(bytes / CODEX_ARCHIVE_FLUSH_FLOOR_BYTES_PER_MS);
+// @@@ codexReopenThread - load an evicted thread back into the shared app-server WITHOUT running a turn. The
+// app-server evicts an idle thread from its in-memory loaded set, and codex-headless readiness/liveness proves
+// online only when the thread is resident (thread/loaded/list). A visible-TUI resume reloads it implicitly via
+// `resume "$tid"`; headless has no TUI, so its resume must issue this `thread/resume` itself or readiness times
+// out for a thread that is perfectly fine on disk. `excludeTurns` + a one-row page keeps a huge rollout from
+// streaming back — we only need the load, not the history. Idempotent: reopening an already-loaded thread is a
+// no-op the server answers at once.
+export function codexReopenThread(sock, threadId, budgetMs = 20_000) {
+    return new Promise((resolve) => {
+        const conn = createConnection(sock);
+        const fs = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
+        let upgraded = false, settled = false;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                conn.destroy();
+            }
+            catch { /* */ }
+            resolve(r);
+        };
+        const timer = setTimeout(() => done({ ok: false, error: `codex app-server did not reopen thread ${threadId} within ${budgetMs}ms` }), budgetMs);
+        conn.on('error', (e) => done({ ok: false, error: `codex app-server connection failed: ${rpcError(e)}` }));
+        conn.on('close', () => done({ ok: false, error: 'codex app-server closed before thread/resume was answered' }));
+        const send = (m) => conn.write(wsText(JSON.stringify(m)));
+        conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))));
+        const handle = (json) => {
+            let m;
+            try {
+                m = JSON.parse(json);
+            }
+            catch {
+                return;
+            }
+            if (m.error)
+                return done({ ok: false, error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` });
+            if (m.id === 1 && m.result) {
+                send({ method: 'initialized', params: {} });
+                return send({ id: 2, method: 'thread/resume', params: { threadId, excludeTurns: true, initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' } } });
+            }
+            if (m.id === 2 && m.result)
+                return done({ ok: true });
+        };
+        conn.on('data', (chunk) => {
+            fs.buf = Buffer.concat([fs.buf, chunk]);
+            if (!upgraded) {
+                const i = fs.buf.indexOf('\r\n\r\n');
+                if (i < 0)
+                    return;
+                const head = fs.buf.slice(0, i).toString('utf8');
+                if (!/^HTTP\/1\.1 101/.test(head))
+                    return done({ ok: false, error: 'codex app-server refused WebSocket upgrade for thread/resume' });
+                upgraded = true;
+                fs.buf = fs.buf.slice(i + 4);
+                send(wsInitialize);
+            }
+            if (drainWsFrames(fs, conn, handle))
+                done({ ok: false, error: 'codex app-server closed during thread/resume' });
+        });
+    });
+}
 // Codex treats an omitted or empty sourceKinds filter as "interactive" defaults. Cold proof must census the
 // entire native thread graph, including subAgent/thread-spawn rows that have no Spex record, so the adapter
 // supplies every protocol source kind explicitly for its thread/list calls.
@@ -2413,6 +2558,18 @@ function stripCodexTrustFor(cur, proj, hooksJson) {
     }
     return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n*$/, '');
 }
+// @@@ assertCodexConfigParses - ~/.codex/config.toml has TWO uncoordinated writers, codex itself and this adapter,
+// and neither rewrite is something the other waits for. A body read mid-write (a line cut short) or one already
+// broken must never be written back: codex refuses the whole file, and every dispatched thread then dies at
+// config load. The check is on the bytes about to land, so stripping this project's own duplicate still heals.
+function assertCodexConfigParses(file, body) {
+    try {
+        parseToml(body);
+    }
+    catch (error) {
+        throw new Error(`refusing to rewrite ${file}: it does not parse as TOML (${error instanceof Error ? error.message : String(error)}); the file is broken or another writer is mid-write — repair it, then rerun`);
+    }
+}
 // additively stamp PROJECT trust (`[projects."<proj>"] trust_level = "trusted"`) AND the per-hook
 // `trusted_hash` blocks for each event into the user's GLOBAL ~/.codex/config.toml, so a dispatched or
 // self-launched codex trusts THIS project's config layer (enabling hook discovery) AND treats each hook as
@@ -2432,9 +2589,11 @@ export function writeCodexTrust(proj, events, cmdFor) {
     }
     const blk = `# spexcode:trust:${proj} (managed — do not edit)\n${lines.join('\n')}\n# spexcode:trust:end:${proj}`;
     const cleaned = stripCodexTrustFor(existsSync(file) ? readFileSync(file, 'utf8') : '', proj, hooksJson);
+    const next = cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`;
+    assertCodexConfigParses(file, next);
     if (!existsSync(home))
         mkdirSync(home, { recursive: true });
-    writeFileIfChanged(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`);
+    writeFileIfChanged(file, next);
     return file;
 }
 // the inverse of writeCodexTrust: strip THIS project's codex trust from the GLOBAL config.toml — the SAME
@@ -2452,7 +2611,9 @@ function removeCodexTrust(proj) {
         !cur.includes(`# spexcode:trust:${proj} `) && !cur.includes(`# spexcode:trust:end:${proj}`))
         return;
     const cleaned = stripCodexTrustFor(cur, proj, hooksJson);
-    writeFileSync(file, cleaned ? `${cleaned}\n` : '');
+    const next = cleaned ? `${cleaned}\n` : '';
+    assertCodexConfigParses(file, next);
+    writeFileIfChanged(file, next);
 }
 // is this file git-tracked in proj? (guards cleanHarness's deleteIfEmpty; env-stripped git, never throws)
 function isTrackedFile(proj, f) {
@@ -2671,10 +2832,9 @@ export const claudeHarness = {
     dispatchId: 'claude',
     headless: false,
     events: CLAUDE_EVENTS,
-    ownsRendezvous: true, // reclaude opens the rendezvous control socket (prompt delivery + liveness)
+    ownsRendezvous: true, // claude's background daemon opens the rendezvous control socket (prompt delivery + liveness)
     paneTitleIsSelfSummary: true, // claude writes its live task summary into the OSC pane title → headline derives from it
-    executionTrace: readProjectJsonlExecutionTrace,
-    readTranscript: readClaudeTranscript,
+    transcript: claudeTranscript,
     launchCmd: (_id, _rt, cmd) => claudeBaseCmd(cmd), // claude's full invocation IS its base command (the tail is appended by the caller)
     baseCmd: claudeBaseCmd,
     oneShotTurn: (prompt, cmd) => ({ command: `${claudeBaseCmd(cmd)} -p`, stdin: prompt }), // --print reads the prompt from stdin
@@ -2792,10 +2952,9 @@ export const codexHarness = {
     headless: false,
     sharedRuntimeSpawn: true,
     events: CODEX_EVENTS,
-    ownsRendezvous: false, // no reclaude daemon — liveness + prompts through the project app-server socket
+    ownsRendezvous: false, // no rendezvous daemon — liveness + prompts through the project app-server socket
     paneTitleIsSelfSummary: false, // codex's pane title is a spinner + the cwd folder name, NOT a task summary → headline uses the prompt
-    executionTrace: readCodexExecutionTrace,
-    readTranscript: readCodexTranscript,
+    transcript: codexTranscript,
     launchCmd: (id, runtimeDir, cmd) => codexLaunchCommand(id, codexBaseCmd(cmd), undefined, runtimeDir ?? runtimeRoot()), // the full app-server+TUI script BUILT AROUND the resolved base command; ONE app-server per PROJECT
     baseCmd: codexBaseCmd,
     oneShotTurn: (prompt, cmd) => ({ command: `${codexBaseCmd(cmd)} exec -`, stdin: prompt }), // `exec -` reads the prompt from stdin
@@ -3094,11 +3253,13 @@ async function codexHeadlessReadinessProof(current) {
         return null;
     const descriptor = codexHeadlessHarness.sharedRuntimes?.(record.runtimeDir)
         .find((candidate) => candidate.key === codexDescriptorKey(endpoint));
-    if (!descriptor?.residency)
+    if (!descriptor)
         return null;
     const generationBefore = codexRuntimeGenerationProof(record.runtimeDir, endpoint);
     if (!generationBefore)
         return null;
+    if (!descriptor.residency)
+        return null;
     let resident;
     try {
         resident = await descriptor.residency();
@@ -3179,7 +3340,7 @@ export const codexHeadlessHarness = {
 // hook binding (its lifecycle surface is the in-process extension API), so the shim is a GENERATED TypeScript
 // extension (.pi/extensions/spexcode.ts, run natively by pi) that forwards five claude-shaped events to
 // dispatch.sh AND binds this session's rendezvous socket itself (the adapter's launchEnv exports
-// CLAUDE_BG_RENDEZVOUS_SOCK) speaking the reclaude line protocol — so
+// CLAUDE_BG_RENDEZVOUS_SOCK) speaking claude's rendezvous line protocol — so
 // deliverViaRendezvous and the socket-listener liveness work through the same adapter seam. Trust: pi gates project-local
 // extensions behind saved per-directory trust (~/.pi/agent/trust.json), so writeTrust stamps the main
 // checkout there (the nearest-parent lookup covers nested worktrees) and the launch carries `--approve` as
@@ -3189,10 +3350,9 @@ export const piHarness = {
     dispatchId: 'pi',
     headless: false,
     events: PI_EVENTS,
-    ownsRendezvous: true, // the generated extension binds rvSock(id) and speaks the reclaude protocol
+    ownsRendezvous: true, // the generated extension binds rvSock(id) and speaks claude's rendezvous protocol
     paneTitleIsSelfSummary: false, // pi's pane title is not an agent-written task summary → headline uses the prompt preview
-    executionTrace: readSessionJsonlExecutionTrace,
-    readTranscript: (threadId, range) => unsupportedTranscriptReader('pi', threadId, range),
+    transcript: piTranscript,
     launchCmd: (_id, _rt, cmd) => `${piBaseCmd(cmd)} --approve`, // --approve = one-run project trust (belt to writeTrust's braces)
     baseCmd: piBaseCmd,
     sessionIdArg: (id) => `--session-id ${id}`, // caller pins the exact session id, claude-style (created if missing)
@@ -3242,6 +3402,8 @@ export const piHeadlessHarness = {
     launchCmd: (id, runtimeDir, cmd) => piHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), piBaseCmd(cmd)),
     liveness: sessionHomeLiveness,
     deliver: deliverViaPiHeadless,
+    // the controller aborts its own turn child natively and confirms only once that child is gone
+    interrupt: interruptPiHeadless,
     cleanupRuntime: (rec) => unlinkSocks(piHeadlessSock(rec.session), rvSock(rec.session)),
     coldRuntime: async (rec) => {
         const result = await piHeadlessColdRuntime(rec);
@@ -3262,8 +3424,7 @@ export const zcodeHarness = {
     events: ZCODE_EVENTS,
     ownsRendezvous: false,
     paneTitleIsSelfSummary: false,
-    executionTrace: noExecutionTrace,
-    readTranscript: (threadId, range) => unsupportedTranscriptReader('zcode', threadId, range),
+    transcript: unsupportedTranscript('zcode'),
     launchCmd: (_id, _rt, cmd) => `${zcodeBaseCmd(cmd)} --prompt`,
     baseCmd: zcodeBaseCmd,
     // z-code's one-turn launcher already IS the non-interactive shape; it takes the prompt as an argument.
@@ -3299,8 +3460,7 @@ export const opencodeHarness = {
     // socket the launch env hands it, so the shared reply poke and socket-listener liveness are reused verbatim.
     ownsRendezvous: true,
     paneTitleIsSelfSummary: false, // opencode's TUI title is not the agent's live task self-summary → headline uses the prompt
-    executionTrace: readLocalStoreExecutionTrace,
-    readTranscript: (threadId, range) => unsupportedTranscriptReader('opencode', threadId, range),
+    transcript: opencodeTranscript,
     launchCmd: (_id, _rt, cmd) => opencodeLaunchCommand(opencodeBaseCmd(cmd)), // the tail-branching script (prompt vs --resume/--continue marker)
     baseCmd: opencodeBaseCmd,
     // `opencode run` takes the message positionally; it documents no stdin form, so the prompt is an argument.
@@ -3361,6 +3521,9 @@ export const opencodeHeadlessHarness = {
     deliver: async (rec, text) => {
         return deliverViaSocketOrWake(rec.session, text, rec.mid, () => spawnOpenCodeHeadlessTurn(rec, text, opencodeBaseCmd(rec.launchCmd ?? undefined), rvSock(rec.session)), `opencode-headless rendezvous probe was inconclusive for session ${rec.session} - refusing to start a possibly duplicate turn`);
     },
+    // `opencode run` serves the rendezvous socket only for the turn it runs, so the plugin's session abort IS the
+    // interrupt, and the listener going dead is the turn's exit — confirmed only then, so the next delivery wakes cold
+    interrupt: (rec) => interruptViaRendezvous(rec.session, 'opencode-headless', { settle: true }),
 };
 // every adapter — materialize iterates this to write each harness's artifacts in one pass.
 export const HARNESSES = [claudeHarness, codexHarness, opencodeHarness, piHarness, zcodeHarness, claudeHeadlessHarness, opencodeHeadlessHarness, piHeadlessHarness, codexHeadlessHarness];
@@ -3390,12 +3553,6 @@ export function launcherList(root = mainCheckout()) {
     })
         .sort((a, b) => a.name.localeCompare(b.name));
 }
-// The dashboard's visibility projection. It never removes a launcher from the complete config/CLI path;
-// it only narrows GET /api/settings for the New Session picker ([[launcher-visibility]]).
-export function dashboardLauncherList(root = mainCheckout()) {
-    const showHeadless = readConfig(root).dashboard?.showHeadlessLaunchers === true;
-    return launcherList(root).filter((launcher) => showHeadless || !launcher.headless);
-}
 export const MISSING_DEFAULT_LAUNCHER_ERROR = 'sessions.defaultLauncher is required for a launch without --launcher; set it in spexcode.json or spexcode.local.json (for example {"sessions":{"defaultLauncher":"claude"}})';
 // the configured default launcher NAME ([[launcher-select]]) — the profile `spex session new`/a dropdown pick with no
 // explicit choice resolves. Missing config is a fail-loud setup error, never an implicit fallthrough to a

package/node_modules/@spexcode/spec-cli/dist/host.js

@@ -506,7 +506,11 @@ function readBody(req) {
 export function startHostDashboard(opts) {
     const distDir = opts.distDir ?? resolveDistDir();
     const peers = new MachinePeerGateway();
-    peers.start();
+    // a refused control socket is reclaimed inside start(); only a LIVE owner rejects, and that is fatal for a host
+    void peers.start().catch((error) => {
+        console.error(`spex dashboard: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    });
     const sseClients = new Set();
     let lastBroadcast = '';
     // reconcile → push the fresh list to every /projects/stream subscriber when it changed.

package/node_modules/@spexcode/spec-cli/dist/index.js

@@ -7,7 +7,7 @@ import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { etag } from 'hono/etag';
 import { createNodeWebSocket } from '@hono/node-ws';
-import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig, loadReviewConfig, readAliasedRawRecord, runtimeRoot } from '@spexcode/spec-core';
+import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig, loadReviewConfig, runtimeRoot } from '@spexcode/spec-core';
 import { issuesEnabled, resolveRemark, retractRemark } from './localIssues.js';
 import { closeIssue, createIssue, findIssue, mergedIssues, promote } from './issues.js';
 import { remarkWithLoopIn, replyIssueWithLoopIn } from './loop-in.js';
@@ -21,10 +21,9 @@ import { gitA, gitTry, repoRoot } from '@spexcode/spec-core';
 import { cockpitReview } from './cockpit.js';
 import { EMPTY_PROMPT_ERROR, retractDiffComment, listSessions, listArchivedSessionIndex, sendText, drainSession, markHumanPromptActive, interruptSession, rawKey, stopSession, closeSession, quarantineCorruptRecord, restoreQuarantinedRecord, resumeSession, mergeSession, captureSessionResult, sessionPrompt, renameSession, setSessionSort, linkZCodeChildSession, projectCreatedSession, sessionCreateRequest, superviseQueue, superviseTurnFailures, superviseDelivery, startWorktreeTrashReaper, SessionRecordUnusable, TMUX_SOCK, sessionDiff, saveDiffComment, sendDiffComments, canonicalWatchRecipients } from './sessions.js';
 import { readTimeline } from './session-timeline.js';
-import { readSessionExecution, sessionExecutionStream } from './session-execution.js';
-import { defaultHarness, HARNESSES, codexHarness, dashboardLauncherList, launcherDefault, harnessById } from './harness.js';
+import { readSessionTranscript, readSessionTranscriptTool, sessionTranscriptStream } from './session-transcript.js';
+import { defaultHarness, HARNESSES, codexHarness, launcherList, launcherDefault } from './harness.js';
 import { ensureCodexGenerationLedger, reclaimDrainingCodexGenerations } from './codex-runtime-generations.js';
-import { TranscriptReadError } from './transcript-reader.js';
 import { readBlobByHash } from '@spexcode/spec-eval/evaltab';
 import { putBlob } from '@spexcode/spec-eval/cache';
 import { fileHumanReading } from '@spexcode/spec-eval/filing';
@@ -299,11 +298,10 @@ app.post('/api/evidence', async (c) => {
 });
 // the SETTINGS read surface — one route for everything spexcode.json / spexcode.local.json resolves to:
 // `layout` (resolveLayout()'s main/worktrees/branch shape — the write-guard's project-identity probe reads
-// `.layout.main`) and the dashboard-visible launcher profiles ([[launcher-visibility]]) the New-Session picker
-// offers — `{ name, harness, cmd, headless }`: the cmd is read-only display data for the picker (the dashboard sits
+// `.layout.main`) and the complete launcher profiles ([[launcher-select]]) the New-Session picker offers —
+// `{ name, harness, cmd, headless }`: the cmd is read-only display data for the picker (the dashboard sits
 // behind the gateway auth; the browser can read but never edit config) — plus the configured `default` NAME
-// so the picker pre-selects the SAME launcher a bare `spex session new` uses when that row is visible, else
-// its first visible row rather than a hidden headless default,
+// so the picker pre-selects the SAME launcher a bare `spex session new` uses, else its first row.
 // Missing defaultLauncher is returned as an actionable config error, not hidden by falling through to the
 // built-in `claude` launcher.
 // `tmuxSocket` is the `-L <name>` label our private tmux server runs under (a backend fact, env-overridable),
@@ -311,7 +309,7 @@ app.post('/api/evidence', async (c) => {
 // beside the blessed `spex session attach` command — the frontend never hardcodes the socket.
 app.get('/api/settings', async (c) => c.json({
     layout: await resolveLayout(),
-    launchers: dashboardLauncherList(),
+    launchers: launcherList(),
     tmuxSocket: TMUX_SOCK,
     ...launcherDefault(),
 }));
@@ -784,60 +782,12 @@ app.get('/api/sessions/:id/capture', async (c) => {
         return c.text('session offline (no live pane)', 409);
     return c.text('capture failed', 502);
 });
-// A live adapter-owned execution observation, intentionally distinct from the durable conversation timeline.
-// The response carries only the backend-normalized latest working note and typed tool rows; no transcript bytes
-// or parser schema cross this API boundary.
-app.get('/api/sessions/:id/execution', (c) => {
-    const execution = readSessionExecution(c.req.param('id') || '');
-    return execution ? c.json(execution) : c.json({ error: 'no such session' }, 404);
-});
-app.get('/api/sessions/:id/execution/stream', (c) => sessionExecutionStream(c));
-// The native transcript is a bounded payload behind the durable timeline index. Bounds are explicit epoch
-// milliseconds so the route never guesses which status interval the caller intended.
-app.get('/api/sessions/:id/transcript', async (c) => {
-    const id = c.req.param('id') || '';
-    const fromRaw = c.req.query('from');
-    const toRaw = c.req.query('to');
-    if (fromRaw == null || toRaw == null || fromRaw === '' || toRaw === '')
-        return c.json({ error: 'transcript needs both from and to epoch milliseconds' }, 400);
-    const from = Number(fromRaw);
-    const to = Number(toRaw);
-    if (!Number.isFinite(from) || !Number.isFinite(to) || !Number.isInteger(from) || !Number.isInteger(to) || from >= to)
-        return c.json({ error: 'transcript interval is invalid: from and to must be integer epoch milliseconds with from < to' }, 400);
-    let raw;
-    try {
-        raw = readAliasedRawRecord(id);
-    }
-    catch (error) {
-        return c.json({ error: `session ${id} record is unreadable: ${error instanceof Error ? error.message : String(error)}` }, 500);
-    }
-    if (!raw || !raw.governed)
-        return c.json({ error: `session ${id} does not exist` }, 404);
-    let harness;
-    try {
-        harness = harnessById(typeof raw.harness === 'string' && raw.harness ? raw.harness : defaultHarness.id);
-    }
-    catch (error) {
-        return c.json({ error: error instanceof Error ? error.message : String(error) }, 500);
-    }
-    const threadId = harness.exactNativeTargetId({
-        session: raw.session_id,
-        harnessSessionId: typeof raw.harness_session_id === 'string' ? raw.harness_session_id : null,
-        stopped: !!raw.stopped,
-        archived: !!raw.archived,
-    });
-    if (!threadId)
-        return c.json({ error: `session ${id} transcript is unavailable: native harness identity is missing` }, 409);
-    try {
-        return c.json(await harness.readTranscript(threadId, { from, to }));
-    }
-    catch (error) {
-        if (!(error instanceof TranscriptReadError))
-            throw error;
-        const status = error.reason === 'unsupported' ? 501 : error.reason === 'invalid' ? 422 : 409;
-        return c.json({ error: error.message, reason: error.reason }, status);
-    }
-});
+// The native transcript behind the durable timeline index ([[transcript-reader]], [[session-transcript]]):
+// a closed interval by GET, the open working interval by SSE. Bounds are explicit epoch milliseconds so the
+// route never guesses which stretch the caller intended; native bytes stay behind the adapter.
+app.get('/api/sessions/:id/transcript', (c) => readSessionTranscript(c));
+app.get('/api/sessions/:id/transcript/stream', (c) => sessionTranscriptStream(c));
+app.get('/api/sessions/:id/transcript/tool/:toolId', (c) => readSessionTranscriptTool(c));
 // the session's persisted interaction history ([[session-timeline]]): authored status transitions (with the
 // FULL note text) + delivered prompts, timestamped, oldest first — what a terminal-free surface renders as
 // the conversation. `?limit=<n>` caps the tail (default 500). 404 for an unknown/non-governed id.
@@ -1045,8 +995,14 @@ app.post('/api/sessions/:id/input', async (c) => {
             return c.json({ ok: false, error: EMPTY_PROMPT_ERROR }, 400);
         const deliveryKey = typeof body?.deliveryId === 'string' && body.deliveryId.trim() ? body.deliveryId.trim() : undefined;
         // Command Box acceptance is the durable append. Do not hold the HTTP request on a
-        // slow native handoff: the delivery supervisor already owns the queued retry path.
-        const r = await sendText(id, text, undefined, deliveryKey ? { deliveryKey, deferDrain: true } : { deferDrain: true });
+        // slow native handoff: the delivery supervisor already owns the queued retry path. The Conversation
+        // footer is a Command Box on a terminal-free surface, so it says `replyVia:"note"` here exactly as a
+        // text send would, and the note-reply insert rides the same delivery.
+        const r = await sendText(id, text, undefined, {
+            deferDrain: true,
+            ...(deliveryKey ? { deliveryKey } : {}),
+            ...(body?.replyVia === 'note' ? { replyVia: 'note' } : {}),
+        });
         if (!r.ok)
             return c.json(r, 502);
         // Start the first handoff without holding the HTTP response on native readiness. The queue remains the

package/node_modules/@spexcode/spec-cli/dist/machine-peer.d.ts

@@ -51,8 +51,9 @@ export declare class MachinePeerGateway {
     private control;
     private retry;
     private closing;
-    start(): void;
+    start(): Promise<void>;
     private startControl;
+    private listenControl;
     private handleRpc;
     private startInbound;
     private stopInbound;

package/node_modules/@spexcode/spec-cli/dist/machine-peer.js

@@ -72,13 +72,17 @@ export function readPeerMachineId() {
     writeStore({ ...store, machineId });
     return machineId;
 }
+// @@@ peer sender spelling - the authenticated peer identity travels as the message's ordinary `senderSessionId`,
+// so it must fit the protocol's frozen session_id grammar `[0-9A-Za-z_][0-9A-Za-z_-]*` (session-protocol §5.2:
+// no `:`, no leading `-`; namespaces are encoded INTO the id). `peer_<machineId>_<sessionId>` is that encoding;
+// the earlier `peer:` spelling was refused by every receiving backend with PROTOCOL_SESSION_ID_INVALID.
 export function peerSenderRef(machineId, sessionId) {
-    return sessionId && validMachineId(sessionId) ? `peer:${machineId}:${sessionId}` : `peer:${machineId}`;
+    return sessionId && validMachineId(sessionId) ? `peer_${machineId}_${sessionId}` : `peer_${machineId}`;
 }
 function validPeerSender(value, machineId) {
     if (typeof value !== 'string')
         return false;
-    const match = value.match(/^peer:([0-9a-f-]{36})(?::([0-9a-f-]{36}))?$/i);
+    const match = value.match(/^peer_([0-9a-f-]{36})(?:_([0-9a-f-]{36}))?$/i);
     return !!match && match[1] === machineId && (match[2] === undefined || validMachineId(match[2]));
 }
 export function findMachinePeer(sshAddress) {
@@ -367,34 +371,61 @@ function sshArgs(peer) {
         '--', peer.sshAddress,
     ];
 }
+// true iff something ACCEPTS a connection at this unix path; any error (ECONNREFUSED for a leftover path, ENOENT
+// for a vanished one) means no live listener.
+function probeUnixListener(path) {
+    return new Promise((resolve) => {
+        const socket = createConnection(path);
+        socket.once('connect', () => { socket.destroy(); resolve(true); });
+        socket.once('error', () => resolve(false));
+    });
+}
 export class MachinePeerGateway {
     inbound = new Map();
     children = new Map();
     control = null;
     retry = null;
     closing = false;
+    // start() resolves once the control socket is claimed. With no leftover path the claim is synchronous (the
+    // listener is issued before the promise settles, so callers may issue control RPCs right away); a leftover path
+    // is probed first, which is the only asynchronous branch.
     start() {
         for (const peer of listMachinePeers())
             this.startInbound(peer);
-        this.startControl();
-        for (const peer of listMachinePeers())
-            if (peer.owner)
-                this.ensureTunnel(peer);
-        this.retry = setInterval(() => {
+        return this.startControl().then(() => {
             for (const peer of listMachinePeers())
-                if (peer.owner && peer.state === 'connecting')
+                if (peer.owner)
                     this.ensureTunnel(peer);
-        }, PEER_RETRY_MS);
-        this.retry.unref();
+            this.retry = setInterval(() => {
+                for (const peer of listMachinePeers())
+                    if (peer.owner && peer.state === 'connecting')
+                        this.ensureTunnel(peer);
+            }, PEER_RETRY_MS);
+            this.retry.unref();
+        });
     }
+    // @@@ stale control socket - a killed gateway never unlinks peer.sock, so the FILE proves nothing about
+    // ownership; only a connect does. A live gateway accepts the connection; a leftover path refuses it
+    // (ECONNREFUSED). So a missing path is claimed at once, a refusing path is unlinked and reclaimed, and only an
+    // accepting listener is "another `spex dashboard`" — the same test claude-rendezvous applies to its socket file.
     startControl() {
         const path = peerSocketPath();
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        if (existsSync(path)) {
-            const error = new Error(`machine peer service already owns ${path} — another \`spex dashboard\` may be running`);
-            error.name = 'BackendError';
-            throw error;
+        if (!existsSync(path)) {
+            this.listenControl(path);
+            return Promise.resolve();
         }
+        return probeUnixListener(path).then((live) => {
+            if (live) {
+                const error = new Error(`machine peer service already owns ${path} — another \`spex dashboard\` is running`);
+                error.name = 'BackendError';
+                throw error;
+            }
+            rmSync(path, { force: true });
+            this.listenControl(path);
+        });
+    }
+    listenControl(path) {
         this.control = createNetServer({ allowHalfOpen: true }, (socket) => {
             let input = '';
             socket.setEncoding('utf8');

package/node_modules/@spexcode/spec-cli/dist/opencode.js

@@ -89,8 +89,16 @@ export const SpexcodePlugin = async (ctx) => {
   }
 
   // The shared rendezvous server receives best-effort reply pokes. An unadopted plugin simply leaves the
-  // timeline line for its next turn boundary; the SDK injection remains host-owned.
-  rt.serveRendezvous(injectPrompt, { canInject: () => !!(client && rootSession) })
+  // timeline line for its next turn boundary; the SDK injection remains host-owned. An interrupt is
+  // opencode's own session abort on the adopted root session, confirmed back over the same socket.
+  rt.serveRendezvous(injectPrompt, {
+    canInject: () => !!(client && rootSession),
+    interrupt: async () => {
+      if (!client || !rootSession) throw new Error("no opencode session is adopted - nothing to interrupt")
+      const r = await client.session.abort({ path: { id: rootSession } })
+      if (r === false || (r && r.data === false)) throw new Error("no opencode turn is running - nothing to interrupt")
+    },
+  })
 
   const toolPayload = (input, output) => {
     const sid = (input && input.sessionID) || ""