spexcode 0.6.7 → 0.7.0-next.0

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/source-list.d.ts

@@ -0,0 +1,13 @@
+import { type SourcePolicy } from './source-files.js';
+export declare const SOURCE_LIST_MAX_ENTRIES = 500;
+export type SourceDirEntry = {
+    name: string;
+    path: string;
+    kind: 'dir' | 'file';
+};
+export type SourceListing = {
+    dir: string;
+    entries: SourceDirEntry[];
+    truncated: boolean;
+};
+export declare function listSourceDir(root: string, dir: string, policy: SourcePolicy, governedRoots: string[]): SourceListing;

package/node_modules/@spexcode/spec-cli/dist/source-list.js

@@ -0,0 +1,99 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, normalize, relative, sep } from 'node:path';
+import { isSourceFile } from './source-files.js';
+import { SourceReadError } from './source-read.js';
+// The LISTING half of the governed-source surface. `source-read` opens one file; this names what is there
+// to open, one directory at a time, so a reader can browse the project the way any editor lets them browse
+// it instead of having to already know a path.
+//
+// @@@ one gate, not a second definition - a FILE appears here exactly when `isSourceFile` would let
+// `/api/source` open it. That is the whole reason this shares the predicate rather than growing a listing
+// policy of its own: a row the reader clicks and gets a 404 from is worse than a row that was never drawn,
+// and two predicates that agree today are two predicates free to disagree tomorrow.
+// Bounded like [[node-attachments]]'s walk, and for the same reason: a directory that has accumulated ten
+// thousand generated files should degrade into a long list rather than a wedged read. Unlike that walk this
+// one is ONE level deep — the client expands a level at a time — so a depth cap would be a cap on a
+// recursion that does not exist here; the bound that matters is the entry count.
+export const SOURCE_LIST_MAX_ENTRIES = 500;
+// Directories that are never the project's own code and would drown the listing they appear in. This is a
+// listing-hygiene rule and it is deliberately NAMED rather than derived: `isSourceFile` has no opinion about
+// a directory, and with no include globs configured it would happily admit a dependency's shipped `.js`.
+// Keeping the list short and explicit is the honest form — a file inside one of these is still readable by
+// direct address if the policy admits it; it simply is not offered as something to browse.
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+const skipDir = (name) => SKIP_DIRS.has(name) || name.startsWith('.');
+// Repo-relative, worktree-contained, or a loud 400. Containment is checked by RESOLVING and comparing, not
+// by pattern-matching the string: a `..` that normalises back inside is legitimate, one that escapes is not,
+// and an absolute path is refused outright because `join` would silently reinterpret it as relative and hand
+// the caller a confusing answer about a path they did not mean.
+function resolveDir(root, dir) {
+    const raw = String(dir || '');
+    if (!raw || raw === '.')
+        return { rel: '', full: root };
+    if (raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw))
+        throw new SourceReadError(`dir must be repo-relative and inside the worktree: ${dir}`, 400);
+    const rel = normalize(raw).replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+    const full = normalize(join(root, rel));
+    const back = relative(root, full);
+    if (rel === '..' || rel.startsWith('../') || back.startsWith('..') || back.split(sep).some((s) => s === '..'))
+        throw new SourceReadError(`dir must be repo-relative and inside the worktree: ${dir}`, 400);
+    return { rel, full };
+}
+// A directory is browsable when it lies inside a governed root, or CONTAINS one — the second case is what
+// makes `governedRoots: ['spec-cli/src']` reachable at all, since every ancestor on the way down to it is
+// outside every root while still being the only path there. `.` as a root means the whole project, which
+// makes every directory inside.
+const withinGovernedRoots = (rel, roots) => roots.some((raw) => {
+    const root = String(raw || '').replace(/\/+$/, '').replace(/^\.\//, '');
+    if (!root || root === '.')
+        return true;
+    if (!rel)
+        return true;
+    return rel === root || rel.startsWith(`${root}/`) || root.startsWith(`${rel}/`);
+});
+// One level of a governed directory. The roots themselves are the listing at `dir: ''`, so the tree has a
+// top without the client having to know the config — it asks for the same thing at every level.
+export function listSourceDir(root, dir, policy, governedRoots) {
+    const { rel, full } = resolveDir(root, dir);
+    if (!withinGovernedRoots(rel, governedRoots))
+        throw new SourceReadError(`not inside this project's governed roots: ${rel}`, 404);
+    let names;
+    try {
+        names = readdirSync(full);
+    }
+    catch (e) {
+        // the CODE, never the message — Node puts the absolute host path into the exception text and these
+        // strings are API responses ([[source-read]]).
+        throw new SourceReadError(`cannot list ${rel || '.'}: ${e?.code ?? 'read failed'}`, 404);
+    }
+    const dirs = [];
+    const files = [];
+    let truncated = false;
+    for (const name of names.sort()) {
+        if (dirs.length + files.length >= SOURCE_LIST_MAX_ENTRIES) {
+            truncated = true;
+            break;
+        }
+        const path = rel ? `${rel}/${name}` : name;
+        let st;
+        // a vanishing entry mid-listing is skipped, never thrown out of the endpoint.
+        try {
+            st = statSync(join(full, name));
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            if (skipDir(name) || !withinGovernedRoots(path, governedRoots))
+                continue;
+            dirs.push({ name, path, kind: 'dir' });
+            continue;
+        }
+        if (!isSourceFile(root, path, policy))
+            continue;
+        files.push({ name, path, kind: 'file' });
+    }
+    // directories first, then files, each already alphabetical — the order every file browser uses, decided
+    // here rather than in the client so two clients cannot sort one listing two ways.
+    return { dir: rel, entries: [...dirs, ...files], truncated };
+}

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

@@ -0,0 +1,16 @@
+import { type SourcePolicy } from './source-files.js';
+export declare const SOURCE_SLICE_MAX_BYTES: number;
+export declare class SourceReadError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export type SourceSlice = {
+    path: string;
+    size: number;
+    offset: number;
+    bytes: number;
+    text: string;
+    eof: boolean;
+};
+export declare function readSlice(full: string, rel: string, offset?: number, limit?: number): SourceSlice;
+export declare function readSourceSlice(root: string, path: string, policy: SourcePolicy, offset?: number, limit?: number): SourceSlice;

package/node_modules/@spexcode/spec-cli/dist/source-read.js

@@ -0,0 +1,84 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { join, normalize } from 'node:path';
+import { isSourceFile } from './source-files.js';
+// A source read is a WINDOW over a file, never the whole file. The viewer asks for a byte range and gets
+// back that slice plus the file's total size, so the first paint of a 40 MB file costs the same as a 4 KB
+// one and the client decides how much more to pull. Whole-file delivery is not an option that exists here:
+// it is the shape that has to be walked back once a repository contains one generated bundle.
+export const SOURCE_SLICE_MAX_BYTES = 256 * 1024;
+export class SourceReadError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'SourceReadError';
+        this.status = status;
+    }
+}
+// @@@ one gate, not a second definition - a file is readable here exactly when the lint/coverage walk
+// would call it a source file. Sharing `isSourceFile` means "what the product will show you" and "what the
+// product will govern" can never drift apart into two answers.
+function resolveGoverned(root, path, policy) {
+    if (!path)
+        throw new SourceReadError('path is required', 400);
+    const rel = normalize(path).replace(/\\/g, '/').replace(/^\.\//, '');
+    if (rel.startsWith('/') || rel === '..' || rel.startsWith('../'))
+        throw new SourceReadError(`path must be repo-relative and inside the worktree: ${path}`, 400);
+    if (!isSourceFile(root, rel, policy))
+        throw new SourceReadError(`not a readable source file under this project's source policy: ${rel}`, 404);
+    return join(root, rel);
+}
+// Snap the slice to the last newline it contains. A byte window cut mid-line would also cut mid-codepoint,
+// so the viewer would render a replacement char and a half row that the next slice repeats. Reporting the
+// SNAPPED length as `bytes` keeps the client's cursor arithmetic honest: it always resumes on a line start.
+// The final slice of a file is returned whole — there is no following slice to hand the remainder to.
+function snapToLine(buf, atEof) {
+    if (atEof)
+        return buf;
+    const cut = buf.lastIndexOf(0x0a);
+    if (cut < 0)
+        return buf; // a single line longer than the window: hand it over and let the client ask again
+    return buf.subarray(0, cut + 1);
+}
+// @@@ the window is shared, the GATE is not - what may be read differs by surface (governed source answers
+// to the coverage policy; a node's own folder answers to the spec tree), but "read a byte window and snap it
+// to a line" is one behaviour and exists once. A second copy of the windowing is how the two would drift
+// into disagreeing about what `bytes` means.
+export function readSlice(full, rel, offset = 0, limit = SOURCE_SLICE_MAX_BYTES) {
+    const start = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+    const want = Math.min(Math.max(Math.floor(Number.isFinite(limit) ? limit : 0), 1), SOURCE_SLICE_MAX_BYTES);
+    let fd = null;
+    try {
+        fd = openSync(full, 'r');
+        const size = fstatSync(fd).size;
+        if (start >= size)
+            return { path: rel, size, offset: start, bytes: 0, text: '', eof: true };
+        const raw = Buffer.allocUnsafe(Math.min(want, size - start));
+        const read = readSync(fd, raw, 0, raw.length, start);
+        const slice = snapToLine(raw.subarray(0, read), start + read >= size);
+        return {
+            path: rel,
+            size,
+            offset: start,
+            bytes: slice.length,
+            text: slice.toString('utf8'),
+            eof: start + slice.length >= size,
+        };
+    }
+    catch (e) {
+        if (e instanceof SourceReadError)
+            throw e;
+        // The CODE, never the message: Node puts the absolute path it tried to open into `e.message`, and this
+        // string is an API response. A caller is owed what went wrong with the path it asked for, not where
+        // this checkout happens to live on the host.
+        throw new SourceReadError(`cannot read ${rel}: ${e?.code ?? 'read failed'}`, 404);
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+// The governed-source surface: readable exactly when the coverage walk would call it a source file.
+export function readSourceSlice(root, path, policy, offset = 0, limit = SOURCE_SLICE_MAX_BYTES) {
+    const rel = normalize(path).replace(/\\/g, '/').replace(/^\.\//, '');
+    return readSlice(resolveGoverned(root, path, policy), rel, offset, limit);
+}

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

@@ -0,0 +1,7 @@
+import { type SourceSlice } from './source-read.js';
+export type NodeAttachment = {
+    name: string;
+    size: number;
+};
+export declare function listNodeAttachments(root: string, id: string): NodeAttachment[];
+export declare function readNodeAttachment(root: string, id: string, name: string, offset?: number, limit?: number): SourceSlice;

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

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, normalize, relative, sep } from 'node:path';
+import { specDir } from '@spexcode/spec-core';
+import { readSlice, SourceReadError, SOURCE_SLICE_MAX_BYTES } from './source-read.js';
+// [[node-attachments]]: a spec node's folder is the unit, and until now the board could see exactly one
+// file in it. Everything else a node carries — its eval contract, an evidence directory, a raw capture, a
+// working note written beside the spec that cites it — existed on disk and nowhere in the product.
+//
+// This is deliberately NOT the governed-source surface. `/api/source` answers to the coverage policy, and
+// that policy excludes `.spec/**` on purpose: the spec tree is the product's own data, not code it governs.
+// Loosening that predicate to reach these files would have broken the one invariant that keeps "what the
+// product shows" and "what the product governs" the same set. So the gate is different and the window read
+// is shared — which is the right way round.
+// Bounded so a node that accumulates an evidence dump degrades into a long list rather than a wedged read.
+const MAX_ENTRIES = 500;
+const MAX_DEPTH = 4;
+// The two files with their own surfaces: the body IS the node's document, and readings ARE the eval
+// timeline. Listing them here would offer a second, worse way to read what the board already renders well.
+const OWN_SURFACE = new Set(['spec.md', 'evals.ndjson']);
+function nodeRoot(root, id) {
+    const dir = specDir(id);
+    if (!dir)
+        throw new SourceReadError(`no such spec node: ${id}`, 404);
+    return join(root, dir);
+}
+// Every read is confined to the node's own folder by RESOLVING and then checking containment, never by
+// pattern-matching the input: a `..` that normalises back inside is fine, and one that escapes is caught
+// wherever it came from.
+function resolveInside(base, name) {
+    if (!name)
+        throw new SourceReadError('name is required', 400);
+    // An absolute name would be silently reinterpreted as relative by `join`. Containment would still hold,
+    // but the caller would get a confusing 404 about a path it did not mean; refusing it says what happened.
+    if (name.startsWith('/') || /^[A-Za-z]:[\\/]/.test(name))
+        throw new SourceReadError(`attachment name must be relative to the node's folder: ${name}`, 400);
+    const full = normalize(join(base, name));
+    const rel = relative(base, full);
+    if (!rel || rel.startsWith('..') || rel.split(sep).some((s) => s === '..'))
+        throw new SourceReadError(`attachment must stay inside the node's own folder: ${name}`, 400);
+    if (OWN_SURFACE.has(rel.split(sep)[rel.split(sep).length - 1]) && !rel.includes(sep))
+        throw new SourceReadError(`${rel} has its own surface in the dashboard, not an attachment`, 400);
+    return full;
+}
+export function listNodeAttachments(root, id) {
+    const base = nodeRoot(root, id);
+    const out = [];
+    const walk = (dir, depth) => {
+        if (depth > MAX_DEPTH || out.length >= MAX_ENTRIES)
+            return;
+        let entries = [];
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries.sort()) {
+            if (out.length >= MAX_ENTRIES)
+                return;
+            const full = join(dir, entry);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                // A node's folder ends where a CHILD node's folder begins. A directory holding a spec.md is another
+                // node, and everything under it belongs to that node — listing it here would let a parent claim its
+                // children's evidence and make the same file appear under several nodes.
+                if (existsSync(join(full, 'spec.md')))
+                    continue;
+                walk(full, depth + 1);
+                continue;
+            }
+            if (OWN_SURFACE.has(entry))
+                continue;
+            out.push({ name: relative(base, full).split(sep).join('/'), size: st.size });
+        }
+    };
+    walk(base, 0);
+    return out;
+}
+export function readNodeAttachment(root, id, name, offset = 0, limit = SOURCE_SLICE_MAX_BYTES) {
+    const base = nodeRoot(root, id);
+    const full = resolveInside(base, name);
+    return readSlice(full, name, offset, limit);
+}

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

@@ -0,0 +1,23 @@
+export declare class SpecBodyEditError extends Error {
+    readonly status: 400 | 404 | 409;
+    readonly code: string;
+    readonly detail?: Record<string, unknown> | undefined;
+    constructor(message: string, status: 400 | 404 | 409, code: string, detail?: Record<string, unknown> | undefined);
+}
+export type SpecBodyEdit = {
+    startLine: number;
+    endLine: number;
+    original: string;
+    replacement: string;
+    reason?: string;
+};
+export type SpecBodyEditResult = {
+    ok: true;
+    changed: boolean;
+    path: string;
+    commit: string | null;
+    startLine: number;
+    endLine: number;
+};
+export declare function readSpecBodyEdit(raw: unknown): SpecBodyEdit;
+export declare function editSpecBody(id: string, patch: SpecBodyEdit): Promise<SpecBodyEditResult>;

package/node_modules/@spexcode/spec-cli/dist/spec-body-edit.js

@@ -0,0 +1,138 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseFrontmatter, repoRoot, specDir, gitTry } from '@spexcode/spec-core';
+// [[spec-body-edit]]: the one seam through which a human at the board edits a spec BODY and lands it as a
+// real commit — the "edit this file on the web" affordance, held to this project's law rather than
+// GitHub's.
+//
+// Four structural guarantees, each enforced by construction rather than by checking a request field:
+//
+//  1. ONLY A SPEC BODY. The target file is DERIVED from the node id through the spec tree's own reader, so
+//     no request can name a path; and only the region between the frontmatter and the end of the file is
+//     rewritten, so no request can move a `code:` anchor, a status, or a single byte of source.
+//  2. ONLY THE REGION THE READER SAW. The caller sends back the exact lines it rendered. If the file has
+//     moved underneath them the write is REFUSED with the current text — never merged, never guessed. Every
+//     such precondition is checked while the tree is still untouched, so a refusal costs nothing.
+//  3. THE GATES STAY UP. The commit opens exactly ONE door in [[main-guard]] — `SPEXCODE_ALLOW_MAIN`, the
+//     named escape hatch — and never `--no-verify`. The neighbouring programmatic writers ([[local-issues]],
+//     [[human-ok]]) may skip the hook because their paths are unanchored DATA; a `spec.md` is the contract
+//     itself, so it must pass the same spec-lint gate a session's commit passes. A refusal is reported
+//     verbatim, with the tree put back the way it was found.
+//  4. NOTHING IS STORED. The commit is the whole record: [[source-of-truth]] recomputes the node's version
+//     from its count of content commits, so the version bumps and drift re-derives with no extra bookkeeping.
+export class SpecBodyEditError extends Error {
+    status;
+    code;
+    detail;
+    constructor(message, status, code, detail) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.detail = detail;
+    }
+}
+// The body a line number addresses is the TRIMMED body — the same text `/api/specs/:id/content` serves and
+// the same text the reader's line stamps were computed against. The file's leading and trailing whitespace
+// is held aside and put back untouched, so an edit changes the region and nothing else in the file.
+function splitFile(source) {
+    const { body } = parseFrontmatter(source);
+    const head = source.slice(0, source.length - body.length);
+    const lead = body.length - body.trimStart().length;
+    const trimmed = body.trim();
+    return { prefix: head + body.slice(0, lead), trimmed, suffix: body.slice(lead + trimmed.length) };
+}
+const isInt = (v) => Number.isInteger(v);
+export function readSpecBodyEdit(raw) {
+    const b = (raw ?? {});
+    if (!isInt(b.startLine) || !isInt(b.endLine) || b.startLine < 1 || b.endLine < b.startLine) {
+        throw new SpecBodyEditError('body needs a 1-based line range { startLine, endLine } with endLine >= startLine', 400, 'bad-range');
+    }
+    if (typeof b.original !== 'string' || typeof b.replacement !== 'string') {
+        throw new SpecBodyEditError('body needs { original, replacement } — the text the reader saw and the text to put in its place', 400, 'bad-text');
+    }
+    return {
+        startLine: b.startLine,
+        endLine: b.endLine,
+        original: b.original,
+        replacement: b.replacement,
+        ...(typeof b.reason === 'string' && b.reason.trim() ? { reason: b.reason.trim() } : {}),
+    };
+}
+export async function editSpecBody(id, patch) {
+    const root = repoRoot();
+    const dir = specDir(id);
+    if (!dir)
+        throw new SpecBodyEditError(`no such spec node: ${id}`, 404, 'no-node');
+    // guarantee 1, made structural: the path came from the spec tree, and it must still look like one. A
+    // node whose folder resolved outside `.spec/` is a broken tree, not an edit target.
+    const relPath = `${dir}/spec.md`;
+    if (!relPath.startsWith('.spec/') || !relPath.endsWith('/spec.md') || relPath.includes('..')) {
+        throw new SpecBodyEditError(`node ${id} does not resolve to a spec body inside .spec/`, 404, 'no-node');
+    }
+    const file = join(root, relPath);
+    if (!existsSync(file))
+        throw new SpecBodyEditError(`node ${id} has no spec.md on disk`, 404, 'no-node');
+    const source = readFileSync(file, 'utf8');
+    const { prefix, trimmed, suffix } = splitFile(source);
+    const lines = trimmed.split('\n');
+    if (patch.endLine > lines.length) {
+        throw new SpecBodyEditError(`lines ${patch.startLine}-${patch.endLine} run past the end of the body (${lines.length} lines)`, 409, 'stale-region', { bodyLines: lines.length });
+    }
+    // guarantee 2. The reader's copy of the region is the precondition; a mismatch is a CONCURRENT MODIFICATION,
+    // reported with the text that is actually there so the human can see what moved.
+    const current = lines.slice(patch.startLine - 1, patch.endLine).join('\n');
+    if (current !== patch.original) {
+        throw new SpecBodyEditError(`lines ${patch.startLine}-${patch.endLine} of ${relPath} changed since they were read — the edit was not applied`, 409, 'stale-region', { current });
+    }
+    const next = prefix + [...lines.slice(0, patch.startLine - 1), ...patch.replacement.split('\n'), ...lines.slice(patch.endLine)].join('\n') + suffix;
+    if (next === source)
+        return { ok: true, changed: false, path: relPath, commit: null, startLine: patch.startLine, endLine: patch.endLine };
+    // Everything above is read-only, and deliberately: the caller gets the diagnosis that is actually about
+    // their edit before the tree's state is allowed to have an opinion. Only a real write needs a clean index
+    // — a path already carrying a STAGED change belongs to whoever staged it, and committing here would sweep
+    // their work into this edit's commit, so it refuses rather than guess whose change it is.
+    const staged = await gitTry(['-C', root, 'diff', '--cached', '--name-only', '--', relPath]);
+    if (staged.ok && staged.stdout.trim()) {
+        throw new SpecBodyEditError(`${relPath} already has a staged change — commit or unstage it before editing here`, 409, 'staged-conflict');
+    }
+    writeFileSync(file, next);
+    const restore = () => {
+        writeFileSync(file, source);
+        return gitTry(['-C', root, 'reset', '--quiet', '--', relPath]);
+    };
+    const message = [
+        `spec: ${id} — edited in the dashboard`,
+        '',
+        `Body lines ${patch.startLine}-${patch.endLine} replaced through the dashboard's spec editor ([[spec-body-edit]]).`,
+        ...(patch.reason ? ['', patch.reason] : []),
+        '',
+        // Server-derived, exactly as [[human-ok]] derives its actor: the identity of a board edit is the person
+        // at the board, and no request body gets to claim to be someone else.
+        'Session: human',
+    ].join('\n');
+    const add = await gitTry(['-C', root, 'add', '--', relPath]);
+    if (!add.ok) {
+        await restore();
+        throw new SpecBodyEditError(`git could not stage ${relPath}: ${add.stderr.trim() || 'unknown failure'}`, 409, 'git-failed');
+    }
+    // guarantee 3: the ONE named door. `SPEXCODE_ALLOW_MAIN` waives only the main-authoring guard, so the
+    // spec-lint shim and the reference-transaction candidate gate both still judge this commit. On a
+    // node branch the flag changes nothing at all — the same call works from either checkout.
+    const commit = await gitTry(['-C', root, 'commit', '--quiet', '-m', message, '--', relPath], {
+        extraEnv: { SPEXCODE_ALLOW_MAIN: '1' },
+    });
+    if (!commit.ok) {
+        await restore();
+        const why = [commit.stderr, commit.stdout].map((s) => s.trim()).filter(Boolean).join('\n') || 'git commit failed with no output';
+        throw new SpecBodyEditError(`the commit was refused, so ${relPath} was put back unchanged:\n${why}`, 409, 'commit-refused');
+    }
+    const head = await gitTry(['-C', root, 'rev-parse', 'HEAD']);
+    return {
+        ok: true,
+        changed: true,
+        path: relPath,
+        commit: head.ok ? head.stdout.trim() : null,
+        startLine: patch.startLine,
+        endLine: patch.startLine + patch.replacement.split('\n').length - 1,
+    };
+}

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

