spexcode 0.6.8 → 0.7.0-next.1

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

@@ -39,21 +39,34 @@ export default function spexcode(pi: ExtensionAPI) {
   const toolFields = (toolName: string, input: unknown) =>
     ({ tool_name: TOOL[toolName] ?? toolName, tool_input: rt.toolInput(input, "path") })
 
+  // the RUNNING turn's context, kept from the events pi hands us mid-turn: ctx.abort() is pi's own "stop the
+  // current agent operation" — the one honest interrupt — and only a turn that is actually streaming has one.
+  let turn: { abort: () => void; isIdle: () => boolean } | null = null
   // bound as soon as the extension loads so liveness reads online early; only a governed launch carries the
   // socket env (sessions.ts rvEnv) — a self-launched bare \`pi\` skips this.
-  const rv = rt.serveRendezvous((text: string) => pi.sendUserMessage(text, { deliverAs: "steer" }))
+  const rv = rt.serveRendezvous((text: string) => pi.sendUserMessage(text, { deliverAs: "steer" }), {
+    interrupt: () => {
+      if (!turn || turn.isIdle()) throw new Error("no pi turn is running - nothing to interrupt")
+      turn.abort()
+    },
+  })
 
   pi.on("session_start", async (_event, ctx) => {
     sessionId = ctx.sessionManager.getSessionId() || sessionId
     process.env.PI_SESSION_ID = sessionId   // tool subprocesses inherit it → spex CLI knows its session
     await rt.dispatchEvent("SessionStart")
   })
-  pi.on("input", async (event) => { await rt.dispatchEvent("UserPromptSubmit", { prompt: event.text }) })
-  pi.on("tool_call", async (event) => {
+  // agent_start is the earliest event a running turn hands us — before the first model token — so an
+  // interrupt that arrives while the model is still thinking finds a turn to abort rather than nothing.
+  pi.on("agent_start", async (_event, ctx) => { turn = ctx })
+  pi.on("turn_start", async (_event, ctx) => { turn = ctx })
+  pi.on("input", async (event, ctx) => { turn = ctx; await rt.dispatchEvent("UserPromptSubmit", { prompt: event.text }) })
+  pi.on("tool_call", async (event, ctx) => {
+    turn = ctx
     const r = await rt.dispatchEvent("PreToolUse", toolFields(event.toolName, event.input))
     if (rt.blocked(r)) return { block: true, reason: rt.blockReason(r, "blocked by a SpexCode hook") }
   })
-  pi.on("tool_result", async (event) => { await rt.dispatchEvent("PostToolUse", toolFields(event.toolName, event.input)) })
+  pi.on("tool_result", async (event, ctx) => { turn = ctx; await rt.dispatchEvent("PostToolUse", toolFields(event.toolName, event.input)) })
   // Stop rides the runtime's dispatchStop on TWO bindings that never duplicate: agent_end performs the
   // NORMAL dispatch (pi awaits its listeners inside the run loop and drains a queued teach as the SAME
   // awaited prompt's continuation — never the orphaned settle-time prompt whose late inject threw
@@ -69,7 +82,7 @@ export default function spexcode(pi: ExtensionAPI) {
     async (reason: string) => pi.sendUserMessage(reason, { deliverAs: "steer" }),
     "a SpexCode Stop hook blocked this stop without giving a reason",
   )
-  pi.on("agent_end", async () => { await stop() })
+  pi.on("agent_end", async () => { turn = null; await stop() })
   pi.on("agent_settled", async () => { if (rt.stopPending()) await stop() })
   pi.on("session_shutdown", async () => { rv?.close() })
 }

package/node_modules/@spexcode/spec-cli/dist/pi-headless.d.ts

@@ -3,6 +3,7 @@ import type { DispatchResult, HarnessDeliveryRecord } from './harness.js';
 export declare const piHeadlessSock: (id: string) => string;
 export declare function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: string): string;
 export declare const deliverViaPiHeadless: (rec: HarnessDeliveryRecord, text: string) => Promise<DispatchResult>;
+export declare const interruptPiHeadless: (rec: HarnessDeliveryRecord) => Promise<DispatchResult>;
 export declare function piHeadlessColdRuntime(rec: Pick<HarnessDeliveryRecord, 'session'>): Promise<DispatchResult>;
 export declare class PiHeadlessController {
     private readonly id;
@@ -19,6 +20,7 @@ export declare class PiHeadlessController {
     private terminateTurn;
     private waitForExit;
     private accept;
+    private interrupt;
     private handle;
     private spawnTurn;
 }

package/node_modules/@spexcode/spec-cli/dist/pi-headless.js

@@ -12,6 +12,7 @@ const CONTROL_TIMEOUT_MS = 30_000;
 const START_TIMEOUT_MS = 30_000;
 const TERM_EXIT_GRACE_MS = 500;
 const KILL_EXIT_GRACE_MS = 2_000;
+const INTERRUPT_EXIT_GRACE_MS = 15_000;
 /** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
 export const piHeadlessSock = (id) => join(tmpdir(), `spexcode-ph-${id}.sock`);
 export function piHeadlessLaunchCommand(id, runtimeDir, piCmd) {
@@ -21,6 +22,13 @@ export const deliverViaPiHeadless = (rec, text) => controlRequest(piHeadlessSock
     name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
     rejected: 'pi-headless controller rejected the request',
 });
+// The controller owns the turn child, so it is the one actor that can both abort the turn natively and
+// know when that turn is actually over — an interrupt confirmed here means no pi process serves this
+// session any more, and the next delivery is a clean cold wake rather than a poke into an exiting agent.
+export const interruptPiHeadless = (rec) => controlRequest(piHeadlessSock(rec.session), { type: 'interrupt' }, {
+    name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'pi-headless controller rejected the interrupt',
+});
 // The resident controller and a running pi turn own two per-session listeners. The generic lifecycle
 // teardown has already proved and removed the exact controller leaf before this runs; cold filing is valid
 // only once neither listener can still accept work for this session.
@@ -137,7 +145,25 @@ export class PiHeadlessController {
             });
         });
     }
+    // Abort the running turn through pi's own ctx.abort() (the shim answers over the child's rendezvous socket,
+    // so pi records the turn as aborted and the conversation stays resumable), then wait for that child to
+    // exit. A turn whose extension holds no context yet — pi still booting, before its first agent event —
+    // is still THIS controller's process, so it is terminated as the owner rather than left to run.
+    async interrupt() {
+        const turn = this.child;
+        if (!turn || turn.process.exitCode !== null)
+            return { ok: false, error: `no pi-headless turn is running for session ${this.id} - nothing to interrupt` };
+        const { interruptViaRendezvous } = await import('./harness.js');
+        const aborted = await interruptViaRendezvous(this.id, 'pi-headless');
+        if (!aborted.ok && !/no pi turn is running|nothing to interrupt/.test(aborted.error || ''))
+            return aborted;
+        if (!aborted.ok || !await this.waitForExit(turn, INTERRUPT_EXIT_GRACE_MS))
+            await this.terminateTurn(turn);
+        return { ok: true };
+    }
     async handle(request) {
+        if (request.type === 'interrupt')
+            return this.interrupt();
         if (request.type !== 'deliver')
             return { ok: false, error: 'unknown pi-headless control request' };
         if (!request.text)
@@ -171,6 +197,7 @@ export class PiHeadlessController {
             if (this.child === turn)
                 this.child = null;
             resolveExit(code);
+            // an aborted child leaves non-zero too; the session layer's interrupt marker reads that exit as the interrupt it was
             if (code !== 0 && !this.closing)
                 void import('./harness.js').then(({ reportHeadlessTurnExit }) => reportHeadlessTurnExit(this.id, 'pi-headless', code, this.cwd));
         });

package/node_modules/@spexcode/spec-cli/dist/session-transcript.d.ts

@@ -0,0 +1,57 @@
+import type { Context } from 'hono';
+import { type Harness } from './harness.js';
+type Target = {
+    ok: true;
+    harness: Harness;
+    threadId: string;
+} | {
+    ok: false;
+    status: 404 | 409 | 500;
+    error: string;
+};
+export declare function resolveTranscriptTarget(id: string): Target;
+export declare function readSessionTranscript(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 500 | 404 | 409, "json">) | (Response & import("hono").TypedResponse<{
+    readonly revision: string;
+    readonly from: number;
+    readonly to: number;
+    readonly turns: readonly {
+        readonly id: string;
+        readonly at: number;
+        readonly role: "user" | "assistant";
+        readonly text?: string | undefined;
+        readonly tools?: readonly {
+            readonly id: string;
+            readonly name: string;
+            readonly input?: string | undefined;
+            readonly output?: string | undefined;
+            readonly outputLines: number;
+            readonly outputBytes: number;
+        }[] | undefined;
+    }[];
+    readonly truncated: boolean;
+    readonly omittedTurns: number;
+    readonly omittedBytes: number;
+    readonly outOfOrderEvents: number;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+    reason: string;
+}, 409 | 422 | 501, "json">)>;
+export declare function readSessionTranscriptTool(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+    reason: string;
+}, 409 | 422 | 501, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 500 | 404 | 409, "json">) | (Response & import("hono").TypedResponse<{
+    id: string;
+    output: string | null;
+    outputLines: number;
+    outputBytes: number;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export declare function sessionTranscriptStream(c: Context): Promise<Response>;
+export {};

package/node_modules/@spexcode/spec-cli/dist/session-transcript.js

@@ -0,0 +1,137 @@
+import { streamSSE } from 'hono/streaming';
+import { readAliasedRawRecord } from '@spexcode/spec-core';
+import { defaultHarness, harnessById } from './harness.js';
+import { TranscriptReadError, openFrameStream } from '@spexcode/transcript';
+export function resolveTranscriptTarget(id) {
+    let raw;
+    try {
+        raw = readAliasedRawRecord(id);
+    }
+    catch (error) {
+        return { ok: false, status: 500, error: `session ${id} record is unreadable: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (!raw || !raw.governed)
+        return { ok: false, status: 404, error: `session ${id} does not exist` };
+    let harness;
+    try {
+        harness = harnessById(typeof raw.harness === 'string' && raw.harness ? raw.harness : defaultHarness.id);
+    }
+    catch (error) {
+        return { ok: false, status: 500, error: error instanceof Error ? error.message : String(error) };
+    }
+    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 { ok: false, status: 409, error: `session ${id} transcript is unavailable: native harness identity is missing` };
+    return { ok: true, harness, threadId };
+}
+const epoch = (value) => {
+    if (value == null || value === '')
+        return null;
+    const number = Number(value);
+    return Number.isFinite(number) && Number.isInteger(number) ? number : null;
+};
+const failure = (error) => {
+    if (!(error instanceof TranscriptReadError))
+        throw error;
+    return { body: { error: error.message, reason: error.reason }, status: error.reason === 'unsupported' ? 501 : error.reason === 'invalid' ? 422 : 409 };
+};
+// GET /api/sessions/:id/transcript?from=<ms>&to=<ms> — a closed interval, both bounds explicit so the route
+// never guesses which stretch the caller meant.
+export async function readSessionTranscript(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 = epoch(fromRaw);
+    const to = epoch(toRaw);
+    if (from === null || to === null || from >= to)
+        return c.json({ error: 'transcript interval is invalid: from and to must be integer epoch milliseconds with from < to' }, 400);
+    const target = resolveTranscriptTarget(id);
+    if (!target.ok)
+        return c.json({ error: target.error }, target.status);
+    try {
+        return c.json(await target.harness.transcript.read(target.threadId, { from, to }));
+    }
+    catch (error) {
+        const { body, status } = failure(error);
+        return c.json(body, status);
+    }
+}
+// GET /api/sessions/:id/transcript/tool/:toolId?from=<ms> — one call's recorded output, read when a person
+// opens it. The live stream withholds output bodies (below), so this is where a body comes from; the interval
+// is `[from, now]`, the same stretch the stream reads, and a call outside it is a 404.
+export async function readSessionTranscriptTool(c) {
+    const id = c.req.param('id') || '';
+    const toolId = c.req.param('toolId') || '';
+    const from = epoch(c.req.query('from'));
+    if (from === null || !toolId)
+        return c.json({ error: 'transcript tool needs a tool id and from as integer epoch milliseconds' }, 400);
+    const target = resolveTranscriptTarget(id);
+    if (!target.ok)
+        return c.json({ error: target.error }, target.status);
+    try {
+        const read = await target.harness.transcript.read(target.threadId, { from, to: Math.max(from + 1, Date.now()) });
+        for (const turn of read.turns)
+            for (const tool of turn.tools ?? []) {
+                if (tool.id !== toolId)
+                    continue;
+                return c.json({ id: tool.id, output: tool.output ?? null, outputLines: tool.outputLines, outputBytes: tool.outputBytes });
+            }
+        return c.json({ error: `tool ${toolId} is not in this interval` }, 404);
+    }
+    catch (error) {
+        const { body, status } = failure(error);
+        return c.json(body, status);
+    }
+}
+const TICK_MS = 500;
+const HEARTBEAT_TICKS = 20;
+// GET /api/sessions/:id/transcript/stream?from=<ms> — the open interval [from, now], carried over SSE. What a
+// frame holds, when one is worth sending, and how a subscriber merges it are [[transcript-frames]]'
+// `openFrameStream`, shared with every other transport; this route owns only the carriage: a tick that asks
+// the stream to publish, one `transcript` SSE event per frame it yields, and periodic `ping` heartbeats so the
+// browser's dead-man can reopen a silent stream. Reading happens only while a client is subscribed and stops
+// on abort, closing the cursor.
+export async function sessionTranscriptStream(c) {
+    const id = c.req.param('id') || '';
+    const from = epoch(c.req.query('from'));
+    if (from === null)
+        return c.json({ error: 'transcript stream needs from as integer epoch milliseconds' }, 400);
+    const target = resolveTranscriptTarget(id);
+    if (!target.ok)
+        return c.json({ error: target.error }, target.status);
+    const frames = openFrameStream(target.harness.transcript, target.threadId, from);
+    return streamSSE(c, async (stream) => {
+        let aborted = false;
+        let ticks = 0;
+        const publish = async () => {
+            const frame = await frames.publish();
+            if (frame)
+                await stream.writeSSE({ event: 'transcript', data: JSON.stringify(frame) });
+        };
+        stream.onAbort(() => { aborted = true; frames.close(); });
+        try {
+            await publish();
+            while (!aborted) {
+                await stream.sleep(TICK_MS);
+                if (aborted)
+                    break;
+                await publish();
+                if (++ticks % HEARTBEAT_TICKS === 0)
+                    await stream.writeSSE({ event: 'ping', data: 'x' });
+            }
+        }
+        catch {
+            // EventSource reconnects a dropped stream; a native read must never take the session server down.
+        }
+        finally {
+            frames.close();
+        }
+    });
+}

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

@@ -342,6 +342,10 @@ export declare function markState(status: Lifecycle, opts?: {
 export declare function markHumanPromptActive(sessionId: string): boolean;
 export declare const markDone: (proposal?: Proposal, sessionId?: string, note?: string) => boolean;
 export declare function markTurnFailure(sessionId: string | undefined, note: string): boolean;
+export declare const INTERRUPTED_NOTE = "interrupted: the human stopped this turn; the next message continues the conversation";
+export declare function stampInterrupt(id: string): void;
+export declare function clearInterruptMarker(id: string): void;
+export declare const markInterrupted: (sessionId: string) => boolean;
 export declare function markHeadlessTurnFailure(sessionId: string, harness: string, exitCode: string): boolean;
 export declare function existingHarnessLaunchTarget(id: string): string | null;
 export declare function stageHarnessLaunchProof(sessionId: string | undefined, harnessSessionId: string | undefined, launchPayload: string): boolean;

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

@@ -1,7 +1,7 @@
 import { execFile, execFileSync, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createHash, randomUUID } from 'node:crypto';
-import { readFileSync, writeFileSync, existsSync, renameSync, linkSync, mkdirSync, rmSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, renameSync, linkSync, mkdirSync, rmSync, readdirSync, realpathSync, statSync, unlinkSync } from 'node:fs';
 import { join, dirname, isAbsolute, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { rm as rmAsync, readdir as readdirAsync } from 'node:fs/promises';
@@ -1458,7 +1458,7 @@ export function withPeerSenderHint(text, sender, sshAddress, machineId) {
     const who = sender.label && sender.label !== sender.id ? `session "${sender.label}" (${sender.id})` : `session ${sender.id}`;
     return `${text}\n\n— from ${who} on machine ${machineId}. To reply: spex session send --ssh ${sshAddress} ${sender.id} "<your reply>"`;
 }
-export const withNoteReplyHint = (text) => `${text}\n\n— REQUIRED REPLY TRANSPORT (PER-MESSAGE): this terminal-free sender CANNOT see normal assistant/final output. Do not stop after only printing the answer. As your FINAL action, put your COMPLETE reply to this message in the truthful declaration's --note. For an answered exploratory question or simple answer awaiting the sender's follow-up, run \`spex session ask --note "<complete reply>"\`; if the true state is done or parked, put the same complete reply in that declaration's --note instead. This declaration command is reply transport, not part of the requested work, and remains REQUIRED even when the message says to use no tools, make no tool calls, or only print/reply. A later message arriving WITHOUT this notice means the sender is back at a terminal and reads your normal output again.`;
+export const withNoteReplyHint = (text) => `${text}\n\n— REPLY TRANSPORT: This sender cannot read normal assistant output. Before ending this turn, make your FINAL tool call a Spex declaration carrying the COMPLETE reply in --note: use \`session ask\` when waiting for a human reply; use \`done\` or \`park\` when that is the truthful state. This rule applies even when asked to only print/reply or make no tool calls.\n\nFor multi-line replies, preserve real LF characters. \`functions.exec\` runs a shell command through bash, so never interpolate \`JSON.stringify(note)\` into it; use stdin, a heredoc, or base64, then pass \`--note \"$note\"\`. Never use \`String.raw\` or literal backslash+n. Do not call any tool after the declaration.`;
 export const withTerminalReplyHint = (text) => `${text}\n\n— sent from a terminal-attached client: the sender now reads your terminal output directly. Reply in your normal conversation output from here on — stop putting replies in declaration --notes (the earlier terminal-free notices no longer apply; a --note can go back to being a short status line).`;
 export const slugify = (s) => (s || 'session').normalize('NFC').replace(/[^\p{L}\p{N}_-]+/gu, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '') || 'session';
 const MENTION = /\[\[(\.?[\p{L}\p{N}_-]+)\]\]/u;
@@ -1880,7 +1880,7 @@ function observeQueuedLaunchReadiness(id, harness, timeoutMs = SOCKET_READY_TIME
                 return;
             if (current.status === 'queued') {
                 publishCanonicalLifecycle(current, 'active', null, null);
-                writeRecord({ ...current, status: 'active', proposal: null, note: null, launchOwner: null, launchReadinessStartedAt: null });
+                writeRecord({ ...current, status: 'active', proposal: null, note: null, stopped: false, launchOwner: null, launchReadinessStartedAt: null });
             }
             else if (current.launchReadinessStartedAt != null)
                 writeRecord({ ...current, launchReadinessStartedAt: null });
@@ -1991,7 +1991,7 @@ async function startQueuedUnlocked(id) {
         // headline precedence stands on.
         const launched = readRecord(id) || wt.rec;
         publishCanonicalLifecycle(launched, 'active', null, null);
-        writeRecord({ ...launched, status: 'active', proposal: null, note: null, launchOwner: null, launchReadinessStartedAt: readinessStartedAt });
+        writeRecord({ ...launched, status: 'active', proposal: null, note: null, stopped: false, launchOwner: null, launchReadinessStartedAt: readinessStartedAt });
         if (!h.launchPayloadProof)
             removeLaunchFile(id);
         // release the boot-window hold once the socket is up (then isOccupying takes over) or after the bounded
@@ -2988,7 +2988,7 @@ async function prepareSession(prompt, parent, launcher, name, context) {
                 try {
                     gitMutationStarted = true;
                     traceSessionCreate(id, requestDigest, phase, 'start', 'worktree-add');
-                    const added = await withGitAbortSignal(signal, () => gitTry(['-C', root, 'worktree', 'add', '-b', branch, path, startPoint], { extraEnv: DEFER_FOOTPRINT_REFRESH }));
+                    const added = await withGitAbortSignal(signal, () => gitTry(['-C', root, 'worktree', 'add', '--no-track', '-b', branch, path, startPoint], { extraEnv: DEFER_FOOTPRINT_REFRESH }));
                     traceSessionCreate(id, requestDigest, phase, 'finish', 'worktree-add');
                     if (added.ok)
                         Object.assign(owned, { path: true, worktree: true, branch: true });
@@ -3129,26 +3129,23 @@ async function waitForReady(id, harness, pending, timeoutMs = SOCKET_READY_TIMEO
     if (harness.launchPayloadProof && !current()?.harnessSessionId) {
         for (;;) {
             if (hasReadableLaunchReceipt(id)) {
-                if (recordLockHeld) {
+                // The probe above ran outside the fence, so another consumer (the drain, a resume recovery) may have
+                // taken the receipt first. Under the fence a receipt that is already gone with the identity bound is
+                // that consumer's success, not a missing receipt; gone and unbound means keep waiting.
+                const consume = () => {
                     readinessWakeSuppressed.add(id);
                     try {
+                        if (!hasReadableLaunchReceipt(id))
+                            return !!readRecord(id)?.harnessSessionId;
                         consumeHarnessLaunchProofUnlocked(id);
+                        return true;
                     }
                     finally {
                         readinessWakeSuppressed.delete(id);
                     }
-                }
-                else
-                    await withRecordLock(id, async () => {
-                        readinessWakeSuppressed.add(id);
-                        try {
-                            consumeHarnessLaunchProofUnlocked(id);
-                        }
-                        finally {
-                            readinessWakeSuppressed.delete(id);
-                        }
-                    });
-                break;
+                };
+                if (recordLockHeld ? consume() : await withRecordLock(id, async () => consume()))
+                    break;
             }
             if (Date.now() >= deadline)
                 return null;
@@ -3484,9 +3481,57 @@ export function markTurnFailure(sessionId, note) {
         return true;
     });
 }
+// @@@ interrupt projection - a CONFIRMED human interrupt ended the turn, and the record says so the way an
+// undeclared stop does: `asking`, with the reason, because the agent now waits for the human's next message.
+// Active-only like every other turn-outcome writer: a declaration that landed first (the agent answered
+// before the abort reached it) stays authoritative. The marker is stamped before the abort is sent so the
+// adapter's own exit report — a one-turn process leaves with a non-zero code when aborted — reads the same
+// outcome instead of filing a failed turn; it expires so a genuine failure later is never mistaken for it.
+export const INTERRUPTED_NOTE = 'interrupted: the human stopped this turn; the next message continues the conversation';
+const INTERRUPT_MARKER_TTL_MS = 15_000;
+const interruptMarkerPath = (id) => sessionArtifactPath(id, 'turn.interrupted');
+export function stampInterrupt(id) {
+    mkdirSync(storeDir(id), { recursive: true });
+    writeFileSync(interruptMarkerPath(id), String(Date.now()));
+}
+export function clearInterruptMarker(id) {
+    try {
+        unlinkSync(interruptMarkerPath(id));
+    }
+    catch { /* never stamped, or already consumed */ }
+}
+function consumeInterruptMarker(id) {
+    let at = NaN;
+    try {
+        at = Number(readFileSync(interruptMarkerPath(id), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    clearInterruptMarker(id);
+    return Number.isFinite(at) && Date.now() - at <= INTERRUPT_MARKER_TTL_MS;
+}
+function projectInterruptedUnlocked(sessionId) {
+    const rec = readLiveRecord(sessionId);
+    if (!rec?.governed || rec.status !== 'active' || rec.stopped || rec.archived)
+        return false;
+    const application = configuredSessionApplicationIfCutover();
+    if (application) {
+        application.transitionSession(sessionId, {
+            status: 'asking', proposal: null, note: INTERRUPTED_NOTE,
+            recipientSessionIds: canonicalWatchRecipients(application, sessionId, 'asking'),
+        });
+        return true;
+    }
+    writeRecord({ ...rec, status: 'asking', proposal: null, note: INTERRUPTED_NOTE });
+    return true;
+}
+export const markInterrupted = (sessionId) => withRecordLockSync(sessionId, () => projectInterruptedUnlocked(sessionId));
 export function markHeadlessTurnFailure(sessionId, harness, exitCode) {
     if (exitCode === '0')
         return false;
+    if (consumeInterruptMarker(sessionId))
+        return markInterrupted(sessionId);
     const outcome = /^\d+$/.test(exitCode) ? `exit code ${exitCode}` : `signal ${exitCode}`;
     return markTurnFailure(sessionId, `${harness} turn exited with ${outcome}`);
 }
@@ -5296,17 +5341,38 @@ export function canonicalMessageText(message, recipient) {
     }
     throw new ResourceConflict(`canonical message kind ${message.kind} cannot be delivered as session text`);
 }
-// Hard interrupt is adapter-native control, distinct from stop's process teardown. A harness without a
-// confirmed native primitive refuses loudly; there is no signal/PTY fallback that could target the wrong turn.
+// Hard interrupt is adapter-native control, distinct from stop's process teardown. A harness with a native
+// primitive uses it. Without one the transport decides: a HEADLESS adapter has no keyboard, so it refuses
+// loudly rather than emulating an interrupt with a signal that could hit the wrong process; a PANE-BACKED
+// TUI has an operator's keyboard by definition, so its interrupt is the key that operator would press —
+// C-c into its own pane, through the raw-key channel below — and only while its lifecycle is actually
+// active, because the same key on an idle TUI is a second Ctrl-C away from quitting it.
 export async function interruptSession(id) {
+    // The lifecycle read and the key send share ONE record lock: a declaration that lands between them would
+    // otherwise turn "interrupt the working turn" into "Ctrl-C an idle TUI", so there is no window.
     return withRecordLock(id, async () => {
         const rec = readRecord(id);
         if (!rec)
             return { ok: false, error: `no session record for ${id} - nothing to interrupt` };
         const h = harnessById(rec.harness || defaultHarness.id);
-        if (!h.interrupt)
+        if (h.interrupt) {
+            // stamped BEFORE the abort: the adapter's exit report can race the confirmation, and either order must
+            // read "interrupted" (see the interrupt projection); a refused interrupt leaves no trace behind.
+            stampInterrupt(id);
+            const result = await h.interrupt({ ...rec, runtimeDir: runtimeRoot() });
+            if (!result.ok) {
+                clearInterruptMarker(id);
+                return result;
+            }
+            projectInterruptedUnlocked(id);
+            return result;
+        }
+        if (h.headless)
             return { ok: false, error: `harness ${h.id} has no native hard-interrupt control` };
-        return h.interrupt({ ...rec, runtimeDir: runtimeRoot() });
+        if (rec.status !== 'active')
+            return { ok: false, error: `session ${id} is not working (lifecycle ${rec.status}) - nothing to interrupt` };
+        const sent = await sendRawKeysLocked(id, ['C-c']);
+        return sent ? { ok: true } : { ok: false, error: `session ${id} has no live pane to interrupt` };
     });
 }
 // @@@ rawKey - the RAW-KEYSTROKE nav path, kept DELIBERATELY on `tmux send-keys` and NEVER the rendezvous
@@ -5367,21 +5433,23 @@ function rawKeyArgs(id, key) {
 // ORDER, so they reach the pane in exactly the order they were struck. Concurrent per-key POSTs used to race
 // (browser + server + send-keys all parallel) and scramble the sequence; a single serialised batch cannot.
 // An unknown token is skipped without dropping the rest; false only if the tmux session is gone or nothing sent.
+// the send itself, for a caller that already holds the record lock (rawKey below; interruptSession above)
+async function sendRawKeysLocked(id, keys) {
+    const list = keys.filter((k) => typeof k === 'string' && k.length > 0);
+    if (list.length === 0 || !(await alive(id)))
+        return false;
+    let sent = false;
+    for (const k of list) {
+        const args = rawKeyArgs(id, k);
+        if (!args)
+            continue;
+        await tmux(args);
+        sent = true;
+    }
+    return sent;
+}
 export async function rawKey(id, key) {
-    const sent = await withRecordLock(id, async () => {
-        const list = (Array.isArray(key) ? key : [key]).filter((k) => typeof k === 'string' && k.length > 0);
-        if (list.length === 0 || !(await alive(id)))
-            return false;
-        let sent = false;
-        for (const k of list) {
-            const args = rawKeyArgs(id, k);
-            if (!args)
-                continue;
-            await tmux(args);
-            sent = true;
-        }
-        return sent;
-    });
+    const sent = await withRecordLock(id, () => sendRawKeysLocked(id, Array.isArray(key) ? key : [key]));
     // Raw-key remote control is transport fallback, not a lifecycle event. Freshness belongs to the
     // harness turn hooks or a successfully handed-over durable prompt; navigation keys cannot forge working.
     return sent;

package/node_modules/@spexcode/spec-cli/dist/shim-runtime.js

@@ -117,6 +117,8 @@ const spexShimRuntime = (cfg) => {
 
   // The per-session rendezvous control socket is a best-effort same-turn poke. The timeline remains the
   // message's durable copy, so this listener only receives reply lines and never confirms or rejects them.
+  // An "interrupt" line is the one CONFIRMED message: the host's native abort runs and the socket answers
+  // interrupt-done or interrupt-rejected, because an interrupt has no durable copy to fall back on.
   const serveRendezvous = (inject, opts) => {
     const sock = (process.env.CLAUDE_BG_RENDEZVOUS_SOCK || "").trim()
     if (!sock) return null
@@ -125,6 +127,7 @@ const spexShimRuntime = (cfg) => {
     const server = __spexCreateServer((c) => {
       let buf = ""
       c.on("error", () => { /* probes disconnect abruptly — expected */ })
+      const answer = (o) => { try { c.write(JSON.stringify(o) + "\\n") } catch { /* the asker left — nothing to confirm to */ } }
       c.on("data", (d) => {
         buf += d.toString("utf8")
         let nl
@@ -133,6 +136,17 @@ const spexShimRuntime = (cfg) => {
           buf = buf.slice(nl + 1)
           let msg
           try { msg = JSON.parse(line) } catch { continue }
+          if (msg && msg.type === "interrupt") {
+            const abort = opts && opts.interrupt
+            if (!abort) { answer({ type: "interrupt-rejected", error: "this " + HARNESS + " shim exposes no native abort" }); continue }
+            try {
+              Promise.resolve(abort()).then(
+                () => answer({ type: "interrupt-done" }),
+                (e) => answer({ type: "interrupt-rejected", error: String((e && e.message) || e) }),
+              )
+            } catch (e) { answer({ type: "interrupt-rejected", error: String((e && e.message) || e) }) }
+            continue
+          }
           if (msg && msg.type === "reply" && typeof msg.text === "string") {
             if (opts && opts.canInject && !opts.canInject()) continue
             const mid = typeof msg.mid === "string" ? msg.mid : ""

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

@@ -49,7 +49,7 @@ const childApiBase = `http://127.0.0.1:${proxyPort}`;
 // observe the source closure, compile it, then make the supervisor's normal zero-downtime swap. A source edit
 // must never cause a restart that still runs the old dist.
 const watchRoots = workspaceRoot
-    ? [sourceRoot, join(workspaceRoot, 'spec-forge', 'src'), join(workspaceRoot, 'spec-eval', 'src'), join(workspaceRoot, 'packages', 'spec-core', 'src')]
+    ? [sourceRoot, join(workspaceRoot, 'spec-forge', 'src'), join(workspaceRoot, 'spec-eval', 'src'), join(workspaceRoot, 'packages', 'spec-core', 'src'), join(workspaceRoot, 'packages', 'transcript', 'src')]
     : [here];
 function buildWorkspace() {
     if (!workspaceRoot)

package/node_modules/@spexcode/spec-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-cli",
-  "version": "0.6.8",
+  "version": "0.7.0-next.1",
   "type": "module",
   "description": "SpexCode CLI + server. The root spexcode package delegates to this compiled package; dashboard assets live in @spexcode/spec-dashboard.",
   "bin": {
@@ -35,11 +35,13 @@
     "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
   },
   "dependencies": {
-    "@spexcode/session-application": "0.6.8",
-    "@spexcode/session-selflaunch": "0.6.8",
-    "@spexcode/spec-core": "0.6.8",
-    "@spexcode/spec-eval": "0.6.8",
-    "@spexcode/spec-forge": "0.6.8"
+    "@spexcode/session-application": "0.7.0-next.1",
+    "@spexcode/session-selflaunch": "0.7.0-next.1",
+    "@spexcode/spec-core": "0.7.0-next.1",
+    "@spexcode/spec-eval": "0.7.0-next.1",
+    "@spexcode/spec-forge": "0.7.0-next.1",
+    "@spexcode/transcript": "0.7.0-next.1",
+    "smol-toml": "^1.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.16.0",

package/node_modules/@spexcode/spec-core/dist/layout.d.ts

@@ -14,7 +14,6 @@ export type Config = {
         apiUrl?: string;
         title?: string;
         icon?: string;
-        showHeadlessLaunchers?: boolean;
     };
     uploads?: {
         maxBytes?: number;

package/node_modules/@spexcode/spec-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-core",
-  "version": "0.6.8",
+  "version": "0.7.0-next.1",
   "type": "module",
   "description": "SpexCode's dependency-minimal spec graph core.",
   "files": [