spexcode 0.2.1 → 0.2.3

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,8 +352,10 @@ 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: {
@@ -326,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}
 
@@ -337,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}
@@ -345,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}
 
@@ -352,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

@@ -5,7 +5,7 @@ import { etag } from 'hono/etag'
 import { createNodeWebSocket } from '@hono/node-ws'
 import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig } from './specs.js'
 import { issuesEnabled, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
-import { closeIssue, createIssue, issueStores, mergedIssues, replyIssue } from './issues.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
@@ -224,14 +224,34 @@ app.post('/api/issues', async (c) => {
   }
 })
 
+// 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 /
 // resolve / retract a remark through the SAME functions `spex remark|resolve|retract` call, adding no
 // 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(() => ({}))
@@ -306,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]].

package/spec-cli/src/issues.ts

@@ -10,7 +10,7 @@
 import type { ForgeIssue, ForgePR } from '../../spec-forge/src/port.js'
 import { resolveLinks } from '../../spec-forge/src/links.js'
 import { DEFAULT_FORGE_HOST, FORGE_DRIVERS, forgeDriverFor, forgeIssueStores } from '../../spec-forge/src/drivers.js'
-import { loadLocalIssues, loadOne, postLocalIssue, reply, resolve, issuesEnabled, replyLocalIssue, runIssueWrite, ISSUE_WRITE_SUBS } from './localIssues.js'
+import { closeLocalIssue, loadLocalIssues, loadOne, postLocalIssue, reply, issuesEnabled, replyLocalIssue, runIssueWrite, ISSUE_WRITE_SUBS } from './localIssues.js'
 import { dispatchMentions, parseMentions, type DispatchOutcome, type LoopIn } from './mentions.js'
 import { envSessionId } from './layout.js'
 import { loadSpecsLite } from './specs.js'
@@ -36,9 +36,8 @@ export type Issue = {
   store: string      // 'local' | a forge host ('github') — the adapter that holds it
   concern: string
   by: string
-  status: string     // its own lifecycle: local open|accepted|rejected|landed; forge open|closed
+  status: string     // its own lifecycle: local open|landed; forge open|closed
   nodes: string[]
-  signers: string[]
   created: string
   body: string
   replies: Reply[]
@@ -122,7 +121,6 @@ export function fromForge(slice: ForgeSlice, nodeIds: string[]): Issue[] {
     by: i.author,
     status: (i.state || '').toLowerCase(),
     nodes: nodesByNumber.get(i.number) ?? [],
-    signers: [],
     created: i.createdAt,
     body: i.body,
     // the forge comments ARE the thread — the same Reply shape a local thread carries, so nothing
@@ -148,10 +146,15 @@ export function mergedIssues(forge: ForgeSlice | null, nodeIds: string[]): Issue
     .sort((a, b) => b.created.localeCompare(a.created))
 }
 
+// @@@ createIssue - the ONE creation port, store-routed ([[issues]]): the dashboard's New form
+// (POST /api/issues) and `spex issues open [--store <store>]` run this SAME routine. Default local commits
+// to the trunk store; a forge store creates the REAL forge issue through that store's driver, its body
+// carrying the `Spec: <nodes>` marker so the existing tracer read links it straight back — no promote
+// round-trip needed when the concern is born forge-visible.
 export async function createIssue(
   concern: string,
   opts: { store?: string; nodes?: string[]; body?: string; evidence?: string[]; author?: string } = {},
-): Promise<{ store: string; id: string; url?: string; outcomes: DispatchOutcome[] }> {
+): Promise<{ store: string; id: string; nodes: string[]; url?: string; outcomes: DispatchOutcome[] }> {
   const store = opts.store || 'local'
   const author = opts.author || envSessionId() || 'unknown'
   if (store === 'local') {
@@ -161,7 +164,7 @@ export async function createIssue(
       evidence: opts.evidence,
       author,
     })
-    return { store: 'local', id: thread.id, outcomes }
+    return { store: 'local', id: thread.id, nodes: thread.nodes, outcomes }
   }
 
   const driver = forgeDriverFor(store)
@@ -173,7 +176,7 @@ export async function createIssue(
   })
   const id = `${driver.host}#${number}`
   const outcomes = await dispatchMentions(opts.body || concern, { threadId: id, node: nodes[0] || null, author, status: 'open' })