@@ -9,13 +9,13 @@ import { stat, readdir } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { installProcessGuards } from '@spexcode/spec-core';
-import { listenOrExit } from './listen.js';
+import { listenOrExit, resolveConfiguredPort } from './listen.js';
 import { resolvePublicConfig, startGateway, resolveDistDir } from './gateway.js';
 import { publishEndpoint, dropOwnEndpoint } from './host.js';
 import { repoRoot as servedRepoRoot } from '@spexcode/spec-core';
 import { resolveProjectIdentity } from '@spexcode/spec-core';
 import { startResourceMonitor } from './host-resources.js';
-import { registerBackendInstance, unregisterBackendInstance } from './runtime-ownership.js';
+import { reapOrphanBackendInstances, registerBackendInstance, unregisterBackendInstance } from './runtime-ownership.js';
 import { sessionIdentityEnvVars } from './harness.js';
 import { serverEntrypointArgs } from './tsx-bin.js';
 // the supervisor OWNS the public port, so it must outlive any transient throw: an uncaught error here is
@@ -26,7 +26,14 @@ const packageRoot = join(here, '..');
 const sourceRoot = join(packageRoot, 'src');
 const workspaceRoot = existsSync(sourceRoot) ? join(packageRoot, '..') : null;
 const entryArgs = serverEntrypointArgs(packageRoot, here);
