spexcode 0.2.0 → 0.2.2

package/spec-cli/src/help.ts

@@ -12,8 +12,19 @@ type Entry = { line: string; body: string; see?: string }
 const SEL_NOTE = `SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
 accepts any of the three; none (or @all) means every session.`
 
+const ROUTING_NOTE = `Backend routing: every session verb accepts --api <url> (--port <n> = localhost sugar) to name its
+backend explicitly — the flag always wins. Bare, it resolves: worker env / the cwd project's live
+recorded backend / fallback / :8787 (spex guide config → BACKEND ROUTING).`
+
 // aliases resolve to a canonical entry so `spex help session` and `spex session new --help` meet the same text.
-const ALIAS: Record<string, string> = { 'review-proof': 'review', help: 'help' }
+// The session-sub tokens mirror the CLI's verb-mirror rule: each typeable sub also answers bare at the top
+// level, so its help probe (`spex send --help`, `spex help send`) must land on the session entry, not dead-end.
+const SESSION_SUB_TOKENS = ['reopen', 'done', 'park', 'ask', 'exit', 'close', 'send', 'capture', 'attach', 'rename', 'rawkey', 'prompt']
+const ALIAS: Record<string, string> = {
+  'review-proof': 'eval',
+  help: 'help',
+  ...Object.fromEntries(SESSION_SUB_TOKENS.map((t) => [t, 'session'])),
+}
 
 const ENTRIES: Record<string, Entry> = {
   // ── find & read the graph ─────────────────────────────────────────────────
@@ -23,25 +34,42 @@ const ENTRIES: Record<string, Entry> = {
 
 Finds the spec node(s) whose INTENT matches your topic — ranked by user-story relevance, which
 surfaces user-facing behaviour a code-grep misses. Run it BEFORE touching code: the returned node's
-spec.md body is the current contract for that area. Prints title, id, path, snippet per hit.`,
+spec.md body is the current contract for that area. Prints title, id, path, snippet per hit.
+The corpus is English — query in English (translate first if your question isn't).`,
     see: 'spex owner (file → node, the reverse edge) · spex guide spec (what a node is)',
   },
   owner: {
-    line: 'owner <path>          the reverse edge: which spec node(s) claim a file',
+    line: 'owner <path>          the reverse edge: which spec node(s) govern or reference a file',
     body: `Usage: spex owner <path> [--actionable]
 
-Maps a source file to the spec node(s) governing it, with the verdict spelled out: uncovered
-("give it a home"), sanely governed (read/honor that spec), or over-owned (> maxOwners — split the
-file). --actionable prints NOTHING for the sane case (hook use: only fires when action is needed).`,
+Maps a source file to BOTH spec relations: its GOVERNORS (code: — the source of truth; drives
+drift/yatsu) and its REFERENCERS (related: — coverage only), with the verdict spelled out:
+uncovered ("give it a home"), related-only (covered, but nothing tracks its drift), sanely
+governed (read/honor that spec), or over-owned (> maxOwners — split the file). --actionable
+prints NOTHING unless action is needed (hook use): only uncovered / over-owned fire.`,
     see: 'spex search (topic → node) · spex lint (coverage over the whole tree)',
   },
+  tree: {
+    line: 'tree                  the graph as a human-readable tree (status-coloured, badges)',
+    body: `Usage: spex tree [--node <id>] [--depth N] [--json]
+
+Prints the assembled spec graph as an indented tree — the CLI twin of the dashboard's tidy-tree,
+built from the same board (merged tree + worktree overlay). One line per node: id, derived status
+(coloured when stdout is a tty; NO_COLOR respected — the status word always prints), title, and
+attention badges: drift:N (drifted files), stale:N (yatsu scenarios whose latest reading aged),
+issues:N (open issues), ghost (being added by a worktree).
+  --node <id>   render just that subtree (unknown id fails loud)
+  --depth N     limit levels below the shown root; prunes are counted, never silent
+  --json        the same filtered subtree as nested objects, badge counts precomputed`,
+    see: 'spex board (the full flat JSON payload) · spex search (find one node by intent)',
+  },
   board: {
     line: 'board                 dump the assembled board as JSON (tree · overlay · sessions)',
     body: `Usage: spex board
 
 Prints the full dashboard board state as JSON — the merged spec tree, per-worktree overlay, and the
 session list. Identical to GET /api/board; needs the backend (spex serve) reachable.`,
-    see: 'spex ls (just the sessions, as a table) · spex search (find one node instead of dumping all)',
+    see: 'spex tree (the same graph, human-readable) · spex ls (just the sessions, as a table) · spex search (find one node instead of dumping all)',
   },
   guide: {
     line: 'guide [topic]         the manuals: setup workflow · spec/yatsu file formats · spexcode.json',
@@ -82,40 +110,52 @@ only the trailer. If the intent DID change, edit the spec instead — same commi
   yatsu: {
     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|->]
+       spex yatsu eval [.|<node>] [--scenario <name>] (--pass|--fail) [--note <text>]
+                       [--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
 
 Files a reading of a scenario against its expected — the loss signal the optimizer reads. Measure
-through the REAL product surface (run it, drive a browser, screenshot), never by reasoning about
-the code. A fix's proof is a fail→pass pair on the SAME scenario. \`retract\` is the sanctioned
-undo for a botched filing: it APPENDS a retraction event (traceable, never deletes a line).`,
+through the REAL product surface (run it, drive a browser, capture), never by reasoning about
+the code. Evidence kind follows the behaviour: MOVING/timed behaviour (scroll, animation,
+playback, a multi-step flow) records a \`--video\`; a STATIC end state screenshots \`--image\`;
+backend/CLI files a \`--result\` transcript. A fix's proof is a fail→pass pair on the SAME
+scenario. \`retract\` is the sanctioned undo for a botched filing: it APPENDS a retraction
+event (traceable, never deletes a line).`,
     see: 'spex guide yatsu (yatsu.md format + evidence rules) · spex blob (stash evidence bytes)',
   },
   blob: {
-    line: 'blob put <file|->     stash evidence bytes in the content-addressed cache, print the hash',
+    line: 'blob put|get          evidence bytes ⇄ content hash: put stashes & prints the hash, get reads back',
     body: `Usage: spex blob put <file|->
+       spex blob get <hash> [-o <file>]
 
-Writes bytes into the shared content-addressed evidence cache and prints the hash — transport only,
-no reading filed. Use the hash with --evidence on issues/remarks; re-putting the same content
-restores a pruned or cloned-away blob.`,
+put writes bytes into the shared content-addressed evidence cache and prints the hash — transport
+only, no reading filed. Use the hash with --evidence on issues/remarks; re-putting the same content
+restores a pruned or cloned-away blob.
+
+get is the symmetric read: hash in, bytes out. Local cache first (no backend needed — the evidence
+is usually on this disk), then the backend's /api/yatsu/blob/:hash on a local miss; both missing
+fails loud naming each path. Bytes go to stdout by default (pipe-friendly); -o writes a file.`,
     see: 'spex yatsu eval (file a reading with evidence) · spex issues open --evidence <hash>',
   },
   issues: {
     line: 'issues …              THE issue surface: one merged local+forge list, plus all write verbs',
     body: `Usage: spex issues                                        the merged read (local + forge, store-tagged)
                   [--node <id>] [--store local|github] [--all] [--json]
-       spex issues open "<concern>" [--node <id>…] [--evidence <hash>…] [--body -|<text>]
+       spex issues open "<concern>" [--store local|<host>] [--node <id>…] [--evidence <hash>…] [--body -|<text>]
        spex issues reply <id> --body -|<text> [--evidence <hash>…]     (routes by the issue's store)
-       spex issues sign <id>              co-sign a local issue
-       spex issues resolve <id> --as accepted|rejected|landed
+       spex issues close <id>             close by the issue's store: local lands, forge closes remote
        spex issues promote <id>           move an OPEN local issue to the forge (one recorded action)
        spex issues on|off|status          toggle/inspect the local-issue workflow
 
 Bare \`spex issues\` is the drain view a supervisor reads. \`open\` welcomes taste, annotations, and
-off-mainline smells — not only bugs. (\`nudge\` exists but is fired by the post-merge hook, not typed.)`,
+off-mainline smells — not only bugs; \`--store <host>\` opens straight on the forge (the same port the
+dashboard's New form uses). \`close\` and \`reply\` route by the issue's store — one verb, local or forge,
+the same routing as the dashboard. (\`nudge\` exists but is fired by the post-merge hook, not typed.)
+Mentions: @session · [[node]] work in any concern/body — CLI args included. [[node]] links the topic
+node (it also tags the issue, like --node); @session hands the text to that live agent; @new spawns
+a fresh worker on the thread's node.`,
     see: 'spex remark (pin a resolvable concern to an issue or scenario) · spex forge (trace forge → nodes)',
   },
   remark: {
@@ -138,35 +178,27 @@ Resolves a forge's open issues/PRs to the spec nodes they serve (the Spec: marke
 a node/<id> branch links its PR for free). Read-only — git/.spec stays the single source of truth.`,
     see: 'spex issues (the merged read that includes forge threads)',
   },
-  self: {
-    line: 'self <sub>            diagnose whether the workflow actually reaches THIS agent: doctor | contract | conflicts',
-    body: `Usage: spex self [doctor]      per-layer coverage report: preconditions · git-hook floor · contract ·
-                               hooks + handler existence · backend — for every harness materialize renders
-       spex self contract      print the composed surface:system text any agent here reads
-       spex self conflicts     detect double-delivery (loose artifacts beside the managed ones)
-
-Run it when a worker seems to be missing its contract or hooks — it names the broken layer and the
-repair, instead of you diffing materialized files by hand.`,
-    see: 'spex materialize (re-render the artifacts doctor checks)',
-  },
-
   // ── dispatch & manage sessions (manager loop) ─────────────────────────────
   new: {
-    line: 'new "<prompt>"        launch a worker session in its own node worktree  [--node <id>]',
-    body: `Usage: spex new "<task prompt>" [--node <id>] [--harness <name>] [--launcher <cmd>]
+    line: 'new "<prompt>"        launch a worker session in its own node worktree  [--node <id>] [--launcher <name>]',
+    body: `Usage: spex new "<task prompt>" [--node <id>] [--launcher <name>]
 
 Creates a session: node branch + worktree + a launched agent carrying your prompt (= session new).
 Give it ONLY its task — the dev-flow contract reaches it through the materialized system prompt.
+The launcher name selects both the agent harness and the command/auth profile (built-ins: claude, codex);
+omitting it requires sessions.defaultLauncher in spexcode.json or spexcode.local.json.
 Routes through the running backend (auth env + concurrency cap); prints the created session JSON.
 Then MONITOR it: background \`spex wait <id>\`, or \`spex watch\` for the whole stream.`,
     see: 'spex wait / spex watch (monitor) · spex review (when it proposes) · ' + SEL_NOTE.split('\n')[0],
   },
   ls: {
-    line: 'ls [SEL…]             living-sessions table  [--status a,b] [--json]',
-    body: `Usage: spex ls [SEL…] [--status a,b] [--json]
+    line: 'ls [SEL…]             living-sessions table  [--status a,b] [--json] [--api URL]',
+    body: `Usage: spex ls [SEL…] [--status a,b] [--json] [--api <url> | --port <n>]
 
-One-shot table of living sessions and their states, from whatever backend SPEXCODE_API_URL points
-at (including a remote machine's). ${SEL_NOTE}`,
+One-shot table of living sessions and their states, from the resolved backend — bare \`spex ls\` in a
+project's tree hits THAT project's live backend; --api <url> (or --port <n>) points it anywhere,
+including a remote machine's. ${SEL_NOTE}
+${ROUTING_NOTE}`,
     see: 'spex watch (the live stream) · spex wait (block on one session)',
   },
   watch: {
@@ -194,14 +226,29 @@ ${SEL_NOTE}`,
   review: {
     line: 'review <SEL>          manager cockpit: ahead · merge-base diff · gates · proposal  [--json]',
     body: `Usage: spex review <SEL> [--json]
-       spex review proof <SEL> [--open | --out <path> | --json]
 
 The ONE review payload for a session: commits ahead of the trunk, uncommitted files, its proposal,
 the gates (conflicts with the trunk, lint), and the merge-base diff — decide from this, don't
-hand-run git. \`review proof\` renders the session's proof-of-work as self-contained HTML (diff ·
-measured yatsu loss · gates), fully derived from git + readings.
+hand-run git. The MEASURED side of the decision is \`spex eval <SEL>\`: the changed nodes' eval
+readings, and (--export) the self-contained HTML export.
 ${SEL_NOTE}`,
-    see: 'spex merge (act on an approved review)',
+    see: 'spex eval (the session’s measured loss) · spex merge (act on an approved review)',
+  },
+  eval: {
+    line: 'eval <SEL>            the session’s eval readings: its changed nodes’ measured loss  [--export]',
+    body: `Usage: spex eval <SEL> [--json]
+       spex eval <SEL> --export [--open | --out <path> | --json]
+
+The session's evaluation, read from the backend (the dashboard Eval tab's CLI twin): every spec node
+the session's diff touches, each DECLARED scenario at its CURRENT score (latest reading, rooted at
+the session's worktree). Blind spots lead (declared, never measured — the outstanding loss), then
+the session's OWN measurements ✦-marked, then the inherited baseline (other sessions' latest
+readings) under an explicit divider. A frontend change with no yatsu.md is flagged, never hidden.
+--export writes the evaluation as ONE self-contained HTML artifact instead (diff · evidence
+inlined · gates; --json = the model) for CI/sharing. (\`spex review proof\` is its deprecated alias.)
+This is the READ; filing a reading stays \`spex yatsu eval\`.
+${SEL_NOTE}`,
+    see: 'spex review (gates + diff — the merge decision) · spex yatsu eval (FILE a reading, the write verb)',
   },
   merge: {
     line: 'merge <SEL>           gated merge into the trunk — dispatched to the session’s own agent',
@@ -210,11 +257,13 @@ ${SEL_NOTE}`,
 Dispatches the merge to the session's OWN agent (it knows the work's intent and resolves conflicts);
 the server never touches the trunk's tree. Gates re-check first. After it lands, confirm HEAD
 advanced before closing the session — closing an unmerged branch discards the work.
+Mutating verbs are PROJECT-BOUND: a backend serving another project's repo refuses the write loudly
+(name the target with --api <url> to write cross-project on purpose).
 ${SEL_NOTE}`,
     see: 'spex review (before) · spex session close (after the merge is confirmed)',
   },
   session: {
-    line: 'session <sub>         the state machine: new·reopen·done·park·ask·exit·close·send·capture·prompt',
+    line: 'session <sub>         every session verb answers here: new·ls·watch·wait·review·merge·reopen·done·park·ask·exit·close·send·capture·attach·rename·rawkey·prompt',
     body: `Worker verbs (declare YOUR OWN state — a claim the board and your supervisor act on):
   spex session done --propose merge|nothing|close [--note T]   committed and stopping; merge = ready for review
   spex session park --note <what-you-await>                    a real background task will wake you
@@ -223,14 +272,36 @@ ${SEL_NOTE}`,
 Manager verbs (control another session; all take SEL):
   spex session send <SEL> "<msg>"      deliver a message (fail-loud: a dead dispatch exits non-zero)
   spex session capture <SEL>           the live pane as text
+  spex session rename <SEL> "<name>"   set the display name ("" clears; the right-click rename, as a verb)
+  spex session rawkey <SEL> "<keys>"   raw nav keys to a TUI dialog, in strike order (e.g. "Up Up Enter";
+                                       named keys · single chars · C-/M-/S- combos; fail-loud)
   spex session prompt <SEL>            the session's originating prompt
   spex session reopen <SEL> [--force]  relaunch ONLY if confirmed offline (--force for a wedged live one)
   spex session exit <SEL>              soft stop: kill the agent, KEEP the worktree (resumable)
   spex session close <SEL>             retire the session and its worktree
-  spex session new "<prompt>"          = spex new
+
+Promoted verbs — they answer in this drawer too (same verb, either drawer):
+  spex session new|ls|watch|wait|review|merge …   ≡   spex new|ls|watch|wait|review|merge …
+And the reverse holds for every sub above: it also answers bare at the top level
+(spex send <SEL> "…" ≡ spex session send <SEL> "…"). One implementation, two spellings —
+you never have to guess which drawer a session verb lives in.
+
+Human escape hatch:
+  spex session attach <SEL>            sit in the worker's REAL tmux (detach: C-b d; the session keeps
+                                       running). INTERACTIVE AND BLOCKING — like watch, an agent must
+                                       NEVER run it in a turn (it freezes you): use capture/send/rawkey.
+                                       LOCAL-only — the tmux server is the backend machine's, so it fails
+                                       loud when the resolved backend is remote. Offline session → loud.
+
+Mentions: @session · [[node]] work in ANY prompt, issue, or remark body — text passed as a CLI arg
+included. [[node]] names the topic (a new session derives its node from the prompt's first one);
+@session hands the surrounding text to that live agent; @new dispatches a fresh worker.
 
 (state · fail · idle · commit-gate also exist but are hook-driven — the lifecycle hooks call them;
-never type them.) ${SEL_NOTE}`,
+never type them.) ${SEL_NOTE}
+Manager verbs that WRITE (send/rename/rawkey/reopen/exit/close) are PROJECT-BOUND: a backend serving
+another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.
+${ROUTING_NOTE}`,
     see: 'spex new (launch) · spex wait/watch (monitor) · spex review/merge (land)',
   },
 
@@ -261,7 +332,18 @@ Renders the surface:system config nodes into the managed <!-- spexcode --> block
 CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. Run it after a
 toolchain update or any .config edit that the automatic dispatch gate hasn't picked up — these
 artifacts are generated and gitignored, so they never arrive via git.`,
-    see: 'spex self doctor (verify the render actually reaches an agent)',
+    see: 'spex doctor (verify the render actually reaches an agent)',
+  },
+  doctor: {
+    line: 'doctor                diagnose whether the workflow actually reaches this agent — per-layer, per-harness',
+    body: `Usage: spex doctor             per-layer coverage report: preconditions · git-hook floor · contract ·
+                               hooks + handler existence · backend — for every harness materialize renders
+       spex doctor contract    print the composed surface:system text any agent here reads
+       spex doctor conflicts   detect double-delivery (loose artifacts beside the managed ones)
+
+Run it when a worker seems to be missing its contract or hooks — it names the broken layer and the
+repair, instead of you diffing materialized files by hand.`,
+    see: 'spex materialize (re-render the artifacts doctor checks)',
   },
   serve: {
     line: 'serve                 run the API backend (default :8787)  [--port N] [--public --password pw]',
@@ -270,16 +352,20 @@ artifacts are generated and gitignored, so they never arrive via git.`,
 
 Runs the backend for the repo at cwd behind a zero-downtime supervisor (hot-reloads on source
 change; the public port never gaps). --port pairs with \`spex dashboard --api-port\`, so many
-projects coexist on one host. --public exposes it on a public IP behind a password + self-signed
-TLS (own cert via --tls-cert/--tls-key; --http drops TLS).`,
+projects coexist on one host. On a successful bind it RECORDS its endpoint in the per-project
+runtime tier — that's how a bare \`spex\` run from this project's tree finds this backend (see
+spex guide config → BACKEND ROUTING). --public exposes it on a public IP behind a password +
+self-signed TLS (own cert via --tls-cert/--tls-key; --http drops TLS).`,
     see: 'spex dashboard (the UI on top) · GET /health (liveness probe)',
   },
   dashboard: {
     line: 'dashboard             serve the dashboard UI (default :5173), proxying /api to a running serve',
-    body: `Usage: spex dashboard [--port N=5173] [--api-port N=8787]
+    body: `Usage: spex dashboard [--port N=5173] [--api-port N=8787] [--host H=127.0.0.1]
 
 Serves the bundled dashboard on its own port and proxies /api + the terminal socket to a running
-\`spex serve\`. The installed replacement for the dev-only \`npm run web\`.`,
+\`spex serve\`. The installed replacement for the dev-only \`npm run web\`. Loopback-only by default;
+--host 0.0.0.0 (or a specific interface) opens it to a LAN/tailnet — still plain HTTP with no gate,
+so bind wide only on a network you trust (for the internet, use \`spex serve --public\`).`,
     see: 'spex serve (must be running first)',
   },
 
@@ -324,6 +410,7 @@ Usage: spex <command> [args]      one command's usage: spex help <command>  (or
 Find & read the graph
   ${ENTRIES.search.line}
   ${ENTRIES.owner.line}
+  ${ENTRIES.tree.line}
   ${ENTRIES.board.line}
   ${ENTRIES.guide.line}
 
@@ -335,7 +422,6 @@ Author & verify (the worker loop)
   ${ENTRIES.issues.line}
   ${ENTRIES.remark.line}
   ${ENTRIES.forge.line}
-  ${ENTRIES.self.line}
 
 Dispatch & manage sessions (the manager loop)
   ${ENTRIES.new.line}
@@ -343,6 +429,7 @@ Dispatch & manage sessions (the manager loop)
   ${ENTRIES.watch.line}
   ${ENTRIES.wait.line}
   ${ENTRIES.review.line}
+  ${ENTRIES.eval.line}
   ${ENTRIES.merge.line}
   ${ENTRIES.session.line}
 
@@ -350,11 +437,14 @@ Install & serve (the operator loop)
   ${ENTRIES.init.line}
   ${ENTRIES.uninstall.line}
   ${ENTRIES.materialize.line}
+  ${ENTRIES.doctor.line}
   ${ENTRIES.serve.line}
   ${ENTRIES.dashboard.line}
 
 ${SEL_NOTE}
 
+${ROUTING_NOTE}
+
 Concepts & best practice live in the guide: spex guide (setup) · guide spec · guide yatsu · guide config.
 Machine plumbing (hook/launch-script callees) lives under \`spex internal\` — not part of your vocabulary.`
 }

