spexcode 0.6.2 → 0.6.5

package/README.md

@@ -94,11 +94,13 @@ workflow on its own.
 When you want the live board (the graph, sessions, evals), start the runtime:
 
 ```sh
+npm i -g @spexcode/spec-dashboard # install the optional UI package once
 spex serve       # this project's backend — prints its URL
 spex dashboard   # the machine's one gateway — every project behind one URL
 ```
 
-One `spex dashboard` per machine is enough: every project you serve shows up behind it, and its
+The dashboard is a separate package so writing-only installs do not carry frontend build output. One `spex dashboard`
+per machine is enough: every project you serve shows up behind it, and its
 `/projects` page manages them from the browser.
 [Getting started](https://spexcode.net/getting-started/) walks the rest of the setup.
 

package/bin/spex.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// @@@ root release launcher ([[release-launcher]]) - the metapackage owns one command and delegates all
+// product behavior to the independently compiled CLI package.
+import '@spexcode/spec-cli/bin/spex.mjs'

package/node_modules/@spexcode/spec-cli/bin/spex.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// @@@ spex launcher ([[release-launcher]]) - package installs execute the package's compiled CLI directly;
+// tsx remains a development tool and never enters an adopter's runtime closure.
+import { spawn, spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+// Resolve from THIS package rather than cwd, so global and project-local installs run one compiled CLI.
+const pkg = join(dirname(fileURLToPath(import.meta.url)), '..') // spec-cli/
+const cli = join(pkg, 'dist', 'cli.js')
+const workspace = join(pkg, '..')
+
+// @@@ mid-merge guard ([[merge-tooling-resilience]]) - a released package contains no source to scan;
+// a source workspace does. Refuse to run its possibly stale dist while its imported source trees still
+// carry unresolved conflict markers, so hooks keep the retryable exit-75 contract during a merge.
+const sourceRoot = join(pkg, 'src')
+if (existsSync(sourceRoot)) {
+  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
+  const conflicted = srcRoots.flatMap((root) => {
+    if (!existsSync(root)) return []
+    return readdirSync(root, { recursive: true })
+      .filter((f) => /\.(ts|tsx|js|mjs)$/.test(String(f)))
+      .map((f) => join(root, String(f)))
+      .filter((path) => {
+        try { return /^<{7} /m.test(readFileSync(path, 'utf8')) } catch { return false }
+      })
+  })
+  if (conflicted.length) {
+    console.error('spex: paused mid-merge - unresolved conflict markers in the source SpexCode runs:')
+    for (const file of conflicted) console.error(`  ${file}`)
+    console.error('resolve the merge, rebuild SpexCode, then retry. (exit 75)')
+    process.exit(75)
+  }
+
+  // @@@ source-workspace build ([[release-launcher]]) - the git hooks invoke this launcher straight from a
+  // checkout, where dist is intentionally untracked. Rebuild the complete runtime closure before linting
+  // candidate source; an installed package has no src tree and stays a pure Node -> dist execution path.
+  const runtimeEntries = [
+    cli,
+    join(workspace, 'packages', 'spec-core', 'dist', 'index.js'),
+    join(workspace, 'spec-eval', 'dist', 'index.js'),
+    join(workspace, 'spec-forge', 'dist', 'index.js'),
+  ]
+  const newestSource = srcRoots.reduce((newest, root) => {
+    if (!existsSync(root)) return newest
+    for (const entry of readdirSync(root, { recursive: true })) {
+      const path = join(root, String(entry))
+      try {
+        if (/\.(ts|tsx|js|mjs)$/.test(path)) newest = Math.max(newest, statSync(path).mtimeMs)
+      } catch { /* a concurrent source edit can only make the next invocation rebuild again */ }
+    }
+    return newest
+  }, 0)
+  const rebuild = runtimeEntries.some((entry) => {
+    try { return statSync(entry).mtimeMs < newestSource } catch { return true }
+  })
+  if (rebuild) {
+    const build = spawnSync('npm', ['run', 'build'], { cwd: workspace, stdio: 'inherit' })
+    if (build.error || build.status !== 0 || !existsSync(cli)) {
+      console.error('spex: source workspace build failed; fix it, then retry.')
+      process.exit(build.status ?? 1)
+    }
+  }
+}
+const args = process.argv.slice(2)
+const env = { ...process.env }
+// A backend/dashboard is a project or host control plane, never the managed session that happened to start it.
+if (args[0] === 'serve' || args[0] === 'dashboard') {
+  const identityKeys = (env.SPEXCODE_SESSION_IDENTITY_VARS
+    || 'SPEXCODE_SESSION_ID,CLAUDE_CODE_SESSION_ID,CODEX_THREAD_ID,OPENCODE_SESSION_ID,PI_SESSION_ID')
+    .split(',').map((key) => key.trim()).filter(Boolean)
+  for (const key of identityKeys) delete env[key]
+}
+spawn(process.execPath, [cli, ...args], { stdio: 'inherit', env })
+  .on('exit', (code) => process.exit(code ?? 0))

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

@@ -0,0 +1,2 @@
+export declare function assertLocalBackend(): Promise<void>;
+export declare function attachSession(id: string): Promise<number>;

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

@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process';
+import { networkInterfaces } from 'node:os';
+import { alive, apiBase, TMUX_SOCK } from './sessions.js';
+const AGENT_ALTERNATIVES = 'read the pane with `spex session show <SEL> --capture`, drive it with `session send` (plain text first; `--keys` only as a last resort)';
+// attach only makes sense on the machine that runs the tmux server — the backend's. The board the selector
+// resolved against IS that backend, so the test is: does the RESOLVED backend (see [[remote-client]]'s
+// ladder — flag / worker env / cwd record / fallback) point at this machine? Loopback and any address this
+// host owns count as local; anything else (a tailnet/LAN IP of another box, a hostname we can't claim)
+// fails loud with the reason and the remote-capable alternatives, never a silent local fallback onto a
+// tmux socket that holds no sessions.
+export async function assertLocalBackend() {
+    const base = await apiBase();
+    let host;
+    try {
+        host = new URL(base).hostname;
+    }
+    catch {
+        host = '';
+    }
+    const mine = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+    for (const addrs of Object.values(networkInterfaces()))
+        for (const a of addrs ?? [])
+            mine.add(a.address);
+    if (mine.has(host))
+        return;
+    console.error(`spex session attach: attach is LOCAL-only, and the resolved backend is another machine (${base}).
+The tmux session lives on THAT machine — a terminal can't be attached over HTTP. Either run attach there
+(e.g. over ssh), or ${AGENT_ALTERNATIVES} — those work remotely.`);
+    process.exit(2);
+}
+// foreground takeover of the session's real tmux window; returns only via detach (C-b d) or the session
+// ending. Interactive and blocking by design — a caller without a terminal (an agent inside its turn, a
+// pipe) is refused up front and pointed at the remote-capable verbs instead of tmux's bare "not a terminal".
+export async function attachSession(id) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(`spex session attach: attach is INTERACTIVE and needs a terminal — it blocks until you detach.
+An agent must not run it inside a turn (it freezes you); ${AGENT_ALTERNATIVES}.`);
+        process.exit(2);
+    }
+    if (!(await alive(id))) {
+        console.error(`spex session attach: ${id} is offline — no live tmux session to attach.
+Bring it back with \`spex session resume ${id}\`, or read its record with \`spex session show ${id}\`.`);
+        return 1;
+    }
+    console.log(`attaching to ${id} — detach with C-b d (the session keeps running)`);
+    const r = spawnSync('tmux', ['-u', '-L', TMUX_SOCK, 'attach-session', '-t', id], { stdio: 'inherit' });
+    return r.status ?? 1;
+}

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

