spexcode 0.6.2 → 0.6.5

package/node_modules/@spexcode/spec-core/dist/layout.js

@@ -0,0 +1,548 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { git, repoRoot, gitA, gitAbortError, currentGitBuildAbortSignal, gitInterpretationIdentity, headSha, worktreeSpecSig, worktreeSpecDelta, worktreeSpecDeltas, withGitAbortSignal } from './git.js';
+import { guardWorktree } from './resilience.js';
+import { HARNESS_IDENTITIES } from './harness-identity.js';
+import { encodeProject, projectRuntimeRoot } from './project-store.js';
+// Read an OPTIONAL JSON config file. An ABSENT file is the legitimate default (return {}); a
+// PRESENT-but-malformed one is a user error we must NOT swallow — a typo would otherwise silently
+// drop every tuned setting the file holds (lint budgets, launchers, layout) and revert to defaults
+// with no diagnostic. Fail LOUD, naming the file and the parse error, so the author sees what broke.
+export function readJsonConfig(p) {
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        const err = new Error(`malformed ${p}: ${e.message}\n  → its settings were NOT applied. Fix the JSON syntax (an absent file is a fine default; a broken one is not).`);
+        err.name = 'ConfigError'; // rendered message-only at the CLI boundary (like BackendError), not as a stack dump
+        throw err;
+    }
+}
+// committed `spexcode.json` with an OPTIONAL machine-local `spexcode.local.json` layered on top (gitignored).
+// The local layer is the durable home for HOST-SPECIFIC values that must never be committed — e.g. an
+// absolute worker-launcher path (the host-path leak the repo otherwise warns against). Precedence per field:
+// local over committed; a targeted env override (e.g. SPEXCODE_CODEX_SERVER_CMD) still wins at its read site.
+export function readConfig(root) {
+    const committed = readJsonConfig(join(root, 'spexcode.json'));
+    const local = readJsonConfig(join(root, 'spexcode.local.json'));
+    const out = { ...committed };
+    for (const k of Object.keys(local)) {
+        const b = committed[k], o = local[k];
+        out[k] = (b && o && typeof b === 'object' && typeof o === 'object' && !Array.isArray(o)) ? { ...b, ...o } : o;
+    }
+    return out;
+}
+export const templateConfigPath = fileURLToPath(new URL('../templates/spexcode.json', import.meta.url));
+const MIN_POSITIVE_INTEGER = 1;
+const MIN_NONNEGATIVE_INTEGER = 0;
+function uploadConfigError(field, rule) {
+    const error = new Error(`uploads.${field} must be ${rule}`);
+    error.name = 'ConfigError';
+    throw error;
+}
+function configuredInteger(value, field, minimum) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum) {
+        uploadConfigError(field, minimum === MIN_POSITIVE_INTEGER ? 'a positive integer' : 'a non-negative integer');
+    }
+    return value;
+}
+function resolveUploadPolicy(values) {
+    const policy = {
+        maxBytes: configuredInteger(values.maxBytes, 'maxBytes', MIN_POSITIVE_INTEGER),
+        chunkBytes: configuredInteger(values.chunkBytes, 'chunkBytes', MIN_POSITIVE_INTEGER),
+        concurrency: configuredInteger(values.concurrency, 'concurrency', MIN_POSITIVE_INTEGER),
+        requestTimeoutMs: configuredInteger(values.requestTimeoutMs, 'requestTimeoutMs', MIN_POSITIVE_INTEGER),
+        retryLimit: configuredInteger(values.retryLimit, 'retryLimit', MIN_NONNEGATIVE_INTEGER),
+        retryDelayMs: configuredInteger(values.retryDelayMs, 'retryDelayMs', MIN_NONNEGATIVE_INTEGER),
+        incompleteTtlMs: configuredInteger(values.incompleteTtlMs, 'incompleteTtlMs', MIN_POSITIVE_INTEGER),
+        cleanupIntervalMs: configuredInteger(values.cleanupIntervalMs, 'cleanupIntervalMs', MIN_POSITIVE_INTEGER),
+        minFreeBytes: configuredInteger(values.minFreeBytes, 'minFreeBytes', MIN_NONNEGATIVE_INTEGER),
+        evidenceMaxBytes: configuredInteger(values.evidenceMaxBytes, 'evidenceMaxBytes', MIN_POSITIVE_INTEGER),
+    };
+    if (policy.chunkBytes > policy.maxBytes)
+        uploadConfigError('chunkBytes', 'no greater than uploads.maxBytes');
+    return policy;
+}
+export function uploadPolicyDefaults() {
+    return resolveUploadPolicy(readJsonConfig(templateConfigPath).uploads);
+}
+// The seed template is the sole default-value source. Existing projects may omit `uploads`; they receive this
+// policy, while a committed/local value overrides it through readConfig's existing one-level merge.
+export function readUploadPolicy(root) {
+    const configured = readConfig(root).uploads;
+    return resolveUploadPolicy({ ...uploadPolicyDefaults(), ...configured });
+}
+// The shared git common dir (env-stripped git() so a hook's exported GIT_DIR can't misdirect it).
+// Cache by resolved checkout path: callers may deliberately chdir between isolated repositories in one process.
+const commonDirsByPath = new Map();
+const topsByPath = new Map();
+export function gitCommonDir() {
+    return commonDirFor(process.cwd());
+}
+function commonDirFor(proj) {
+    const key = resolve(proj);
+    const known = commonDirsByPath.get(key);
+    if (known)
+        return known;
+    const common = git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
+    commonDirsByPath.set(key, common);
+    return common;
+}
+function topFor(proj) {
+    const key = resolve(proj);
+    const known = topsByPath.get(key);
+    if (known)
+        return known;
+    const top = git(['-C', proj, 'rev-parse', '--show-toplevel']).trim();
+    topsByPath.set(key, top);
+    return top;
+}
+export function mainBranch() {
+    let checkout;
+    try {
+        checkout = mainCheckout();
+    }
+    catch {
+        return 'main';
+    }
+    return readConfig(checkout).mainBranch?.trim() || 'main';
+}
+// the MAIN checkout (the root working tree) for a project — the SAME answer from main OR any linked worktree
+// (dirname of the shared git common dir). Codex reads a LINKED worktree's PROJECT hooks from the root checkout's
+// `.codex` (codex-rs hooks_config_folder override), NOT the worktree's, so the codex hooks shim + trust
+// materialize here while AGENTS.md/skills stay per-worktree — see [[harness-adapter]] (harness.ts).
+export function mainCheckout(proj) {
+    const gcd = proj ? commonDirFor(proj) : gitCommonDir();
+    return dirname(gcd);
+}
+// @@@ main root - identity checks need creation's configured-main answer without the record/overlay work in resolveLayout.
+export function mainRoot(proj) {
+    if (proj) {
+        const checkout = mainCheckout(proj);
+        const configured = readConfig(checkout).main?.trim();
+        return configured ? resolve(checkout, configured) : checkout;
+    }
+    try {
+        const checkout = mainCheckout();
+        const configured = readConfig(checkout).main?.trim();
+        return configured ? resolve(checkout, configured) : checkout;
+    }
+    catch {
+        return repoRoot();
+    }
+}
+// @@@ global per-session store - Fork A: NO SpexCode files live in the worktree any more, so the worktree's
+// spec/code tree is pristine (zero per-session pollution). Every per-session runtime artifact — the
+// structured record (session.json) AND the launcher products (prompt, launch, launch.sh) AND the recorded comms AND
+// the spec-discipline sentinels — lives in a per-USER GLOBAL store, keyed by the harness `session_id` so two
+// agents in one folder never clobber, and grouped PER PROJECT (mirroring Claude's ~/.claude/projects/<enc>/)
+// so the board enumerates ONE directory. This is the single seam that knows where the store sits; sessions.ts
+// and the shell hooks resolve through the SAME scheme (the hooks reimplement it in bash, so any change here
+// must be mirrored in .plugins/core/*/). SPEXCODE_HOME overrides the root for test isolation.
+// encode a project-root path into ONE safe directory segment (Claude's scheme: path separators → '-'). The
+// SAME transform runs in TS and in the shell hooks, so a board read and a hook write land on the SAME dir.
+// this project's per-PROJECT runtime tier — the sessions/ records AND the per-TREE materialize slots (below) —
+// living under the SAME global per-project dir, so NOTHING SpexCode materializes stays in the worktree (the
+// worktree holds only the harness-discovered CLAUDE.md/AGENTS.md + shims, which must sit in-tree).
+// proj-aware for `spex init <dir>` / materialize(proj); cwd-based default for the hooks/board. The shell
+// hooks mirror this as hp_runtime_dir.
+export function runtimeRoot(proj) {
+    const gcd = proj ? commonDirFor(proj) : gitCommonDir();
+    return projectRuntimeRoot(gcd);
+}
+// the per-WORKTREE materialize slot — <runtime>/trees/<enc(worktree-toplevel)> — holding the materialize
+// products that are a pure function of ONE tree's .plugins (hooks-manifest, content-hash, plugin-folders).
+// Slotted per tree exactly like sessions/<id> is slotted per session: the old single global file made the
+// last-materialized tree win, so dispatch ran tree A's compiled hook set inside tree B's sessions
+// ([[hook-dispatch]]). Key = the sessions encodeProject transform over `rev-parse --show-toplevel`, the
+// SAME derivation dispatch.sh's shell mirror (hp_tree_dir) runs from its own cwd — so writer and reader
+// land on the same slot from the same tree, and only from the same tree. Throws when `wt` is not a live
+// git tree (fail loud); a best-effort caller (the close-time GC) wraps it.
+export function treeSlotDir(wt) {
+    const top = topFor(wt);
+    return join(runtimeRoot(wt), 'trees', encodeProject(top || wt));
+}
+// this project's per-session records dir, one session's dir, its structured record, and a sibling artifact —
+// all keyed by session_id under <home>/projects/<enc>/sessions/.
+export function sessionsRoot() { return join(runtimeRoot(), 'sessions'); }
+export function sessionStoreDir(id) { return join(sessionsRoot(), id); }
+export function sessionRecordPath(id) { return join(sessionStoreDir(id), 'session.json'); }
+export function sessionArtifactPath(id, name) { return join(sessionStoreDir(id), name); }
+export const SESSION_LIFECYCLES = ['active', 'idle', 'awaiting', 'parked', 'error', 'asking', 'queued'];
+export const SESSION_PROPOSALS = ['merge', 'nothing', 'close'];
+const sessionLifecycles = new Set(SESSION_LIFECYCLES);
+const sessionProposals = new Set(SESSION_PROPOSALS);
+export const isSessionLifecycle = (value) => typeof value === 'string' && sessionLifecycles.has(value);
+export const isSessionProposal = (value) => typeof value === 'string' && sessionProposals.has(value);
+// A launch candidate is durable before it is public. Readers of the authored lifecycle use this one parser
+// so the board and the independent timeline observer cannot disagree about an in-flight resume. Invalid
+// pending bytes throw: a damaged publication fence is unknowable state, never permission to project online.
+export function rawLaunchReadinessOriginal(raw) {
+    const pending = raw.launch_readiness_pending;
+    if (pending == null || pending === '')
+        return null;
+    const original = pending && typeof pending === 'object' ? pending.original : null;
+    if (pending.version !== 1 || !Number.isFinite(pending.startedAt) || !original || typeof original !== 'object'
+        || !isSessionLifecycle(original.status)
+        || !(original.proposal === null || original.proposal === '' || isSessionProposal(original.proposal))
+        || !(typeof original.note === 'string' || original.note === null)
+        || typeof original.stopped !== 'boolean' || typeof original.archived !== 'boolean'
+        || !(typeof original.cold_proof === 'string' || original.cold_proof === null)
+        || !(typeof original.adapter_recovery === 'string' || original.adapter_recovery === null)) {
+        throw new Error(`session '${raw.session_id}' has an invalid launch_readiness_pending fence`);
+    }
+    return original;
+}
+// the agent's OWN session id from the environment — the only locator now that the record left the worktree.
+// Three tiers, in order:
+//   (1) a harness's per-thread env var (`sessionEnvVar`) RESOLVED VIA THE ALIAS — when it lands on a governed
+//       record (directly, or through that record's `harness_session_id`), that record's SpexCode id is the
+//       answer. This MUST win: codex's design-C runs ONE shared per-project app-server whose env carries the
+//       FIRST launched session's `SPEXCODE_SESSION_ID`, and the agent's shell tool (its `spex session
+//       done/park/ask`) runs INSIDE that app-server process, so `SPEXCODE_SESSION_ID` is contaminated with the
+//       wrong session. But codex injects the ACTING thread's id into every spawned command's env as
+//       CODEX_THREAD_ID (== codex's `sessionEnvVar`), so the per-thread var aliases to the RIGHT record while
+//       the shared `SPEXCODE_SESSION_ID` does not.
+//   (2) else `SPEXCODE_SESSION_ID` (the GOVERNED record id the launcher bakes in) — the claude path and the
+//       non-shared baseline.
+//   (3) else a harness's env var RAW — a self-launched, non-governed agent's own minted id, which has no
+//       governed record to alias to (codex CODEX_THREAD_ID / claude CLAUDE_CODE_SESSION_ID). The RAW form must
+//       stay BELOW (2): an un-aliased codex thread id is not a record key, so it must never beat a real
+//       `SPEXCODE_SESSION_ID`.
+// Claude is UNCHANGED: its `sessionEnvVar` (CLAUDE_CODE_SESSION_ID) already EQUALS its record id, so tier (1)
+// resolves to that very id — the same value `SPEXCODE_SESSION_ID` would have returned; there is no shared
+// app-server to contaminate it. No worktree fallback. (sessions.ts's `ownSessionId` delegates here; spec-eval
+// reads it to resolve the current node.)
+export function envSessionId() {
+    for (const h of HARNESS_IDENTITIES) {
+        const v = process.env[h.sessionEnvVar];
+        if (v && v.trim()) {
+            const r = readAliasedRawRecord(v.trim());
+            if (r)
+                return r.session_id;
+        }
+    }
+    const o = process.env.SPEXCODE_SESSION_ID;
+    if (o && o.trim())
+        return o.trim();
+    for (const h of HARNESS_IDENTITIES) {
+        const v = process.env[h.sessionEnvVar];
+        if (v && v.trim())
+            return v.trim();
+    }
+    return null;
+}
+export function readRecordEntry(id) {
+    const path = sessionRecordPath(id);
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { kind: 'absent' };
+        throw e;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return { kind: 'corrupt', path, error: e instanceof Error ? e.message : String(e) };
+    }
+    if (!raw || typeof raw !== 'object' || !raw.session_id)
+        return { kind: 'corrupt', path, error: 'parsed, but carries no session_id — not a session record' };
+    return { kind: 'ok', raw: raw };
+}
+// The ONE public session-record parser. Internal mutation/readiness code uses readRecordEntry's exact raw
+// candidate; every public projection passes through here. A valid pending fence replaces all lifecycle-facing
+// fields with its frozen original and forces offline liveness. Malformed pending bytes remain a present,
+// corrupt/unknown row instead of leaking candidate state or disappearing as absence.
+export function projectPublicRecordEntry(id, entry) {
+    if (entry.kind === 'absent')
+        return entry;
+    if (entry.kind === 'corrupt')
+        return {
+            kind: 'corrupt', sessionId: id, governed: null, path: entry.path, error: entry.error, liveness: 'unknown',
+        };
+    try {
+        const original = rawLaunchReadinessOriginal(entry.raw);
+        if (!original)
+            return { kind: 'ok', raw: entry.raw, liveness: null };
+        return {
+            kind: 'ok',
+            raw: {
+                ...entry.raw,
+                status: original.status,
+                proposal: original.proposal || null,
+                note: original.note || null,
+                stopped: original.stopped,
+                archived: original.archived,
+                cold_proof: original.cold_proof ?? undefined,
+                adapter_recovery: original.adapter_recovery ?? undefined,
+                launch_readiness_pending: '',
+            },
+            liveness: 'offline',
+        };
+    }
+    catch (error) {
+        return {
+            kind: 'corrupt',
+            sessionId: id,
+            governed: typeof entry.raw.governed === 'boolean' ? entry.raw.governed : null,
+            path: sessionRecordPath(id),
+            error: error instanceof Error ? error.message : String(error),
+            liveness: 'unknown',
+        };
+    }
+}
+export function readPublicRecordEntry(id) {
+    return projectPublicRecordEntry(id, readRecordEntry(id));
+}
+export function readRawRecord(id) {
+    try {
+        const e = readRecordEntry(id);
+        return e.kind === 'ok' ? e.raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+// resolve a possibly-ALIASED session id to its raw record. A codex hook or spawned command can carry the codex
+// THREAD id — payload session_id / CODEX_THREAD_ID — not the SpexCode record id the store is keyed by. Direct id
+// wins; else the one record that captured this id as `harness_session_id` (the backend stored it at thread/start,
+// before any tool turn).
+// Null when neither resolves. Mirrors the shell `hp_store_dir` alias grep — one resolution rule, both layers.
+export function readAliasedRawRecord(id) {
+    const e = readAliasedRecordEntry(id);
+    return e.kind === 'ok' ? e.raw : null;
+}
+// the same alias resolution, keeping the three-way outcome. A CORRUPT record at the direct id settles the
+// question — we found this session and cannot read it; walking on to the alias would report a corrupt record
+// as absent, the exact collapse this type exists to prevent.
+export function readAliasedRecordEntry(id) {
+    const direct = readRecordEntry(id);
+    if (direct.kind !== 'absent')
+        return direct;
+    // @@@ absence splits in two, and only one half is an alias question - an id owning a store dir is already
+    // one of ours (the sentinel-only agent above), so its emptiness is settled; searching would let an unrelated
+    // record answer under a live session's own name, and costs a whole-store re-parse per 1s supervisor tick.
+    if (existsSync(sessionStoreDir(id)))
+        return { kind: 'absent' };
+    for (const sid of listSessionIds()) {
+        const r = readRawRecord(sid);
+        if (r && r.harness_session_id && r.harness_session_id === id)
+            return { kind: 'ok', raw: r };
+    }
+    return { kind: 'absent' };
+}
+// every session_id this project has a record for (the board's enumeration source — replaces `git worktree
+// list`). A MISSING store dir means no session ever launched → []. But any OTHER readdir failure THROWS
+// (preserving the fail-loud-enumeration invariant `git worktree list` had): a transient FS error must never
+// read as "every session vanished" — the watch poll skips the tick on a throw, never emitting a false mass-close.
+export function listSessionIds() {
+    let ents;
+    try {
+        ents = readdirSync(sessionsRoot(), { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    return ents.filter((d) => d.isDirectory()).map((d) => d.name);
+}
+// @@@ branch -> session, so a moved ref can DERIVE its invalidation scope - a session's evaluation depends
+// on its own branch tip, the base branch tip and their merge-base; no other ref participates. Without this
+// map a ref watcher knows only that "something under refs/ moved" and the honest fallback is to invalidate
+// every session ([[taste]] 19). One record read per session, and only when the session store itself moved.
+export function sessionBranchIndex() {
+    const index = new Map();
+    for (const id of listSessionIds()) {
+        let branch;
+        try {
+            branch = readRawRecord(id)?.branch;
+        }
+        catch {
+            continue;
+        } // a corrupt record narrows nothing
+        if (typeof branch === 'string' && branch)
+            index.set(branch, id);
+    }
+    return index;
+}
+// Retain only completed per-worktree overlays. Interpretation + main tip + HEAD + working signature completely
+// determine the merge-base and projection; a landed main tip therefore dissolves now-moot ops on the next read.
+const deltaCache = new Map();
+const safeHead = (p) => { try {
+    return headSha(p);
+}
+catch {
+    return '';
+} };
+let layoutHeadWarned = false;
+const layoutDeltaFlights = new Map();
+// One exact public layout generation owns the cold overlay computation. The map is only an in-flight join:
+// the entry is deleted at settlement and deltaCache remains the sole retained result state.
+async function layoutDeltas(paths, main, mainRef, mainSha) {
+    const snapshots = paths.map((path) => ({ path, head: safeHead(path), sig: worktreeSpecSig(path) }));
+    const interpretation = gitInterpretationIdentity(main);
+    const flightKey = JSON.stringify([interpretation, mainRef, mainSha, snapshots.map(({ path, head, sig }) => [path, head, sig]).sort((a, b) => a[0].localeCompare(b[0]))]);
+    let flight = layoutDeltaFlights.get(flightKey);
+    if (flight?.controller.signal.aborted) {
+        layoutDeltaFlights.delete(flightKey);
+        flight = undefined;
+    }
+    if (!flight) {
+        const controller = new AbortController();
+        const entry = { promise: Promise.resolve(new Map()), controller, waiters: new Set(), settled: false };
+        entry.promise = withGitAbortSignal(controller.signal, async () => {
+            const outcomes = new Map();
+            const misses = [];
+            for (const snapshot of snapshots) {
+                const key = `${interpretation}\0${mainSha}\0${snapshot.head}\0${snapshot.sig}`;
+                const hit = snapshot.head && mainSha ? deltaCache.get(snapshot.path) : null;
+                if (hit?.key === key)
+                    outcomes.set(snapshot.path, { ops: hit.ops });
+                else
+                    misses.push(snapshot);
+            }
+            const valid = misses.filter(({ head }) => !!head && !!mainSha);
+            const batched = await worktreeSpecDeltas(main, mainSha, valid.map(({ path, head }) => ({ path, head })), interpretation);
+            for (const snapshot of valid) {
+                const outcome = batched.get(snapshot.path) ?? { error: new Error(`layout overlay batch omitted ${snapshot.path}`) };
+                if ('error' in outcome)
+                    outcomes.set(snapshot.path, outcome);
+                else {
+                    const key = `${interpretation}\0${mainSha}\0${snapshot.head}\0${snapshot.sig}`;
+                    deltaCache.set(snapshot.path, { key, ops: outcome.ops });
+                    outcomes.set(snapshot.path, { ops: outcome.ops });
+                }
+            }
+            await Promise.all(misses.filter(({ head }) => !head || !mainSha).map(async (snapshot) => {
+                if (!existsSync(snapshot.path)) {
+                    outcomes.set(snapshot.path, { error: new Error(`worktree ${snapshot.path} is absent`) });
+                    return;
+                }
+                if (!layoutHeadWarned) {
+                    layoutHeadWarned = true;
+                    console.warn('spec-cli: layout overlay cache bypassed (unreadable HEAD/main tip), recomputing every read');
+                }
+                try {
+                    outcomes.set(snapshot.path, { ops: await worktreeSpecDelta(snapshot.path, mainRef) });
+                }
+                catch (error) {
+                    outcomes.set(snapshot.path, { error });
+                }
+            }));
+            return outcomes;
+        }).finally(() => {
+            entry.settled = true;
+            if (layoutDeltaFlights.get(flightKey) === entry)
+                layoutDeltaFlights.delete(flightKey);
+        });
+        layoutDeltaFlights.set(flightKey, entry);
+        flight = entry;
+    }
+    const token = Symbol(flightKey);
+    const callerSignal = currentGitBuildAbortSignal();
+    flight.waiters.add(token);
+    let onAbort = null;
+    try {
+        if (!callerSignal)
+            return await flight.promise;
+        if (callerSignal.aborted)
+            throw gitAbortError();
+        return await Promise.race([
+            flight.promise,
+            new Promise((_, reject) => {
+                onAbort = () => reject(gitAbortError());
+                callerSignal.addEventListener('abort', onAbort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (onAbort)
+            callerSignal?.removeEventListener('abort', onAbort);
+        flight.waiters.delete(token);
+        if (!flight.settled && flight.waiters.size === 0)
+            flight.controller.abort();
+    }
+}
+export async function resolveLayout(options = {}) {
+    const root = repoRoot();
+    const main = dirname(gitCommonDir()); // the main checkout — same answer from main OR any linked worktree
+    const cfg = readConfig(main);
+    const base = mainBranch();
+    const convention = {
+        main: cfg.main || '',
+        mainBranch: base,
+        branchPrefix: cfg.branchPrefix ?? 'node/',
+    };
+    const mainRef = base;
+    // the board enumerates the GLOBAL per-session store (NOT `git worktree list`): every GOVERNED record this
+    // project owns, each carrying the worktree_path its spec-delta is computed from. Non-governed (user-self-
+    // launched) records are excluded — board state is a managed-session concern ([[state]]). Each delta is
+    // independent → compute (or cache-hit) in parallel, keyed by worktree path as before. guardWorktree wraps
+    // each: a worktree whose dir was genuinely removed mid-read (a worker self-merged + retired it) is OMITTED;
+    // one that still exists but hit a transient detail failure is kept as a DEGRADED row from the last cached delta.
+    const publicEntries = listSessionIds().map((id) => readPublicRecordEntry(id))
+        .filter((entry) => entry.kind === 'corrupt' ? entry.governed !== false : entry.kind === 'ok' && entry.raw.governed);
+    const records = publicEntries.flatMap((entry) => entry.kind === 'ok' ? [entry] : []);
+    const projectedActive = options.activeSessionIds ? new Set(options.activeSessionIds) : null;
+    const isActive = (record) => projectedActive
+        ? projectedActive.has(record.session_id)
+        : !record.archived;
+    // main's tip, resolved ONCE per board read — a component of every worktree's overlay cache key
+    // ([[worktree-linker]]: landed content must dissolve the ops it made moot).
+    const mainSha = await (async () => {
+        try {
+            return (await gitA(['-C', main, 'rev-parse', '--verify', `${mainRef}^{commit}`])).trim();
+        }
+        catch {
+            return '';
+        }
+    })();
+    const activePaths = records.filter(({ raw }) => isActive(raw)).map(({ raw }) => raw.worktree_path);
+    const deltas = await layoutDeltas(activePaths, main, mainRef, mainSha);
+    const rows = await Promise.all(records.map(({ raw: r, liveness }) => {
+        const node = r.node ?? (r.branch && r.branch.startsWith(convention.branchPrefix) ? r.branch.slice(convention.branchPrefix.length) : null);
+        const base = { path: r.worktree_path, branch: r.branch, node, session: r.session_id, status: r.status, isMain: false, ...(liveness ? { liveness } : {}), ops: [] };
+        // @@@ projected shelves cost nothing - a cold archived session ([[archive]]) keeps its record but leaves
+        // the working-set projection and skips the per-worktree spec delta. An archived runtime hazard is still
+        // projected active by listSessions, so it deliberately retains the same ops in both full and splice builds.
+        if (!isActive(r))
+            return Promise.resolve(base);
+        return guardWorktree(r.worktree_path, () => {
+            const outcome = deltas.get(r.worktree_path);
+            if (!outcome)
+                throw new Error(`layout overlay missing ${r.worktree_path}`);
+            if ('error' in outcome)
+                throw outcome.error;
+            return { ...base, ops: outcome.ops };
+        }, () => {
+            const cached = deltaCache.get(r.worktree_path);
+            if (!cached)
+                throw new Error(`layout overlay failed before ${r.worktree_path} had a last-known result`);
+            return { ...base, ops: cached.ops };
+        });
+    }));
+    const corruptRows = publicEntries.flatMap((entry) => entry.kind === 'corrupt'
+        ? [{ path: '', branch: null, node: null, session: entry.sessionId, status: 'corrupt', liveness: 'unknown', isMain: false, ops: [] }]
+        : []);
+    const sessionWorktrees = [...rows.filter((w) => w !== null), ...corruptRows];
+    // the main checkout row (isMain) — always present, carries no overlay; it anchors the merged tree the board draws.
+    const mainRow = { path: main, branch: base, node: null, session: null, status: null, isMain: true, ops: [] };
+    const worktrees = [mainRow, ...sessionWorktrees];
+    // drop cache entries for worktrees that may no longer hold one — closed sessions (gone from the store) AND
+    // newly-cold archived ones (which no longer compute a delta), so archiving SELF-EVICTS its cached ops instead of
+    // stranding them in a map nothing prunes.
+    const live = new Set(records.filter(({ raw }) => isActive(raw)).map(({ raw }) => raw.worktree_path));
+    for (const k of [...deltaCache.keys()])
+        if (!live.has(k))
+            deltaCache.delete(k);
+    return { main: convention.main || main || root, convention, worktrees };
+}

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

@@ -0,0 +1,37 @@
+export type ProcessIdentity = {
+    pid: number;
+    startToken: string;
+};
+export type ProcessAdapter = Readonly<{
+    platform: NodeJS.Platform;
+    startToken(pid: number): string | null;
+    processGroupId(pid: number): number | null;
+    linuxSessionId(pid: number): number | null;
+}>;
+export type VerifiedDetachedRuntime = Readonly<ProcessIdentity & {
+    receiptVersion: 4;
+    processGroupId: number;
+    linuxSessionId?: number;
+}>;
+export type DetachedRuntimeVerification = {
+    ok: true;
+    identity: VerifiedDetachedRuntime;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function parseProcStat(text: string): {
+    ppid: number;
+    processGroupId: number;
+    sessionId: number;
+    ticks: number;
+    startToken: string;
+    rssPages: number;
+};
+export declare function processStartToken(pid: number, procRoot?: string): string | null;
+export declare const hostProcessAdapter: ProcessAdapter;
+export declare function verifyDetachedRuntime(pid: number, receiptFile: string, adapter?: ProcessAdapter): DetachedRuntimeVerification;
+export declare function detachedRuntimeIsGone(pid: number, receiptFile: string, adapter?: ProcessAdapter): boolean;
+export declare function migrateLegacyDetachedRuntimeReceipt(pid: number, legacyScopeFile: string, receiptFile: string, adapter?: ProcessAdapter): boolean;
+export declare function writeDetachedRuntimeReceipt(pid: number, receiptFile: string, adapter?: ProcessAdapter): VerifiedDetachedRuntime;
+export declare const detachedRuntimeGenerationToken: (identity: VerifiedDetachedRuntime) => string;