-  return { store: driver.host, id, url, outcomes }
+  return { store: driver.host, id, nodes, url, outcomes }
 }
 
 // @@@ promote - the ONE cross-store verb ([[issues]]): a local concern that outgrew the repo moves to the
@@ -181,9 +184,11 @@ export async function createIssue(
 // body + the `Spec: <nodes>` marker (the round-trip: the existing tracer read links it straight back to
 // the same nodes, no new linking code) + the evidence hashes + a provenance footer — and created through
 // the driver (the only network toucher). ORDER makes failure safe: create the forge issue FIRST; only
-// then close the local thread out (a reply carrying the permalink, then resolve `landed`) — an
+// then close the local thread out (a reply carrying the permalink, then status `landed`) — an
 // unreachable forge throws with the local thread untouched, and only an `open` thread promotes.
-export async function promote(id: string): Promise<{ url: string; number: number; host: string }> {
+// `author` mirrors the other write verbs: the effective session id by default, `'human'` from the dashboard.
+export async function promote(id: string, opts: { author?: string } = {}): Promise<{ url: string; number: number; host: string }> {
+  const author = opts.author || envSessionId() || 'unknown'
   const t = loadOne(id)
   if (t.status !== 'open') throw new Error(`'${id}' is ${t.status} — only an open local issue promotes`)
   const driver = forgeDriverFor(DEFAULT_FORGE_HOST)
@@ -192,11 +197,11 @@ export async function promote(id: string): Promise<{ url: string; number: number
     t.body,
     t.nodes.length ? `\nSpec: ${t.nodes.join(', ')}` : '',
     t.evidence.length ? `\nEvidence: ${t.evidence.join(', ')} (yatsu blob hashes)` : '',
-    `\n---\nPromoted from the local issue \`${id}\` (opened by ${t.by} @ ${t.created}; promoted by ${envSessionId() || 'unknown'}).`,
+    `\n---\nPromoted from the local issue \`${id}\` (opened by ${t.by} @ ${t.created}; promoted by ${author}).`,
   ].filter(Boolean).join('\n')
   const { number, url } = await driver.createIssue({ title: t.concern, body })
-  reply(id, `promoted to the forge: ${url}`)
-  resolve(id, 'landed')
+  reply(id, `promoted to the forge: ${url}`, author)
+  closeLocalIssue(id)
   return { url, number, host: driver.host }
 }
 
@@ -230,11 +235,11 @@ export async function replyIssue(
 }
 
 // @@@ closeIssue - ONE lifecycle close over every store ([[issues]]): the issue owns its status, so the
-// dashboard Close button routes by id and never writes node state. Local closes resolve the local thread
+// dashboard Close button routes by id and never writes node state. Local closes mark the local thread
 // `landed`; forge closes call the driver's close verb and let the forced read-back reveal the closed state.
 export async function closeIssue(id: string): Promise<{ store: string; status: string; url?: string }> {
   const forge = /^([A-Za-z0-9-]+)#(\d+)$/.exec(id)
-  if (!forge) return { store: 'local', status: resolve(id, 'landed').as }   // resolve() returns {as, already} since the idempotent-write change; status stays the plain string
+  if (!forge) return { store: 'local', status: closeLocalIssue(id).status }
   const driver = forgeDriverFor(forge[1])
   if (!driver) throw new Error(`unknown forge host '${forge[1]}' — known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')}`)
   const { url } = await driver.closeIssue({ number: parseInt(forge[2], 10) })
@@ -250,25 +255,48 @@ const hasFlag = (args: string[], name: string) => args.includes(`--${name}`)
 
 // `spex issues …` — the ONE issues surface. Bare (with filters) it is THE read over every store: the
 // drain view a supervisor/human works from, `[--node id] [--store local|<host>] [--all] [--json]`. A write
-// first-positional (open|reply|sign|resolve|on|off|status|nudge — localIssues.ts) routes to the store's
-// write verbs; `promote` is the one cross-store verb. The list imposes NO salience ranking — recurrence
-// (signers, replies) is a signal the drain WEIGHS by judgment, never an automatic priority order. The forge
-// slice is a LIVE pull; an unreachable forge degrades loudly to local-only (one stderr note) — local
-// reading never hostages on a network.
+// first-positional (open|reply|on|off|status|nudge — localIssues.ts) routes to the store's
+// write verbs (open and reply are themselves store-routed: `open --store <host>` / a `<host>#<n>` id go
+// through the driver); `close` is the store-routed lifecycle verb (the SAME closeIssue the dashboard's
+// Close button calls); `promote` is the one cross-store verb. The list imposes NO salience ranking —
+// replies are a signal the drain WEIGHS by judgment, never an automatic priority
+// order. The forge slice is a LIVE pull; an unreachable forge degrades loudly to local-only (one stderr
+// note) — local reading never hostages on a network.
 export async function runIssues(args: string[]): Promise<number> {
   if (ISSUE_WRITE_SUBS.has(args[0])) return runIssueWrite(args)
+  if (args[0] === 'close') {
+    // the CLI leg of the ONE close verb ([[issues]] closeIssue — the same routing POST /api/issues/:id/close
+    // runs): a local id resolves the thread `landed`, a forge id (`<host>#<n>`) closes the remote issue
+    // through the driver. Lifecycle on the issue object, never node state.
+    const id = args[1]
+    if (!id || id.startsWith('--')) { console.error('usage: spex issues close <issue-id>   (a local id, or a forge id like github#12)'); return 2 }
+    try {
+      const r = await closeIssue(id)
+      console.log(r.store === 'local'
+        ? `closed '${id}' — local thread landed`
+        : `closed '${id}' on ${r.store}${r.url ? `  ${r.url}` : ''}`)
+      return 0
+    } catch (e) {
+      console.error(`spex issues close: ${e instanceof Error ? e.message : e}`)
+      return 1
+    }
+  }
   if (args[0] === 'promote') {
     const id = args[1]
     if (!id || id.startsWith('--')) { console.error('usage: spex issues promote <local-issue-id>'); return 2 }
     try {
       const r = await promote(id)
-      console.log(`promoted '${id}' → ${r.host}#${r.number}  ${r.url}\n  local thread resolved landed (permalink recorded in its reply trail)`)
+      console.log(`promoted '${id}' → ${r.host}#${r.number}  ${r.url}\n  local thread closed landed (permalink recorded in its reply trail)`)
       return 0
     } catch (e) {
       console.error(`spex issues promote: ${e instanceof Error ? e.message : e}`)
       return 1
     }
   }
+  if (args[0] && !args[0].startsWith('--')) {
+    console.error(`spex issues: unknown subcommand '${args[0]}'`)
+    return 2
+  }
   const nodeIds = loadSpecsLite().map((s) => s.id)
   let forge: ForgeSlice | null = null
   try {
@@ -292,7 +320,6 @@ export async function runIssues(args: string[]): Promise<number> {
     const tags = [p.store, p.status !== 'open' ? `[${p.status}]` : '', p.nodes.length ? `re: ${p.nodes.join(', ')}` : '', p.by ? `by ${p.by}` : ''].filter(Boolean).join('  ·  ')
     console.log(`• ${p.concern}  [${p.id}]`)
     console.log(`    ${tags}`)
-    if (p.signers.length) console.log(`    +${p.signers.length} signed: ${p.signers.join(', ')}`)
     if (p.replies.length) console.log(`    ${p.replies.length} reply(ies) in thread`)
     if (p.url) console.log(`    ${p.url}`)
   }