@spexcode/spec-cli 0.6.6 → 0.6.8

package/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 } from '@spexcode/spec-core';
+import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig, loadReviewConfig, readAliasedRawRecord, 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';
@@ -19,10 +19,12 @@ import { getBoardJson } from './graphCache.js';
 import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged, flushDeferredWorktreeRegistryChange } from './graphStream.js';
 import { gitA, gitTry, repoRoot } from '@spexcode/spec-core';
 import { cockpitReview } from './cockpit.js';
-import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, quarantineCorruptRecord, restoreQuarantinedRecord, archiveSession, resumeSession, mergeSession, captureSessionResult, sessionPrompt, findSessionClosure, renameSession, setSessionSort, linkZCodeChildSession, sessionCreateRequest, superviseQueue, superviseTurnFailures, superviseDelivery, SessionRecordUnusable, TMUX_SOCK } from './sessions.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, dashboardLauncherList, launcherDefault } from './harness.js';
+import { defaultHarness, HARNESSES, codexHarness, dashboardLauncherList, launcherDefault, harnessById } 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';
@@ -30,6 +32,10 @@ import { fileHumanOk } from '@spexcode/spec-eval/humanok';
 import { buildExportModel, renderExportHtml, buildSessionEvals, SessionEvalUnavailableError } from '@spexcode/spec-eval/sessioneval';
 import { appendUpload, cancelUpload, completeUpload, createUpload, evidenceMaxBytes, startUploadReaper, UploadError, uploadStatus } from './uploads.js';
 import { listSessionFiles, openSessionFile, SESSION_FILE_PREVIEW_MAX_BYTES, sessionFilePreviewKind, SessionFileError } from './session-files.js';
+import { readSourceSlice, SourceReadError, SOURCE_SLICE_MAX_BYTES } from './source-read.js';
+import { listSourceDir } from './source-list.js';
+import { loadConfig as loadLintConfig } from './lint.js';
+import { listNodeAttachments, readNodeAttachment } from './spec-attachments.js';
 import { attachViewer, detachViewer, resizeBridge, hideViewer, forwardInput, superviseBridges } from './pty-bridge.js';
 import { installProcessGuards } from '@spexcode/spec-core';
 import { resolveProjectIdentity } from '@spexcode/spec-core';
@@ -38,11 +44,17 @@ import { collectResourceReport, ResourceConflict } from './host-resources.js';
 import { reparentRequest, SessionReparentRequestError } from './session-reparent.js';
 import { buildGuidanceCatalog } from './guidance-catalog.js';
 import { installEvalHost } from './eval-host.js';
+import { configuredSessionApplicationIfCutover, setSessionApplicationCommitObserver } from './session-application.js';
+import { editSpecBody, readSpecBodyEdit, SpecBodyEditError } from './spec-body-edit.js';
 installEvalHost();
 // last-resort net: an unforeseen async throw (e.g. a worktree vanishing mid-read during a worker
 // self-merge) is logged and the server KEEPS SERVING instead of exiting and dropping the public port.
 installProcessGuards();
+startWorktreeTrashReaper();
 const app = new Hono();
