spexcode 0.6.1 → 0.6.5

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

@@ -0,0 +1,111 @@
+import { type CockpitReview } from './cockpit.js';
+import { type Session, type SessionClosure, type Resolved, type DispatchResult } from './sessions.js';
+export declare class BackendError extends Error {
+    readonly status?: number | undefined;
+    readonly transport?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, transport?: unknown | undefined);
+}
+export declare function backendConnectionRefused(error: unknown): boolean;
+export declare function localCachedSessions(includeArchived?: boolean): Session[];
+export declare function clientListSessions(includeArchived?: boolean): Promise<Session[]>;
+export declare function clientSessionClosure(selector: string): Promise<SessionClosure | null>;
+export declare function clientResources(): Promise<import('./host-resources.js').ResourceReport>;
+export declare function resolveClientSession(selector: string, includeArchived?: boolean): Promise<Resolved>;
+export type CaptureResult = {
+    ok: true;
+    pane: string;
+} | {
+    ok: false;
+    status: number;
+    reason: string;
+};
+export declare function clientCapture(id: string): Promise<CaptureResult>;
+export declare function clientSend(id: string, text: string, from?: string): Promise<DispatchResult>;
+export declare function clientSendThroughPeer(sshAddress: string, id: string, text: string, from?: string): Promise<DispatchResult>;
+export declare function clientListSessionsThroughPeer(sshAddress: string, projectAnchor: string): Promise<Session[]>;
+export type PeerSessionCreateInput = {
+    prompt: string;
+    launcher?: string;
+    name?: string;
+    base?: string;
+};
+export declare function clientCreateThroughPeer(sshAddress: string, projectAnchor: string, input: PeerSessionCreateInput): Promise<Session>;
+export declare function clientReview(id: string): Promise<CockpitReview | null>;
+export type ExportResult = {
+    ok: true;
+    body: string;
+} | {
+    ok: false;
+    status: number;
+};
+export declare function clientEvalExport(id: string): Promise<ExportResult>;
+type SessionEvalPage = {
+    items: any[];
+    page: number;
+    pageCount: number;
+    total: number;
+    gates: any[];
+    unknown: number;
+    revision: string;
+    summary?: any;
+    evalRevision?: any;
+};
+export type EvalsResult = {
+    ok: true;
+    model: SessionEvalPage & {
+        id: string;
+    };
+} | {
+    ok: false;
+    status: number;
+};
+export declare function clientEvals(id: string): Promise<EvalsResult>;
+export declare function clientMerge(id: string): Promise<{
+    dispatched: boolean;
+    reason?: string;
+    code?: string;
+}>;
+export declare function clientResume(id: string, force?: boolean): Promise<{
+    ok: boolean;
+    error?: string;
+    refused?: boolean;
+    info?: string;
+}>;
+export declare function clientStop(id: string): Promise<boolean>;
+export declare function clientInterrupt(id: string): Promise<DispatchResult>;
+export declare function clientClose(id: string): Promise<boolean>;
+export declare function clientCloseThroughPeer(sshAddress: string, id: string): Promise<boolean>;
+export declare function clientQuarantine(id: string, witness: {
+    adapter: string;
+    thread: string | null;
+    tmux: string;
+    worktree: string;
+    branch: string;
+}): Promise<{
+    id: string;
+    bundle: string;
+    sha256: string;
+    observedAt: string;
+}>;
+export declare function clientRestoreQuarantine(id: string): Promise<{
+    id: string;
+    bundle: string;
+    sha256: string;
+    observedAt: string;
+}>;
+export declare function clientArchive(id: string, on?: boolean): Promise<boolean>;
+export declare function clientRename(id: string, name: string): Promise<boolean>;
+export declare function clientReparent(children: string[], parent: string | null): Promise<import('./sessions.js').SessionReparentResult>;
+export declare function clientSendRawKeys(id: string, keys: string[]): Promise<boolean>;
+export type ShowResult = {
+    ok: true;
+    session: Session & {
+        prompt: string | null;
+    };
+} | {
+    ok: false;
+    status: number;
+};
+export declare function clientShow(id: string): Promise<ShowResult>;
+export declare function clientShowThroughPeer(sshAddress: string, id: string): Promise<ShowResult>;
+export {};

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