package/spec-cli/src/index.ts

@@ -4,8 +4,8 @@ import { cors } from 'hono/cors'
 import { etag } from 'hono/etag'
 import { createNodeWebSocket } from '@hono/node-ws'
 import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig } from './specs.js'
-import { issuesEnabled, postLocalIssue, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
-import { closeIssue, mergedIssues, replyIssue } from './issues.js'
+import { issuesEnabled, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
+import { closeIssue, createIssue, issueStores, mergedIssues, promote, replyIssue } from './issues.js'
 import { residentForgeState, refreshForgeNow } from '../../spec-forge/src/resident.js'
 import { summarize } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
@@ -13,7 +13,7 @@ import { getBoardJson } from './boardCache.js'
 import { boardStream, notifyBoardChanged } from './boardStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
 import { newSession, listSessions, sendKeys, rawKey, exitSession, closeSession, reopen, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, superviseQueue } from './sessions.js'
-import { defaultHarness, HARNESSES, launcherList, defaultLauncher } from './harness.js'
+import { defaultHarness, HARNESSES, launcherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-yatsu/src/evaltab.js'
 import { putBlob } from '../../spec-yatsu/src/cache.js'
 import { yatsuNodes } from '../../spec-yatsu/src/yatsu.js'
@@ -146,11 +146,11 @@ app.get('/api/config', (c) => c.json(loadConfig()))
 // the named launcher profiles ([[launcher-select]]) the New-Session form's dropdown offers — `{ name, harness }`
 // only (the `cmd` is a host secret, never shipped to the browser) — plus the configured `default` NAME so the
 // dropdown pre-selects the SAME launcher a bare `spex new` uses (the CLI/config default), instead of the
-// alphabetically-first one. `launchers` is empty (and `default` '') when a project configured none, so the form
-// falls back to the plain harness picker.
+// alphabetically-first one. Missing defaultLauncher is returned as an actionable config error, not hidden by
+// falling through to the built-in `claude` launcher.
 app.get('/api/launchers', (c) => c.json({
   launchers: launcherList().map(({ name, harness }) => ({ name, harness })),
-  default: defaultLauncher(),
+  ...launcherDefault(),
 }))
 // the ISSUES read surface ([[issues]]) for the dashboard's issues page — the merged list over every store
 // (local threads + the resident forge slice), the SAME mergedIssues() the CLI drain reads, verbatim
@@ -159,6 +159,7 @@ app.get('/api/launchers', (c) => c.json({
 app.get('/api/issues', etag(), (c) =>
   c.json({
     enabled: issuesEnabled(),
+    stores: issueStores(),
     issues: mergedIssues({ host: 'github', state: residentForgeState() }, loadSpecsLite().map((s) => s.id)),
   }))
 // the WRITE surface ([[local-issues]] / [[issues-view]]) — the human reply path, STORE-ROUTED through the one
@@ -211,10 +212,34 @@ app.post('/api/issues', async (c) => {
   if (!concern) return c.json({ error: 'empty concern' }, 400)
   const nodes = Array.isArray(body?.nodes) ? (body.nodes as unknown[]).filter((n): n is string => typeof n === 'string') : []
   const postBody = typeof body?.body === 'string' ? body.body : undefined
+  const store = typeof body?.store === 'string' && body.store.trim() ? body.store.trim() : 'local'
   // typed evidence[] — yatsu content-addressed hashes (the annotator's clip reference rides here, not prose)
   const evidence = Array.isArray(body?.evidence) ? (body.evidence as unknown[]).filter((h): h is string => typeof h === 'string' && /^[0-9a-f]{64}$/.test(h)) : []
-  const { thread, outcomes } = await postLocalIssue(concern, { nodes, body: postBody, evidence, author: 'human' })
-  return c.json({ ok: true, id: thread.id, outcomes: summarize(outcomes) }, 201)
+  try {
+    const r = await createIssue(concern, { store, nodes, body: postBody, evidence, author: 'human' })
+    if (r.store !== 'local') await refreshForgeNow()
+    return c.json({ ok: true, id: r.id, store: r.store, url: r.url, outcomes: summarize(r.outcomes) }, 201)
+  } catch (e) {
+    return c.json({ error: String((e as Error).message || e) }, store === 'local' ? 500 : 502)
+  }
+})
+
+// promotion moves an open local thread to the forge as one recorded action ([[issues]]'s promote verb,
+// verbatim: forge issue first, then the permalink reply + local close. The forced forge read-back means
+// the reload that follows shows the promoted issue in the merged list. Fail loud: an unreachable forge is a
+// 502 with the local thread untouched.
+app.post('/api/issues/:id/promote', async (c) => {
+  if (!issuesEnabled()) return c.json({ error: 'issues workflow is off' }, 403)
+  const id = c.req.param('id')
+  if (id.includes('#')) return c.json({ error: 'only a local issue promotes' }, 400)
+  try {
+    const r = await promote(id, { author: 'human' })
+    await refreshForgeNow()
+    return c.json({ ok: true, ...r })
+  } catch (e) {
+    const msg = String((e as Error).message || e)
+    return c.json({ error: msg }, /^no local issue/.test(msg) ? 404 : 502)
+  }
 })
 
 // the REMARK write surface ([[remark-substrate]]) — server PARITY with the CLI: the dashboard can author /
@@ -222,9 +247,11 @@ app.post('/api/issues', async (c) => {
 // capability. A ref (`<thread-id>#<rid>`) rides the request BODY, not the path (a '#' in a URL is a
 // fragment). Identity is derived SERVER-SIDE — this is the dashboard's human surface, so the actor is
 // `'human'`, the SAME sentinel /api/issues stamps; it is NEVER read from the request body. That keeps R3's
-// teeth structural (identity is not spoofable over the wire) and honest on both surfaces: resolve rejects
-// `'human'` (agent-only — an agent resolves through the CLI, never the dashboard), and retract binds to the
-// human who authored (only their own `'human'` remarks). Who-may-resolve/retract cannot depend on transport.
+// teeth structural (identity is not spoofable over the wire) and identical on both surfaces: resolve is any
+// SECOND party's deliberate judgment — the human resolves an agent's remark here exactly as an agent
+// resolves through the CLI, and self-resolve stays rejected by the same identity comparison ('human' can
+// never resolve a human-authored remark) — and retract binds to the author (only the human's own remarks).
+// Who-may-resolve/retract cannot depend on transport.
 app.post('/api/remarks', async (c) => {
   if (!issuesEnabled()) return c.json({ error: 'issues workflow is off' }, 403)
   const body = await c.req.json().catch(() => ({}))
@@ -299,15 +326,15 @@ app.post('/api/sessions', async (c) => {
   const body = await c.req.json().catch(() => ({}))
   const prompt = typeof body?.prompt === 'string' ? body.prompt : ''
   if (!prompt.trim()) return c.json({ error: 'empty prompt' }, 400)
-  const harness = typeof body?.harness === 'string' ? body.harness : undefined
+  if (typeof body?.harness === 'string') return c.json({ error: 'harness is not a create-session input; use launcher' }, 400)
   // the named launcher ([[launcher-select]]) — fixes the session's harness AND its persisted launch command.
   const launcher = typeof body?.launcher === 'string' && body.launcher.trim() ? body.launcher.trim() : undefined
   // parent = the spawning session's id, resolved by the CALLER (createSession) in its own process and passed
   // through here ([[session-nesting]]); the browser's New Session omits it → a top-level session.
   const parent = typeof body?.parent === 'string' && body.parent.trim() ? body.parent.trim() : null
   try {
-    return c.json(await newSession(typeof body?.node === 'string' ? body.node : null, prompt, harness, parent, launcher), 201)
-  } catch (e) { return c.json({ error: String((e as Error).message || e) }, 400) }   // unknown harness/launcher id → 400, not a 500
+    return c.json(await newSession(typeof body?.node === 'string' ? body.node : null, prompt, parent, launcher), 201)
+  } catch (e) { return c.json({ error: String((e as Error).message || e) }, 400) }   // unknown launcher id → 400, not a 500
 })
 // one server-side merge bundle (ahead/dirty/diff(merge-base)/gates/proposal) for the manager cockpit;
 // dashboard and `spex review` are thin callers. 404 for an unknown id. See [[manager-cockpit]].