spexcode 0.2.6 → 0.2.7

package/README.md

@@ -110,8 +110,10 @@ on the machine.
 spex new "make the settings page remember the last tab" --node settings
 ```
 
-launches a worker session in its own worktree on branch `node/settings`. The worker reads the
-governing spec before touching code, makes the change, rewrites the spec body to match, commits
+launches a worker session in its own worktree on branch `node/settings-…`. The `--node` flag (or a
+`[[settings]]` mention in the prompt, same effect) sets the branch name and board attribution; the
+worker still finds and reads the governing spec itself before touching code. It makes the change,
+rewrites the spec body to match, commits
 both (a hook stamps the `Session:` trailer), then proposes a merge and stops. Workers never merge
 themselves. The merge stays with the manager: when you fire it, the session's own agent runs the
 actual `git merge`, so conflicts land on the one who knows the work. The same dispatch is a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/src/cli.ts

@@ -510,7 +510,15 @@ if (cmd === 'serve') {
   }))
   if ('reached' in r) { console.log(r.reached); process.exit(0) }
   if ('gone' in r) { console.error(`spex wait: no such (living) session ${id}`); process.exit(2) }
-  if ('backendDown' in r) { console.error(`spex wait: ${r.backendDown}`); process.exit(1) }   // fail loud, not a false timeout
+  // a backend failure is a verdict about the TRANSPORT, never the session ([[graph]], issue #40): it prints
+  // its own outcome token on stdout — a word OUTSIDE the session-status vocabulary, so a supervisor reading
+  // the one status line can never mistake "I could not reach the board" for "the session is offline" — and
+  // exits 3, distinct from the plain no-actionable-status timeout (1) and the vanished target (2).
+  if ('backendDown' in r) {
+    console.error(`spex wait: ${r.backendDown}`)
+    console.log(r.kind === 'unreachable' ? 'backend-unreachable' : 'backend-error')
+    process.exit(3)
+  }
   console.error(`spex wait: timeout — ${id} did not reach an actionable status within ${timeoutSec}s`)
   process.exit(1)
 } else if (cmd === 'new') {

package/spec-cli/src/guide.ts

@@ -176,7 +176,7 @@ reading (\`--last\` makes that explicit; repeat to peel junk back one filing at
 
 THE SCOREBOARD: readings live in yatsu.evals.ndjson beside the yatsu.md — one JSON line per measurement
 (a second git-as-database axis). Freshness is derived live from git: a reading goes STALE when a governed
-code file, the scenario (the yatsu.md), or the evaluator moves since it was filed.
+code file or the scenario (the yatsu.md) moves since it was filed.
   spex yatsu scan [--changed]   blind spots: yatsu-schema (malformed) · yatsu-drift (stale) ·
                                 yatsu-missing (never measured) · yatsu-uncovered (governed source, no yatsu.md) ·
                                 yatsu-owners (a file governed by > maxOwners scenarios — split it)
@@ -326,21 +326,16 @@ Example — govern your own source dir and loosen the altitude budget:
               { "plugin": "<folder>" } bundle. Default (omitted): all native harnesses. PERSISTENT and
               git-transactional: the edit takes effect at the next git-native materialize anchor (the commit
               that carries it, a checkout/merge that receives it, or a manual \`spex materialize\`) — a
-              deselected harness's artifacts are pruned by that pass.
-  render      RETIRED (the old three-word footprint vote) — ignored with a loud notice. Materialized
-              artifacts are never tracked; there is exactly one residence behavior. Remove the field.
-              \`spex guide footprint\`.
-  private     RETIRED (old private-overlay toggle) — ignored with a loud notice, same as \`render\`; its
-              data-untrack semantics are gone. See \`spex guide footprint\` MIGRATIONS.`
+              deselected harness's artifacts are pruned by that pass.`
 
-const FOOTPRINT = `spex guide footprint — what SpexCode plants in a repo, and who sees it (no vote — one behavior)
+const FOOTPRINT = `spex guide footprint — what SpexCode plants in a repo, and who sees it (one fixed behavior per kind)
 
 SpexCode claims software engineering's HEAD (the recording of intent) and TAIL (the storage of
 measurement) and leaves the MIDDLE — construction — to the harness/agent/test framework; freshness
 stitches the two ends into a closed loop. The footprint follows: the head+tail (.spec, spexcode.json,
 readings) is the ASSET and lives in git like source; everything else is derived wiring or a machine fact.
