spexcode 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/src/anchors.ts

@@ -27,8 +27,44 @@ export type Extractor = {
 export type CodeEntry = { path: string; anchor: string | null }
 export function parseCodeEntry(raw: string): CodeEntry {
   const i = raw.indexOf('#')
-  if (i < 0) return { path: raw, anchor: null }
-  return { path: raw.slice(0, i), anchor: raw.slice(i + 1).trim() || null }
+  if (i < 0) return { path: raw.trim(), anchor: null }
+  return { path: raw.slice(0, i).trim(), anchor: raw.slice(i + 1).trim() || null }
+}
+
+// ---- relation parsing: ONE structured path+selector grammar for code: AND related: ----
+// A relation's raw rows group per base path: a row is bare (`path`, whole-file — today's semantics,
+// unchanged) or scoped (`path#symbol`), and any number of scoped rows on the SAME base file fold into
+// one entry whose selectors are OR'd (a commit hitting any counts once; no selector-count cap — the
+// benchmark roster's 1–3 was an annotation rubric, never product syntax). STRUCTURAL verdicts live
+// here, pure and loud: an exact duplicate row, mixing bare with selectors on one base path, and a
+// selector on a glob are all `problems` the caller turns into integrity errors. Filesystem/git
+// verdicts (existence, directories, dead/ambiguous units, extractor readiness) stay the caller's —
+// this parser never touches fs.
+export type RelationEntry = { path: string; selectors: string[] }
+export type RelationParse = { entries: RelationEntry[]; problems: string[] }
+export function parseRelation(raws: string[], relation: 'code' | 'related'): RelationParse {
+  const order: string[] = []
+  const byPath = new Map<string, { bare: boolean; selectors: string[] }>()
+  const problems: string[] = []
+  for (const raw of raws) {
+    const { path, anchor } = parseCodeEntry(raw)
+    let e = byPath.get(path)
+    if (!e) { e = { bare: false, selectors: [] }; byPath.set(path, e); order.push(path) }
+    if (anchor === null) {
+      if (e.bare) problems.push(`${relation}: lists '${path}' twice — drop the duplicate entry`)
+      e.bare = true
+    } else if (e.selectors.includes(anchor)) {
+      problems.push(`${relation}: lists selector '${path}#${anchor}' twice — drop the duplicate`)
+    } else e.selectors.push(anchor)
+  }
+  for (const path of order) {
+    const e = byPath.get(path)!
+    if (e.bare && e.selectors.length)
+      problems.push(`${relation}: mixes bare '${path}' with '${path}#…' selectors — one base path is either whole-file or selector-scoped, never both; drop one form`)
+    if (e.selectors.length && path.includes('*'))
+      problems.push(`${relation}: '${path}#${e.selectors[0]}' puts a selector on a glob — a selector scopes ONE real file`)
+  }
+  return { entries: order.map((p) => ({ path: p, selectors: byPath.get(p)!.selectors })), problems }
 }
 
 // ---- extractor: ts-ast (the designated extractor for the JS family) ----
@@ -280,21 +316,26 @@ export function windowCommits(idx: DriftIndex, sinceHash: string, path: string):
   return (idx.fileCommits.get(path) ?? []).filter((h) => !inAncestors(idx, base, h) && !cover.some((a) => inAncestors(idx, a, h)))
 }
 
-// which window commits TOUCHED the anchored unit: the commit's --unified=0 hunks intersect the unit's
-// line range extracted from the file AS IT EXISTED AT THAT COMMIT (never from HEAD — units later renamed
-// or moved still attribute correctly). A version whose content the extractor cannot parse is a
-// CONSERVATIVE hit (`unparseable` set) — over-warn, never silently skip.
-export type AnchorHit = { commit: string; unparseable?: string }
-export async function anchorHitCommits(root: string, win: string[], path: string, symbol: string, x: Extractor): Promise<AnchorHit[]> {
+// which window commits TOUCHED any of the anchored units: the commit's --unified=0 hunks intersect a
+// unit's line range extracted from the file AS IT EXISTED AT THAT COMMIT (never from HEAD — units later
+// renamed or moved still attribute correctly). Several selectors are OR — a commit appears ONCE, with
+// `selectors` naming exactly which units its hunks intersected (so diagnostics can attribute the hit).
+// A version whose content the extractor cannot parse is a CONSERVATIVE hit for every selector
+// (`unparseable` set) — over-warn, never silently skip.
+export type AnchorHit = { commit: string; selectors: string[]; unparseable?: string }
+export async function anchorHitCommits(root: string, win: string[], path: string, symbols: string[], x: Extractor): Promise<AnchorHit[]> {
   const hits: AnchorHit[] = []
   for (const c of win) {
     const at = await unitsAt(root, c, path, x)
     if ('absent' in at) continue // file not in that commit's tree — nothing of the anchor to touch
-    if ('unparseable' in at) { hits.push({ commit: c, unparseable: at.unparseable }); continue }
-    const ranges = at.units.filter((u) => u.name === symbol)
-    if (!ranges.length) continue // unit didn't exist under this name at that commit
+    if ('unparseable' in at) { hits.push({ commit: c, selectors: [...symbols], unparseable: at.unparseable }); continue }
+    const bySym = symbols
+      .map((sym) => ({ sym, ranges: at.units.filter((u) => u.name === sym) }))
+      .filter((s) => s.ranges.length) // a unit absent under this name at that commit can't be touched
+    if (!bySym.length) continue
     const hunks = await hunksAt(root, c, path)
-    if (hunks.some(([a, b]) => ranges.some((u) => a <= u.end && u.start <= b))) hits.push({ commit: c })
+    const touched = bySym.filter((s) => hunks.some(([a, b]) => s.ranges.some((u) => a <= u.end && u.start <= b))).map((s) => s.sym)
+    if (touched.length) hits.push({ commit: c, selectors: touched })
   }
   return hits
 }

package/spec-cli/src/cli.ts

@@ -404,7 +404,11 @@ if (cmd === 'serve') {
     const owners = specOwners(p)
     const related = specRelated(p)
     const maxOwners = loadConfig(process.cwd()).maxOwners
-    const names = (xs: { id: string }[]) => xs.map((o) => `'${o.id}'`).join(', ')
+    // a selector-SCOPED governor (every claiming code: entry carries `#symbol` — [[code-anchor]]) still
+    // DISPLAYS, marked, but does not count toward the too-many-owners bound: it claims named units, not
+    // the whole file.
+    const whole = owners.filter((o) => !o.scoped)
+    const names = (xs: { id: string; scoped?: boolean }[]) => xs.map((o) => `'${o.id}'${o.scoped ? ' (scoped)' : ''}`).join(', ')
     const relLine = related.length ? `\n  also referenced by ${names(related)} (related: coverage only — no drift, no eval freshness)` : ''
     if (owners.length === 0 && related.length === 0) {
       console.log(`${rel} — no spec claims this yet (uncovered). If your change is substantive, give it a home before it drifts.`)
@@ -413,16 +417,16 @@ if (cmd === 'serve') {
       // but a human asking gets the honest nuance: nothing tracks this file's drift.
       if (has('actionable')) process.exit(0)
       console.log(`${rel} — not governed (no code: claim), but referenced by ${names(related)} (related: coverage only). Nothing tracks its drift; if your change is substantive, consider giving it a governing home.`)
-    } else if (owners.length <= maxOwners) {
+    } else if (whole.length <= maxOwners) {
       // a sanely-owned file is NOT actionable: --actionable callers (the per-edit spec-of-file hook) stay
       // silent here, so the annotation fires only on an OVER-owned or uncovered file — rare and worth acting on.
       if (has('actionable')) process.exit(0)
-      const named = owners.map((o) => `'${o.id}'`).join(', ')
+      const named = names(owners)
       const lead = owners.length === 1 ? `${rel} is governed by ${named} — ${owners[0].desc}` : `${rel} is governed by ${named} (shared, fine).`
       console.log(`${lead} Read/honor the spec; if your change shifts the intent, update the spec in the SAME commit.${relLine}`)
     } else {
-      const ids = owners.map((o) => o.id).join(', ')
-      console.log(`${rel} is governed by ${owners.length} specs (${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
+      const ids = names(owners)
+      console.log(`${rel} is governed whole-file by ${whole.length} specs (all claims: ${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
     }
   } else if (sub === 'lint') {
     const { specLint, DRIFT_GUIDANCE } = await import('./lint.js')

package/spec-cli/src/gateway.ts

@@ -243,7 +243,14 @@ function serveStatic(req: http.IncomingMessage, res: http.ServerResponse, distDi
   const rel = normalize(decodeURIComponent(urlPath)).replace(/^(\.\.[/\\])+/, '')
   let file = join(distDir, rel)
   if (!file.startsWith(distDir)) file = join(distDir, 'index.html')
-  if (urlPath === '/' || !existsSync(file)) file = join(distDir, 'index.html')
+  if (urlPath === '/' || !existsSync(file)) {
+    // @@@ missing-asset 404 - only extensionless SPA routes fall back to index.html. A missing FILE
+    // request (it has an extension) is a stale hashed chunk from a pre-rebuild page still open in some
+    // browser: answering it with HTML trips the strict module-MIME check and hides the miss from the
+    // client — 404 instead, so the shell's vite:preloadError recovery can see it and reload.
+    if (urlPath !== '/' && extname(file)) { res.writeHead(404, { 'Content-Type': 'text/plain' }); return res.end('not found') }
+    file = join(distDir, 'index.html')
+  }
   if (!existsSync(file)) { res.writeHead(503); return res.end('dashboard build missing') }
   const type = MIME[extname(file)] || 'application/octet-stream'
   const raw = readFileSync(file)

package/spec-cli/src/graph.ts

@@ -7,7 +7,7 @@ import { residentForgeState } from '../../spec-forge/src/resident.js'
 import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { mergedIssues } from './issues.js'
 import { evalContext, evalTimeline } from '../../spec-eval/src/evaltab.js'
-import { evalNodesAsync } from '../../spec-eval/src/scenarios.js'
+import { evalNodesAsync, type ScenarioTestReference } from '../../spec-eval/src/scenarios.js'
 
 // a ghost (added) node's parent: the existing node whose directory is the longest prefix of the new one.
 function resolveParent(path: string, byDir: Record<string, string>): string | null {
@@ -29,11 +29,17 @@ export function latestPerScenario<T extends { scenario: string }>(readings: T[])
   return readings.filter((r) => !seen.has(r.scenario) && (seen.add(r.scenario), true))
 }
 
-// the board's scenario fold ([[graph-lean]]): the declared set rides SLIM — {name, tags} is everything an
-// overview surface joins state onto (badge, stats, focus rows, search rows); the prose (description/
-// expected) and per-scenario code stay off the hot poll, carried by `/api/specs/lite` and `/api/specs/:id/evals`.
-export function slimScenarios(scenarios: { name: string; tags?: string[] }[]): { name: string; tags?: string[] }[] {
-  return scenarios.map((s) => ({ name: s.name, ...(s.tags?.length ? { tags: s.tags } : {}) }))
+// the board's scenario fold ([[graph-lean]]): the declared set rides SLIM — name/tags plus the normalized
+// test reference a measuring hand can follow. Prose and per-scenario code stay off the hot poll, carried by
+// `/api/specs/lite` and `/api/specs/:id/evals`; the opaque test case name is metadata, not an executor seam.
+export function slimScenarios(
+  scenarios: { name: string; tags?: string[]; test?: ScenarioTestReference }[],
+): { name: string; tags?: string[]; test?: ScenarioTestReference }[] {
+  return scenarios.map((s) => ({
+    name: s.name,
+    ...(s.tags?.length ? { tags: s.tags } : {}),
+    ...(s.test ? { test: s.test } : {}),
+  }))
 }
 
 export async function buildBoard() {
@@ -139,7 +145,7 @@ export async function buildBoard() {
   // the LATEST reading per scenario (newest-first), which is all any overview surface consumes (the score
   // badge, stats, search all reduce to latest-per-scenario anyway); the full timeline stays off the board
   // and is lazy-loaded by the eval tab from `/api/specs/:id/evals`. `scenarios` (the declared set) rides
-  // SLIM — {name, tags} only, the fields every overview surface joins state onto — with its prose
+  // SLIM — name/tags/test only, the fields every overview surface or measuring hand needs — with its prose
   // (description/expected) and per-scenario code off the hot poll: they ride the `/api/specs/lite` corpus
   // (search palette, focus-panel preview) and the `/api/specs/:id/evals` timeline (eval tab).
   // evalContext reuses the specs + driftIndex above; evalTimeline short-circuits non-measurable nodes. The

package/spec-cli/src/guide.ts

@@ -62,13 +62,22 @@ FRONTMATTER (YAML between the opening and closing --- lines; every field optiona
            Drives drift + eval freshness. Many nodes MAY govern the same file (ordinary
            composition); a file governed by > maxOwners nodes warns (the \`owners\` rule — split it). Omit
            for a pure-prose node: a cross-cutting contract no file owns.
-           The entry may pin ONE named unit — an ANCHOR: \`path#symbol\` (\`#Class.method\` for a class
-           method; top-level functions, arrow/const declarations, classes, enums anchor cleanly; a
-           type/interface anchor warns). An anchor upgrades drift on THAT unit to a blocking error
-           (\`anchor-drift\`); without one, drift stays advisory forever. Anchors are optional.
+           The entry may pin named units — ANCHORS: one or more \`path#symbol\` rows, ALL on the same
+           base file (\`#Class.method\` for a class method; top-level functions, arrow/const declarations,
+           classes, enums anchor cleanly; a type/interface anchor warns). One-govern counts DISTINCT
+           base paths, so selectors never widen govern past one file. Several selectors are OR: a
+           commit hitting ANY upgrades drift to the blocking \`anchor-drift\` error (one error per
+           entry, naming the hit selectors — a commit counts once). Without an anchor, drift stays
+           advisory forever. A base path is either whole-file (bare) or selector-scoped, never both;
+           duplicates, globs/directories with a selector, and dead/ambiguous units all error loud. A
+           selector-scoped governor claims units, not the file, so it stays out of the \`owners\` bound
+           (spex spec owner still displays it, marked "(scoped)"). Anchors are optional.
   related: files this node REFERENCES but does not own — a YAML list, same path forms. Carries coverage
            (never drift, never eval freshness, nothing to ack); it is the many-to-many net that claims the files
-           govern doesn't. Every listed path must exist (lint integrity error otherwise).
+           govern doesn't. Every listed path must exist (lint integrity error otherwise). A related row
+           may also pin \`path#symbol\`: the node then hears about a commit ONLY when it moves that
+           unit — a hit is a soft \`related-drift\` warn naming the selector, a miss is SILENT (a scoped
+           related file's ordinary file-level nudge is off). Still never blocks, no ack, no eval freshness.
   surface  plugin-system/.plugins nodes only: one or MORE of system (folded into every agent's prompt) |
            command (a /command) | skill (an on-demand SKILL.md the harness loads when a task matches the
            node's desc) | agent (a spawnable sub-agent definition; its \`tools:\` list is the spawned
@@ -92,11 +101,14 @@ WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
                       deleted/renamed), an ambiguous one (two same-named units in one file), a file that
                       no longer parses, a language with no designated extractor, or an extractor that
                       can't run here (e.g. no host typescript — 'npm i -D typescript' or drop the anchor)
-                      all error, never silently pass.
-  anchor-drift (error) a commit since the node's version intersected the ANCHORED unit's lines (judged
+                      all error, never silently pass. So do a relation's STRUCTURAL defects: a duplicate
+                      entry, a base path both bare and selector-scoped, or a selector on a
+                      glob/directory.
+  anchor-drift (error) a commit since the node's version intersected an ANCHORED unit's lines (judged
                       from the file as it existed AT each commit) and no Spec-OK ack covers it — the
-                      blocking tier of drift. Remedy: update the spec, or \`spex spec ack\` with a real
-                      reason (recorded in the ack commit body).
+                      blocking tier of drift. Selectors on one file are OR'd: one error per entry, the
+                      hit selectors named, each commit counted once. Remedy: update the spec, or
+                      \`spex spec ack\` with a real reason (recorded in the ack commit body).
   one-govern (error)  a node governs (code:) at most ONE file — keep the true subject, move the rest
                       to related:.
   living     (error)  no "## vN" changelog headings — the body is current-state.
@@ -111,14 +123,20 @@ WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
   coverage   (warn)   every source file is claimed by ≥1 node — via code: OR related: (related is the net).
   drift      (warn)   a governed file has commits newer than the node's spec version — it may be stale.
                       ALWAYS advisory: unanchored drift never blocks a commit (the blocking tier is
-                      anchor-drift above). Remedy: edit the spec to the new intent (re-versions the
-                      node), OR \`spex spec ack <node> --reason "…"\` when only mechanics changed and the
-                      contract still holds.
+                      anchor-drift above). On a selector-SCOPED code file whose window has NO hit (a
+                      miss), this advisory stays by default; the committed \`lint.scopedCodeMiss:
+                      "ignore"\` silences ONLY it (hit blocks, bare drift, integrity, acks, related,
+                      eval freshness all untouched). Remedy: edit the spec to the new intent
+                      (re-versions the node), OR \`spex spec ack <node> --reason "…"\` when only
+                      mechanics changed and the contract still holds.
   anchor     (warn)   an anchor pins a type/interface — types reshape with every refactor; anchor the
                       behaviour-bearing unit instead.
-  related-drift (warn) a related: file moved ahead of the node — a soft nudge, one summary line, never blocks.
-  owners     (warn)   a file governed by > maxOwners nodes (default 3) does too much — SPLIT it so each
-                      governor owns its own module (or merge the nodes, or give it one foundation owner).
+  related-drift (warn) a related: file moved ahead of the node — a soft nudge, one summary line, never
+                      blocks. A selector-scoped related row instead warns per HIT (selector named);
+                      its file-level misses are silent.
+  owners     (warn)   a file governed WHOLE-FILE by > maxOwners nodes (default 3) does too much — SPLIT
+                      it so each governor owns its own module (or merge the nodes, or give it one
+                      foundation owner). Selector-scoped governors don't count toward the bound.
   confusable-id (warn) two leaf ids one edit apart read as the same word — rename one to read apart.
 
 LIFECYCLE: author each node on a node/<id> branch, one node per commit; \`spex spec lint\` must reach 0 errors
@@ -141,8 +159,13 @@ FRONTMATTER: a \`scenarios:\` list (a YAML block sequence of mappings). Each sce
                \`frontend-e2e, backend-api, cli, desktop, mobile\`). A tag outside the library is rejected —
                use an existing one, or add it to the library to mint it. Tags classify a scenario (surface,
                device) so it can be filtered and, later, routed to the right driver.
-  test         optional. A repo path to a co-located runnable file (a playwright.spec.ts, a script)
-               the agent MAY run by hand. Not a driver — eval never executes it.
+  test         optional. Either a repo-path scalar (the backward-compatible shorthand) or a strict object:
+                 test:
+                   path: tests/auth.spec.ts
+                   name: rejects an expired session
+               Both forms normalize in JSON to \`{ "path": "..." }\` with optional \`"name"\`. The object
+               requires exactly \`path\` + \`name\`; its case name is opaque text preserved for the measuring
+               hand. The path must exist. SpexCode does not parse WDIO/Playwright or execute anything.
   code         optional. The file THIS scenario GOVERNS, ideally one (a comma list / flow list \`[a, b]\` is
                allowed) — its own slice of the code freshness axis, so scenarios on one node go stale
                independently. Absent → it inherits the node's \`code:\` list. A file governed by > maxOwners
@@ -354,10 +377,16 @@ the guard (the flag is the declaration of intent). Reads point anywhere.
   lint.altitude            body budgets: { lineBudget, charBudget, sizeable, dense, steps }
                            (defaults 50 / 4200 / 35 / 1.3 / 3).
   lint.maxChildren         breadth budget: warn at >= this many direct children (default 8).
-  lint.maxOwners           warn when a file is governed by > this many nodes (default 3).
+  lint.maxOwners           warn when a file is governed WHOLE-FILE by > this many nodes (default 3).
+                           Selector-scoped governors (code: path#symbol) don't count toward the bound.
                            (lint.driftErrorThreshold is RETIRED: the count-based commit gate is replaced
                            by code anchors — \`code: path#symbol\` — whose hits error unconditionally; a
                            leftover key is ignored.)
+  lint.scopedCodeMiss      "warn" (default) | "ignore" — the file-level drift ADVISORY on a selector-
+                           scoped code: file whose window commits hit no selector (a miss). "ignore"
+                           silences ONLY that advisory; it never touches hit blocks (anchor-drift),
+                           bare-path drift, integrity, Spec-OK acks, related semantics, or eval
+                           freshness. A project policy → committed spexcode.json.
   lint.scenarioTags        the closed vocabulary an eval scenario's tags: must draw from (default
                            ["frontend-e2e","backend-api","cli","desktop","mobile"]); extend to mint a tag.
 Example — govern your own source dir and loosen the altitude budget:
@@ -376,9 +405,11 @@ const FOOTPRINT = `spex guide footprint — what SpexCode plants in a repo, and
 
 SpexCode claims software engineering's HEAD (the recording of intent) and TAIL (the storage of
 measurement) and leaves the MIDDLE — construction — to the harness/agent/test framework; freshness
-stitches the two ends into a closed loop. The footprint follows: the head+tail (.spec, spexcode.json,
-evals) is the ASSET and lives in git like source; everything else is derived wiring or a machine fact.
-Materialized artifacts carry no facts, so they are NEVER tracked — there is exactly one residence
+stitches the two ends into a closed loop. Materialize is the base operation of harness ADAPTATION:
+one pass renders the spec tree into whatever artifacts the selected harness auto-discovers, so that
+is how SpexCode reaches an agent — never a launch-time flag. The footprint follows: the head+tail
+(.spec, spexcode.json, evals) is the ASSET and lives in git like source; everything else is derived
+wiring or a machine fact. Materialized artifacts carry no facts, so they are NEVER tracked — there is exactly one residence
 behavior, decided per KIND (and, for a contract file, by its live CONTENT).
 
 ── THE FOUR KINDS (all fixed) ──

package/spec-cli/src/harness.ts

@@ -133,13 +133,21 @@ export interface Harness {
   // grace lives in the caller (sessions.ts liveness), so a still-booting pane reads starting, not offline.
   liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline'
   // deliver a follow-up prompt to a LIVE session and report whether it landed. claude: through the rendezvous
-  // control socket — OPTIMISTIC-after-liveness (loud failure when the socket is missing/dead or the write can't
-  // flush; once the reply line flushes to a live socket it returns ok, without waiting for an application ack —
-  // see replyViaSocket). codex: JSON-RPC on the same app-server WebSocket the
+  // control socket — an ATOMIC reply+repaint chunk whose `repaint-done` proves the reply was PARSED; a close
+  // before it proves a concurrent connect kicked the chunk (the daemon is single-connection) → resend; a wall
+  // expiry on a still-open connection is a busy-not-lost agent → optimistic ok (see replyViaSocket). codex:
+  // JSON-RPC on the same app-server WebSocket the
   // visible TUI uses — it reads the thread live and either `turn/steer`s the message INTO an in-progress turn
   // (mid-turn, not queued for after the agent stops) or `turn/start`s a fresh turn when the thread is idle.
   // Returns ok=false with a reason that propagates to the API.
   deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>
+  // the ONE pane state where this harness SWALLOWS a prompt that its delivery channel confirms (so no
+  // socket-side check can see it): given the live pane text, return the loud human-readable refusal (naming
+  // the recovery) or null when the pane can take a prompt. sendText captures the pane once and consults this
+  // BEFORE delivering; absent on harnesses with no such state (codex delivery ignores the pane). claude: the
+  // TUI's sessions panel ("← for agents") enqueues an injected reply to the panel context and never drains it
+  // — verified live: parsed + enqueued, no dequeue, no turn, daemon silent.
+  deliveryBlockedBy?(paneText: string): string | null
   // --- materialize: clean (the inverse of write — [[harness-select]] prunes a deselected harness) ---
   // clean is the EXACT inverse of materialize's per-harness write: SURGICALLY remove ONLY SpexCode's own
   // artifacts — the managed contract block (sentinels), the generated shim file, the trust block, and the
@@ -161,11 +169,11 @@ export interface Harness {
 }
 
 // a prompt-dispatch outcome. ok=true means delivery is confirmed at the layer that harness proves it: claude at
-// the TRANSPORT/liveness layer (the reply line flushed to a live rendezvous socket — see replyViaSocket for why
-// it is OPTIMISTIC-after-liveness, not a round-trip ack); codex at the application layer (the app-server accepted
-// `turn/steer`/`turn/start`). `error` carries a human-readable reason that propagates to the API route (non-2xx)
-// and the CLI/dashboard. Defined here because it is the harness DELIVERY contract; sessions.ts re-exports it for
-// its existing importers.
+// the DAEMON-PARSE layer (the atomic reply+repaint chunk answered `repaint-done`, or the wall expired on a
+// still-open connection — busy, not lost; see replyViaSocket); codex at the application layer (the app-server
+// accepted `turn/steer`/`turn/start`). `error` carries a human-readable reason that propagates to the API route
+// (non-2xx) and the CLI/dashboard. Defined here because it is the harness DELIVERY contract; sessions.ts
+// re-exports it for its existing importers.
 export type DispatchResult = { ok: boolean; error?: string }
 export type HarnessDeliveryRecord = { session: string; worktreePath?: string; harnessSessionId?: string | null; runtimeDir?: string }
 // the on-demand surface artifacts a materialize pass wrote, by node NAME — so clean() knows EXACTLY which
@@ -252,50 +260,84 @@ function shQuote(s: string): string {
 const PKG = fileURLToPath(new URL('..', import.meta.url))
 const SPEX = join(PKG, 'bin', 'spex.mjs')
 
-// @@@ replyViaSocket - OPTIMISTIC-after-liveness delivery: connect to the LIVE rendezvous socket and WRITE the
-// `{type:reply}\n` line; once that line FLUSHES to the socket with no immediate transport error, the reply is on
-// the wire and claude submits it the moment it yields the event loop — so we return ok:true right there. We do
-// NOT wait for an application-level acceptance ack. The old code wrote a `{type:repaint}` probe after the reply
-// and waited up to 2500ms for a `{type:repaint-done}` to CONFIRM the reply was processed; the ordering barrier is
-// sound one-way (repaint-done ⟹ delivered) but its ABSENCE is NOT proof of non-delivery — a mid-turn/BUSY claude
-// can't answer the probe within the wall, so a message that actually landed reported a COMMON, misleading false
-// failure. The delivery confirmation therefore lives at the TRANSPORT/liveness layer, not the application layer:
-// deliverViaRendezvous already gates on the socket's existence (liveness), and here the FREE, INSTANT transport
-// signals — a connect that throws, a socket 'error' (ECONNREFUSED / EPIPE), or a 'close' BEFORE the write flushes —
-// are still reported as real failures (they cost no waiting). What we knowingly give up is detection of the narrow
-// alive-but-wedged / reply-rejected / shutting-down cases: a rare silent drop, recoverable because the supervisor
-// sees the worker never transition. That tradeoff is the deliberate contract now — see [[harness-adapter]].
-// Never throws.
-function replyViaSocket(sock: string, text: string): Promise<DispatchResult> {
+// @@@ replyViaSocket - ATOMIC parse-confirmed delivery. The daemon is SINGLE-CONNECTION: a new connect
+// `destroy()`s the previous socket, discarding any received-but-not-yet-parsed line with it — and our own
+// `rendezvousListening` liveness probe IS such a connect, fired for every session on every board snapshot. So
+// the previous optimistic write (return ok once the reply line flushed) LOST prompts whenever a probe landed in
+// the write→parse window, a window that widens exactly when claude is busy mid-turn (field: dashboard messages
+// recorded `sent` with no trace in the claude transcript; measured 2/10 lost under a 20ms probe hammer). The
+// daemon parses a chunk's complete lines in ONE synchronous loop, so writing `{type:reply}` + `{type:repaint}`
+// as ONE chunk makes the pair indivisible — a kick loses BOTH or NEITHER — and the outcome decidable from this
+// connection alone:
+//   `repaint-done` arrives  → the reply line before it was parsed (in-order barrier) → ok, CONFIRMED.
+//   'close' before it       → the chunk was never parsed (kicked by a concurrent connect) → resolve kicked:true
+//                             so deliverViaRendezvous RESENDS — a proven loss, so the retry cannot duplicate.
+//   wall expires, conn open → a busy event loop is DELAYING, not losing (the 2500ms-wall lesson: ack absence is
+//                             NOT non-delivery) → ok, OPTIMISTIC — never a false failure on a busy worker.
+//   `reply-rejected`/`auth-rejected`/`shutting-down` → loud failure, not retried.
+// Other daemon lines (heartbeat, state patches) are ignored. Never throws.
+type ReplyOutcome = DispatchResult & { kicked?: boolean }
+function replyViaSocket(sock: string, text: string, wallMs = 10_000): Promise<ReplyOutcome> {
   return new Promise((resolve) => {
     let settled = false
     let c: ReturnType<typeof createConnection>
-    const done = (r: DispatchResult) => {
+    const done = (r: ReplyOutcome) => {
       if (settled) return
       settled = true
+      clearTimeout(wall)
       try { c?.destroy() } catch { /* */ }
       resolve(r)
     }
+    const wall = setTimeout(() => done({ ok: true }), wallMs)
     try {
       c = createConnection({ path: sock })
     } catch (e) {
       done({ ok: false, error: `rendezvous socket connect threw: ${String(e)}` })
       return
     }
-    c.on('error', (e: NodeJS.ErrnoException) => done({ ok: false, error: `rendezvous socket connect failed: ${e?.code || String(e)}` }))
-    c.on('close', () => done({ ok: false, error: 'rendezvous connection closed before the prompt was written' }))
-    // write the reply line; the write callback fires once it flushes to the live socket → optimistic ok. An
-    // immediate transport 'error'/'close' beats the callback and reports the real failure (done is idempotent).
-    c.on('connect', () => c.write(JSON.stringify({ type: 'reply', text }) + '\n', () => done({ ok: true })))
+    // ECONNRESET/EPIPE are the KICK surfacing as an error: the daemon destroy()s the previous connection the
+    // moment a new one connects, and destroying a socket with OUR chunk still unread raises RST — whereas a
+    // parsed chunk answers repaint-done (readable even after a later close) before any clean FIN. So both codes
+    // PROVE the chunk was never parsed → retryable, same as the clean pre-parse close. ECONNREFUSED/ENOENT
+    // (daemon gone) stay loud.
+    c.on('error', (e: NodeJS.ErrnoException) => {
+      const code = e?.code || String(e)
+      const kicked = code === 'ECONNRESET' || code === 'EPIPE'
+      done({ ok: false, ...(kicked ? { kicked } : {}), error: `rendezvous socket error: ${code} — prompt NOT delivered` })
+    })
+    c.on('close', () => done({ ok: false, kicked: true, error: 'rendezvous connection was closed before the daemon parsed the prompt (kicked by a concurrent connect)' }))
+    c.on('connect', () => c.write(JSON.stringify({ type: 'reply', text }) + '\n' + JSON.stringify({ type: 'repaint' }) + '\n'))
+    let buf = ''
+    c.on('data', (d) => {
+      buf += d.toString('utf8')
+      let nl
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl)
+        buf = buf.slice(nl + 1)
+        let type = ''
+        try { type = (JSON.parse(line) as { type?: string })?.type ?? '' } catch { continue }
+        if (type === 'repaint-done') return done({ ok: true })
+        if (type === 'reply-rejected' || type === 'auth-rejected') return done({ ok: false, error: `rendezvous daemon rejected the prompt (${type}) — prompt NOT delivered` })
+        if (type === 'shutting-down') return done({ ok: false, error: 'agent is shutting down — prompt NOT delivered' })
+      }
+    })
   })
 }
 // claude's deliver: the pre-write LIVENESS gate — fail loud BEFORE attempting the socket if it isn't there (a
-// clearer message than a raw connect error, and the delivery's confirmation layer: socket present = agent alive).
-// Then inject the reply optimistically via replyViaSocket (no round-trip ack).
-function deliverViaRendezvous(id: string, text: string): Promise<DispatchResult> {
+// clearer message than a raw connect error, and the delivery's confirmation layer: socket present = agent
+// alive). Then the atomic parse-confirmed write; a KICKED outcome is a proven whole-chunk loss, so it resends
+// (bounded attempts + jitter so re-collision with the probe cadence is unlikely); exhausted retries fail loud.
+const DELIVER_ATTEMPTS = 3
+export async function deliverViaRendezvous(id: string, text: string, wallMs?: number): Promise<DispatchResult> {
   const sock = rvSock(id)
-  if (!existsSync(sock)) return Promise.resolve({ ok: false, error: `no rendezvous control socket for session ${id} (socketless/old session, or the agent is offline) — prompt NOT delivered` })
-  return replyViaSocket(sock, text)
+  if (!existsSync(sock)) return { ok: false, error: `no rendezvous control socket for session ${id} (socketless/old session, or the agent is offline) — prompt NOT delivered` }
+  let last: ReplyOutcome = { ok: false, error: 'not attempted' }
+  for (let attempt = 1; attempt <= DELIVER_ATTEMPTS; attempt++) {
+    last = await replyViaSocket(sock, text, wallMs)
+    if (last.ok || !last.kicked) return { ok: last.ok, ...(last.error ? { error: last.error } : {}) }
+    await new Promise((r) => setTimeout(r, 60 + Math.random() * 140))
+  }
+  return { ok: false, error: `rendezvous delivery was kicked by concurrent connects ${DELIVER_ATTEMPTS}× — prompt NOT delivered, retry the send` }
 }
 
 type JsonRpc = { id?: number; method?: string; params?: unknown; result?: unknown; error?: { code?: number; message?: string } }
@@ -997,6 +1039,15 @@ export const claudeHarness: Harness = {
   // dead-pane-reads-working bug). See rendezvousListening.
   liveness: (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) => (tmuxAlive && !!socketLive ? 'online' : 'offline'),
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
+  // the TUI's sessions panel ("← for agents"): a reply injected here is parsed + enqueued to the PANEL context
+  // and never drained (verified live: `queue-operation: enqueue` with no dequeue, no turn, daemon silent), so
+  // the parse-confirmed delivery above would still report a false success into it. Matched on the panel's own
+  // strings — the new-session composer placeholder, or its footer key hints together (either alone could drift
+  // across claude versions; requiring the footer PAIR keeps a prose false-positive unlikely).
+  deliveryBlockedBy: (paneText) =>
+    paneText.includes('describe a task for a new session') || (paneText.includes('enter to return') && paneText.includes('space to reply'))
+      ? 'the claude TUI is focused on its sessions panel ("← for agents"), which silently swallows injected prompts — press Enter in the session terminal to return to the composer, then resend'
+      : null,
   resumeArg: (rec) => `--resume ${rec.session}`,
 }
 

package/spec-cli/src/help.ts

@@ -55,15 +55,17 @@ a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex
     see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex spec lint (adoption TODO)',
   },
   materialize: {
-    line: 'materialize           re-materialize the harness artifacts (contract block · shims) for cwd’s project',
+    line: 'materialize           the base pass of harness adaptation: render .spec/.plugins into your harness’s artifacts',
     body: `Usage: spex materialize
 
-Materializes the surface:system plugin nodes into the managed <!-- spexcode --> block of
-CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. The materialize anchors on
-git-native events only (init · this verb · session-worktree creation · the pre-commit/post-checkout/
-post-merge hooks) — run it by hand after a toolchain update, or in the setup step of any clone that
-has no spex-planted hooks yet (CI, a cloud agent): the artifacts are generated and excluded, so they
-never arrive via git.`,
+The base operation of HARNESS ADAPTATION: one pass renders the spec tree's surface nodes into the
+artifacts each selected harness auto-discovers — the managed <!-- spexcode --> block of
+CLAUDE.md/AGENTS.md, the .claude/.codex shims, the skills/agents — and prints the content hash.
+The outputs are derived and never tracked: to change one, edit its source (.plugins, spexcode.json)
+and re-materialize — never the artifact. Not a one-time setup: it anchors on git-native events
+(init · this verb · session-worktree creation · the pre-commit/post-checkout/post-merge hooks) —
+run it by hand after a toolchain update, or in the setup step of any clone that has no spex-planted
+hooks yet (CI, a cloud agent): generated and excluded, the artifacts never arrive via git.`,
     see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
   },
   doctor: {
@@ -122,14 +124,18 @@ owner — the reverse edge: a file's GOVERNORS (code: — drives drift + eval fr
 over-owned → split the file). --actionable prints NOTHING unless action is needed (hook use).
 
 lint — checks the whole spec↔code graph and exits non-zero on errors. Errors: integrity (a
-code:/related: file does not exist; a dead/ambiguous/unverifiable \`path#symbol\` anchor; an anchor
-whose language has no designated extractor or whose extractor can't run here) · anchor-drift (a
-commit since the spec's version touched the ANCHORED unit's lines, unacked — the blocking tier of
-drift) · one-govern (a node governs >1 file) · living (a "## vN" changelog heading) · id-format (an
+code:/related: file does not exist; a dead/ambiguous/unverifiable \`path#symbol\` selector; a selector
+whose language has no designated extractor or whose extractor can't run here; a duplicate entry, a
+base path both bare and scoped, or a selector on a glob/directory) · anchor-drift (a
+commit since the spec's version touched an ANCHORED unit's lines, unacked — the blocking tier of
+drift; same-file selectors OR'd, one error naming the hit selectors) · one-govern (a node
+governs >1 DISTINCT file) · living (a "## vN" changelog heading) · id-format (an
 id char outside the whitelist — ascii [a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a
 leaf id reused) · mention (a [[id]] naming no node). Warns: altitude · breadth · coverage · drift
-(UNANCHORED drift — always advisory, never blocks) · anchor (anchoring a type) · related-drift ·
-owners · confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
+(UNANCHORED drift — always advisory, never blocks; on a scoped file's MISS, \`lint.scopedCodeMiss:
+"ignore"\` may silence it) · anchor (anchoring a type) · related-drift (a scoped related row warns
+per selector HIT, misses silent) · owners (whole-file governors only; scoped don't count) ·
+confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
 contrast \`spex eval lint\`, which is pure advisory and never blocks anyone.
 
 ack — stamp Spec-OK on HEAD (an empty stamp commit): the drift remedy when only MECHANICS changed
@@ -218,7 +224,7 @@ ls — node-scoped bare (its per-scenario eval history); session-scoped with an
 ✦-marked ahead of the inherited baseline. --export writes that evaluation as ONE self-contained
 HTML artifact (diff · evidence inlined · gates) for CI/sharing.
 
-scenario ls — the DECLARED contracts (name · tags · latest verdict), no evals: bare lists every
+scenario ls — the DECLARED contracts (name · tags · normalized test reference · latest verdict), no evals: bare lists every
 measurable node's scenarios; --unmeasured keeps only the never-measured — the blind-spot worklist.
 
 lint — the measurement layer's findings: malformed eval.md (eval-schema) · unmeasured (eval-missing) ·