-const publicPort = Number(process.env.PORT || 8787);
+let publicPort;
+try {
+    publicPort = resolveConfiguredPort(process.env.PORT);
+}
+catch (error) {
+    console.error(`spec-cli: invalid PORT — ${error.message}`);
+    process.exit(2);
+}
 const projectRoot = servedRepoRoot(); // the actual git tree whose source/spec/config the child serves
 // @@@ public mode ([[public-mode]]) - with `spex serve --public`, the supervisor is NOT the internet face:
 // the gateway is. The raw-TCP proxy retreats to a loopback internal port (the trusted boundary local agents
@@ -42,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'), join(workspaceRoot, 'packages', 'session-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)
@@ -67,6 +74,8 @@ for (const key of sessionIdentityEnvVars())
     delete process.env[key];
 process.env.SPEXCODE_PROJECT_ROOT = projectRoot;
 process.env.SPEXCODE_INSTANCE_ID = instanceId;
+for (const orphan of reapOrphanBackendInstances(projectRoot))
+    console.warn(`[supervisor] reaped stale backend ${orphan.instanceId} PID ${orphan.candidatePid}`);
 registerBackendInstance(instanceId, process.pid, projectRoot);
 let current = null; // which internal port new proxy connections forward to
 let reloading = false; // single-flight guard for reload()
@@ -246,11 +255,11 @@ catch { /* already gone */ } };
 if (publicCfg) {
     // public mode: the raw proxy stays on loopback; the password-gated gateway owns the public port.
     const distDir = resolveDistDir();
-    listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: () => recordEndpoint(childApiBase), ready: `spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})` });
+    listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: (actualPort) => recordEndpoint(`http://127.0.0.1:${actualPort}`), ready: (actualPort) => `spec-cli supervisor on loopback :${actualPort} (zero-downtime reloads, backend :${first.port})` });
     startGateway({ publicPort, upstreamPort: proxyPort, password: publicCfg.password, tls: publicCfg.tls, distDir, onBindFail: reapChild });
 }
 else {
-    listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => recordEndpoint(childApiBase), ready: `spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})` });
+    listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: (actualPort) => recordEndpoint(`http://127.0.0.1:${actualPort}`), ready: (actualPort) => `spec-cli supervisor serving on http://localhost:${actualPort} (zero-downtime reloads, backend :${first.port})` });
 }
 startResourceMonitor();
 // Watch the source closure in a workspace and the emitted directory in an installed package. Debounce a