-Materialized artifacts carry no facts, so they are NEVER tracked — the old render vote is retired; there
-is exactly one residence behavior, decided per KIND (and, for a contract file, by its live CONTENT).
+Materialized artifacts carry no facts, so they are NEVER tracked — there is exactly one residence
+behavior, decided per KIND (and, for a contract file, by its live CONTENT).
 
 ── THE FOUR KINDS (all fixed) ──
   spec data       .spec/ (incl .config/) + spexcode.json — ALWAYS tracked. Git is the database; there is
@@ -377,7 +372,7 @@ TRACK ≠ PUSH: none of this ever touches remotes; where commits GO is branch/re
 ── GUARANTEES (the forgetting law) ──
 materialize(P₂) ∘ materialize(P₁) = materialize(P₂): every materialize first ERASES all landing points by
 SpexCode's own identity stamps, then re-asserts — legacy states (a .gitignore managed block, a committed
-artifact, the retired vote's homes) are forgotten by the same pass. \`spex uninstall\` is the empty
+artifact) are forgotten by the same pass. \`spex uninstall\` is the empty
 materialize plus the global store: a total backout that never touches your .spec/.config or prose. Fresh
 clones and session worktrees are self-sufficient: data by checkout, materialized artifacts by
 re-materialize, the machine snapshot (spexcode.local.json) by copy.
@@ -389,12 +384,24 @@ the sentinel block (history never sees it); smudge re-injects it on checkout. A
 identity (never a git fatal). Your own edits to the prose still show as real modifications; only the
 block is invisible to git.
 
+── PRIVATE LOCAL NODES (manual posture — works today) ──
+Spec data is always tracked, but tracked WHERE is yours to choose: to keep a node off the shared
+remote, give it a different git HOME instead of untracking it. The manual recipe:
+  1. create the node dir under .spec/ as usual (spec.md and friends);
+  2. add the dir's path to .git/info/exclude — per-clone, so the shared repo never sees it;
+  3. inside the dir, \`git init --separate-git-dir\` pointing somewhere under the main repo's .git/
+     (e.g. .git/spexcode/<name>.git) — the dir then holds only a one-line .git pointer file, so the
+     spec loader never walks an object store;
+  4. commit the node's changes through that inner repo.
+The effect, honestly: filesystem-derived surfaces see the node (board, search, lint); git-derived
+views are blind to it (version count, the history tab, drift), and a dispatched worker's worktree
+checkout does not contain it. Those gaps are what the pending spec-local design (a first-class
+private overlay root) closes — not built yet. Cautions: \`git clean -fdx\` in the outer repo deletes
+the inner repo along with the dir, so off-machine backup means giving the INNER repo its own private
+remote; and taking the node public later is a migration (move it into the shared tree and commit),
+not a flag flip.
+
 ── MIGRATIONS ──
-  render: "..." (retired)   remove the field from spexcode.json / spexcode.local.json — it is ignored
-                            with a loud notice. A previously COMMITTED artifact heals at your next commit
-                            touching it (pre-commit strips the block from the staged blob); or run
-                            \`spex materialize\` + commit the block's removal once.
-  private: true (retired)   same — remove it; its data-untrack semantics are long gone.
   legacy untracked spec     track the sources once:  git add .spec spexcode.json  (commit on your branch)
                             WARNING: tracking is not retroactive secrecy — history already pushed
                             elsewhere cannot be recalled.

package/spec-cli/src/harness.ts

@@ -179,24 +179,33 @@ export const rvSock = (id: string) => join(tmpdir(), `spexcode-rv-${id}.sock`)
 // A crashed/killed claude can leave its rvSock FILE on disk (a unix-domain socket path is NOT auto-unlinked on
 // an unclean exit), so the old `existsSync(rvSock)` read a DEAD pane as `online` for as long as the stale file
 // lingered — the incident's "dead pane stuck `working` for 30+ min". The honest signal is a live LISTENER:
-// connect() to the socket. A real claude is accepting → connects; a stale file → ECONNREFUSED (instant); an
-// absent file → ENOENT (instant). So the common cases cost no waiting; the short timeout only bounds the
-// pathological file-present-but-listener-wedged case (then treated as not-live). Never throws.
-export function rendezvousListening(id: string, timeoutMs = 800): Promise<boolean> {
+// connect() to the socket. The verdict is TRI-STATE, because only two probe results actually PROVE anything:
+//   'live'  — the connect completed: a real claude is accepting.
+//   'dead'  — ECONNREFUSED (a stale file nothing listens on) / ENOENT (no file): death PROVEN, instantly.
+//   'unproven' — the probe itself failed to conclude: a TIMEOUT (under load the prober's event loop fires the
+//     expired timer before the pending connect event — the thrashed-backend incident where every live worker
+//     read offline in one board answer), or EAGAIN (the listen backlog is FULL, which proves a listener is
+//     alive-but-busy, the opposite of dead). Collapsing these into 'dead' is how a load spike masqueraded as
+//     a graveyard (issue #40); the caller must render unproven death as `unknown`, never `offline`.
+// The common cases cost no waiting (connect/refuse/absent are instant); the short timeout only bounds the
+// wedged/thrashed path. Never throws.
+export type ListenerProbe = 'live' | 'dead' | 'unproven'
+const PROVEN_DEAD = new Set(['ECONNREFUSED', 'ENOENT'])
+export function rendezvousListening(id: string, timeoutMs = 800): Promise<ListenerProbe> {
   return new Promise((resolve) => {
     let settled = false
     let c: ReturnType<typeof createConnection> | undefined
-    const done = (v: boolean) => {
+    const done = (v: ListenerProbe) => {
       if (settled) return
       settled = true
       clearTimeout(timer)
       try { c?.destroy() } catch { /* */ }
       resolve(v)
     }
-    const timer = setTimeout(() => done(false), timeoutMs)
-    try { c = createConnection({ path: rvSock(id) }) } catch { return done(false) }
-    c.on('connect', () => done(true))
-    c.on('error', () => done(false))   // ECONNREFUSED (stale file) / ENOENT (gone) — both mean no live agent
+    const timer = setTimeout(() => done('unproven'), timeoutMs)
+    try { c = createConnection({ path: rvSock(id) }) } catch { return done('unproven') }
+    c.on('connect', () => done('live'))
+    c.on('error', (e) => done(PROVEN_DEAD.has((e as NodeJS.ErrnoException).code ?? '') ? 'dead' : 'unproven'))
   })
 }
 // The app-server Unix socket MUST live on a SHORT, sun_path-safe path — NOT nested under the project runtime

package/spec-cli/src/help.ts

@@ -187,6 +187,9 @@ a node/<id> branch links its PR for free). Read-only — git/.spec stays the sin
 
 Creates a session: node branch + worktree + a launched agent carrying your prompt (= session new).
 Give it ONLY its task — the dev-flow contract reaches it through the materialized system prompt.
+--node <id> (or the prompt's first [[id]] mention, same effect) binds the session to that node:
+branch name node/<id>-<shortid>, board attribution, and one appended line with the node's spec.md
+path when the node exists. With neither, the session is bound to no node.
 --prompt-file <path> reads the prompt from a file (- = stdin), so a long multi-paragraph prompt never
 fights shell quoting; it is exclusive with the inline prompt (both given = error), and an unreadable
 or empty file refuses the launch.
@@ -319,7 +322,7 @@ ${ROUTING_NOTE}`,
 Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .config plugins), plants
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
 shims). Additive — never overwrites your files. --preset picks the .config plugin tier (cumulative).