@@ -0,0 +1,33 @@
+import type { DispatchResult, HarnessDeliveryRecord } from './harness.js';
+type ClaudeHeadlessDeliveryRecord = HarnessDeliveryRecord & {
+    status?: string;
+};
+export declare const claudeHeadlessSock: (id: string) => string;
+export declare function claudeHeadlessLaunchCommand(id: string, runtimeDir: string, claudeCmd: string): string;
+export declare const deliverViaClaudeHeadless: (rec: ClaudeHeadlessDeliveryRecord, text: string) => Promise<DispatchResult>;
+export declare const interruptClaudeHeadless: (rec: HarnessDeliveryRecord) => Promise<DispatchResult>;
+export declare class ClaudeHeadlessController {
+    private readonly id;
+    private readonly claudeCmd;
+    private readonly cwd;
+    private server;
+    private child;
+    private controlQueue;
+    private closing;
+    private readonly socketPath;
+    constructor(id: string, _runtimeDir: string, claudeCmd: string, cwd?: string);
+    start(initialPrompt?: string): Promise<void>;
+    close(): Promise<void>;
+    private accept;
+    private handle;
+    private interrupt;
+    private spawnTurn;
+    private observeEvent;
+    private ensureTurnExit;
+    private terminateTurn;
+    private waitForTurnExit;
+    private signalTurn;
+    private writeLine;
+}
+export declare function runClaudeHeadlessController(id: string, runtimeDir: string, claudeCmd: string, tail: string[]): Promise<void>;
+export {};

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

