spexcode 0.2.1 → 0.2.2

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.)
 
@@ -122,13 +126,39 @@ 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 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\`.)
+  STATIC end state  → \`--image <png>\` (repeatable — N stills). Layout, an icon, copy, one rendered frame.
+  backend / CLI     → \`--result <txt>\` (a transcript; \`-\` reads stdin).
+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>]
@@ -162,7 +192,8 @@ PORTABILITY, and picking the right one is the whole discipline:
 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 +222,23 @@ 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
+  sessions.claudeCmd        command used by the built-in "claude" launcher (default
                             'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides.
-  sessions.codexCmd         the UNNAMED default worker launcher for Codex (default 'codex --yolo'); env
+  sessions.codexCmd         command used by the built-in "codex" launcher (default 'codex --yolo'); env
                             SPEXCODE_CODEX_CMD overrides.
-  sessions.launchers        NAMED launcher profiles (see LAUNCHERS).
+  sessions.launchers        additional NAMED launcher profiles (see LAUNCHERS).
   sessions.defaultLauncher  the launcher name a create with no explicit --launcher/dropdown pick uses
-                            (else the unnamed claudeCmd/codexCmd path). A portable NAME → committed.
+                            (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.
 
 ── 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. 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:
   "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 +265,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 }
@@ -53,7 +52,7 @@ export interface Harness {
   // 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).
+  // default. Omitted is only for tests and old records before launch_cmd was pinned.
   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`,
@@ -226,11 +225,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
@@ -1031,8 +1031,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.
@@ -1047,24 +1046,54 @@ export function harnessById(id: string): Harness {
 // 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.
 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.
+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.
 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 }))
+  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))
 }
 
+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 the
+// built-in `claude` launcher.
 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 && !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'})`)
+  harnessById(resolved.harness)   // validate the harness id fail-loud
+  return resolved
 }