spexcode 0.2.1 → 0.2.2

package/spec-cli/src/layout.ts

@@ -27,14 +27,14 @@ type Config = {
   }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)
-    claudeCmd?: string             // the UNNAMED default worker launcher for Claude (default 'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides. A host-specific ABS path belongs in the gitignored spexcode.local.json, not here.
-    codexCmd?: string              // the UNNAMED default worker launcher for Codex (default 'codex --yolo'); env SPEXCODE_CODEX_CMD overrides. Same host-path rule.
+    claudeCmd?: string             // the built-in `claude` launcher command (default 'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides. A host-specific ABS path belongs in the gitignored spexcode.local.json, not here.
+    codexCmd?: string              // the built-in `codex` launcher command (default 'codex --yolo'); env SPEXCODE_CODEX_CMD overrides. Same host-path rule.
     // named launcher profiles: a session picks ONE by name at create time ([[launcher-select]]), fixing both
     // its harness AND its exact launch command; the chosen NAME is persisted on the record so resume reuses the
     // same auth. `harness` defaults to 'claude'. Host-specific `cmd`s (abs wrapper paths) belong in the
     // gitignored spexcode.local.json — the name is portable, the cmd is a machine fact.
     launchers?: { [name: string]: { harness?: 'claude' | 'codex'; cmd: string } }