@@ -0,0 +1,476 @@
+import { existsSync } from 'node:fs';
+import { platform } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { repoRoot } from '@spexcode/spec-core';
+import { resourceBudgets } from './host-resources.js';
+import { envSessionId, listSessionIds, readPublicRecordEntry } from '@spexcode/spec-core';
+import { cockpitReview } from './cockpit.js';
+import { apiBaseInfo, assertProjectMatch, findSessionClosure, fromRaw, optionArgv, resolveSession, toSession } from './sessions.js';
+import { resolveMachinePeer } from './machine-peer.js';
+export class BackendError extends Error {
+    status;
+    transport;
+    constructor(message, status, transport) {
+        super(message);
+        this.status = status;
+        this.transport = transport;
+        this.name = 'BackendError'; // cli.ts's top-level handler matches on the NAME, so it needs no import of this class
+    }
+}
+const usageError = (message) => {
+    const error = new Error(message);
+    error.name = 'UsageError';
+    return error;
+};
+const hasFlag = (name) => optionArgv().includes(`--${name}`);
+function flagValue(name) {
+    const argv = optionArgv();
+    const index = argv.indexOf(`--${name}`);
+    if (index < 0)
+        return null;
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--'))
+        throw usageError(`--${name} expects a value`);
+    return value;
+}
+let gatewayCookie = null;
+function prepareTls(base) {
+    if (!hasFlag('insecure'))
+        return;
+    if (new URL(base).protocol !== 'https:')
+        throw usageError('--insecure requires an https --api endpoint');
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+}
+function passwordFor(target) {
+    const password = flagValue('password') ?? process.env.SPEXCODE_PASSWORD ?? null;
+    if (!password)
+        return null;
+    if (target.source !== 'flag')
+        throw usageError('--password and SPEXCODE_PASSWORD require explicit --api routing');
+    return password;
+}
+function withCookie(init, cookie) {
+    const headers = new Headers(init?.headers);
+    headers.set('cookie', cookie);
+    return { ...init, headers };
+}
+async function loginGateway(base, password) {
+    let response;
+    try {
+        response = await fetch(`${base}/login`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ password }).toString(),
+            redirect: 'manual',
+        });
+    }
+    catch (error) {
+        throw new BackendError(`gateway login could not reach ${base}: ${error.message}`, undefined, error);
+    }
+    if (response.status < 200 || response.status >= 400)
+        throw new BackendError(`gateway login rejected credentials at ${base}`, response.status);
+    const headers = response.headers;
+    const cookies = headers.getSetCookie?.() ?? [response.headers.get('set-cookie') ?? ''];
+    const cookie = cookies.map((value) => value.split(';', 1)[0]).find(Boolean);
+    if (!cookie)
+        throw new BackendError(`gateway login at ${base} did not return an authorization cookie`, response.status);
+    return cookie;
+}
+// the ONE seam where "no backend" becomes loud. A network failure (nothing listening at the resolved base)
+// is the only thing thrown; an HTTP Response of any status is returned for the caller to interpret.
+async function apiFetch(path, init) {
+    const target = await apiBaseInfo();
+    const base = target.url;
+    prepareTls(base);
+    const request = async (cookie) => {
+        try {
+            return await fetch(`${base}${path}`, cookie ? withCookie(init, cookie) : init);
+        }
+        catch (error) {
+            throw new BackendError(`no backend reachable at ${base} — run \`spex serve\` in the project, or name one with --api <url> (${error.message})`, undefined, error);
+        }
+    };
+    const existing = gatewayCookie?.base === base ? gatewayCookie.value : undefined;
+    const response = await request(existing);
+    if (response.status !== 401)
+        return response;
+    if (existing)
+        throw new BackendError(`gateway rejected the authenticated request at ${base}`, 401);
+    const password = passwordFor(target);
+    if (!password)
+        throw new BackendError(`authentication required at ${base} — pass --password <pw> or set SPEXCODE_PASSWORD`, 401);
+    const cookie = await loginGateway(base, password);
+    gatewayCookie = { base, value: cookie };
+    const retried = await request(cookie);
+    if (retried.status === 401)
+        throw new BackendError(`gateway rejected the authenticated request at ${base}`, 401);
+    return retried;
+}
+export function backendConnectionRefused(error) {
+    if (!(error instanceof BackendError))
+        return false;
+    let current = error.transport;
+    let sawRefusal = false;
+    const seen = new Set();
+    while (current && typeof current === 'object' && !seen.has(current)) {
+        seen.add(current);
+        const code = current.code;
+        if (code && code !== 'ECONNREFUSED')
+            return false;
+        if (code === 'ECONNREFUSED')
+            sawRefusal = true;
+        current = current.cause;
+    }
+    return sawRefusal;
+}
+// every MUTATING verb is project-bound ([[remote-client]]'s write guard): resolve the backend, compare its
+// served root to the cwd project, refuse loudly on a same-host mismatch — an explicit --api/--port skips it.
+// Reads stay unguarded (viewer-points-anywhere). Guarding HERE (not per cli.ts branch) covers every caller.
+const guarded = (verb) => assertProjectMatch(`spex ${verb}`);
+const post = (body) => ({ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+const seg = (id) => encodeURIComponent(id);
+// A rendezvous liveness probe can displace the real delivery client.
+function cachedStatus(rec) {
+    if (!rec.worktreePath || !existsSync(rec.worktreePath))
+        return 'retired';
+    if (rec.archived)
+        return 'offline';
+    if (rec.status === 'awaiting')
+        return rec.proposal === 'merge' ? 'review' : rec.proposal === 'close' ? 'close-pending' : 'done';
+    return rec.status === 'active' || rec.status === 'idle' ? 'unknown' : rec.status;
+}
+function corruptCachedSession(id, reason) {
+    const label = `${id.slice(0, 8)} (unreadable record)`;
+    return {
+        id, node: null, branch: null, path: '', label, title: label, raw: { name: null, title: null },
+        parent: null, harness: 'unknown', capabilities: { headless: false }, launcher: null,
+        lifecycle: 'active', proposal: null, merges: 0, status: 'corrupt', liveness: 'unknown',
+        note: `session record is unreadable: ${reason}`, archived: false, archiveHazard: null,
+        prompt: null, promptPreview: null, created: 0, activity: null, sortKey: null,
+    };
+}
+// Also the board a FOLLOW resolves its selectors against ([[session-follow]]): following must work with no
+// `spex serve` running, and asking a backend for the board would cost exactly the tmux/rendezvous probes the
+// follow exists to eliminate. Every field here comes from the store — nothing is probed.
+export function localCachedSessions(includeArchived = false) {
+    const rows = [];
+    for (const id of listSessionIds()) {
+        const entry = readPublicRecordEntry(id);
+        if (entry.kind === 'corrupt') {
+            rows.push(corruptCachedSession(id, entry.error));
+            continue;
+        }
+        if (entry.kind !== 'ok')
+            continue;
+        const rec = fromRaw(entry.raw);
+        if (!rec.governed)
+            continue;
+        rows.push(toSession(rec, cachedStatus(rec), 'unknown'));
+    }
+    return rows.filter((session) => includeArchived || !session.archived)
+        .sort((a, b) => (a.sortKey ?? a.created) - (b.sortKey ?? b.created) || a.id.localeCompare(b.id));
+}
+function localCachedResources() {
+    const projectRoot = repoRoot();
+    const budgets = resourceBudgets(projectRoot);
+    const owners = localCachedSessions(true).map((session) => ({
+        kind: 'session',
+        id: session.id,
+        label: session.label,
+        status: session.lifecycle,
+        liveness: 'unknown',
+        proposal: session.proposal,
+        note: session.note,
+        worktreePath: session.path,
+        branch: session.branch,
+        archived: session.archived,
+        processes: [],
+        rssMiB: 0,
+        pssMiB: null,
+        cpuPercent: 0,
+        budget: { rssMiB: budgets.sessionRssMiB, idleCpuPercent: budgets.idleCpuPercent },
+        findings: ['local-store-only: runtime liveness and process measurements are unavailable'],
+        reclaim: { eligible: false, reason: 'local store read cannot prove runtime ownership or liveness' },
+    }));
+    return {
+        version: 1,
+        measuredAt: new Date().toISOString(),
+        projectRoot,
+        platform: platform(),
+        available: false,
+        unavailableReason: 'backend unavailable; local session store has no runtime resource measurements',
+        host: { memoryTotalMiB: null, memoryUsedMiB: null, memoryAvailableMiB: null, swapTotalMiB: null, swapUsedMiB: null, cpuPercent: null },
+        budgets,
+        owners,
+        totals: { rssMiB: 0, pssMiB: null, cpuPercent: 0 },
+        findings: owners.reduce((total, owner) => total + owner.findings.length, 0),
+    };
+}
+async function cachedRead(remote, local) {
+    try {
+        return await remote();
+    }
+    catch (error) {
+        if (!(error instanceof BackendError) || error.status !== undefined || (await apiBaseInfo()).source === 'flag')
+            throw error;
+        console.error('spex session: backend unreachable; source: local session store (liveness unknown)');
+        return await local();
+    }
+}
+// GET /api/sessions — the board, used by `spex session ls`, and by `spex session watch`/`wait` as their poll source.
+export async function clientListSessions(includeArchived = false) {
+    return cachedRead(async () => {
+        const r = await apiFetch(includeArchived ? '/api/sessions?all=1' : '/api/sessions');
+        if (!r.ok)
+            throw new BackendError(`backend error ${r.status} listing sessions`, r.status);
+        return await r.json();
+    }, () => localCachedSessions(includeArchived));
+}
+// A terminal close removes the record from the board. The audit lookup is deliberately id-addressed and is
+// consulted only after an explicit selector missed that board, so ordinary lists stay a current-state read.
+export async function clientSessionClosure(selector) {
+    return cachedRead(async () => {
+        const r = await apiFetch(`/api/sessions/${seg(selector)}/closure`);
+        if (r.headers.get('x-spexcode-close-history') !== 'v1')
+            throw new BackendError(`backend does not support terminal close history; refusing to label ${selector} as never existed (update the backend)`, 501);
+        if (r.status === 404)
+            return null;
+        if (!r.ok)
+            throw new BackendError(`backend error ${r.status} retrieving close history for ${selector}`, r.status);
+        return await r.json();
+    }, () => findSessionClosure(selector));
+}
+export async function clientResources() {
+    return cachedRead(async () => {
+        const r = await apiFetch('/api/resources');
+        if (!r.ok)
+            throw new BackendError(`backend error ${r.status} loading resources: ${await r.text()}`, r.status);
+        return await r.json();
+    }, localCachedResources);
+}
+// resolve a selector (full id, id-prefix, node, or branch) against the live board, then call with the full id.
+export async function resolveClientSession(selector, includeArchived = true) {
+    return resolveSession(selector, await clientListSessions(includeArchived));
+}
+export async function clientCapture(id) {
+    const r = await apiFetch(`/api/sessions/${seg(id)}/capture`);
+    if (r.ok)
+        return { ok: true, pane: await r.text() };
+    return { ok: false, status: r.status, reason: (await r.text().catch(() => '')) || `status ${r.status}` };
+}
+// POST /api/sessions/:id/input {kind:"text"} appends the prompt to the durable timeline, then best-effort
+// pokes the resolved adapter. HTTP failure means the append itself was refused.
+export async function clientSend(id, text, from) {
+    await guarded('session send');
+    // `from` = the sending agent's own session id; the recipient's log records the sender ([[session-timeline]]) only when
+    // it's present (an agent send), so a human-shell send stays unrecorded.
+    const r = await apiFetch(`/api/sessions/${seg(id)}/input`, post({ kind: 'text', text, ...(from ? { from } : {}) }));
+    return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }));
+}
+// A machine peer's outbound loopback port is an SSH forward into the remote gateway's dedicated ingress.
+// It exposes only the small session-id allowlist the gateway can safely route to a derived local project.
+async function peerFetch(sshAddress, path, init) {
+    const peer = resolveMachinePeer(sshAddress);
+    try {
+        return await fetch(`http://127.0.0.1:${peer.outboundPort}${path}`, init);
+    }
+    catch (error) {
+        throw new BackendError(`communication tunnel for SSH address ${JSON.stringify(sshAddress)} is unreachable — run \`spex peer connect ${sshAddress}\` to repair it (${error.message})`, undefined, error);
+    }
+}
+export async function clientSendThroughPeer(sshAddress, id, text, from) {
+    const response = await peerFetch(sshAddress, `/api/sessions/${seg(id)}/input`, post({ kind: 'text', text, ...(from ? { from } : {}) }));
+    const body = await response.json().catch(() => ({ ok: false, error: `bad peer response (${response.status})` }));
+    const peerBody = body;
+    if (!response.ok && peerBody.ok !== false) {
+        return { ok: false, error: typeof peerBody.error === 'string' ? peerBody.error : `peer request failed (${response.status})` };
+    }
+    return body;
+}
+// The full id is the peer gateway's project anchor. Peer lists deliberately use the default board projection:
+// archives would need a new allowlisted operation, not an unreviewed query-string tunnel.
+export async function clientListSessionsThroughPeer(sshAddress, projectAnchor) {
+    const response = await peerFetch(sshAddress, `/api/sessions/${seg(projectAnchor)}/project/sessions`);
+    if (!response.ok)
+        throw new BackendError(`remote backend refused to list sessions for ${projectAnchor}: ${await response.text()}`, response.status);
+    return await response.json();
+}
+// Peer creation is deliberately separate from sessions.ts createSession: that function's proven-local-refusal
+// fallback would launch on THIS machine. The closed body lets the peer gateway recreate the normal backend
+// idempotency header without becoming a general header proxy.
+export async function clientCreateThroughPeer(sshAddress, projectAnchor, input) {
+    const response = await peerFetch(sshAddress, `/api/sessions/${seg(projectAnchor)}/project/sessions`, post({
+        ...input,
+        requestKey: randomUUID(),
+    }));
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        let message = text;
+        try {
+            message = JSON.parse(text).error || text;
+        }
+        catch { }
+        throw new BackendError(`remote backend rejected session (${response.status}): ${message}`, response.status);
+    }
+    return await response.json();
+}
+// GET /api/sessions/:id/review — the manager cockpit review bundle (null on 404).
+export async function clientReview(id) {
+    return cachedRead(async () => {
+        const r = await apiFetch(`/api/sessions/${seg(id)}/review`);
+        if (r.status === 404)
+            return null;
+        if (!r.ok)
+            throw new BackendError(`backend error ${r.status} reviewing ${id}`, r.status);
+        return await r.json();
+    }, () => cockpitReview(id));
+}
+export async function clientEvalExport(id) {
+    const r = await apiFetch(`/api/sessions/${seg(id)}/evals?format=html`);
+    if (r.ok)
+        return { ok: true, body: await r.text() };
+    return { ok: false, status: r.status };
+}
+export async function clientEvals(id) {
+    const q = encodeURIComponent(`is:eval scope:${id}`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const items = [];
+        let first = null;
+        let changed = false;
+        for (let page = 1;; page++) {
+            const r = await apiFetch(`/api/evals?q=${q}&page=${page}`);
+            if (!r.ok)
+                return { ok: false, status: r.status };
+            const current = await r.json();
+            first ??= current;
+            if (current.revision !== first.revision) {
+                changed = true;
+                break;
+            }
+            items.push(...current.items);
+            if (page >= current.pageCount)
+                break;
+        }
+        if (!changed)
+            return { ok: true, model: { ...first, id, items } };
+    }
+    throw new BackendError(`session eval pages changed while fetching ${id}; retry the command`);
+}
+// POST /api/sessions/:id/merge — a human merge intent dispatched to the session's own agent.
+export async function clientMerge(id) {
+    await guarded('merge');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/merge`, { method: 'POST' });
+    return await r.json().catch(() => ({ dispatched: false, reason: `bad backend response (${r.status})` }));
+}
+// POST /api/sessions/:id/resume — bring the agent back (relaunch ONLY if confirmed offline); demotes
+// working→idle, keeps any declaration. The RESUME GUARD REFUSES (409 {refused:true}) on a live/unproven agent;
+// `force` overrides for a wedged-but-alive process. {ok:false} otherwise = no such session (404). `info`
+// carries a non-error advisory.
+export async function clientResume(id, force = false) {
+    await guarded('session resume');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({ force }));
+    return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }));
+}
+// POST /api/sessions/:id/stop — the soft stop: kill tmux + socket, KEEP the worktree (session goes offline,
+// resumable). Distinct from close. {ok:false} = no such session.
+export async function clientStop(id) {
+    await guarded('session stop');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/stop`, post({}));
+    if (!r.ok)
+        throw new BackendError(`backend refused to stop ${id}: ${await r.text()}`, r.status);
+    return !!(await r.json().catch(() => ({ ok: false })))?.ok;
+}
+// POST /api/sessions/:id/interrupt - native hard interrupt of the current turn. Unsupported harnesses and
+// unreachable control planes return the backend's loud DispatchResult; no signal/raw-key fallback exists.
+export async function clientInterrupt(id) {
+    await guarded('session interrupt');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/interrupt`, post({}));
+    return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }));
+}
+// POST /api/sessions/:id/close — terminal worktree removal. A client-side session id is only an unverified claim.
+export async function clientClose(id) {
+    await guarded('session close');
+    const source = envSessionId();
+    const r = await apiFetch(`/api/sessions/${seg(id)}/close`, post({ source: source ? { kind: 'unverified-session-claim', id: source } : { kind: 'user' } }));
+    if (!r.ok)
+        throw new BackendError(`backend refused to close ${id}: ${await r.text()}`, r.status);
+    return !!(await r.json().catch(() => ({ ok: false })))?.ok;
+}
+// POST /api/sessions/:id/close through a known peer. The local project guard is inapplicable: the peer is
+// already the caller's explicit remote transport, and the remote gateway derives the owning project by id.
+export async function clientCloseThroughPeer(sshAddress, id) {
+    const r = await peerFetch(sshAddress, `/api/sessions/${seg(id)}/close`, post({ source: { kind: 'user' } }));
+    if (!r.ok)
+        throw new BackendError(`remote backend refused to close ${id}: ${await r.text()}`, r.status);
+    return !!(await r.json().catch(() => ({ ok: false })))?.ok;
+}
+export async function clientQuarantine(id, witness) {
+    await guarded('session quarantine');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/quarantine`, post(witness));
+    if (!r.ok)
+        throw new BackendError(`backend refused to quarantine ${id}: ${await r.text()}`, r.status);
+    const body = await r.json();
+    if (!body.ok || !body.id || !body.bundle || !body.sha256 || !body.observedAt)
+        throw new BackendError(`backend returned an invalid quarantine result for ${id}`, r.status);
+    return { id: body.id, bundle: body.bundle, sha256: body.sha256, observedAt: body.observedAt };
+}
+export async function clientRestoreQuarantine(id) {
+    await guarded('session quarantine');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/quarantine/restore`, post({}));
+    if (!r.ok)
+        throw new BackendError(`backend refused to restore ${id}: ${await r.text()}`, r.status);
+    const body = await r.json();
+    if (!body.ok || !body.id || !body.bundle || !body.sha256 || !body.observedAt)
+        throw new BackendError(`backend returned an invalid quarantine restore for ${id}`, r.status);
+    return { id: body.id, bundle: body.bundle, sha256: body.sha256, observedAt: body.observedAt };
+}
+// POST /api/sessions/:id/archive — cold-archive the session ([[archive]]). The legacy on=false spelling is a
+// signpost to the same resume transition; it never performs a record-only unarchive.
+export async function clientArchive(id, on = true) {
+    await guarded(on ? 'session archive' : 'session unarchive');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/archive`, post({ on }));
+    if (!r.ok)
+        throw new BackendError(`backend refused to ${on ? 'archive' : 'unarchive'} ${id}: ${await r.text()}`, r.status);
+    return !!(await r.json().catch(() => ({ ok: false })))?.ok;
+}
+// POST /api/sessions/:id/rename — set (or clear, with a blank) the session's display-name override
+// ([[session-rename]] as a CLI verb). {ok:false} = no such session (404).
+export async function clientRename(id, name) {
+    await guarded('session rename');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/rename`, post({ name }));
+    return !!(await r.json().catch(() => ({ ok: false })))?.ok;
+}
+export async function clientReparent(children, parent) {
+    await guarded('session reparent');
+    const r = await apiFetch('/api/sessions/reparent', post({ children, parent }));
+    if (!r.ok)
+        throw new BackendError(`backend refused to reparent sessions: ${await r.text()}`, r.status);
+    return await r.json();
+}
+// POST /api/sessions/:id/input {kind:"keys"} — the LAST-RESORT raw nav-key face of send (tmux send-keys,
+// NEVER the prompt socket): an ordered token batch drives an interactive TUI menu
+// ([[nav-mode-key-ordering]]). {ok:false} = unknown session, no live pane, or no valid token delivered.
+export async function clientSendRawKeys(id, keys) {
+    await guarded('session send');
+    const r = await apiFetch(`/api/sessions/${seg(id)}/input`, post({ kind: 'keys', keys }));
+    return !!(await r.json().catch(() => ({ ok: false })))?.ok;
+}
+export async function clientShow(id) {
+    return cachedRead(async () => {
+        const r = await apiFetch(`/api/sessions/${seg(id)}`);
+        if (r.ok)
+            return { ok: true, session: await r.json() };
+        return { ok: false, status: r.status };
+    }, () => {
+        const session = localCachedSessions(true).find((item) => item.id === id);
+        return session ? { ok: true, session } : { ok: false, status: 404 };
+    });
+}
+export async function clientShowThroughPeer(sshAddress, id) {
+    const r = await peerFetch(sshAddress, `/api/sessions/${seg(id)}`);
+    if (r.ok)
+        return { ok: true, session: await r.json() };
+    if (r.status === 404)
+        return { ok: false, status: 404 };
+    throw new BackendError(`remote backend refused to show ${id}: ${await r.text()}`, r.status);
+}

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

@@ -0,0 +1,7 @@
+import { type ReviewEvalGate, type ReviewPayload } from './sessions.js';
+export type CockpitReview = Omit<ReviewPayload, 'gates'> & {
+    gates: ReviewPayload['gates'] & {
+        evals: ReviewEvalGate;
+    };
+};
+export declare function cockpitReview(id: string): Promise<CockpitReview | null>;

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

@@ -0,0 +1,26 @@
+import { reviewPayload } from './sessions.js';
+import { sessionEvalProjection } from '@spexcode/spec-eval/sessioneval';
+// @@@ evalGate - the measured-loss readout, taken from [[session-eval]]'s EXISTING projection. This is a cache
+// READ and must stay one: `buildSessionEvals()` calls `reviewPayload()` itself, so BUILDING the model from here
+// would recurse. That hazard used to be held off by a comment; now it is structural — `reviewPayload` no longer
+// carries this field, so the eval side cannot re-enter through it. (It never read the field anyway: `gateRows`
+// consumes lint/conflict/ahead/dirty only. The payload was carrying a value for a caller that ignored it.)
+async function evalGate(id) {
+    const projection = sessionEvalProjection(id);
+    if (!projection)
+        return { phase: 'unavailable' };
+    // only a `ready` projection carries a CURRENT value; last-known is deliberately not reported as current.
+    if (projection.phase !== 'ready' || !projection.value) {
+        return { phase: projection.phase === 'ready' ? 'unavailable' : projection.phase };
+    }
+    const summary = projection.value;
+    return { phase: 'ready', freshPass: summary.pass, freshFail: summary.fail, needReview: summary.review, blind: summary.blind };
+}
+// the cockpit's whole answer for one session: the session-side review plus the eval readout, composed once.
+// The two run in parallel — the eval half is a projection read, independent of every git read in the payload.
+export async function cockpitReview(id) {
+    const [payload, evals] = await Promise.all([reviewPayload(id), evalGate(id)]);
+    if (!payload)
+        return null;
+    return { ...payload, gates: { ...payload.gates, evals } };
+}

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

@@ -0,0 +1 @@
+export declare function codexHeadlessLaunchCommand(id: string, codexCmd?: string, serverCmd?: string, dir?: string): string;

package/{spec-cli/src/codex-headless.ts → node_modules/@spexcode/spec-cli/dist/codex-headless.js}

@@ -1,13 +1,7 @@
-import { codexLaunchCommand } from './harness.js'
-
+import { codexLaunchCommand } from './harness.js';
 // Codex headless keeps the existing app-server bootstrap and backend-owned thread/start + first turn, but
 // deliberately omits the final interactive `--remote … resume` attach. The shared app-server remains the
 // durable home for the thread; follow-up delivery uses codexHarness' existing JSON-RPC transport.
-export function codexHeadlessLaunchCommand(
-  id: string,
-  codexCmd = 'codex',
-  serverCmd?: string,
-  dir?: string,
-): string {
-  return codexLaunchCommand(id, codexCmd, serverCmd, dir, false)
+export function codexHeadlessLaunchCommand(id, codexCmd = 'codex', serverCmd, dir) {
+    return codexLaunchCommand(id, codexCmd, serverCmd, dir, false);
 }