spexcode 0.2.2 → 0.2.4

package/README.md

@@ -1,19 +1,34 @@
-<img src="docs/sdd-tuxedo-pooh.png" alt="tuxedo pooh meme" width="420">
+<div align="center">
 
-# SpexCode
+<img src="docs/banner.png" alt="SpexCode" width="720">
+
+<p>
+  <a href="https://www.npmjs.com/package/spexcode"><img alt="npm" src="https://img.shields.io/npm/v/spexcode?logo=npm&logoColor=white&color=cb3837"></a>
+  <img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-2f81f7">
+  <img alt="node &ge; 22" src="https://img.shields.io/badge/node-%E2%89%A5%2022-3fb950?logo=nodedotjs&logoColor=white">
+  <a href="https://spexcode.net"><img alt="docs" src="https://img.shields.io/badge/docs-spexcode.net-8957e5"></a>
+</p>
+
+</div>
 
 Spec-driven development with AI agents in the loop. SpexCode keeps a versioned tree of specs inside
 your git repo, links every spec to the code it governs, and runs a session manager that dispatches
 coding agents into isolated worktrees. You review and merge; the tool keeps intent and
-implementation from drifting apart. (All screenshots below are this very repo on its own board.)
+implementation from drifting apart.
+
+[![Watch: this repo's spec tree grow from its git history](docs/spec-tree-poster.jpg)](https://spexcode.net/assets/spec-tree-growth.mp4)
 
-English | [中文](./README.zh-CN.md) · Docs: [spexcode.net](https://spexcode.net) · License: MIT
+<sub>▶ This repo's own spec tree, replayed from its git history — 160 spec nodes growing over three weeks. Click for the [full video](https://spexcode.net/assets/spec-tree-growth.mp4).</sub>
+
+English | [中文](./docs/README.zh-CN.md) · Docs: [spexcode.net](https://spexcode.net) · License: MIT
 
 Quick links: [the model](#the-model) · [quick start](#quick-start) ·
 [agents](#working-with-agents) · [yatsu](#measuring-behavior-yatsu) · [config](#configuration)
 
 ## The model
 
+<div align="center"><img src="docs/sdd-tuxedo-pooh.png" alt="spec-driven development meme" width="260"></div>
+
 A spec node is a directory under `.spec/` containing a `spec.md`: frontmatter (title, status, a
 `code:` list of the files it governs) plus a prose body stating what that part of the system is
 supposed to do, right now. Nodes nest, so the tree mirrors how you think about the project rather
@@ -123,7 +138,10 @@ prompt stays task-only. More on this mode of working:
 
 ## Measuring behavior: yatsu
 
-yatsu is the measuring half of [the loop](#the-optimization-loop). A spec says what a part should do; a
+yatsu — short for **You As The Stupid User** — is the measuring half of
+[the loop](#the-optimization-loop): you measure behavior from the product's real surface, the way a
+clueless real end user would touch it, not through an internal helper or shortcut that makes the
+proof easy. A spec says what a part should do; a
 `yatsu.md` beside it says how to check. Each scenario is a plain description plus an expected
 result. yatsu itself runs nothing (no DSL, no runner). An agent runs the scenario however it can:
 a test file, a real browser, or just clicking through by hand and screenshotting. It compares
@@ -172,23 +190,16 @@ to), and `spex guide config` documents every field. The other
 manuals are `spex guide` (the workflow), `spex guide spec`, and `spex guide yatsu`; `spex help`
 maps the commands.
 
-## Status
-
-SpexCode develops itself with itself: the `.spec/` tree in this repo is the tool's own spec, and
-every change to the tool lands through the same worker/manager loop it implements. The dashboard
-you install is the one it was built on. Known warts: `spex session new --help`
-doesn't print help, it creates a session named `--help` (dispatch with `spex new`). And the
-altitude lint currently reports forty-odd warnings against this repo's own specs; I haven't had
-time to pay that down.
-The first public write-up was posted on the [LINUX DO](https://linux.do) community — thanks for
-the first round of discussion there.
-
 ## Contributing
 
 [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) gets you from a clone to a first merged change.
 [`docs/AGENT_GUIDE.md`](docs/AGENT_GUIDE.md) has the full mechanics of the node model and the
 reflexive config system.
 
+## Credit
+
+First introduced on the [LINUX DO](https://linux.do) community — thanks to everyone there for the first round of discussion.
+
 ## License
 
 [MIT](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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

@@ -122,11 +122,12 @@ async function withWatchEdge<T>(selectors: string[], intervalMs: number, body: (
 async function resolveSelectorOrExit(selector: string): Promise<string> {
   if (!selector) { console.error('spex: missing session selector (id | id-prefix | node | branch)'); process.exit(2) }
   const { resolveClientSession } = await import('./client.js')
+  const { sessionLabel } = await import('./sessions.js')
   const r = await resolveClientSession(selector)
   if ('ok' in r) return r.ok.id
   if ('none' in r) { console.error(`spex: no such session: ${selector}`); process.exit(2) }
   console.error(`spex: ambiguous selector "${selector}" matches ${r.ambiguous.length} sessions — be more specific:`)
-  for (const s of r.ambiguous) console.error(`  ${s.id.slice(0, 8)}  ${s.node || s.branch || s.id}`)
+  for (const s of r.ambiguous) console.error(`  ${s.id.slice(0, 8)}  ${sessionLabel(s)}`)
   process.exit(2)
 }
 
@@ -342,7 +343,7 @@ if (cmd === 'serve') {
   if (has('json')) { console.log(JSON.stringify(r, null, 2)) }
   else {
     const g = r.gates
-    console.log(`review ${r.node || r.branch || r.id}  [${r.id}]`)
+    console.log(`review ${r.label}  [${r.id}]`)
     console.log(`  ahead of main : ${r.ahead} commit(s)`)
     console.log(`  uncommitted   : ${r.dirtyNonRuntime} non-runtime file(s)`)
     console.log(`  proposal      : ${r.proposal.kind ?? '—'}${r.proposal.note ? ` — ${r.proposal.note}` : ''}`)

package/spec-cli/src/guide.ts

@@ -94,9 +94,10 @@ before merge. \`spex init\` seeds the first tree; \`spex guide yatsu\` covers th
 const YATSU = `spex guide yatsu — the yatsu.md file format
 
 A yatsu.md sits BESIDE a node's spec.md and says how to MEASURE the node's loss — the gap between live
-behaviour and the spec. It is optional, but a FRONTEND node (its code: includes a UI file —
-.jsx/.tsx/.vue/.svelte/.css, or the dashboard) with no yatsu.md is a blind spot: \`spex yatsu scan\` flags
-it \`yatsu-uncovered\`. yatsu defines no DSL and RUNS NOTHING — the agent measures; yatsu keeps score.
+behaviour and the spec. It is optional, but a node that governs SOURCE code (its code: includes a file whose extension is in
+\`lint.sourceExtensions\` — default .ts/.tsx/.js/.jsx, set it for a Rust/Go/Python tree) with no yatsu.md is
+a blind spot: \`spex yatsu scan\` flags it \`yatsu-uncovered\`. yatsu defines no DSL and RUNS NOTHING — the
+agent measures; yatsu keeps score.
 
 FRONTMATTER: a \`scenarios:\` list (a YAML block sequence of mappings). Each scenario:
   name         REQUIRED. Unique within the file — it keys the sidecar and \`--scenario <name>\`.
@@ -138,22 +139,26 @@ PICK THE EVIDENCE KIND BY WHAT THE BEHAVIOUR DOES OVER TIME:
                       playback, a multi-step interaction flow, keyboard timing — a still of a moving thing
                       proves the wrong thing; RECORD the run (e.g. playwright \`recordVideo\` on the context).
                       STEP EVIDENCE gets a STEP-MAP: when the evidence unfolds in steps, carry named steps
-                      anchored to the evidence's OWN axis, EXPORTED BY THE RUN that produced it — never a
-                      value the agent eyeballs off the finished artefact afterwards (that's misaligned and
-                      dishonest, worse than none). The axis is the evidence's: a video's is TIME. Today's
-                      \`--timeline <json>\` implements exactly that time axis, so a multi-step VIDEO carries one
-                      (skip it for a short single-action clip); copy this shape:
-                        { "v": 1, "events": [ { "tMs": 0, "step": "open board" },
-                                              { "tMs": 1200, "step": "type query" } ] }
-                      \`tMs\` = ms from video start, \`step\` = a short name for that moment. The run exports it:
-                      in whatever drives the recording — Playwright is ONE example, equally a computer-use hand
-                      or any UI-automation/screenshot script — take \`start\` when recording opens and at EACH
-                      real action push \`{ tMs: now - start, step: "…" }\`; dump that array as \`--timeline\`.
-                      (Non-time-axis step evidence — a screenshot SEQUENCE by frame index, a CLI transcript by
-                      line — is the same idea on a different axis, but the schema is tMs-only for now; see the
-                      open issue to generalize \`tMs\` → \`position\`. Don't force a non-time axis into \`tMs\`.)
+                      anchored to a POSITION on the evidence's OWN axis, EXPORTED BY THE RUN that produced it
+                      — never a value the agent eyeballs off the finished artefact afterwards (that's
+                      misaligned and dishonest, worse than none). \`--timeline <json>\` carries one; its \`axis\`
+                      is the evidence's: a video is \`time\` (ms), a transcript \`line\`, a still SEQUENCE \`frame\`,
+                      an action trace \`index\` (the set is OPEN — an unknown axis just renders as a bare number).
+                      \`at\` = the position on that axis, \`step\` = a short name for that moment; copy this shape:
+                        { "v": 2, "axis": "time",
+                          "events": [ { "at": 0, "step": "open board" },
+                                      { "at": 1200, "step": "type query" } ] }
+                      The run exports it: in whatever drives the evidence — Playwright, a computer-use hand, a
+                      CLI harness stamping line numbers — take a baseline and at EACH real step push
+                      \`{ at: <position>, step: "…" }\`; dump that array as \`--timeline\`. Its \`axis\` MUST match the
+                      evidence it rides (a \`line\` map needs a \`--result\` transcript, a \`time\` map a \`--video\`);
+                      skip it for a short single-step artefact. (Legacy \`{ "v": 1, "events": [{ "tMs" }] }\` — the
+                      time axis with \`tMs\` — is still accepted, read as \`axis: "time"\`.)
   STATIC end state  → \`--image <png>\` (repeatable — N stills). Layout, an icon, copy, one rendered frame.
-  backend / CLI     → \`--result <txt>\` (a transcript; \`-\` reads stdin).
+  backend / CLI     → \`--result <txt>\` (a transcript; \`-\` reads stdin). A STRUCTURED export (a JSON
+                      \`--export-json\`, an API payload, a metrics dump) is recognized BY CONTENT and kept as
+                      \`data\` — rendered as a validatable data block, not flattened into scrolling transcript
+                      text; free-form output stays a transcript. You pick the flag; the KIND follows the bytes.
 The flags combine in ONE filing — several stills can ride beside the clip of the same run.
 ANCHOR DISCIPLINE: a reading's \`codeSha\` is HEAD at filing time, and a git sha names only a COMMIT — an
 uncommitted change has none. So measure the tree you are about to commit, COMMIT it, then file; confidence
@@ -171,7 +176,7 @@ THE SCOREBOARD: readings live in yatsu.evals.ndjson beside the yatsu.md — one
 (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.
   spex yatsu scan [--changed]   blind spots: yatsu-schema (malformed) · yatsu-drift (stale) ·
-                                yatsu-missing (never measured) · yatsu-uncovered (frontend, no yatsu.md) ·
+                                yatsu-missing (never measured) · yatsu-uncovered (governed source, no yatsu.md) ·
                                 yatsu-owners (a file governed by > maxOwners scenarios — split it)
   spex yatsu show <node>        the reading timeline (verdict · freshness · evidence), newest first
   spex yatsu clean              GC the content-addressed evidence cache`
@@ -186,8 +191,8 @@ PORTABILITY, and picking the right one is the whole discipline:
                         identity, lint budgets, launcher NAMES. "Git is the database": tracked so the
                         team shares ONE configuration.
   spexcode.local.json   GITIGNORED — host-specific, never committed. Absolute launcher paths, cert/secret
-                        paths, private-overlay mode. Layered OVER spexcode.json (see MERGE below); an env
-                        var (SPEXCODE_CLAUDE_CMD, …) still overrides both at its read site.
+                        paths, private-overlay mode. Layered OVER spexcode.json (see MERGE below); a
+                        targeted env override (SPEXCODE_CODEX_SERVER_CMD, …) still wins at its read site.
 
 Rule of thumb — is the value TRUE FOR THE PROJECT or TRUE FOR THIS MACHINE? A branch name, a dashboard
 icon, a lint budget, a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
@@ -222,23 +227,24 @@ Example:
                             Counts compute slots, not total sessions: idle/asking/review/done do not
                             occupy one. A policy number → committed spexcode.json; omit it to use the
                             default, or tune higher/lower for the project's usual host.
-  sessions.claudeCmd        command used by the built-in "claude" launcher (default
-                            'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides.
-  sessions.codexCmd         command used by the built-in "codex" launcher (default 'codex --yolo'); env
-                            SPEXCODE_CODEX_CMD overrides.
-  sessions.launchers        additional NAMED launcher profiles (see LAUNCHERS).
+  sessions.launchers        the NAMED launcher profiles (see LAUNCHERS). \`spex init\` seeds "claude" and
+                            "codex" here as ordinary entries; edit/add more like any other.
   sessions.defaultLauncher  the launcher name a create with no explicit --launcher/dropdown pick uses
                             (required for no-choice creates). A portable NAME → committed.
-A claudeCmd/codexCmd or a launcher \`cmd\` that is a HOST-SPECIFIC ABSOLUTE PATH belongs in
-spexcode.local.json — the committed file must stay free of machine paths.
+A launcher \`cmd\` that is a HOST-SPECIFIC ABSOLUTE PATH belongs in spexcode.local.json — the committed file
+must stay free of machine paths.
 
 ── LAUNCHERS (the profile block, split across the two files) ──
 A named launcher profile fixes BOTH a session's harness AND its exact launch command; a create picks one
 by name with --launcher/the dashboard dropdown, and the chosen name is persisted on the record so a resume
-reuses the same auth. Built-in profiles always exist:
-  "claude" → { "harness": "claude", "cmd": sessions.claudeCmd or SPEXCODE_CLAUDE_CMD }
-  "codex"  → { "harness": "codex",  "cmd": sessions.codexCmd or SPEXCODE_CODEX_CMD }
-Add more profiles when a project needs named auth/config-dir variants. Shape:
+reuses the same auth. There are NO magic built-ins: \`spex init\` SEEDS "claude" and "codex" as ordinary
+named launchers,
+  "claude" → { "harness": "claude", "cmd": "claude --dangerously-skip-permissions" }
+  "codex"  → { "harness": "codex",  "cmd": "codex --yolo" }
+after which they are edited (or removed) exactly like any launcher you add. To run workers under an auth
+wrapper (e.g. reclaude), point a launcher's \`cmd\` at it in spexcode.local.json — there is no environment
+override that rewrites a launcher's command. Add more profiles when a project needs named auth/config-dir
+variants. Shape:
   "launchers": { "<name>": { "harness": "claude" | "codex", "cmd": "<launch command>" } }
 \`harness\` defaults to "claude"; \`cmd\` is required. Because \`cmd\` is a machine fact (an abs wrapper path),
 the DEFINITION lives in the gitignored spexcode.local.json, while the portable defaultLauncher NAME sits

package/spec-cli/src/harness.ts

@@ -49,14 +49,15 @@ export interface Harness {
 
   // --- launch / sessionId ---
   // the base agent command. Claude: `claude …`; Codex starts a project-scoped app-server and launches the
-  // visible TUI with `--remote` pointed at it. `cmd`, when given, is the SESSION's persisted launcher command
-  // ([[launcher-select]]) and OVERRIDES the ambient env→config→default resolution — so a session created under a
-  // named launcher keeps that exact command (and auth) on resume, never silently reverting to the global
-  // default. Omitted is only for tests and old records before launch_cmd was pinned.
+  // visible TUI with `--remote` pointed at it. `cmd` is the SESSION's persisted launcher command
+  // ([[launcher-select]]) — the resolved `cmd` of the named launcher it was created under. A session always
+  // carries one (pinned at creation), so resume keeps that exact command (and auth), never reverting to a
+  // global default. Omitted is only for tests and old records before launch_cmd was pinned (→ the bare default).
   launchCmd(id: string, runtimeDir?: string, cmd?: string): string
   // the RESOLVED base launcher command alone — the wrapper/binary that carries the agent's config-dir env
   // (claude `CLAUDE_CONFIG_DIR`, codex `CODEX_HOME`), WITHOUT the per-launch script built around it. `cmd`,
-  // when given, wins; else the ambient env→config→default resolution. The launch owner PINS this on the record
+  // when given (the named launcher's `cmd`), IS the answer; else the harness's bare built-in default — there is
+  // no env/config-field resolution (claude/codex are ordinary named launchers). The launch owner PINS this on the record
   // at creation so a resume replays the EXACT launcher that created the conversation — never re-resolving
   // against a since-changed default, which would point `--resume` at the wrong config dir and lose the
   // transcript ([[launcher-select]], the resume-launcher-pin). launchCmd builds its invocation ON TOP of this.
@@ -359,7 +360,7 @@ export function codexSupportsBypassHookTrust(binary: string): boolean {
   bypassProbe.set(binary, ok)
   return ok
 }
-export function codexLaunchCommand(_id: string, codexCmd = process.env.SPEXCODE_CODEX_CMD || 'codex --yolo', serverCmd?: string, dir = runtimeRoot()): string {
+export function codexLaunchCommand(_id: string, codexCmd = 'codex --yolo', serverCmd?: string, dir = runtimeRoot()): string {
   const server = process.env.SPEXCODE_CODEX_SERVER_CMD || serverCmd || codexBinary(codexCmd)
   // The bypass flag ONLY reaches a thread's hook trust as a per-request `config` override, NOT as a CLI flag on
   // the shared `app-server` process (the app-server never reads its own `--dangerously-bypass-hook-trust` for a
@@ -934,9 +935,11 @@ const CLAUDE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostTo
 const CODEX_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'] as const
 
 // the resolved base launcher command per harness (the wrapper that sets the config-dir env), shared by
-// launchCmd and baseCmd so the two never diverge: `cmd` override wins, else ambient env→config→default.
-const claudeBaseCmd = (cmd?: string) => cmd || process.env.SPEXCODE_CLAUDE_CMD || readConfig(mainCheckout()).sessions?.claudeCmd || 'claude --dangerously-skip-permissions'
-const codexBaseCmd = (cmd?: string) => cmd || process.env.SPEXCODE_CODEX_CMD || readConfig(mainCheckout()).sessions?.codexCmd || 'codex --yolo'
+// launchCmd and baseCmd so the two never diverge: the launcher's pinned `cmd` wins. The bare default is only
+// the fallback for a truly-old record with NO pinned cmd and NO launcher name — there is no env/config-field
+// resolution, because claude/codex are ordinary named launchers now ([[launcher-select]]), resolved by name.
+const claudeBaseCmd = (cmd?: string) => cmd || 'claude --dangerously-skip-permissions'
+const codexBaseCmd = (cmd?: string) => cmd || 'codex --yolo'
 
 export const claudeHarness: Harness = {
   id: 'claude',
@@ -1043,36 +1046,28 @@ export function harnessById(id: string): Harness {
 
 // --- named launcher profiles ([[launcher-select]]) ----------------------------------------------------------
 // a launcher = a `{ harness, cmd }` pair in spexcode.json's `sessions.launchers`, keyed by a human-chosen name.
-// harness defaults to claude. resolveLauncher throws fail-loud on an unknown name (a session must never
-// silently launch under the wrong auth) and validates the harness id.
+// `claude` and `codex` are NOT special built-ins — `spex init` SEEDS them as ordinary named launchers (with the
+// regular command path), so they are edited like any other. harness defaults to claude. resolveLauncher throws
+// fail-loud on an unknown name (a session must never silently launch under the wrong auth) and validates the
+// harness id. There is NO env-derived built-in fallback: the dropdown lists exactly the config's real launchers.
 export type Launcher = { name: string; harness: string; cmd: string }
 export type LauncherDefault = { default: string | null; error: string | null }
 
-function builtinLauncher(name: string, root = mainCheckout()): Launcher | null {
-  const cfg = readConfig(root).sessions
-  if (name === 'claude') return { name: 'claude', harness: 'claude', cmd: process.env.SPEXCODE_CLAUDE_CMD || cfg?.claudeCmd || 'claude --dangerously-skip-permissions' }
-  if (name === 'codex') return { name: 'codex', harness: 'codex', cmd: process.env.SPEXCODE_CODEX_CMD || cfg?.codexCmd || 'codex --yolo' }
-  return null
-}
-
-// the configured launchers plus the built-in `claude`/`codex` profiles, as a stable name-sorted list (for the
-// dashboard dropdown + the CLI). There is always a launcher choice; the old separate harness pick is gone.
+// the configured named launchers from spexcode.json, as a stable name-sorted list (for the dashboard dropdown +
+// the CLI). Picking a launcher is the ONLY launch choice; the old separate harness pick is gone.
 export function launcherList(root = mainCheckout()): Launcher[] {
   const m = readConfig(root).sessions?.launchers || {}
-  const out = new Map<string, Launcher>([
-    ['claude', builtinLauncher('claude', root)!],
-    ['codex', builtinLauncher('codex', root)!],
-  ])
-  for (const name of Object.keys(m)) out.set(name, { name, harness: m[name].harness || defaultHarness.id, cmd: m[name].cmd })
-  return [...out.values()].sort((a, b) => a.name.localeCompare(b.name))
+  return Object.keys(m)
+    .map((name) => ({ name, harness: m[name].harness || defaultHarness.id, cmd: m[name].cmd }))
+    .sort((a, b) => a.name.localeCompare(b.name))
 }
 
 export const MISSING_DEFAULT_LAUNCHER_ERROR =
   'sessions.defaultLauncher is required for a launch without --launcher; set it in spexcode.json or spexcode.local.json (for example {"sessions":{"defaultLauncher":"claude"}})'
 
 // the configured default launcher NAME ([[launcher-select]]) — the profile `spex new`/a dropdown pick with no
-// explicit choice resolves. Missing config is a fail-loud setup error, never an implicit fallthrough to the
-// built-in `claude` launcher.
+// explicit choice resolves. Missing config is a fail-loud setup error, never an implicit fallthrough to a
+// `claude` launcher (which `spex init` seeds by name, so a default can point at it explicitly).
 export function defaultLauncher(root = mainCheckout()): string {
   const name = readConfig(root).sessions?.defaultLauncher?.trim()
   if (!name) throw new Error(MISSING_DEFAULT_LAUNCHER_ERROR)
@@ -1091,9 +1086,9 @@ export function launcherDefault(root = mainCheckout()): LauncherDefault {
 
 export function resolveLauncher(name: string, root = mainCheckout()): Launcher {
   const l = readConfig(root).sessions?.launchers?.[name]
-  if (l && !l.cmd) throw new Error(`launcher '${name}' is missing cmd`)
-  const resolved = l ? { name, harness: l.harness || defaultHarness.id, cmd: l.cmd } : builtinLauncher(name, root)
-  if (!resolved) throw new Error(`unknown launcher '${name}' (configured: ${launcherList(root).map((x) => x.name).join(', ') || 'none'})`)
+  if (!l) throw new Error(`unknown launcher '${name}' (configured: ${launcherList(root).map((x) => x.name).join(', ') || 'none'})`)
+  if (!l.cmd) throw new Error(`launcher '${name}' is missing cmd`)
+  const resolved = { name, harness: l.harness || defaultHarness.id, cmd: l.cmd }
   harnessById(resolved.harness)   // validate the harness id fail-loud
   return resolved
 }

package/spec-cli/src/help.ts

@@ -111,7 +111,7 @@ only the trailer. If the intent DID change, edit the spec instead — same commi
     line: 'yatsu <sub>           measure a node’s scenarios & file the loss signal: scan | eval | retract | show | clean',
     body: `Usage: spex yatsu scan [--changed]                       list nodes/scenarios missing readings
        spex yatsu eval [.|<node>] [--scenario <name>] (--pass|--fail) [--note <text>]
-                       [--image <png> …] [--result <path|->] [--video <webm|mp4> [--timeline <json>]]
+                       [--image <png> …] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
        spex yatsu retract [.|<node>] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
        spex yatsu show [.|<node>] [--json]              readings history for a node
        spex yatsu clean [--keep-latest | --all]         prune stored readings

package/spec-cli/src/layout.ts

@@ -27,8 +27,6 @@ type Config = {
   }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)
-    claudeCmd?: string             // the built-in `claude` launcher command (default 'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides. A host-specific ABS path belongs in the gitignored spexcode.local.json, not here.
-    codexCmd?: string              // the built-in `codex` launcher command (default 'codex --yolo'); env SPEXCODE_CODEX_CMD overrides. Same host-path rule.
     // named launcher profiles: a session picks ONE by name at create time ([[launcher-select]]), fixing both
     // its harness AND its exact launch command; the chosen NAME is persisted on the record so resume reuses the
     // same auth. `harness` defaults to 'claude'. Host-specific `cmd`s (abs wrapper paths) belong in the
@@ -78,7 +76,7 @@ export function readJsonConfig(p: string): any {
 // 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; an env var (e.g. SPEXCODE_CLAUDE_CMD) still overrides both at its read site.
+// local over committed; a targeted env override (e.g. SPEXCODE_CODEX_SERVER_CMD) still wins at its read site.
 export function readConfig(root: string): Config {
   const committed = readJsonConfig(join(root, 'spexcode.json'))
   const local = readJsonConfig(join(root, 'spexcode.local.json'))

package/spec-cli/src/lint.ts

@@ -32,9 +32,34 @@ export function loadConfig(root: string): LintConfig {
   // Absent spexcode.json → tuned defaults; a MALFORMED one throws LOUD (readJsonConfig) rather than
   // silently reverting the author's budgets to defaults and green-washing the very warnings they tuned.
   const c = readJsonConfig(join(root, 'spexcode.json'))?.lint ?? {}
-  return { ...DEFAULT_CONFIG, ...c, altitude: { ...DEFAULT_CONFIG.altitude, ...(c.altitude ?? {}) } }
+  const merged = { ...DEFAULT_CONFIG, ...c, altitude: { ...DEFAULT_CONFIG.altitude, ...(c.altitude ?? {}) } }
+  return normalizeConfig(merged)
 }
 
+// canonicalize two adopter-input footguns that would otherwise SILENTLY match ZERO files (the same failure
+// class as an unset governedRoots — a green board that governs nothing). Both are natural mistakes a non-web
+// adopter makes reading the prose, so we accept-what-they-meant rather than reject:
+//  - a LEADING DOT on an extension: the matcher is `\.(ext)$`, so a literal ".ts" becomes `\..ts$` and never
+//    matches. Strip leading dots → ["ts"] and [".ts"] both work (prose historically showed ".ts").
+//  - a testGlob with NO "/": globs anchor to the full repo-relative path, so a bare "*.test.ts" matches only
+//    ROOT-level files and leaks every nested test into coverage. A slash-less glob is a basename intent →
+//    prepend "**/" so it matches that basename at any depth (the default "**/*.test.*" already does).
+export function normalizeConfig(cfg: LintConfig): LintConfig {
+  const dedot = (xs: string[]) => xs.map((x) => x.replace(/^\.+/, ''))
+  return {
+    ...cfg,
+    sourceExtensions: dedot(cfg.sourceExtensions),
+    identifierExtensions: dedot(cfg.identifierExtensions),
+    testGlobs: cfg.testGlobs.map((g) => (g.includes('/') ? g : `**/${g}`)),
+  }
+}
+
+// the source-file matcher, built from the configurable `sourceExtensions` knob. Coverage uses it to decide
+// which tracked files must be governed; yatsu's `yatsu-uncovered` reuses THE SAME knob so ONE setting
+// defines "source" for both coverage axes — a non-web project (Rust/Go/Python .rs/.go/.py) sets it once and
+// both the coverage warning and the loss-signal blind-spot check follow, with no second web-only allowlist.
+export const sourceExtRe = (extensions: string[]) => new RegExp(`\\.(${extensions.join('|')})$`)
+
 // a minimal glob → RegExp anchored to the full repo-relative path: `**` = any dirs, `*` = within a segment.
 function globToRe(glob: string): RegExp {
   const body = glob.split(/(\*\*\/|\*\*|\*|\?)/).map((seg) => {
@@ -103,7 +128,7 @@ export async function specLint(): Promise<Finding[]> {
   const root = repoRoot()
   const cfg = loadConfig(root)
   const ident = identRe(cfg.identifierExtensions)
-  const srcRe = new RegExp(`\\.(${cfg.sourceExtensions.join('|')})$`)
+  const srcRe = sourceExtRe(cfg.sourceExtensions)
   const specs = await loadSpecs()
   const out: Finding[] = []
 
@@ -159,10 +184,14 @@ export async function specLint(): Promise<Finding[]> {
 
   // coverage: every governed source file must be claimed by at least one spec.
   const governed = trackedSourceFiles(root, cfg.governedRoots, srcRe, cfg.testGlobs)
-  // no governed source found at all → the defaults name this repo's own dirs, so an adopter who never set
-  // lint.governedRoots would otherwise see a falsely-clean board. Make it loud and point at the knob.
+  // no governed source found at all → make it a SELF-EXPLANATORY repair entrypoint, not a dead end. The two
+  // knobs governing this are BOTH web-tuned by default (extensions ts/tsx/js/jsx; roots this repo's own dirs),
+  // so a non-web adopter (Rust/Go/Python) hits zero source two ways: right dir but wrong extension, or an
+  // unset root. Naming BOTH knobs, echoing their CURRENT values (so the mismatch is visible — "searching .ts
+  // in a .py tree"), and stating the `lint`-key nesting (a top-level key silently no-ops) turns the warning
+  // into the fix. Concrete non-web extension examples so the repair is copy-pasteable, not a schema hunt.
   if (governed.length === 0)
-    out.push({ level: 'warn', rule: 'coverage', msg: `governing NOTHING — no source files under governedRoots [${cfg.governedRoots.join(', ')}]. Set lint.governedRoots in spexcode.json to your project's source dirs.` })
+    out.push({ level: 'warn', rule: 'coverage', msg: `governing NOTHING — 0 source files matched extensions [${cfg.sourceExtensions.join(', ')}] under governedRoots [${cfg.governedRoots.join(', ')}]. Both knobs live under the "lint" key in spexcode.json (a top-level key is ignored): set governedRoots to your source dir(s) (e.g. ["src"]) AND sourceExtensions to your language (e.g. ["rs"] / ["go"] / ["py"]).` })
   for (const f of governed)
     if (!claimed.has(f)) out.push({ level: 'warn', rule: 'coverage', file: f, msg: `no spec governs: ${f}` })
 

package/spec-cli/src/sessions.ts

@@ -4,6 +4,7 @@ import { randomUUID } from 'node:crypto'
 import { readFileSync, writeFileSync, appendFileSync, existsSync, renameSync, mkdirSync, rmSync, readdirSync, realpathSync, statSync } from 'node:fs'
 import { join, dirname, relative, isAbsolute } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { linkUntrackedSpecSources } from './worktree-sources.js'
 import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, type ReviewDiffFile } from './git.js'
 import { loadSpecs } from './specs.js'
 import { defaultHarness, defaultLauncher, harnessById, resolveLauncher, rvSock, rendezvousListening, type Harness, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
@@ -43,7 +44,8 @@ import { stripRefSigil } from './mentions.js'
 // deliberately does NOT touch it. `merges` is METADATA (how many times merged), shown as a badge, not a state.
 //
 // Launch rules (CLAUDE.md / memory): private `tmux -L <label>` socket + `--dangerously-skip-permissions`.
-// SPEXCODE_TMUX / SPEXCODE_CLAUDE_CMD override both for tests.
+// SPEXCODE_TMUX overrides the tmux socket for tests; the launch COMMAND comes from the session's pinned
+// launcher ([[launcher-select]]), not an env var.
 
 const pexec = promisify(execFile)
 export const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode'
@@ -1001,12 +1003,13 @@ export async function assertProjectMatch(verb: string): Promise<void> {
 }
 
 // @@@ createSession (dispatch via backend) - `spex new` / `spex session new` must launch the worker in the
-// BACKEND's process, not the caller's. The backend owns the launch env (notably SPEXCODE_CLAUDE_CMD, which
-// reclaude strips from agent envs) AND the concurrency cap. An agent that runs `spex new` (e.g. a supervisor)
-// has a stripped env, so an in-process launch would spawn workers under plain `claude` and 401 at boot. So
-// the CLI POSTs to the running backend whenever one answers, making the backend the single owner of session
-// launching. Only when NO backend is reachable do we fall back to launching in this process (with a stderr
-// warning) — the backend's own POST handler calls newSession directly, so it never re-enters this path.
+// BACKEND's process, not the caller's, because the backend is the single owner of the concurrency cap and the
+// launch QUEUE (drainQueue). An in-process launch by an agent that runs `spex new` (e.g. a supervisor) would
+// bypass that queue and the maxActive gate. (The launch COMMAND is not a process-env concern anymore — it
+// comes from the session's pinned launcher, resolved from project config [[launcher-select]], identical in
+// either process.) So the CLI POSTs to the running backend whenever one answers. Only when NO backend is
+// reachable do we fall back to launching in this process (with a stderr warning) — the backend's own POST
+// handler calls newSession directly, so it never re-enters this path.
 export async function createSession(node: string | null, prompt: string, launcher?: string): Promise<Session> {
   await assertProjectMatch('spex new')
   // @@@ parent = the CALLER's own session ([[session-nesting]]). Resolve it HERE, in the caller's process,
@@ -1059,6 +1062,9 @@ export async function newSession(node: string | null, prompt: string, parent: st
   const branch = `node/${slug}`
   const path = join(mainRoot(), '.worktrees', slug)
   await gitA(['-C', mainRoot(), 'worktree', 'add', '-b', branch, path, mainBranch()])
+  // a private-overlay repo keeps the spec sources out of git, so the checkout alone leaves this worktree
+  // spec-blind and hook-dead — link them from main ([[private-overlay]]; no-op on a default-mode repo).
+  linkUntrackedSpecSources(mainRoot(), path)
   // prepared but NOT launched: enters the queue as `queued`. drainQueue() below launches it at once when a
   // slot is free, else it waits — durable as a global record (+ its worktree), so it survives a backend
   // restart and is still findable. governed:true — this is a DASHBOARD/CLI-launched session, so it feeds the
@@ -1266,6 +1272,7 @@ export type ReviewGates = {
 }
 export type ReviewPayload = {
   id: string; node: string | null; branch: string | null
+  label: string              // the session's identity, derived ONCE via deriveLabel — the review surface renders THIS, never its own node||branch||id chain
   ahead: number              // commits the node branch is ahead of main
   dirtyNonRuntime: number    // uncommitted files excluding SpexCode's own runtime files
   diff: ReviewDiffFile[]     // the worker's real changes, anchored at the merge-base
@@ -1332,6 +1339,7 @@ export async function reviewPayload(id: string): Promise<ReviewPayload | null> {
   const dirtyNonRuntime = statusOut.split('\n').filter(Boolean).map(porcelainPath).length
   return {
     id, node: wt.rec.node, branch: wt.branch,
+    label: deriveLabel({ id, name: wt.rec.name, node: wt.rec.node, title: wt.rec.title, branch: wt.branch }),
     ahead: Number(aheadOut.trim()) || 0,
     dirtyNonRuntime, diff,
     gates: { conflictsWithMain, lint },

package/spec-cli/src/worktree-sources.ts

@@ -0,0 +1,19 @@
+import { existsSync, symlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+// @@@ worktree-sources ([[private-overlay]]) - a fresh session worktree checks out only TRACKED content, and
+// private mode keeps `.spec` + `spexcode.json` untracked (spexcode.local.json is untracked in BOTH modes) —
+// so git alone hands a dispatched agent a worktree with NO spec tree: every hook handler script is absent
+// (the dispatcher silently runs nothing), spex sees zero nodes, and the gate re-renders per event over empty
+// config roots. Link those sources from the main checkout instead. On a default-mode repo the checkout
+// already carries them, so each link guard no-ops — one mechanism, never a mode branch. A failure degrades
+// that worker (no hooks, no specs), so it is reported, not swallowed.
+export function linkUntrackedSpecSources(main: string, wt: string): void {
+  for (const f of ['.spec', 'spexcode.json', 'spexcode.local.json']) {
+    try {
+      if (existsSync(join(main, f)) && !existsSync(join(wt, f))) symlinkSync(join(main, f), join(wt, f))
+    } catch (e) {
+      console.error(`spexcode: could not link ${f} from ${main} into worktree ${wt} — that worker runs without it (${e})`)
+    }
+  }
+}

package/spec-cli/templates/spexcode.json

@@ -1,5 +1,12 @@
 {
   "lint": {
     "governedRoots": ["."]
+  },
+  "sessions": {
+    "launchers": {
+      "claude": { "harness": "claude", "cmd": "claude --dangerously-skip-permissions" },
+      "codex": { "harness": "codex", "cmd": "codex --yolo" }
+    },
+    "defaultLauncher": "claude"
   }
 }