-    defaultLauncher?: string       // the launcher a create with no explicit --launcher/dropdown pick uses (else the unnamed claudeCmd/codexCmd path)
+    defaultLauncher?: string       // the launcher a create with no explicit --launcher/dropdown pick uses; required for no-choice creates
   }
   serve?: {
     // public-exposure config for `spex serve --public` (resolved gateway-side; see [[public-mode]] / gateway.ts).
@@ -161,7 +161,7 @@ export type RawRecord = {
   node: string | null; title: string | null; name: string | null; parent?: string | null
   status: string; proposal: string | null; merges: number; note: string | null
   sortkey: number | null; createdAt: number; harness?: string; harness_session_id?: string
-  launcher?: string   // the named launcher profile this session was created under ([[launcher-select]]); absent/empty → the unnamed global default
+  launcher?: string   // the launcher profile this session was created under ([[launcher-select]]); absent/empty only on old records predating launchers
   launch_cmd?: string // the RESOLVED base launcher command PINNED at creation, so a resume replays the EXACT launcher (and its config-dir env) that made the conversation, never a since-changed default ([[launcher-select]] resume-launcher-pin); absent → old record, fall back to the launcher name / ambient
 }
 // the agent's OWN session id from the environment — the only locator now that the record left the worktree.

package/spec-cli/src/localIssues.ts

@@ -2,7 +2,7 @@
 // [[mentions]]). A thread IS an Issue whose `store` is 'local' — membership implied by WHERE the file lives,
 // never written into it. One thread = one PLAIN markdown file at <main>/.spec/.issues/<id>.md; there is
 // deliberately no content-kind taxonomy (a change suggestion, an annotation, a Q&A are the same mechanism —
-// the prose says what it is). Others sign/reply/discuss like an async chatroom; a supervisor drains it via
+// the prose says what it is). Others reply/discuss like an async chatroom; a supervisor drains it via
 // `spex issues` (reading is the port's job, issues.ts — this module owns only the store + its write verbs).
 // Because a thread file is NOT named spec.md, the spec walk never nodes it and isSpecMd ignores it —
 // invisible to lint / drift / deriveStatus / board with ZERO exemption. The store lives on the TRUNK, not
@@ -87,10 +87,9 @@ const currentSession = (): string => envSessionId() || 'unknown'
 const sleep = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
 
 // ── file format ──────────────────────────────────────────────────────────────────────────────────────
-// frontmatter (concern/by/status/nodes/evidence/signers/created) + a prose body, then any replies — each
+// frontmatter (concern/by/status/nodes/evidence/created) + a prose body, then any replies — each
 // preceded by a `<!-- reply: <by> @ <iso> -->` sentinel: invisible in rendered markdown, unambiguous to
-// parse. Only the store writes these files, so a fixed shape is safe. Lists are `key: a, b` scalars so a
-// +1 sign is a one-line change.
+// parse. Only the store writes these files, so a fixed shape is safe.
 //
 // A REMARK ([[remark-substrate]]) is a reply carrying extra state, appended to the SAME sentinel as a
 // ` :: <space-joined k=v attrs>` tail (a plain reply has no tail → parses unchanged, backward compatible):
@@ -120,9 +119,8 @@ function parse(id: string, text: string): Issue {
     store: 'local',
     concern: fm.concern || id,
     by: fm.by || 'unknown',
-    status: fm.status || 'open',
+    status: fm.status === 'landed' ? 'landed' : 'open',
     nodes: list(fm.nodes),
-    signers: list(fm.signers),
     created: fm.created || '',
     body: body.join('\n').trim(),
     replies: replies.map((r) => ({ ...r, body: r.body.trim() })),
@@ -165,7 +163,6 @@ function serialize(p: Issue): string {
     `status: ${safeScalar(p.status)}`,
     p.nodes.length ? `nodes: ${p.nodes.join(', ')}` : '',
     p.evidence.length ? `evidence: ${p.evidence.join(', ')}` : '',
-    p.signers.length ? `signers: ${p.signers.join(', ')}` : '',
     `created: ${p.created}`,
   ].filter(Boolean)
   let out = `---\n${fm.join('\n')}\n---\n\n${safeBody(p.body)}\n`
@@ -259,7 +256,7 @@ function ensureStoreMigrated(): void {
 // structurally invisible to spec-lint, and the commit is provably store-only (one .spec/.issues/ path), so the
 // pre-commit gate would only pass anyway — running it just burns seconds (tsx cold-start) holding the lock.
 // A NO-CHANGE write is idempotent SUCCESS, never a failure: when the serialized bytes already equal the
-// stored state (a duplicate resolve/sign — the store IS the requested state), `git commit` would exit 1
+// stored state (a duplicate close — the store IS the requested state), `git commit` would exit 1
 // 'nothing to commit', so we detect the no-op after `add` (the staged path equals HEAD → status is silent)
 // and skip the commit. Returns whether the store actually changed, so a caller can say 'already <state>'.
 // MUST run while holding withStoreLock — it is the write half of a locked read-modify-write; its callers
@@ -286,7 +283,7 @@ function writeStoreFile(p: Issue, message: string): boolean {
 }
 
 // prepare (a FRESH read-modify or a new thread) + write + commit a single store file, all under the store
-// lock so the read-modify-write is atomic. prepare() runs INSIDE the lock, so a reply/sign/resolve reads the
+// lock so the read-modify-write is atomic. prepare() runs INSIDE the lock, so a reply/close reads the
 // current thread, never a stale copy. A pre-rename store migrates first (before the lock — ensure takes it).
 // `changed: false` = the store already held exactly this state (see writeStoreFile) — success, nothing committed.
 function commitStore(message: string, prepare: () => Issue): { issue: Issue; changed: boolean } {
@@ -312,7 +309,6 @@ export function openIssue(concern: string, opts: { nodes?: string[]; body?: stri
     by: opts.author || currentSession(),
     status: 'open',
     nodes,
-    signers: [],
     created: new Date().toISOString(),
     body: (opts.body || `(no detail given — ${concern})`).trim(),
     replies: [],
@@ -395,25 +391,13 @@ export async function postLocalIssue(
   return { thread, outcomes }
 }
 
-export function sign(id: string): string[] {
-  const by = currentSession()
-  return commitStore(`issue(${id}): signed by ${by}`, () => {
+export function closeLocalIssue(id: string): { status: 'landed'; already: boolean } {
+  const { changed } = commitStore(`issue(${id}): close`, () => {
     const p = loadOne(id)
-    if (!p.signers.includes(by)) p.signers.push(by)
-    return p
-  }).issue.signers
-}
-
-const RESOLUTIONS = new Set(['accepted', 'rejected', 'landed'])
-// `already` = the thread was in that state before this call — an idempotent success, nothing committed.
-export function resolve(id: string, as: string): { as: string; already: boolean } {
-  if (!RESOLUTIONS.has(as)) throw new Error(`resolution must be one of: ${[...RESOLUTIONS].join(' | ')}`)
-  const { changed } = commitStore(`issue(${id}): resolve ${as}`, () => {
-    const p = loadOne(id)
-    p.status = as
+    p.status = 'landed'
     return p
   })
-  return { as, already: !changed }
+  return { status: 'landed', already: !changed }
 }
 
 // ── remarks ([[remark-substrate]]) ──────────────────────────────────────────────────────────────────
@@ -439,7 +423,7 @@ function findOrCreateEvalThread(node: string, scenario: string, author: string):
     if (existing) return existing
     const p: Issue = {
       id: uniqueId(concern), store: 'local', concern, by: author, status: 'open',
-      nodes: [node], signers: [], created: new Date().toISOString(),
+      nodes: [node], created: new Date().toISOString(),
       body: `Remarks on the \`${scenario}\` eval of [[${node}]].`, replies: [], evidence: [],
     }
     writeStoreFile(p, `issue: ${concern}`)
@@ -479,16 +463,18 @@ function parseRemarkRef(ref: string): { id: string; rid: string } {
   return { id: ref.slice(0, i), rid: ref.slice(i + 1) }
 }
 
-// resolve a remark (R3): a DELIBERATE call, agent-only (the dashboard's `human` is rejected — a human
-// RETRACTS their own, resolve is a second party's judgment), NEVER the author (no self-resolve), and
-// MONOTONIC (no un-resolve — a regression is a NEW remark). `by` is the resolving party.
+// resolve a remark (R3): a DELIBERATE call by a SECOND PARTY — never the author (no self-resolve: an
+// identity comparison, so the dashboard's `human` cannot resolve a human-authored remark either), and
+// MONOTONIC (no un-resolve — a regression is a NEW remark). The resolver's identity is derived by the
+// SURFACE ([[remark-substrate]] LAW L): a governed session id from the CLI, the `human` sentinel from the
+// dashboard — both are real second parties, so the same rule runs on both. `by` is the resolving party.
 export function resolveRemark(ref: string, by: string): { thread: Issue; rid: string } {
   const { id, rid } = parseRemarkRef(ref)
   const { issue: thread } = commitStore(`remark(${id}#${rid}): resolved by ${by}`, () => {
     const p = loadOne(id)
     const r = p.replies.find((x) => x.rid === rid)
     if (!r) throw new Error(`no remark '${ref}' in that thread`)
-    if (!by || by === 'human' || by === 'unknown') throw new Error(`resolve is agent-only (needs a real session identity, got '${by || 'none'}'): a human withdraws their own remark with \`spex retract\`, not resolve`)
+    if (!by || by === 'unknown') throw new Error(`resolve needs a real identity (got '${by || 'none'}'): run it under a governed session, or from the dashboard (its actor is 'human')`)
     if (r.resolved) throw new Error(`remark '${ref}' is already resolved — monotonic: a regression is a NEW remark, never an un-resolve`)
     if (r.by === by) throw new Error(`refusing to self-resolve '${ref}': the author (${by}) may not resolve their own remark — resolve is a second party's deliberate judgment`)
     r.resolved = true; r.resolvedBy = by; r.resolvedAt = new Date().toISOString()
@@ -525,16 +511,16 @@ export function nudge(node: string): string {
     '── issues ─────────────────────────────────────────────────────────',
     `Your work (${node || 'this node'}) just landed. Two issue checks before you close:`,
     '',
-    '1. CLOSE what you finished. An issue whose work just landed is resolved, not',
+    '1. CLOSE what you finished. An issue whose work just landed is closed, not',
     '   left open — the open set is the OUTSTANDING work, so a stale open reads as a',
-    '   lie:  spex issues --store local     then   spex issues resolve <id> --as landed',
+    '   lie:  spex issues --store local     then   spex issues close <id>',
     '',
     '2. RECORD only what OUTLIVES this task — a concern you are NOT acting on now:',
     '   an off-mainline smell / awkward boundary / wish, or a trivial-but-must-not-',
     "   forget to-do that doesn't earn a spec node. NOT a bug tracker (that is the",
     '   spec graph + the forge), NOT your assigned task or a fix you are about to',
     '   make — those need no issue. Only the taste that would otherwise evaporate:',
-    '     spex issues                              # read first — sign/reply if already raised',
+    '     spex issues                              # read first — reply if already raised',
     '     spex issues open "<concern>" [--node <id>]   # else open one',
     'A supervisor drains the store later. (Advisory — skip if nothing is owed.)',
     '───────────────────────────────────────────────────────────────────',
@@ -547,7 +533,7 @@ export function nudge(node: string): string {
 // still-open local threads THIS session touched (authored or replied; eval `eval: <node> · <scenario>`
 // containers excluded — they host remarks and outlive every session by design) and prints NOTHING when the
 // session owes nothing, when the feature is OFF, or when there is no session identity. Some issues rightly
-// outlive their session (a taste concern waiting for the drain), so the ask is resolve OR say why it stays
+// outlive their session (a taste concern waiting for the drain), so the ask is close OR say why it stays
 // open — never a forced close.
 export function closeoutNudge(sessionId: string | null | undefined): string {
   if (!sessionId || sessionId === 'unknown' || !issuesEnabled()) return ''
@@ -555,7 +541,7 @@ export function closeoutNudge(sessionId: string | null | undefined): string {
     t.status === 'open' && !EVAL_CONCERN_RE.test(t.concern) &&
     (t.by === sessionId || t.replies.some((r) => r.by === sessionId)))
   if (!mine.length) return ''
-  return `\n\nIssue closeout — ${mine.length} still-open local issue(s) you touched (opened or replied): ${mine.map((t) => t.id).join(', ')}. For each, resolve it now if its work is finished (\`spex issues resolve <id> --as landed|rejected|accepted\`), or reply why it should stay open past this session (\`spex issues reply <id> --body "<why>"\`). Some issues rightly outlive their session — this is a reminder to sweep, not a gate.`
+  return `\n\nIssue closeout — ${mine.length} still-open local issue(s) you touched (opened or replied): ${mine.map((t) => t.id).join(', ')}. For each, close it now if its work is finished (\`spex issues close <id>\`), or reply why it should stay open past this session (\`spex issues reply <id> --body "<why>"\`). Some issues rightly outlive their session — this is a reminder to sweep, not a gate.`
 }
 
 // ───────────────────────── CLI ─────────────────────────
@@ -563,7 +549,7 @@ const fl = (args: string[], name: string): string | undefined => {
   const i = args.indexOf(`--${name}`)
   return i >= 0 ? args[i + 1] : undefined
 }
-const VALUE_FLAGS = new Set(['--node', '--body', '--as', '--evidence', '--scenario', '--code-sha'])
+const VALUE_FLAGS = new Set(['--node', '--body', '--evidence', '--scenario', '--code-sha', '--store'])
 // bare positionals, skipping flags + their values.
 function bare(args: string[]): string[] {
   const out: string[] = []
@@ -585,9 +571,10 @@ const repeated = (args: string[], name: string): string[] =>
   args.flatMap((a, i) => (a === `--${name}` ? [args[i + 1]] : [])).filter(Boolean) as string[]
 
 // the local-issue WRITE verbs, folded into the one issues surface (`spex issues <sub>` — the read routes
-// here when its first positional is a write sub): open "<concern>" [--node id…] [--evidence hash…]
-// [--body -|text], the id-based reply | sign | resolve, and the feature toggle on | off | status. `nudge`
-// is internal (the post-merge hook's caller). Store is a property of the issue, never a second command.
+// here when its first positional is a write sub): open "<concern>" [--store local|<host>] [--node id…]
+// [--evidence hash…] [--body -|text], the id-based reply, and the feature toggle
+// on | off | status. `nudge` is internal (the post-merge hook's caller). Store is a property of the issue,
+// never a second command — open and reply route by it (issues.ts createIssue/replyIssue).
 export async function runIssueWrite(args: string[]): Promise<number> {
   const sub = args[0]
   try {
@@ -611,35 +598,32 @@ export async function runIssueWrite(args: string[]): Promise<number> {
       if (s) console.log(`  ${s}`)
       return 0
     }
-    if (sub === 'sign') {
-      const id = bare(args.slice(1))[0]
-      if (!id) { console.error('usage: spex issues sign <issue-id>'); return 2 }
-      console.log(`signed '${id}' — signers: ${sign(id).join(', ')}`)
-      return 0
-    }
-    if (sub === 'resolve') {
-      const id = bare(args.slice(1))[0]
-      const as = fl(args, 'as')
-      if (!id || !as) { console.error('usage: spex issues resolve <issue-id> --as accepted|rejected|landed'); return 2 }
-      const r = resolve(id, as)
-      console.log(r.already ? `'${id}' already ${r.as} — store unchanged` : `resolved '${id}' → ${r.as}`)
-      return 0
-    }
     if (sub === 'nudge') {
       // internal: the post-merge hook calls this to print the (toggle-aware) nudge for a merged node.
       const text = nudge(bare(args.slice(1))[0] || '')
       if (text) console.log(text)
       return 0
     }
-    // `open`: start a new local issue. The concern is the bare positional(s) after the sub.
+    // `open`: start a new issue — STORE-ROUTED through the one creation port ([[issues]] createIssue, the
+    // same routine POST /api/issues runs): default local commits to the trunk store; `--store <host>`
+    // creates the real forge issue through that store's driver (no promote round-trip when the concern is
+    // born forge-visible). The concern is the bare positional(s) after the sub.
     const concern = sub === 'open' ? bare(args.slice(1)).join(' ').trim() : ''
     if (!concern) {
-      console.error('usage: spex issues open "<concern>" [--node <id>…] [--evidence <hash>…] [--body -|<text>]\n       spex issues reply|sign|resolve <issue-id> …  |  on|off|status')
+      console.error('usage: spex issues open "<concern>" [--store local|<host>] [--node <id>…] [--evidence <hash>…] [--body -|<text>]\n       spex issues reply|close|promote <issue-id> …  |  on|off|status')
       return 2
     }
-    const p = openIssue(concern, { nodes: repeated(args, 'node'), body: readBody(args), evidence: repeated(args, 'evidence') })
-    console.log(`opened '${p.id}'${p.nodes.length ? ` (re: ${p.nodes.join(', ')})` : ''} — committed to the local issue store; read it with \`spex issues\``)
-    const s = summarize(await dispatchMentions(p.body || concern, { threadId: p.id, node: p.nodes[0] || null, author: p.by, status: p.status }))
+    const r = await (await import('./issues.js')).createIssue(concern, {
+      store: fl(args, 'store'),
+      nodes: repeated(args, 'node'),
+      body: readBody(args),
+      evidence: repeated(args, 'evidence'),
+    })
+    const re = r.nodes.length ? ` (re: ${r.nodes.join(', ')})` : ''
+    console.log(r.store === 'local'
+      ? `opened '${r.id}'${re} — committed to the local issue store; read it with \`spex issues\``
+      : `opened '${r.id}' on ${r.store}${re} — ${r.url}`)
+    const s = summarize(r.outcomes)
     if (s) console.log(`  ${s}`)
     return 0
   } catch (e) {
@@ -650,7 +634,7 @@ export async function runIssueWrite(args: string[]): Promise<number> {
 
 // the first positionals runIssueWrite handles — the issues command routes these to it, everything else is
 // the read. Exported so the router and the runner can never drift.
-export const ISSUE_WRITE_SUBS = new Set(['open', 'reply', 'sign', 'resolve', 'on', 'off', 'status', 'nudge'])
+export const ISSUE_WRITE_SUBS = new Set(['open', 'reply', 'on', 'off', 'status', 'nudge'])
 
 // ── remark CLI ([[remark-substrate]]) — CLI-first: the whole author→resolve→retract loop, no server needed ──
 // `spex remark <host> --body -|<text> [--code-sha <sha>] [--scenario <name>] [--evidence <hash>…]`

package/spec-cli/src/materialize.ts

@@ -9,7 +9,6 @@ import { git } from './git.js'
 import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
 import { resolveHarnessTargets, partitionHarnesses } from './harness-select.js'
 import { emitPlugin, cleanPlugin, pluginBundleDir, pluginVersion } from './plugin-harness.js'
-import { tsxBin } from './tsx-bin.js'
 
 // @@@ materialize - the "pay-per-change" node step (≈0.85s) the cheap shell gate invokes ONLY when the
 // .config content-hash moved. It renders the spec tree's surface nodes into the flat artifacts each
@@ -26,7 +25,10 @@ import { tsxBin } from './tsx-bin.js'
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
-const SPEX = `${tsxBin(PKG)} ${join(PKG, 'src', 'cli.ts')}`
+// the ONE spex entry: the launcher (bin/spex.mjs), never a raw `tsx cli.ts` pair — the launcher owns tsx
+// resolution AND the mid-merge guard (a conflicted source tree degrades to one line + exit 75, not an
+// esbuild stacktrace), so every hook-baked callback inherits both.
+const SPEX = join(PKG, 'bin', 'spex.mjs')
 // the manifest + content-hash marker render into the GLOBAL per-project store (layout.runtimeRoot), NOT the
 // worktree — the worktree keeps zero SpexCode-rendered runtime; only the harness-discovered contract files +
 // shims (which the harness must find in-tree) are written under proj below.

package/spec-cli/src/mentions.ts

@@ -13,6 +13,18 @@ const NODE_RE = /\[\[([^\]\s]+)\]\]/g
 
 const uniq = (xs: string[]): string[] => [...new Set(xs)]
 
+// ── CLI sigil tolerance ───────────────────────────────────────────────────────────────────────────────
+// In FREE TEXT the sigils are required — they are what marks a reference apart from prose. In a CLI
+// ARGUMENT the whole token IS the reference, so the sigil is optional: `spex review @graph` ≡
+// `spex review graph`, `spex yatsu eval [[cli-surface]]` ≡ `spex yatsu eval cli-surface`. One shared strip,
+// applied by the session-selector matcher and every node-arg read site, so the habit a user learns in the
+// dashboard's input boxes works verbatim on the CLI — never a second grammar to learn.
+export function stripRefSigil(token: string): string {
+  const wrapped = /^\[\[(.*)\]\]$/.exec(token)
+  if (wrapped) return wrapped[1]
+  return token.startsWith('@') ? token.slice(1) : token
+}
+
 export function parseMentions(text: string): { actors: string[]; nodes: string[] } {
   const actors: string[] = []
   const nodes: string[] = []
@@ -47,6 +59,15 @@ export function resolveActors(tokens: string[], sessions: ActorSession[]): Resol
   })
 }
 
+// Any spawn's parent = its originator ([[session-nesting]]): the `@new` worker nests under the session that
+// wrote the mention — but ONLY when the author IS a real board session id. A dashboard 'human', a CLI
+// 'unknown', or a forge login resolves to no session → null → a top-level worker, never a phantom nest.
+// Exact id match only (lineage is provenance, not addressing — no prefix/name resolution), any liveness:
+// a parent that later closes is auto-promoted at read time by the derived tree.
+export function spawnParent(author: string, sessions: { id: string }[]): string | null {
+  return sessions.some((s) => s.id === author) ? author : null
+}
+
 // ── dispatch (integration) ─────────────────────────────────────────────────────────────────────────────
 export type DispatchOutcome = { token: string; result: 'sent' | 'spawned' | 'offline' | 'unresolved' | 'failed'; detail?: string; note?: string }
 
@@ -92,7 +113,7 @@ export async function dispatchMentions(
       // deliberate audit/re-measure), but the worker prompt carries the status and the outcome line warns.
       const settled = ctx.status && ctx.status !== 'open' ? ctx.status : undefined
       try {
-        const s = await newSession(ctx.node, newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status))
+        const s = await newSession(ctx.node, newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status), spawnParent(ctx.author, sessions))
         out.push({ token: r.token, result: 'spawned', detail: s.id, ...(settled ? { note: `thread ${settled}` } : {}) })
       } catch (e) { out.push({ token: r.token, result: 'failed', detail: e instanceof Error ? e.message : String(e) }) }
       continue

package/spec-cli/src/pty-bridge.ts

@@ -17,6 +17,11 @@ type Pending = (lines: Buffer[]) => void
 type Bridge = {
   id: string; pty: IPty; cols: number; rows: number; prewarmed: boolean
   repaintToken: number
+  // the size VOTE: whether this client currently asserts window size. Only a bridge some viewer has SIZED
+  // (visible connect / resize — never a hidden board-load connect) votes; all others carry tmux's
+  // ignore-size client flag and are size-NEUTRAL, so a foreign backend instance sharing the socket can
+  // never move a window a human is watching (see setVote).
+  voting: boolean
   // control-mode parser state: an incomplete-line BYTE buffer, the in-flight command block (%begin..%end) with
   // its command number, a FIFO of one resolver per command sent (tmux answers in order), and the last
   // %layout-change size so a repaint knows the pane already converged and needn't wait for the event.
@@ -269,10 +274,15 @@ function ensureBridge(id: string, prewarm = false): Bridge | null {
       env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' } as Record<string, string>,
     })
   } catch { return null }
-  b = { id, pty: p, cols, rows, prewarmed: prewarm, repaintToken: 0, buf: Buffer.alloc(0), block: null, blockNum: '', cmdQ: [], needsFull: true }
+  b = { id, pty: p, cols, rows, prewarmed: prewarm, repaintToken: 0, voting: false, buf: Buffer.alloc(0), block: null, blockNum: '', cmdQ: [], needsFull: true }
   bridges.set(id, b)
   const bx = b
   p.onData((d) => feed(bx, d as unknown as Buffer))   // encoding:null → d is a Buffer (typings say string)
+  // every client starts size-NEUTRAL: flag it before any refresh-client -C can enter the FIFO (a bare
+  // attach asserts nothing — measured: only -C moves a window — so there is no pre-flag race). Sent as a
+  // stream command, not an attach-time `-f`, so a pre-3.2 tmux degrades to a harmless in-stream %error
+  // (old size-fight behaviour) instead of a client that cannot attach at all.
+  void command(b, 'refresh-client -f ignore-size')
   // attach-session exited (session died or we detached): drop the bridge, unblock any awaiting command AND any
   // %layout-change waiter (no timer backs it now, so a bridge that dies mid-convergence MUST resolve its
   // waiter or the awaiting repaint hangs), and if viewers remain kick a reconcile to re-bind fast.
@@ -285,6 +295,19 @@ function ensureBridge(id: string, prewarm = false): Bridge | null {
   return b
 }
 
+// flip this client's size vote — the arbitration that makes ANY number of backend instances share one tmux
+// socket without size-fights. tmux's `ignore-size` client flag means "yield while any unflagged client is
+// attached" (server-wide, and void when ALL clients are flagged — then everyone counts again, which is what
+// keeps the single-backend warm hold working). So: a bridge votes (unflags) from the moment a viewer SIZES
+// it, and goes neutral again when its last viewer leaves. A suppressed refresh-client -C still receives its
+// one %layout-change (measured — announcing the window's real size), so the deterministic resize wait and
+// the accept-any-announced-size rule need no change on either side of the flag.
+function setVote(b: Bridge, on: boolean): void {
+  if (b.voting === on) return
+  b.voting = on
+  void command(b, `refresh-client -f ${on ? '!' : ''}ignore-size`)
+}
+
 function killBridge(id: string): void {
   const b = bridges.get(id)
   if (!b) return
@@ -312,6 +335,7 @@ export function attachViewer(id: string, v: Viewer, initialSize?: { cols: number
   if (!b) return false   // spawn failed → caller closes the socket → detachViewer prunes this subscriber
   b.needsFull = true     // a (re)connecting viewer's xterm is blank / just reset → its first frame must be FULL
   if (initialSize && initialSize.cols > 0 && initialSize.rows > 0) {
+    setVote(b, true)                                   // a sized viewer → this client asserts window size
     applySize(b, initialSize.cols, initialSize.rows)   // resize-then-repaint at the client's true size
   }
   // else HIDDEN connect (0×0, no size): paint nothing now — the first frame is driven purely by the client's
@@ -455,6 +479,7 @@ export function detachViewer(id: string, v: Viewer): void {
   subscribers.delete(id)
   const b = bridges.get(id)
   if (b && !b.prewarmed) killBridge(id)
+  else if (b) setVote(b, false)   // kept warm → back to size-neutral: an unwatched client must not out-vote a watched one
 }
 // a viewer fitted xterm → record the size as the last-known fit (even with no bridge yet, for pre-warm)
 // and resize the shared client. Repaints even on an unchanged size (a reconnect needs the frame). `full` (a
@@ -464,7 +489,7 @@ export function resizeBridge(id: string, cols: number, rows: number, full = fals
   if (!(cols > 0 && rows > 0)) return
   lastFit.set(id, { cols, rows }); lastFitAny = { cols, rows }
   const b = bridges.get(id)
-  if (b) { if (full) b.needsFull = true; applySize(b, cols, rows) }
+  if (b) { if (full) b.needsFull = true; setVote(b, true); applySize(b, cols, rows) }
 }
 // resize the client + repaint WITHOUT recording a viewer fit — the primitive both a real resize and the
 // supervisor's pre-sizing share, so the supervisor can't clobber lastFit/lastFitAny with a stale value.
@@ -482,12 +507,22 @@ async function reconcileOnce(): Promise<void> {
     if (!(await alive(s.id))) continue
     live.add(s.id)
     // already ours → keep warm and resize a stale warm bridge to the last-known viewer size off-screen,
-    // so a first open finds the pane already at its size. The size-diff guard makes a converged bridge a no-op.
+    // so a first open finds the pane already at its size. TWO staleness guards, by vote state: a NEUTRAL
+    // client's hold is suppressed while any sized viewer votes on the socket, so its own client size would
+    // read "converged" after one suppressed attempt and wedge the hold forever — compare against the
+    // WINDOW's real size (lastLayout) instead, retrying each tick (one suppressed no-op command) until the
+    // first tick after the socket goes quiet: deferred, not lost. A VOTING client keeps the client-size
+    // guard: its -C lands, and when two voting instances watch ONE session the window is genuinely
+    // contended — latest assert wins and STOPS (a window-truth guard would re-assert every tick and turn
+    // that contention into a visible size ping-pong war).
     const existing = bridges.get(s.id)
     if (existing) {
       existing.prewarmed = true
       const want = prewarmSize(s.id)
-      if (want.cols !== existing.cols || want.rows !== existing.rows) applySize(existing, want.cols, want.rows)
+      const stale = existing.voting
+        ? want.cols !== existing.cols || want.rows !== existing.rows
+        : existing.lastLayout !== `${want.cols}x${want.rows}`
+      if (stale) applySize(existing, want.cols, want.rows)
       continue
     }
     // no bridge for a live session: viewers waiting → re-bind and repaint (nothing else re-arms an idle

package/spec-cli/src/ranker.ts

@@ -10,7 +10,9 @@ const W_BODY = 1
 
 // a tiny stoplist of question scaffolding + length-1 tokens, dropped so "how does the … is it …" can't drown
 // the content words. Deliberately small and general — NOT tuned to any benchmark; just the function words a
-// natural-language query carries that match nothing meaningful.
+// natural-language query carries that match nothing meaningful. Quantifiers (many, several, same, too…) are
+// NOT stopped: in this corpus they are load-bearing ("too many owners" IS the multi-ownership concept —
+// dropping them measurably breaks that reach).
 const STOP = new Set([
   'the', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'on', 'is', 'it', 'its', 'as', 'at', 'by', 'for',
   'how', 'does', 'do', 'what', 'which', 'that', 'this', 'these', 'those', 'with', 'from', 'into', 'are',
@@ -32,11 +34,24 @@ function words(text: string): string[] {
   return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
 }
 
-// name match is forward-only (a chosen short field — reverse would let a plural query light up every `spec-*`
-// name); desc/body match bidirectionally so a singular/plural mismatch still hits, reverse gated to words ≥3
-// chars so a stray short word can't swallow a longer term (IDF neutralises the generic words it pulls in).
-function nameMatch(term: string, w: string): boolean { return w.startsWith(term) }
-function textMatch(term: string, w: string): boolean { return w.startsWith(term) || (w.length >= 3 && term.startsWith(w)) }
+// light query-side stem for prefix matching: drop a trailing plural 's' (len≥4, not 'ss') then a mute 'e'
+// (len≥5) — so `sessions` prefix-reaches `session`, `merge`→`merg` reaches `merging`, `declare`→`declar`
+// reaches `declaration`. Without the e-drop the spec's promised merge↔merging reach silently never worked
+// (`'merging'.startsWith('merge')` is false). Query-side only; IDF self-neutralises the extra reach (a
+// looser term matches more docs → bigger df → smaller idf), so no flood.
+function stem(t: string): string {
+  let s = t
+  if (s.length >= 4 && s.endsWith('s') && !s.endsWith('ss')) s = s.slice(0, -1)
+  if (s.length >= 5 && s.endsWith('e')) s = s.slice(0, -1)
+  return s
+}
+
+// name match is forward-only (a chosen short field — reverse would let a stray short word swallow it);
+// desc/body match bidirectionally so a longer doc word still reaches a shorter query term, reverse gated to
+// words ≥3 chars so a stray short word can't swallow a longer term (IDF neutralises the generic words it
+// pulls in).
+function nameMatch(term: string, w: string): boolean { return w.startsWith(stem(term)) }
+function textMatch(term: string, w: string): boolean { return w.startsWith(stem(term)) || (w.length >= 3 && term.startsWith(w)) }
 
 // classic BM25 tf: frequency with saturation (K1 sets how fast it saturates) and length-normalisation (B),
 // both in a wide insensitive plateau. tf=0 → 0.
@@ -51,13 +66,16 @@ function bm25tf(tf: number, len: number, avgLen: number): number {
 type Fields<T> = { ref: T; name: string; nameWords: string[]; desc: string; descWords: string[]; bodyWords: string[]; snippetText: string }
 
 // the pre-IDF weight a term earns against one doc, picking its single best tier (three fields): a name
-// word-prefix beats a name substring beats a desc hit beats a body hit. Name and desc are short, chosen
-// fields → binary presence; the body carries the BM25-saturated, length-normalised frequency that
-// discriminates the long ties.
-function tierWeight<T>(term: string, n: Fields<T>, avgBodyLen: number): number {
+// word-prefix beats a name substring beats a desc hit beats a body hit. Name is a short, chosen field →
+// binary presence. Desc is presence too (a curated one-liner — repetition there is stuffing, not evidence)
+// but LENGTH-NORMALISED: it was flat-binary until descs drifted long and a bloated desc became a cheat code
+// (one 60-word desc catches every query term a curated one-liner can't). bm25tf(1, avgLen, avgLen) = 1, so
+// a hit in an average-length desc scores exactly the old binary W_DESC — the normalisation only bites
+// outliers. The body keeps the full BM25-saturated term-frequency that discriminates the long ties.
+function tierWeight<T>(term: string, n: Fields<T>, avgBodyLen: number, avgDescLen: number): number {
   if (n.nameWords.some((w) => nameMatch(term, w))) return W_NAME_PREFIX
   if (n.name.includes(term)) return W_NAME_SUBSTR
-  if (n.descWords.some((w) => textMatch(term, w))) return W_DESC
+  if (n.descWords.some((w) => textMatch(term, w))) return W_DESC * bm25tf(1, n.descWords.length, avgDescLen)
   const tf = n.bodyWords.reduce((c, w) => c + (textMatch(term, w) ? 1 : 0), 0)
   return W_BODY * bm25tf(tf, n.bodyWords.length, avgBodyLen)
 }
@@ -108,6 +126,7 @@ export function rankDocs<T>(query: string, inputs: RankInput<T>[], opts: { limit
   // a rare one carries the rank. Read from the corpus, not hand-set.
   const N = docs.length
   const avgBodyLen = docs.reduce((a, n) => a + n.bodyWords.length, 0) / (N || 1)
+  const avgDescLen = docs.reduce((a, n) => a + n.descWords.length, 0) / (N || 1)
   const idf: Record<string, number> = {}
   for (const t of qterms) {
     let df = 0
@@ -120,7 +139,7 @@ export function rankDocs<T>(query: string, inputs: RankInput<T>[], opts: { limit
   const scored: Ranked<T>[] = []
   for (const n of docs) {
     let score = 0
-    for (const t of qterms) score += tierWeight(t, n, avgBodyLen) * idf[t]
+    for (const t of qterms) score += tierWeight(t, n, avgBodyLen, avgDescLen) * idf[t]
     if (score <= 0) continue
     scored.push({ ref: n.ref, score: Math.round(score * 100) / 100, snippet: snippetFor(n.snippetText, n.desc, qterms) })
   }

package/spec-cli/src/search.bench.mjs

@@ -1,5 +1,10 @@
-// throwaway benchmark harness for spec-search — drives the REAL `spex search --json` over the 15 holdout
-// cases and reports recall@1, recall@3, MRR. Not shipped/committed; the cases live in the node's yatsu.md.
+// throwaway benchmark harness for spec-search — drives the REAL `spex search --json` over the holdout
+// cases and reports recall@1, recall@3, MRR. The cases live in the node's yatsu.md.
+//
+// Labels are node LEAF names, matched with the same de-collision rule the loader applies (specs.ts reId):
+// a returned id matches a label if it IS the label or ends with `_<label>` — so a bare leaf keeps matching
+// after collision-qualification renames it (e.g. `spec-scout` → `injected-context_spec-scout`). A label may
+// also be written pre-qualified to pin one collision branch.
 import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
@@ -8,29 +13,33 @@ const BIN = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'spex.mjs
 
 const CASES = [
   ['exit-cleanup', "does /exit remove the session's worktree and tmux, or just orphan them?", ['session-console']],
-  ['owner-at-edit', 'how does an agent learn which spec governs a file it just edited?', ['injected-context/spec-of-file']],
+  ['owner-at-edit', 'how does an agent learn which spec governs a file it just edited?', ['spec-of-file']],
   ['main-block', 'what stops an agent from committing or merging straight into main?', ['main-guard']],
   ['main-escape', 'the escape hatch that lets seeding run on the main branch', ['main-guard']],
   ['inter-agent-msg', 'how do two running agent sessions send messages to each other?', ['agent-reply-channel', 'comms']],
   ['search-hidden-node', 'keyboard shortcut to find a node hidden inside a collapsed subtree', ['keyboard-nav']],
-  ['session-order', 'how is the order of sessions in the session list decided?', ['session-reorder']],
+  ['session-order', 'how is the order of sessions in the session list decided?', ['session-console']],
   ['node-status', 'what makes a node show as pending vs active vs merged vs drift?', ['spec-node-states']],
   ['dashboard-backend', 'how does the dashboard reach the backend API and on which port?', ['api-endpoint']],
   ['loss-measured', "how is a node's loss measured and its scenarios scored?", ['yatsu-core']],
   ['launch-injection', "what context gets injected into a freshly launched agent's prompt?", ['injected-context']],
-  ['read-before-code', 'the one-shot nudge that makes an agent read its spec before touching code', ['injected-context/spec-first']],
+  ['read-before-code', 'the one-shot nudge that makes an agent read its spec before touching code', ['spec-first']],
   ['hot-reload', 'zero-downtime backend reload without dropping connections', ['supervisor']],
   ['many-owners', 'can several specs own the same code file, and what happens if too many do?', ['governed-related']],
   ['active-spec-search', 'an injected sub-agent that searches specs for the agent, the spec analog of Explore', ['spec-scout']],
+  ['declare-done', 'how does a worker declare it is done', ['state']],
 ]
 
+// de-collision-aware label match: exact id, or the id's trailing `_`-suffix is the label.
+const matches = (id, label) => id === label || id.endsWith('_' + label)
+
 let r1 = 0, r3 = 0, mrr = 0
 const rows = []
 for (const [name, query, expect] of CASES) {
   const out = execFileSync('node', [BIN, 'search', query, '--json', '--limit', '10'], { encoding: 'utf8' })
   const results = JSON.parse(out)
   const ids = results.map((x) => x.id)
-  const rank = ids.findIndex((id) => expect.includes(id)) + 1   // 1-based; 0 = not found
+  const rank = ids.findIndex((id) => expect.some((label) => matches(id, label))) + 1   // 1-based; 0 = not found
   const hit1 = rank === 1
   const hit3 = rank >= 1 && rank <= 3
   if (hit1) r1++
@@ -43,5 +52,19 @@ for (const row of rows) {
   const mark = row.rank === 1 ? '✓1' : (typeof row.rank === 'number' && row.rank <= 3 ? '·3' : (row.rank === '—' ? '✗ ' : `·${row.rank}`))
   console.log(`${mark} ${row.name.padEnd(20)} want=${row.expect.padEnd(22)} rank=${String(row.rank).padStart(2)}  top3: ${row.top}`)
 }
+
+// zero-result fail-loud regression: a CJK query over the English corpus returns nothing, and the
+// zero-result message must carry the corpus-is-English translate-and-retry fact (fail-loud, unconditional)
+// plus the browse-all next step (no nearest titles — a CJK query has nothing to be lexically near).
+const cjk = execFileSync('node', [BIN, 'search', '重命名一个会话'], { encoding: 'utf8' })
+const cjkPass = cjk.includes('corpus is English') && cjk.includes('spex tree')
+console.log(`${cjkPass ? '✓ ' : '✗ '} cjk-zero-result       want=corpus-is-English + spex-tree  ${cjkPass ? 'both present' : 'MISSING: ' + cjk.trim()}`)
+
+// zero-result typo routing: an English typo that matches nothing must surface the nearest node titles
+// (per-word edit distance) plus the browse-all next step, so a typo routes forward instead of dead-ending.
+const typo = execFileSync('node', [BIN, 'search', 'kyeboard'], { encoding: 'utf8' })
+const typoPass = typo.includes('nearest titles') && typo.includes('keyboard-nav') && typo.includes('spex tree')
+console.log(`${typoPass ? '✓ ' : '✗ '} typo-zero-result      want=nearest-titles(keyboard-nav) + spex-tree  ${typoPass ? 'both present' : 'MISSING: ' + typo.trim()}`)
+
 console.log('—'.repeat(72))
-console.log(`recall@1 = ${r1}/${n} = ${(r1 / n).toFixed(3)}   recall@3 = ${r3}/${n} = ${(r3 / n).toFixed(3)}   MRR = ${(mrr / n).toFixed(3)}`)
+console.log(`recall@1 = ${r1}/${n} = ${(r1 / n).toFixed(3)}   recall@3 = ${r3}/${n} = ${(r3 / n).toFixed(3)}   MRR = ${(mrr / n).toFixed(3)}   cjk-hint = ${cjkPass ? 'PASS' : 'FAIL'}   typo-route = ${typoPass ? 'PASS' : 'FAIL'}`)