@@ -0,0 +1,307 @@
+import { rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { controlRequest, withTimeout } from './headless-controller.js';
+import { shQuote } from './sh.js';
+const PKG = fileURLToPath(new URL('..', import.meta.url));
+const SPEX = join(PKG, 'bin', 'spex.mjs');
+const CONTROL_TIMEOUT_MS = 60_000;
+const START_TIMEOUT_MS = 30_000;
+const INTERRUPT_TIMEOUT_MS = 10_000;
+const RESULT_WAIT_MS = 20_000;
+const RESULT_EXIT_GRACE_MS = 500;
+const TERM_EXIT_GRACE_MS = 500;
+const KILL_EXIT_GRACE_MS = 2_000;
+const userEvent = (text) => JSON.stringify({
+    type: 'user',
+    message: { role: 'user', content: [{ type: 'text', text }] },
+});
+export const claudeHeadlessSock = (id) => join(tmpdir(), `spexcode-ch-${id}.sock`);
+export function claudeHeadlessLaunchCommand(id, runtimeDir, claudeCmd) {
+    return [shQuote(SPEX), 'internal', 'claude-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(claudeCmd), '--'].join(' ');
+}
+export const deliverViaClaudeHeadless = (rec, text) => controlRequest(claudeHeadlessSock(rec.session), { type: 'deliver', text, mode: rec.status === 'active' ? 'steer' : 'wake' }, {
+    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'claude-headless control rejected the request',
+});
+export const interruptClaudeHeadless = (rec) => controlRequest(claudeHeadlessSock(rec.session), { type: 'interrupt' }, {
+    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'claude-headless control rejected the request',
+});
+export class ClaudeHeadlessController {
+    id;
+    claudeCmd;
+    cwd;
+    server = null;
+    child = null;
+    controlQueue = Promise.resolve();
+    closing = false;
+    socketPath;
+    constructor(id, _runtimeDir, claudeCmd, cwd = process.cwd()) {
+        this.id = id;
+        this.claudeCmd = claudeCmd;
+        this.cwd = cwd;
+        this.socketPath = claudeHeadlessSock(id);
+    }
+    async start(initialPrompt) {
+        try {
+            rmSync(this.socketPath, { force: true });
+        }
+        catch { /* stale control socket is replaced at startup */ }
+        this.server = createServer((socket) => this.accept(socket));
+        await new Promise((resolve, reject) => {
+            const onError = (error) => { this.server?.off('listening', onListening); reject(error); };
+            const onListening = () => { this.server?.off('error', onError); resolve(); };
+            this.server.once('error', onError);
+            this.server.once('listening', onListening);
+            this.server.listen(this.socketPath);
+        });
+        if (initialPrompt)
+            void this.spawnTurn(initialPrompt, false).catch((error) => {
+                console.error(`[spex claude-headless] initial turn failed: ${error.message}`);
+            });
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        const child = this.child;
+        try {
+            if (child)
+                await this.ensureTurnExit(child);
+        }
+        finally {
+            await new Promise((resolve) => {
+                if (!this.server)
+                    return resolve();
+                this.server.close(() => resolve());
+            });
+            try {
+                rmSync(this.socketPath, { force: true });
+            }
+            catch { /* best-effort cleanup after close */ }
+        }
+    }
+    accept(socket) {
+        socket.setEncoding('utf8');
+        let buffer = '';
+        let handled = false;
+        socket.on('data', (chunk) => {
+            if (handled)
+                return;
+            buffer += chunk;
+            const nl = buffer.indexOf('\n');
+            if (nl < 0)
+                return;
+            handled = true;
+            let request;
+            try {
+                request = JSON.parse(buffer.slice(0, nl));
+            }
+            catch (error) {
+                socket.end(`${JSON.stringify({ ok: false, error: `invalid control request: ${error.message}` })}\n`);
+                return;
+            }
+            this.controlQueue = this.controlQueue.then(async () => {
+                const result = await this.handle(request).catch((error) => ({ ok: false, error: error.message }));
+                socket.end(`${JSON.stringify(result)}\n`);
+            });
+        });
+    }
+    async handle(request) {
+        if (request.type === 'deliver') {
+            if (!request.text)
+                return { ok: false, error: 'empty prompt - nothing to deliver' };
+            const current = this.child;
+            if (request.mode === 'steer' && current?.active && current.process.stdin.writable) {
+                await this.writeLine(current, userEvent(request.text));
+                return { ok: true };
+            }
+            if (current?.active) {
+                await Promise.race([
+                    withTimeout(current.result, RESULT_WAIT_MS, 'previous claude-headless turn did not reach its result before idle wake'),
+                    current.exited.then((code) => { throw new Error(`previous claude-headless turn exited before its result (code ${code ?? 'signal'})`); }),
+                ]);
+            }
+            if (current)
+                await this.ensureTurnExit(current);
+            await this.spawnTurn(request.text, true);
+            return { ok: true };
+        }
+        if (request.type === 'interrupt')
+            return this.interrupt();
+        return { ok: false, error: 'unknown claude-headless control request' };
+    }
+    async interrupt() {
+        const child = this.child;
+        if (!child?.active || !child.process.stdin.writable)
+            return { ok: true };
+        const requestId = randomUUID();
+        const ack = new Promise((resolve) => child.interruptAcks.set(requestId, resolve));
+        await this.writeLine(child, JSON.stringify({
+            type: 'control_request',
+            request_id: requestId,
+            request: { subtype: 'interrupt' },
+        }));
+        try {
+            await withTimeout(ack, INTERRUPT_TIMEOUT_MS, `claude-headless interrupt was not confirmed for session ${this.id}`);
+            return { ok: true };
+        }
+        finally {
+            child.interruptAcks.delete(requestId);
+        }
+    }
+    async spawnTurn(text, resume) {
+        if (this.closing)
+            throw new Error('claude-headless controller is closing');
+        const mode = resume ? ['--resume', this.id] : ['--session-id', this.id];
+        const args = ['-p', ...mode, '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'];
+        const command = `exec ${this.claudeCmd} ${args.map(shQuote).join(' ')}`;
+        const childProcess = spawn('/bin/sh', ['-lc', command], {
+            cwd: this.cwd,
+            env: process.env,
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let sawFirstEvent;
+        const firstEvent = new Promise((resolve) => { sawFirstEvent = resolve; });
+        let resolveExit;
+        const exited = new Promise((resolve) => { resolveExit = resolve; });
+        let sawResult;
+        const result = new Promise((resolve) => { sawResult = resolve; });
+        const turn = {
+            process: childProcess,
+            active: true,
+            completed: false,
+            exited,
+            teardown: null,
+            result,
+            sawResult,
+            firstEvent,
+            sawFirstEvent,
+            interruptAcks: new Map(),
+        };
+        this.child = turn;
+        let stdoutBuffer = '';
+        childProcess.stdout.setEncoding('utf8');
+        childProcess.stderr.pipe(process.stderr);
+        childProcess.stdout.on('data', (chunk) => {
+            stdoutBuffer += chunk;
+            for (;;) {
+                const nl = stdoutBuffer.indexOf('\n');
+                if (nl < 0)
+                    break;
+                const line = stdoutBuffer.slice(0, nl);
+                stdoutBuffer = stdoutBuffer.slice(nl + 1);
+                const nativeLine = `${line}\n`;
+                globalThis.process.stdout.write(nativeLine);
+                turn.sawFirstEvent();
+                this.observeEvent(turn, line);
+            }
+        });
+        childProcess.once('error', (error) => {
+            console.error(`[spex claude-headless] child spawn failed: ${error.message}`);
+        });
+        childProcess.once('close', (code) => {
+            turn.active = false;
+            if (stdoutBuffer)
+                console.error('[spex claude-headless] dropped a partial non-line stdout event');
+            if (this.child === turn)
+                this.child = null;
+            resolveExit(code);
+            if (!turn.completed && code !== 0 && !this.closing) {
+                void import('./harness.js').then(({ reportHeadlessTurnExit }) => reportHeadlessTurnExit(this.id, 'claude-headless', code, this.cwd));
+            }
+        });
+        await this.writeLine(turn, userEvent(text));
+        await Promise.race([
+            withTimeout(turn.firstEvent, START_TIMEOUT_MS, `claude-headless child produced no stream event for session ${this.id}`),
+            turn.exited.then((code) => { throw new Error(`claude-headless child exited before accepting the turn (code ${code ?? 'signal'})`); }),
+        ]);
+    }
+    observeEvent(turn, line) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (event?.type === 'control_response' && typeof event?.response?.request_id === 'string') {
+            turn.interruptAcks.get(event.response.request_id)?.();
+        }
+        if (event?.type === 'result' && !turn.completed) {
+            turn.completed = true;
+            turn.active = false;
+            turn.sawResult();
+            void this.ensureTurnExit(turn).catch((error) => {
+                console.error(`[spex claude-headless] completed turn teardown failed: ${error.message}`);
+            });
+        }
+    }
+    ensureTurnExit(turn) {
+        turn.teardown ??= this.terminateTurn(turn);
+        return turn.teardown;
+    }
+    async terminateTurn(turn) {
+        if (turn.completed) {
+            if (turn.process.stdin.writable)
+                turn.process.stdin.end();
+            if (await this.waitForTurnExit(turn, RESULT_EXIT_GRACE_MS))
+                return;
+            this.signalTurn(turn, 'SIGKILL');
+            await withTimeout(turn.exited, KILL_EXIT_GRACE_MS, `claude-headless completed turn process group ${turn.process.pid ?? 'unknown'} did not exit after SIGKILL`);
+            return;
+        }
+        this.signalTurn(turn, 'SIGTERM');
+        if (await this.waitForTurnExit(turn, TERM_EXIT_GRACE_MS))
+            return;
+        this.signalTurn(turn, 'SIGKILL');
+        await withTimeout(turn.exited, KILL_EXIT_GRACE_MS, `claude-headless turn process group ${turn.process.pid ?? 'unknown'} did not exit after SIGKILL`);
+    }
+    async waitForTurnExit(turn, timeoutMs) {
+        try {
+            await withTimeout(turn.exited, timeoutMs, 'turn exit grace elapsed');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    signalTurn(turn, signal) {
+        const pid = turn.process.pid;
+        try {
+            if (pid)
+                process.kill(-pid, signal);
+            else
+                turn.process.kill(signal);
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+    }
+    writeLine(turn, line) {
+        return new Promise((resolve, reject) => {
+            if (!turn.process.stdin.writable)
+                return reject(new Error('claude-headless child stdin is not writable'));
+            turn.process.stdin.write(`${line}\n`, (error) => error ? reject(error) : resolve());
+        });
+    }
+}
+export async function runClaudeHeadlessController(id, runtimeDir, claudeCmd, tail) {
+    const controller = new ClaudeHeadlessController(id, runtimeDir, claudeCmd);
+    const resume = tail[0] === '--resume';
+    const prompt = resume ? undefined : tail[0] === '--session-id' ? tail.slice(2).join(' ') : tail.join(' ');
+    await controller.start(prompt);
+    await new Promise((resolve) => {
+        const stop = () => void controller.close().finally(resolve);
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        process.once('SIGHUP', stop);
+    });
+}

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

@@ -0,0 +1 @@
+export {};