-Footprint needs no vote: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
+Footprint is fixed: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
 a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex guide footprint).`,
     see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex lint (adoption TODO)',
   },

package/spec-cli/src/sessions.ts

@@ -334,10 +334,13 @@ async function procSnapshot(): Promise<ProcTable> {
 }
 // @@@ LiveSnap - the ONE liveness snapshot the whole session list shares. `windows` = our live tmux windows
 // (id → PaneProbe) + one whole-box process table; `sockets` = the ids whose rendezvous socket has a LIVE
-// LISTENER (connect-probed once here, not the file-exists lie — [[harness-adapter]]); `probeFailed` = the tmux
-// window probe itself FAILED (timed out under load), which is DISTINCT from "tmux up, no sessions" — the former
-// means death is UNPROVEN so those rows read `unknown`, the latter is authoritative and reads `offline`.
-export type LiveSnap = { probeFailed: boolean; windows: Map<string, PaneProbe>; sockets: Set<string> }
+// LISTENER (connect-probed once here, not the file-exists lie — [[harness-adapter]]); `unproven` = the ids whose
+// LISTENER probe could not conclude (timeout under load / EAGAIN off a full-but-alive backlog — see
+// rendezvousListening's tri-state) — death UNPROVEN, so those rows read `unknown`, never `offline`;
+// `probeFailed` = the tmux window probe itself FAILED (timed out under load), which is DISTINCT from "tmux up,
+// no sessions" — the former means death is UNPROVEN so those rows read `unknown`, the latter is authoritative
+// and reads `offline`.
+export type LiveSnap = { probeFailed: boolean; windows: Map<string, PaneProbe>; sockets: Set<string>; unproven: Set<string> }
 async function liveSnapshot(): Promise<LiveSnap> {
   const windows = new Map<string, PaneProbe>()
   let out: string
@@ -346,7 +349,7 @@ async function liveSnapshot(): Promise<LiveSnap> {
   } catch (e) {
     // a TIMEOUT/kill is a probe FAILURE (we can't tell who's alive → unknown, never a false graveyard). A clean
     // non-zero exit ("no server running" — genuinely zero sessions) is authoritative → the empty map = offline.
-    return { probeFailed: probeTimedOut(e), windows, sockets: new Set() }
+    return { probeFailed: probeTimedOut(e), windows, sockets: new Set(), unproven: new Set() }
   }
   const procs = await procSnapshot().catch(() => undefined)   // codex-only, auxiliary; its failure isn't a liveness failure
   for (const line of out.split('\n')) {
@@ -356,12 +359,19 @@ async function liveSnapshot(): Promise<LiveSnap> {
     windows.set(name, { panePid: Number.isFinite(pid) && pid > 0 ? pid : undefined, procs })
   }
   // LISTENER probe for every windowed session, once, in parallel (tooth: a live listener, not a lingering
-  // socket file). A codex session has no rvSock → instant ENOENT → not in the set, and codex ignores it anyway.
+  // socket file). A codex session has no rvSock → instant ENOENT → proven dead for the socket axis (codex
+  // ignores it anyway). The tri-state matters here: 'unproven' (timeout/EAGAIN — a wedged or thrashed but
+  // possibly-alive listener) lands in `unproven`, never silently in the not-live bucket, so liveness() can
+  // render it `unknown` instead of a false `offline` (issue #40's load-spike graveyard).
   const ids = [...windows.keys()]
   const listening = await Promise.all(ids.map((id) => rendezvousListening(id)))
   const sockets = new Set<string>()
-  ids.forEach((id, i) => { if (listening[i]) sockets.add(id) })
-  return { probeFailed: false, windows, sockets }
+  const unproven = new Set<string>()
+  ids.forEach((id, i) => {
+    if (listening[i] === 'live') sockets.add(id)
+    else if (listening[i] === 'unproven') unproven.add(id)
+  })
+  return { probeFailed: false, windows, sockets, unproven }
 }
 
 // @@@ paneTitles - every session pane's RAW tmux title, free from tmux. The worker launches one pane per
@@ -389,10 +399,11 @@ async function paneTitles(): Promise<Map<string, string>> {
 // dashboard waiting for its slow cold-path fallback. Sorted so it only moves on a real change.
 export async function sessionSignature(): Promise<string> {
   const [snap, titles] = await Promise.all([liveSnapshot(), paneTitles()])
-  // fold in probe-failure and the live-listener set so a socket dying (claude exit) OR the probe flipping to
-  // unknown pushes a board-changed immediately, not only on window churn.
+  // fold in probe-failure, the live-listener set AND the unproven set so a socket dying (claude exit), the
+  // probe flipping to unknown, or a listener wedging (unproven) pushes a board-changed immediately, not only
+  // on window churn.
   return (snap.probeFailed ? 'PROBEFAIL|' : '') + [...snap.windows.keys()].sort().join(',') + '#' +
-    [...snap.sockets].sort().join(',') + '|' + [...titles].sort().map(([k, v]) => `${k}=${v}`).join(',')
+    [...snap.sockets].sort().join(',') + '~' + [...snap.unproven].sort().join(',') + '|' + [...titles].sort().map(([k, v]) => `${k}=${v}`).join(',')
 }
 
 // @@@ paneActivity - the harness-aware live self-summary: the SINGLE place a raw pane title becomes (or does
@@ -463,6 +474,10 @@ export function liveness(rec: SessRec, snap: LiveSnap): Liveness {
   // online-signal hasn't appeared yet reads 'starting' for the boot window, only past it 'offline'.
   const h = harnessById(rec.harness || defaultHarness.id)
   if (h.liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online') return 'online'
+  // not provably online — but if this session's LISTENER probe couldn't conclude (timeout under load / EAGAIN
+  // off a full-but-alive backlog), death is UNPROVEN: `unknown`, never a false `offline` a supervisor would
+  // act on (issue #40 — a wedged-but-alive worker must not read as an actionable corpse).
+  if (snap.unproven.has(rec.session)) return 'unknown'
   const at = launchedAt.get(rec.session)
   return at && Date.now() - at < BOOT_GRACE_MS ? 'starting' : 'offline'
 }
@@ -1647,8 +1662,12 @@ export type WatchOpts = { source: () => Promise<Session[]>; selectors?: string[]
 // "block for a worker, then exit" that is GUARANTEED to return. The deadline is checked EVERY poll, before
 // EVERY sleep (and even when a poll throws), so a target stuck in ANY non-actionable state
 // (`working`/`parked`/`idle`/`queued`/`starting`) can never hang the caller — it exits at the deadline.
-// `reached` = the target hit an actionable status; the rest are the loud exits.
-export type WatchOutcome = { reached: DisplayStatus } | { timedOut: true } | { gone: true } | { backendDown: string }
+// `reached` = the target hit an actionable status; the rest are the loud exits. `backendDown` is a verdict
+// about the TRANSPORT, never the session — `kind` keeps its two shapes distinct for the caller's outcome
+// surface: 'unreachable' (nothing listening, the whole timeout was spent retrying) vs 'http' (reachable but
+// broken, failed loud at once). The caller must surface these OUTSIDE the session-status vocabulary — a
+// supervisor must never be able to read a transport failure as a session state (issue #40).
+export type WatchOutcome = { reached: DisplayStatus } | { timedOut: true } | { gone: true } | { backendDown: string; kind: 'unreachable' | 'http' }
 export async function watchSessions(emit: (line: string) => void, opts: WatchOpts): Promise<WatchOutcome> {
   const { source, selectors = [], statuses, includeIdle = false, intervalMs = 5000, as, until } = opts
   const tag = as ? `[${as}] ` : ''
@@ -1702,7 +1721,7 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
       //    is rebooting its hot-reloaded child behind the stable port on a sibling merge. This is TRANSIENT:
       //    record it, warn ONCE, and keep polling — the deadline (below) is the only hard wall, so a
       //    backgrounded `spex wait` survives the ~1s restart instead of dying on the interrupted fetch.
-      if (until && isBackendDown(e) && !isBackendUnreachable(e)) return { backendDown: (e as Error).message }
+      if (until && isBackendDown(e) && !isBackendUnreachable(e)) return { backendDown: (e as Error).message, kind: 'http' }
       if (isBackendDown(e)) {
         downMsg = (e as Error).message
         if (!warnedDown) { warnedDown = true; console.error(`${tag}[spex] watch: ${downMsg}; retrying every ${intervalMs / 1000}s…`) }
@@ -1712,7 +1731,7 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
     // guarantees `spex wait` can never hang on a worker stuck outside WATCH_ACTIONABLE — nor spin forever on a
     // backend that never comes back. Hitting the deadline while still unreachable reports THAT (`backendDown`),
     // not a false "no actionable status" timeout, so the manager sees the honest cause.
-    if (until && Date.now() >= deadline) return downMsg ? { backendDown: downMsg } : { timedOut: true }
+    if (until && Date.now() >= deadline) return downMsg ? { backendDown: downMsg, kind: 'unreachable' } : { timedOut: true }
     await sleep(intervalMs)
   }
 }

package/spec-cli/templates/spec/project/.config/supervisor/spec.md

@@ -5,4 +5,4 @@ status: active
 hue: 280
 desc: Launch a supervisor agent that manages other agents from the main checkout to drive a goal to completion.
 ---
-You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. **FIRST, read `<root>/CLAUDE.md` — specifically its "Supervising — the manager loop" section** — that is your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize). Then drive the goal: decompose it into spec-node tasks and dispatch one worker per independent task (`spex new "<task>" --node <id>` — give each ONLY its task), monitor with `spex watch`, review proposals with `spex review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex review <id>` or `spex ls` — both return immediately); never block on `spex watch`, which STREAMS forever and will freeze your turn. One footgun that bites a fresh supervisor: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Report progress as you go and when the goal is complete. Your goal follows:
+You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. **FIRST, read `<root>/CLAUDE.md` — specifically its "Supervising — the manager loop" section** — that is your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize). Then drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex new "<task>"` — give each ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), monitor with `spex watch`, review proposals with `spex review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex review <id>` or `spex ls` — both return immediately); never block on `spex watch`, which STREAMS forever and will freeze your turn. One footgun that bites a fresh supervisor: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Report progress as you go and when the goal is complete. Your goal follows: