spexcode 0.2.0 → 0.2.2

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'}`)

package/spec-cli/src/search.ts

@@ -4,6 +4,45 @@ import { rankDocs, type RankInput } from './ranker.js'
 export type SearchResult = { id: string; title: string; path: string; score: number; snippet: string }
 export type SearchStats = { nodes: number; tokens: number; ms: number }
 
+// zero-result fallback: nearest node titles by per-word edit distance over title+id — the lightweight
+// string distance that routes a typo'd query to a next step. Each query word takes its best normalised
+// Levenshtein similarity against any title/id word (≥0.5, so unrelated words don't accumulate), then the
+// words sum. Same loadSpecsLite read as the ranker; deliberately NOT part of rankDocs scoring (this
+// tolerates typos, the ranker must not).
+export function nearestTitles(query: string, n = 3): { id: string; title: string }[] {
+  const words = (s: string) => s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 1)
+  const lev = (a: string, b: string) => {
+    const dp = Array.from({ length: b.length + 1 }, (_, i) => i)
+    for (let i = 1; i <= a.length; i++) {
+      let prev = dp[0]
+      dp[0] = i
+      for (let j = 1; j <= b.length; j++) {
+        const cur = dp[j]
+        dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+        prev = cur
+      }
+    }
+    return dp[b.length]
+  }
+  const qws = words(query)
+  if (!qws.length) return []   // nothing to be "near" (e.g. a pure-CJK query) — the caller still points at spex tree
+  return loadSpecsLite()
+    .map((s) => {
+      const tws = [...new Set(words(`${s.title} ${s.id}`))]
+      let score = 0
+      for (const q of qws) {
+        let best = 0
+        for (const t of tws) best = Math.max(best, 1 - lev(q, t) / Math.max(q.length, t.length))
+        if (best >= 0.5) score += best
+      }
+      return { id: s.id, title: s.title, score }
+    })
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, n)
+    .map(({ id, title }) => ({ id, title }))
+}
+
 export async function searchSpecs(query: string, opts: { limit?: number; onStats?: (s: SearchStats) => void } = {}): Promise<SearchResult[]> {
   const t0 = performance.now()
   // pre-sort by (shorter id, then id): rankDocs sorts stably, so for equal-scored nodes this IS the tiebreak.