spexcode 0.2.1 → 0.2.3

package/spec-cli/src/{self.ts → doctor.ts}

@@ -1,11 +1,12 @@
-// @@@ spex self - the SELF-DIAGNOSIS surface (spec-cli/self). When a user launches their OWN claude/codex
-// with no SpexCode process in the launch, the workflow reaches that agent only through the files
-// materialize() renders (the manifest in the global store; the in-tree contract blocks + hook shims + codex
-// trust). `self` answers "is this agent actually governed, or silently running free?" — diagnosing that
-// materialized contract per LAYER, looping the same HARNESSES adapter materialize renders through (so claude
-// AND codex are covered with no hardcoded paths). It catches the SILENT failure: a shim whose handler is
-// missing, a PATH that can't resolve `spex`, a contract that never landed. Read-only today: `doctor`,
-// `contract` (print the surface:system text any agent reads), `env`. install/uninstall are STAGED (noteStaged).
+// @@@ spex doctor - the DIAGNOSIS surface ([[doctor]]; command renamed from `self`, which misread as the
+// tool itself / the global install). When a user launches their OWN claude/codex with no SpexCode process
+// in the launch, the workflow reaches that agent only through the files materialize() renders (the manifest
+// in the global store; the in-tree contract blocks + hook shims + codex trust). Bare `spex doctor` answers
+// "is this agent actually governed, or silently running free?" — diagnosing that materialized contract per
+// LAYER, looping the same HARNESSES adapter materialize renders through (so claude AND codex are covered
+// with no hardcoded paths). It catches the SILENT failure: a shim whose handler is missing, a PATH that
+// can't resolve `spex`, a contract that never landed. Read-only today: the bare report, `contract` (print
+// the surface:system text any agent reads), `conflicts`. install/uninstall are STAGED (noteStaged).
 import { existsSync, readFileSync, readdirSync, accessSync, constants } from 'node:fs'
 import { join, dirname, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -171,17 +172,17 @@ async function doubleDeliveryReport(base: string): Promise<{ lines: string[]; co
     L.push('  • remove the independently-installed plugin bundle (delete its dir, or `claude plugin uninstall spexcode`); or')
     L.push('  • if you WANT the plugin, stop the native delivery: set spexcode.json "harnesses" to a plugin target')
     L.push('    (e.g. ["plugin",{"plugin":".claude"}] → {"plugin":".claude"}) so `spex materialize` prunes the loose shim/contract/skills; or')
-    L.push('  • remove the loose copy directly (`spex self uninstall` [staged] / `spex uninstall`).')
+    L.push('  • remove the loose copy directly (`spex doctor uninstall` [staged] / `spex uninstall`).')
   } else {
     L.push('No double-delivery: each harness is reached by at most one spexcode-stamped channel.')
   }
   return { lines: L, conflict }
 }
 