+// Canonical lifecycle commits do not touch a watched JSON file. Bridge those commits into the existing board
+// stream so status/proposal/parent changes arrive without waiting for a later human send or delivery tick.
+setSessionApplicationCommitObserver(() => notifyBoardChanged('sessions'));
 startUploadReaper();
 app.use('/api/*', cors());
 app.onError((error, c) => {
@@ -127,6 +139,24 @@ app.get('/api/specs/:id/content', (c) => {
     const x = specContent(c.req.param('id'));
     return x ? c.json(x) : c.json({ body: '', parts: null }, 404);
 });
+// [[spec-body-edit]]: the WRITE half of the spec document — a human at the board replaces a line range of
+// a node's body and it lands as a real commit. The endpoint takes no path (it derives one from the node id)
+// and rewrites nothing but the body, so a request cannot reach code or frontmatter; a region that moved
+// since it was read is a 409 with the current text, never a merge. The version bump and drift are
+// recomputed from the commit by [[source-of-truth]] — nothing else is written.
+app.post('/api/specs/:id/body', async (c) => {
+    try {
+        const result = await editSpecBody(c.req.param('id'), readSpecBodyEdit(await c.req.json().catch(() => null)));
+        if (result.changed)
+            notifyBoardChanged('full');
+        return c.json(result);
+    }
+    catch (e) {
+        if (e instanceof SpecBodyEditError)
+            return c.json({ error: e.message, code: e.code, ...(e.detail ?? {}) }, e.status);
+        throw e;
+    }
+});
 app.get('/api/specs/:id/history', async (c) => c.json(await specHistory(c.req.param('id'))));
 // the spec.md line diff one version introduced — the history tab's per-version proof-of-change, fetched
 // lazily when an older version's item expands (the latest version's diff ships with the board as node.lastDiff).
@@ -135,6 +165,64 @@ app.get('/api/specs/:id/diff/:hash', async (c) => c.json(await specDiffAt(c.req.
 // worktree's working tree. An untracked brand-new node is invisible to `git diff <base>`, so when the base
 // diff is empty AND status is `??` synthesize an all-additions view via `diff --no-index` (gitTry — --no-index
 // exits 1, which gitA would swallow). Gated on `??` so a tracked file with no pending change stays empty.
+// [[source-read]]: a governed source file, read as a byte WINDOW. The spec tree names the files it governs
+// but the board could never open one — this is the read half of "spec and code on one screen". The policy
+// gate is `isSourceFile`, the SAME predicate the coverage walk uses, so the set of files the board can show
+// is by construction the set the project governs. Query: path (repo-relative), offset, limit; the response
+// carries the file's total size so the client can page without a second HEAD.
+app.get('/api/source', (c) => {
+    try {
+        const root = repoRoot();
+        const slice = readSourceSlice(root, c.req.query('path') || '', loadLintConfig(root), Number(c.req.query('offset') ?? 0), Number(c.req.query('limit') ?? SOURCE_SLICE_MAX_BYTES));
+        return c.json(slice);
+    }
+    catch (e) {
+        if (e instanceof SourceReadError)
+            return c.json({ error: e.message }, e.status);
+        throw e;
+    }
+});
+// [[source-list]]: the LISTING half of the same surface. /api/source opens a file the caller can already
+// name; this names what is there to open, one directory at a time, so the explorer can browse ordinary code
+// the way any editor does. Same `isSourceFile` gate and the same refusals — a row the reader clicks and gets
+// a 404 from is worse than a row that was never drawn. `dir` empty lists the governed roots themselves.
+app.get('/api/files', (c) => {
+    try {
+        const root = repoRoot();
+        const cfg = loadLintConfig(root);
+        return c.json(listSourceDir(root, c.req.query('dir') || '', cfg, cfg.governedRoots));
+    }
+    catch (e) {
+        if (e instanceof SourceReadError)
+            return c.json({ error: e.message }, e.status);
+        throw e;
+    }
+});
+// [[node-attachments]]: what a node carries in its own folder besides its body and its readings. The board
+// showed exactly one file per node folder; these are the rest — eval contracts, evidence dirs, raw captures.
+// A different gate from /api/source on purpose (the spec tree is the product's own data, deliberately outside
+// the coverage policy), the same windowed read underneath.
+app.get('/api/specs/:id/files', (c) => {
+    try {
+        return c.json({ files: listNodeAttachments(repoRoot(), c.req.param('id')) });
+    }
+    catch (e) {
+        if (e instanceof SourceReadError)
+            return c.json({ error: e.message }, e.status);
+        throw e;
+    }
+});
+app.get('/api/specs/:id/files/content', (c) => {
+    try {
+        const slice = readNodeAttachment(repoRoot(), c.req.param('id'), c.req.query('name') || '', Number(c.req.query('offset') ?? 0), Number(c.req.query('limit') ?? SOURCE_SLICE_MAX_BYTES));
+        return c.json(slice);
+    }
+    catch (e) {
+        if (e instanceof SourceReadError)
+            return c.json({ error: e.message }, e.status);
+        throw e;
+    }
+});
 app.get('/api/edit', async (c) => {
     const source = c.req.query('source') || '', path = c.req.query('path') || '';
     if (!source || !path)
@@ -265,7 +353,8 @@ app.get('/api/evals/impact', etag(), async (c) => {
 // most five lightweight neighbors. A missing worktree scope resolves explicitly to trunk; it never
 // serializes another scenario's history or the scoped model.
 app.get('/api/evals/detail', etag(), async (c) => {
-    await ensureBoardFileWatchers(c.req.query('scope')?.trim() || undefined);
+    // Detail is a bounded, direct eval read. It builds only the addressed scope and must not
+    // synchronously reconcile the global worktree watcher registry before answering.
     const node = c.req.query('node')?.trim();
     const scenario = c.req.query('scenario')?.trim();
     if (!node || !scenario)
@@ -495,6 +584,7 @@ app.delete('/api/uploads/:id', (c) => {
 // sessions: real tmux-backed Claude Code sessions. List + spawn, stream the live pane (WebSocket),
 // forward keystrokes, and close.
 app.get('/api/sessions', async (c) => c.json(await listSessions(c.req.query('all') === '1' || c.req.query('all') === 'true')));
+app.get('/api/sessions/archive-index', async (c) => c.json(await listArchivedSessionIndex()));
 app.get('/api/resources', async (c) => c.json(await collectResourceReport()));
 app.post('/api/sessions', async (c) => {
     const requestKey = c.req.header('idempotency-key') || randomUUID();
@@ -510,7 +600,7 @@ app.post('/api/sessions', async (c) => {
     outgoing?.once('close', cancel);
     try {
         const body = await c.req.json().catch(() => null);
-        const result = await sessionCreateRequest(body, { requestKey, signal: controller.signal });
+        const result = await sessionCreateRequest(body, { requestKey, signal: controller.signal, onPublished: projectCreatedSession });
         // The durable row is now public. Nudge the cheap session projection explicitly so a dashboard does not
         // wait for the best-effort store watcher; any held candidate worktree event remains a separate full claim.
         if (result.status === 201)
@@ -530,12 +620,149 @@ app.post('/api/sessions', async (c) => {
         outgoing?.off('close', cancel);
     }
 });
+const runtimeApplicationOr503 = (_c) => {
+    const application = configuredSessionApplicationIfCutover();
+    if (!application)
+        throw new ResourceConflict('session runtime is unavailable until the legacy JSON store is migrated');
+    return application;
+};
+app.get('/api/session-runtime/:id/events', (c) => {
+    const application = runtimeApplicationOr503(c);
+    return c.json(application.events.read(c.req.param('id')));
+});
+app.get('/api/session-runtime/:id/replay', (c) => {
+    const application = runtimeApplicationOr503(c);
+    return c.json(application.replayState(c.req.param('id')));
+});
+app.post('/api/session-runtime/:id/state', async (c) => {
+    const application = runtimeApplicationOr503(c);
+    const body = await c.req.json().catch(() => null);
+    if (body?.status !== undefined && typeof body.status !== 'string')
+        return c.json({ error: 'status must be a string' }, 400);
+    if (body?.proposal !== undefined && body.proposal !== null && typeof body.proposal !== 'string')
+        return c.json({ error: 'proposal must be a string or null' }, 400);
+    if (body?.note !== undefined && body.note !== null && typeof body.note !== 'string')
+        return c.json({ error: 'note must be a string or null' }, 400);
+    if (body?.parentSessionId !== undefined && body.parentSessionId !== null && typeof body.parentSessionId !== 'string')
+        return c.json({ error: 'parentSessionId must be a string or null' }, 400);
+    try {
+        const sessionId = c.req.param('id');
+        const nextStatus = body?.status ?? application.readState(sessionId)?.status;
+        return c.json(application.transitionSession(c.req.param('id'), {
+            status: body?.status,
+            proposal: body?.proposal,
+            note: body?.note,
+            parentSessionId: body?.parentSessionId,
+            reason: typeof body?.reason === 'string' ? body.reason : null,
+            recipientSessionIds: nextStatus === undefined ? undefined : canonicalWatchRecipients(application, sessionId, nextStatus),
+        }));
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : String(error), code: error?.code }, 409);
+    }
+});
+app.post('/api/session-runtime/:id/watch', async (c) => {
+    const application = runtimeApplicationOr503(c);
+    const body = await c.req.json().catch(() => null);
+    if (typeof body?.watcherSessionId !== 'string' || !body.watcherSessionId.trim())
+        return c.json({ error: 'watcherSessionId is required; identity is never inferred' }, 400);
+    const edge = application.attachWatcher(body.watcherSessionId, c.req.param('id'), typeof body.channel === 'string' ? body.channel : undefined);
+    return c.json(edge, 201);
+});
+app.post('/api/session-runtime/:id/bind', async (c) => {
+    const application = runtimeApplicationOr503(c);
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.namespace !== 'string' || typeof body.runtimeKind !== 'string' || typeof body.nativeSessionId !== 'string' || typeof body.nativeStartToken !== 'string') {
+        return c.json({ error: 'namespace, runtimeKind, nativeSessionId, and nativeStartToken are required; identity is never inferred' }, 400);
+    }
+    try {
+        const binding = application.bindRuntime(c.req.param('id'), {
+            namespace: body.namespace,
+            runtimeKind: body.runtimeKind,
+            nativeSessionId: body.nativeSessionId,
+            nativeStartToken: body.nativeStartToken,
+            metadata: body.metadata && typeof body.metadata === 'object' && !Array.isArray(body.metadata) ? body.metadata : undefined,
+        }, typeof body.expectedGeneration === 'number' ? body.expectedGeneration : undefined);
+        return c.json(binding, 200);
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : String(error), code: error?.code }, 409);
+    }
+});
+app.post('/api/session-runtime/:id/publish', async (c) => {
+    const application = runtimeApplicationOr503(c);
+    const body = await c.req.json().catch(() => null);
+    if (typeof body?.kind !== 'string' || typeof body.body !== 'string')
+        return c.json({ error: 'kind and UTF-8 body are required' }, 400);
+    const result = application.notifyRecipients(c.req.param('id'), {
+        kind: body.kind,
+        body: Buffer.from(body.body, 'utf8'),
+        senderSessionId: typeof body.senderSessionId === 'string' ? body.senderSessionId : undefined,
+    });
+    return c.json(result, 201);
+});
+app.post('/api/session-runtime/:id/dequeue', async (c) => {
+    const application = runtimeApplicationOr503(c);
+    const body = await c.req.json().catch(() => null);
+    if (typeof body?.namespace !== 'string')
+        return c.json({ error: 'namespace is required' }, 400);
+    try {
+        const message = application.dequeueForRuntime(c.req.param('id'), body.namespace, typeof body.expectedGeneration === 'number' ? body.expectedGeneration : undefined);
+        return c.json(message, 200);
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : String(error), code: error?.code }, 409);
+    }
+});
 // one server-side merge bundle (ahead/dirty/diff(merge-base)/gates/proposal) for the manager cockpit;
 // dashboard and `spex session review` are thin callers. 404 for an unknown id. See [[manager-cockpit]].
 app.get('/api/sessions/:id/review', async (c) => {
     const r = await cockpitReview(c.req.param('id'));
     return r ? c.json(r) : c.json({ error: 'no such session' }, 404);
 });
+// Per-worktree diff: the branch's commits plus, while the session's worktree is on disk, its uncommitted
+// changes. Metadata is cheap and patches are fetched per file — `path` with `scope` names which one — with an
+// explicit byte window so a large review never materializes the whole tree in one response.
+app.get('/api/sessions/:id/diff', async (c) => {
+    const offset = Math.max(0, Number(c.req.query('offset')) || 0);
+    const limit = Math.min(240_000, Math.max(1, Number(c.req.query('limit')) || 120_000));
+    const scope = c.req.query('scope') === 'working' ? 'working' : 'branch';
+    const result = await sessionDiff(c.req.param('id'), c.req.query('path') || undefined, offset, limit, scope);
+    return result ? c.json(result) : c.json({ error: 'no such session' }, 404);
+});
+app.post('/api/sessions/:id/diff-comments', async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    try {
+        const comment = await saveDiffComment(c.req.param('id'), {
+            id: typeof body?.id === 'string' ? body.id : undefined,
+            filePath: typeof body?.filePath === 'string' ? body.filePath : '',
+            lineStart: Number(body?.lineStart), lineEnd: Number(body?.lineEnd),
+            body: typeof body?.body === 'string' ? body.body : '',
+            diffIdentity: typeof body?.diffIdentity === 'string' ? body.diffIdentity : '',
+        });
+        return comment ? c.json(comment, 201) : c.json({ error: 'no such session' }, 404);
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+    }
+});
+// Retract removes one row from the record's review conversation. 404 for a row (or session) that is not
+// there, so a double-retract is honestly "already gone" rather than a silent success.
+app.delete('/api/sessions/:id/diff-comments/:commentId', async (c) => {
+    try {
+        const removed = await retractDiffComment(c.req.param('id'), c.req.param('commentId'));
+        return removed ? c.json(removed) : c.json({ error: 'no such diff comment' }, 404);
+    }
+    catch (error) {
+        return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+    }
+});
+app.post('/api/sessions/:id/diff-comments/send', async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const ids = Array.isArray(body?.ids) ? body.ids.filter((id) => typeof id === 'string') : undefined;
+    const result = await sendDiffComments(c.req.param('id'), ids);
+    return c.json(result, result.ok ? 200 : 409);
+});
 // The self-contained HTML is the sole full-model transport exception. Interactive rows, including the CLI,
 // use /api/evals pages; a bare request fails loudly rather than reopening a hidden full JSON path.
 app.get('/api/sessions/:id/evals', async (c) => {
@@ -565,6 +792,52 @@ app.get('/api/sessions/:id/execution', (c) => {
     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 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.
@@ -576,13 +849,6 @@ app.get('/api/sessions/:id/timeline', (c) => {
 // the session RECORD detail (`spex session show`): the board row (status · node · branch · launcher · …)
 // plus the full originating prompt (the row itself carries only the preview). One id-addressed read backs
 // the CLI's show; 404 for an unknown id.
-app.get('/api/sessions/:id/closure', (c) => {
-    // A missing close fact and a backend that predates this route are different answers. The client requires
-    // this capability marker even on 404, so an old backend can never turn a closed id into "never existed".
-    c.header('x-spexcode-close-history', 'v1');
-    const closure = findSessionClosure(c.req.param('id'));
-    return closure ? c.json(closure) : c.json({ error: 'no terminal close history for this session' }, 404);
-});
 app.get('/api/sessions/:id', async (c) => {
     const id = c.req.param('id');
     const row = (await listSessions(true)).find((s) => s.id === id);
@@ -645,7 +911,7 @@ app.post('/api/sessions/:id/resume', async (c) => {
 // A merge intent to the session's own agent (it runs the merge), never a server merge.
 app.post('/api/sessions/:id/merge', async (c) => {
     const r = await mergeSession(c.req.param('id'));
-    return c.json(r, r.dispatched ? 200 : (r.status ?? 409));
+    return c.json(r, r.dispatched ? 200 : 409);
 });
 // one WS owns one native tmux client (pty-bridge): server→client = that client's rendered PTY bytes (binary);
 // client→server text controls resize, visibility, and xterm-native input (which carries the mouse/wheel
@@ -764,7 +1030,10 @@ app.post('/api/sessions/:id/input', async (c) => {
         // `from` (the sender's session id) rides only an agent-to-agent send → the backend records the comms
         // edge ([[session-timeline]]); a raw human dispatch omits it and is not logged. `replyVia:"note"` marks a
         // terminal-free sender ([[session-timeline]]): the server appends the note-reply insert to the delivery.
-        const r = await sendText(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined, {
+        const text = typeof body?.text === 'string' ? body.text : '';
+        if (!text.trim())
+            return c.json({ ok: false, error: EMPTY_PROMPT_ERROR }, 400);
+        const r = await sendText(c.req.param('id'), text, typeof body?.from === 'string' ? body.from : undefined, {
             ...(body?.replyVia === 'note' ? { replyVia: 'note' } : {}),
         });
         return c.json(r, r.ok ? 200 : 502);
@@ -772,9 +1041,27 @@ app.post('/api/sessions/:id/input', async (c) => {
     if (body?.kind === 'command') {
         const id = c.req.param('id');
         const text = typeof body?.text === 'string' ? body.text : '';
-        const r = await sendText(id, text);
+        if (!text.trim())
+            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 });
         if (!r.ok)
             return c.json(r, 502);
+        // Start the first handoff without holding the HTTP response on native readiness. The queue remains the
+        // acceptance boundary; only a successful dequeue is allowed to publish human activity.
+        // A deferred drain is an asynchronous handoff, not proof that a prompt was delivered. Only the
+        // accepted queue state for this request may reopen a waiting lifecycle; an empty/raced drain must
+        // never turn a focus-only or retry-only path into `working`.
+        const handoffDeferred = r.delivery === 'deferred';
+        void drainSession(id).then(() => {
+            if (!handoffDeferred)
+                return;
+            const application = configuredSessionApplicationIfCutover();
+            if (application ? !application.readPendingMessages(id).length : true)
+                markHumanPromptActive(id);
+        }).catch((error) => console.error(`spex: command handoff deferred for ${id}: ${error instanceof Error ? error.message : String(error)}`));
         const outcomes = await dispatchNewMentions(text, { sessionId: id });
         return c.json({ ...r, outcomes, mentionSummary: summarizeDispatch(outcomes) });
     }
@@ -820,14 +1107,8 @@ app.post('/api/sessions/:id/quarantine/restore', async (c) => {
     const result = await restoreQuarantinedRecord(c.req.param('id'));
     return c.json({ ok: true, ...result });
 });
-// archive / legacy unarchive signpost ([[archive]]) — archive proves exact cold/offline ownership before filing;
-// `{on:false}` enters the same resume transition and recreates the preserved conversation. {ok:false}=no such session.
-app.post('/api/sessions/:id/archive', async (c) => {
-    const body = await c.req.json().catch(() => ({}));
-    return c.json({ ok: await archiveSession(c.req.param('id'), body?.on !== false) });
-});
 // set (or clear, with a blank) a session's display-name override; persists to the session's global record
-// (`session.json`) so it survives a restart. Unknown id → 404. That record sits INSIDE the watched store, but
+// (`runtime.json`) so it survives a restart. Unknown id → 404. That envelope sits INSIDE the watched store, but
 // the store watch is best-effort (it can fail to attach), so the route still nudges the stream explicitly
 // ([[graph-stream]]) — the rename shows in ~150ms deterministically, never waiting out a cold tick.
 app.post('/api/sessions/:id/rename', async (c) => {
@@ -875,6 +1156,27 @@ const port = Number(process.env.PORT || 8787);
 const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' });
 installConnectionReaper(server);
 injectWebSocket(server);
+// Reclaim only stale, draining Codex generations whose exact detached identity and native reference census
+// prove they have no loaded threads. The current generation and any uncertain/shared process remain intact.
+try {
+    const root = runtimeRoot();
+    await ensureCodexGenerationLedger(root);
+    const descriptors = new Map((codexHarness.sharedRuntimes?.(root) ?? []).map((descriptor) => [descriptor.key, descriptor]));
+    const results = await reclaimDrainingCodexGenerations(root, async (endpoint) => {
+        const key = endpoint.id === 'legacy' ? 'codex-app-server' : `codex-app-server:${endpoint.id}`;
+        const residency = descriptors.get(key)?.residency;
+        if (!residency)
+            return { healthy: false, referenceIds: [], peerCount: 0 };
+        const result = await residency();
+        return { healthy: result.healthy, referenceIds: result.referenceIds, peerCount: 0 };
+    });
+    for (const result of results)
+        if (result.reclaimed)
+            console.log(`[codex] reclaimed stale generation ${result.generationId}`);
+}
+catch (error) {
+    console.error(`[codex] stale generation sweep retained resources: ${error.message}`);
+}
 superviseBridges(); // restore visible helpers after failure; their viewer subscriptions survive replacement
 superviseQueue(); // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
 superviseTurnFailures(); // reconcile adapter-owned native failure subscriptions across backend replacement

package/dist/init.js

@@ -127,7 +127,7 @@ export async function specInit(targetArg, presetArg, harnessArg) {
     const flagRaw = (harnessArg ?? '').trim() ? parseHarnessFlag(harnessArg.trim()) : null;
     const chosenHarnesses = flagRaw ?? readConfig(targetDir).harnesses ?? null;
     if (chosenHarnesses === null) {
-        console.error(`spex init: --harness is required — name the harness(es) this repo delivers into, e.g. \`spex init --harness claude\`. Known native ids: ${NATIVE_HARNESS_IDS.join(', ')} (comma-separate several; a plugin bundle: --harness plugin:<folder>). A pre-existing spexcode.json "harnesses" field also satisfies this.`);
+        console.error(`spex init: --harness is required — name the harness(es) this repo delivers into, e.g. \`spex init --harness claude\`. Known native ids: ${NATIVE_HARNESS_IDS.join(', ')} (comma-separate several; a plugin bundle: --harness plugin:<folder>). Use --harness none to adopt the spec tree and its lint WITHOUT writing into any agent's config. A pre-existing spexcode.json "harnesses" field also satisfies this.`);
         process.exit(1);
     }
     let selectedNativeEvents = null;