-// ping the backend (apiBase) with a short timeout so doctor never hangs on a dead/wrong SPEXCODE_API_URL.
+// ping the backend (the resolved apiBase) with a short timeout so doctor never hangs on a dead/wrong backend.
 async function backendReachable(): Promise<{ base: string; up: boolean }> {
   let base = 'http://127.0.0.1:8787'
-  try { base = (await import('./sessions.js')).apiBase() } catch { /* keep default */ }
+  try { base = await (await import('./sessions.js')).apiBase() } catch { /* keep default */ }
   const ctrl = new AbortController()
   const t = setTimeout(() => ctrl.abort(), 800)
   try { return { base, up: (await fetch(`${base}/api/sessions`, { signal: ctrl.signal })).ok } }
@@ -210,7 +211,7 @@ async function doctor(): Promise<number> {
 
   const L: string[] = []
   const line = (k: string, v: string) => L.push(`  ${k.padEnd(16)}: ${v}`)
-  L.push('spex self doctor — how the SpexCode workflow reaches this agent\n')
+  L.push('spex doctor — how the SpexCode workflow reaches this agent\n')
 
   L.push('Agent')
   line('detected', runningHarness ? `${runningHarness.id}  (${runningHarness.sessionEnvVar}=${process.env[runningHarness.sessionEnvVar]})` : 'none detected (no harness session env var set)')
@@ -244,9 +245,9 @@ async function doctor(): Promise<number> {
   line('nodes', names.length ? names.join(', ') : 'none — contract is empty')
   for (const h of HARNESSES) {
     const present = h.contractFiles(base).every((f) => /<!--\s*spexcode:start\s*-->/.test(read(f)))
-    line(`in ${h.id}`, present ? `block present (${h.contractFiles(base).map((f) => f.replace(base + '/', '')).join(', ')})` : 'NOT landed — run `spex self contract` / materialize')
+    line(`in ${h.id}`, present ? `block present (${h.contractFiles(base).map((f) => f.replace(base + '/', '')).join(', ')})` : 'NOT landed — run `spex doctor contract` / materialize')
   }
-  line('view', 'spex self contract')
+  line('view', 'spex doctor contract')
 
   // --- hooks: the shim → dispatch, the manifest, and EVERY handler readable in the worktree ---
   L.push('\nLayer 3 — hooks (shim → dispatch · manifest · handler-existence)')
@@ -286,7 +287,7 @@ async function doctor(): Promise<number> {
   line('layer 2', body.length === 0 ? 'ABSENT (no contract)' : 'see per-harness above')
   line('layer 3', manifestText ? 'see handler-existence above' : 'ABSENT (no manifest — agent ungoverned)')
   line('layer 4', up ? 'present' : managed ? 'EXPECTED but backend down' : 'absent (normal for bring-your-own-agent)')
-  line('layer 5', dd.conflict ? 'CONFLICT (double-delivery — see Layer 5; `spex self conflicts`)' : 'clean (single channel)')
+  line('layer 5', dd.conflict ? 'CONFLICT (double-delivery — see Layer 5; `spex doctor conflicts`)' : 'clean (single channel)')
 
   // --- footprint: every artifact Spex wrote here, + any slot held by something not ours ---
   L.push('\nFootprint (what Spex wrote into this environment)')
@@ -310,7 +311,7 @@ async function doctor(): Promise<number> {
 // print the layer-2 contract so any agent/harness can be handed exactly what materialize folds in.
 function contract(): number {
   const { body } = contractText()
-  if (!body) { console.error('spex self: no surface:system nodes in this .spec tree — the contract is empty.'); return 0 }
+  if (!body) { console.error('spex doctor: no surface:system nodes in this .spec tree — the contract is empty.'); return 0 }
   console.log(body)
   return 0
 }
@@ -321,7 +322,7 @@ async function conflicts(): Promise<number> {
   const cwd = process.cwd()
   const base = repoRoot(cwd) ?? cwd
   const { lines, conflict } = await doubleDeliveryReport(base)
-  console.log(['spex self conflicts — does SpexCode reach this agent through more than one discovery channel?\n', ...lines].join('\n'))
+  console.log(['spex doctor conflicts — does SpexCode reach this agent through more than one discovery channel?\n', ...lines].join('\n'))
   return conflict ? 1 : 0
 }
 
@@ -329,16 +330,16 @@ async function conflicts(): Promise<number> {
 // install/uninstall are STAGED: wiring layer-3 hooks into a standalone repo is only SAFE once the hooks
 // detect a missing managed session and degrade. So the diagnosis ships first; the installer lands behind it.
 function noteStaged(verb: string): number {
-  console.error(`spex self ${verb} is not available yet — it is staged behind the hook-degradation prerequisite
+  console.error(`spex doctor ${verb} is not available yet — it is staged behind the hook-degradation prerequisite
 (the live hooks must detect a missing managed session and degrade before they can be safely wired into your
-own agent's config). Meanwhile: \`spex self doctor\` reports your coverage, and \`spex self contract\` prints
+own agent's config). Meanwhile: \`spex doctor\` reports your coverage, and \`spex doctor contract\` prints
 the workflow text you can hand any agent.`)
   return 2
 }
 
 function usage(): number {
-  console.error(`spex self — diagnose how the SpexCode workflow reaches your agent
-  doctor       per-layer report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint  (default)
+  console.error(`spex doctor — diagnose how the SpexCode workflow reaches your agent
+  (bare)       per-layer report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
   contract     print the surface:system contract text (hand it to any agent)
   conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)
   install      [staged] wire the materialized contract + hooks into your agent  (--agent claude, --minimal)
@@ -346,14 +347,14 @@ function usage(): number {
   return 0
 }
 
-export async function runSelf(args: string[]): Promise<number> {
-  switch (args[0] ?? 'doctor') {
-    case 'doctor': return await doctor()
+export async function runDoctor(args: string[]): Promise<number> {
+  switch (args[0]) {
+    case undefined: return await doctor()
     case 'contract': return contract()
     case 'conflicts': return await conflicts()
     case 'install': return noteStaged('install')
     case 'uninstall': return noteStaged('uninstall')
     case 'help': case '--help': case '-h': return usage()
-    default: console.error(`spex self: unknown subcommand "${args[0]}"`); usage(); return 2
+    default: console.error(`spex doctor: unknown subcommand "${args[0]}"`); usage(); return 2
   }
 }

package/spec-cli/src/guide.ts

@@ -8,7 +8,8 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    It always operates on the repo of your current directory — that cwd is the only "which repo" knob.
    (Dogfooding an unpublished HEAD from a source checkout? \`npm link\` at the repo ROOT — that links
    the \`spexcode\` package itself, never the internal @spexcode/spec-cli. Both paths own the same
-   \`spex\` bin, so uninstall one before switching (\`npm rm -g spexcode\`). A source link ships no
+   \`spex\` bin, so uninstall one before switching (\`npm rm -g spexcode\`; a legacy link of the
+   inner package uninstalls as \`@spexcode/spec-cli\`). A source link ships no
    prebuilt dashboard dist — \`spex dashboard\` needs a manual dashboard build, or use the dev server.)
 
 2. Adopt a repo
@@ -24,6 +25,9 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
      spex dashboard                              # serves the bundled board on :5173, proxying /api
    Point it at another backend with --api-port (pairs with \`spex serve --port\`); one dashboard per
    project. The board is a viewer — which backend it proxies is the only "which project" knob.
+   Loopback-only by default: viewing from another machine needs \`--host 0.0.0.0\` (or a specific
+   interface) — still plain HTTP with no gate, so bind wide only on a LAN/tailnet you trust (for
+   the internet, use \`spex serve --public\` instead).
    (Dogfood/source alternative: API_URL=http://localhost:<port> npm run dev in spec-dashboard —
    the dev server; "dashboard": { "apiUrl": "..." } in spexcode.json applies only to that layout.)
 
@@ -90,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>\`.
@@ -122,13 +127,43 @@ pre-commit \`yatsu check-staged\` BLOCKS the commit.
 BODY (after the frontmatter): prose naming the measurement method — YATU ("You As The User"): the agent
 looks at / calls the real product surface, not an internal helper chosen to make the proof easy.
 
-MEASURING AND FILING: the agent runs the scenario however it likes (a browser screenshot, an API
+MEASURING AND FILING: the agent runs the scenario however it likes (a browser run, an API
 transcript, a by-hand pass), compares the result to \`expected\`, and files it:
-  spex yatsu eval <node> --scenario <name> (--pass | --fail) [--note <text>] [--image <png> | --result <txt>|-]
+  spex yatsu eval <node> --scenario <name> (--pass | --fail) [--note <text>]
+                 [--image <png> …repeatable] [--result <txt>|-] [--video <webm|mp4> [--timeline <json>]]
 The verdict is \`--pass\` or \`--fail\` (a measurement must commit to one — an unmeasured scenario is \`missing\`,
 not a hedged fail). \`--note <text>\` is an OPTIONAL one-line annotation on either (why it failed, how far a
-pass sits from ideal); it does NOT replace evidence — the image/transcript is the captured actual behaviour.
-Frontend → \`--image <png>\` (visual evidence); backend → \`--result <txt>\` (a transcript; \`-\` reads stdin).
+pass sits from ideal); it does NOT replace evidence — the image/video/transcript is the captured actual behaviour.
+PICK THE EVIDENCE KIND BY WHAT THE BEHAVIOUR DOES OVER TIME:
+  MOVES / is timed  → \`--video <webm|mp4>\`. Terminal scroll or redraw, an animation or transition, media
+                      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 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). 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
+is earned on the working tree, but the anchor can only land after the commit. Filing from a dirty tree
+mis-anchors the reading (its sha lacks the change it measured) and it goes stale the moment you commit.
 
 A botched filing (a junk e2e/smoke run, a wrong verdict) is undone through the SAME surface:
   spex yatsu retract <node> [--scenario <name>] [--last | --ts <iso>] [--note <why>]
@@ -141,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`
@@ -156,13 +191,14 @@ 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
 PATH of a launcher wrapper, a TLS cert path, private mode are machine facts → gitignored spexcode.local.json.
-Both files are optional; omit any field to take its default.
+Both files are optional; omit any field to take its default, except \`sessions.defaultLauncher\` when using
+\`spex new\` or the dashboard without an explicit launcher choice.
 
 MERGE: spexcode.local.json is layered over spexcode.json ONE LEVEL DEEP — per top-level section (dashboard,
 sessions, …), the two objects are shallow-merged with LOCAL WINNING per key; sections only one file names
@@ -191,19 +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        the UNNAMED default worker launcher for Claude (default
-                            'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides.
-  sessions.codexCmd         the UNNAMED default worker launcher for Codex (default 'codex --yolo'); env
-                            SPEXCODE_CODEX_CMD overrides.
-  sessions.launchers        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
-                            (else the unnamed claudeCmd/codexCmd path). 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.
+                            (required for no-choice creates). A portable NAME → committed.
+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, and the chosen name is persisted on the record so a resume reuses the same auth. Shape:
+by name with --launcher/the dashboard dropdown, and the chosen name is persisted on the record so a resume
+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
@@ -230,6 +271,23 @@ in the committed spexcode.json — the merge keeps both:
                          spexcode.local.json.
 The gateway password is NEVER read from these files (flag/env only), so serve.public stays committable.
 
+── BACKEND ROUTING (not a config field — how a \`spex\` command picks its backend) ──
+One host runs many projects' backends, and a shell inherits the launching backend's SPEXCODE_API_URL —
+an env var cannot prove intent (exported-on-this-command vs inherited look identical), so the client
+resolves its backend per this ladder, flag first:
+  1.  --api <url>            explicit flag on any session verb — ALWAYS wins (--port <n> is localhost
+                             sugar for --api http://127.0.0.1:<n>).
+  2a. worker (SPEXCODE_SESSION_ID set): env SPEXCODE_API_URL — the backend-injected lifeline; cwd
+                             discovery never steals it.
+  2b. human (no session id): the cwd project's RECORDED live backend — \`spex serve\` records {url,pid}
+                             in ~/.spexcode/projects/<enc>/backend.json at bind time; the reader
+                             health-probes before trusting (a dead record is ignored).
+  3.  the other side as fallback (human with no live record → env; worker with no env → record).
+  4.  default http://127.0.0.1:$PORT||8787.
+WRITES are project-bound: every mutating verb (new/merge/send/close/rename/rawkey/reopen/exit) refuses
+loudly when the resolved backend serves a DIFFERENT same-host project — an explicit --api/--port skips
+the guard (the flag is the proof of intent). Reads point anywhere.
+
 ── ISSUES (spexcode.json — portable policy) ──
   issues.enabled      the issues-workflow on/off switch (default ON). OFF silences the post-merge nudge and
                       hides the dashboard view; the CLI toggle is \`spex issues on|off\`.

package/spec-cli/src/harness.ts

@@ -8,7 +8,6 @@ import { promisify } from 'node:util'
 import { fileURLToPath } from 'node:url'
 import { claudeSlashCommands, codexSlashCommands, type SlashCommand } from './slash-commands.js'
 import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
-import { tsxBin } from './tsx-bin.js'
 
 // @@@ harness-adapter - the ONE seam between SpexCode and the coding-agent harness (Claude Code, Codex, …).
 // Every harness-specific fact lives behind THIS interface with one implementation per harness; product code
@@ -19,8 +18,8 @@ import { tsxBin } from './tsx-bin.js'
 // DETECTION. There is no payload-sniffing: each adapter OWNS its shim, and the shim bakes the harness id as
 // dispatch.sh's first argument (`bash <dispatch> <id> <Event>`). dispatch.sh exports SPEXCODE_HARNESS, so a
 // hook subprocess learns its harness deterministically from the shim that wired it — never from guessing the
-// payload shape. On the TS side the harness is the launcher's choice (the dashboard launches `defaultHarness`)
-// or ALL adapters at once (materialize renders every harness's artifacts).
+// payload shape. On the TS side the harness is derived from the selected launcher or ALL adapters at once
+// (materialize renders every harness's artifacts).
 
 export type HarnessId = 'claude' | 'codex'
 export type HarnessLivenessRecord = { session: string; harnessSessionId?: string | null }
@@ -50,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 → the unnamed default resolution (env-overridable, for tests + old records).
+  // 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.
@@ -226,11 +226,12 @@ function shQuote(s: string): string {
   return `'${s.replace(/'/g, `'\\''`)}'`
 }
 
-// the tsx + cli.ts invocation, baked into the codex launch script (mirrors materialize.ts's SPEX) so the
-// launch shell can call back into `spex codex-launch` to own the thread + fire the first turn before it
-// exec's the visible TUI.
+// the spex launcher (bin/spex.mjs), baked into the codex launch script (mirrors materialize.ts's SPEX) so
+// the launch shell can call back into `spex codex-launch` to own the thread + fire the first turn before it
+// exec's the visible TUI. The launcher, never a raw `tsx cli.ts` pair: it owns tsx resolution and the
+// mid-merge guard (conflicted source → one line + exit 75, not a stacktrace).
 const PKG = fileURLToPath(new URL('..', import.meta.url))
-const SPEX = `${tsxBin(PKG)} ${join(PKG, 'src', 'cli.ts')}`
+const SPEX = join(PKG, 'bin', 'spex.mjs')
 
 // @@@ replyViaSocket - OPTIMISTIC-after-liveness delivery: connect to the LIVE rendezvous socket and WRITE the
 // `{type:reply}\n` line; once that line FLUSHES to the socket with no immediate transport error, the reply is on
@@ -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',
@@ -1031,8 +1034,7 @@ export const codexHarness: Harness = {
 // every adapter — materialize iterates this to render each harness's artifacts in one pass.
 export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness]
 
-// the harness the dashboard/CLI launcher drives today (Claude). The single place a future codex launcher
-// would flip; product code reads this rather than naming Claude.
+// the legacy/default adapter for old records and config defaults. New launches derive harness from a launcher.
 export const defaultHarness: Harness = claudeHarness
 
 // resolve an adapter by id (the detector). Throws on an unknown id — fail loud, never silently default.
@@ -1044,27 +1046,49 @@ 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 }
 
-// the configured launchers, as a stable name-sorted list (for the dashboard dropdown + the CLI). Empty when a
-// project configured none — the caller then falls back to the unnamed harness pick.
+// 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 || {}
-  return Object.keys(m).sort().map((name) => ({ name, harness: m[name].harness || defaultHarness.id, cmd: m[name].cmd }))
+  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. '' when none configured. The dashboard reads this to PRE-SELECT its New-Session
-// dropdown to match the CLI/config default, so the two surfaces agree on which launcher a bare create uses.
+// 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 {
-  return readConfig(root).sessions?.defaultLauncher || ''
+  const name = readConfig(root).sessions?.defaultLauncher?.trim()
+  if (!name) throw new Error(MISSING_DEFAULT_LAUNCHER_ERROR)
+  return name
+}
+
+export function launcherDefault(root = mainCheckout()): LauncherDefault {
+  try {
+    const name = defaultLauncher(root)
+    resolveLauncher(name, root)
+    return { default: name, error: null }
+  } catch (e) {
+    return { default: null, error: String((e as Error).message || e) }
+  }
 }
 
 export function resolveLauncher(name: string, root = mainCheckout()): Launcher {
   const l = readConfig(root).sessions?.launchers?.[name]
-  if (!l || !l.cmd) throw new Error(`unknown launcher '${name}' (configured: ${launcherList(root).map((x) => x.name).join(', ') || 'none'})`)
-  harnessById(l.harness || defaultHarness.id)   // validate the harness id fail-loud
-  return { name, harness: l.harness || defaultHarness.id, cmd: l.cmd }
+  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
 }