spexcode 0.3.0 → 0.4.1

package/spec-cli/src/lint.ts

@@ -1,8 +1,9 @@
-import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { repoRoot, stagedFiles, git } from './git.js'
+import { repoRoot, git, driftIndex, historyIndex, rowsFor } from './git.js'
 import { loadSpecs } from './specs.js'
 import { readJsonConfig } from './layout.js'
+import { extractors, extractorFor, extOf, resolveAnchor, windowCommits, anchorHitCommits } from './anchors.js'
 
 export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
 
@@ -13,9 +14,12 @@ export type LintConfig = {
   identifierExtensions: string[]// extensions the altitude bare-filename signal recognises (see IDENT below)
   altitude: { lineBudget: number; charBudget: number; sizeable: number; dense: number; steps: number }
   maxChildren: number        // breadth budget: warn at >= this many direct children
-  driftErrorThreshold: number// commit-local gate HARD-BLOCKS a commit touching a node >= this many commits behind
   maxOwners: number          // warn when a file is governed (code:) by > this many nodes
   scenarioTags: string[]     // the closed vocabulary an eval scenario's `tags:` must draw from; extend it to mint a new tag
+  scopedCodeMiss: 'warn' | 'ignore' // the file-level drift ADVISORY on a selector-scoped code: file whose window has no
+                             // selector hit ([[code-anchor]]). 'warn' (default) keeps today's drift warning; 'ignore'
+                             // silences ONLY that advisory — hit blocks, bare code drift, integrity, acks, related
+                             // semantics, and eval freshness are all untouched by this knob.
 }
 const DEFAULT_CONFIG: LintConfig = {
   governedRoots: ['spec-dashboard/src', 'spec-cli/src'],
@@ -24,9 +28,9 @@ const DEFAULT_CONFIG: LintConfig = {
   identifierExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'md'],
   altitude: { lineBudget: 50, charBudget: 4200, sizeable: 35, dense: 1.3, steps: 3 },
   maxChildren: 8,
-  driftErrorThreshold: 3,
   maxOwners: 3,
   scenarioTags: ['frontend-e2e', 'backend-api', 'cli', 'desktop', 'mobile'],
+  scopedCodeMiss: 'warn',
 }
 export function loadConfig(root: string): LintConfig {
   // Absent spexcode.json → tuned defaults; a MALFORMED one throws LOUD (readJsonConfig) rather than
@@ -45,6 +49,10 @@ export function loadConfig(root: string): LintConfig {
 //    ROOT-level files and leaks every nested test into coverage. A slash-less glob is a basename intent →
 //    prepend "**/" so it matches that basename at any depth (the default "**/*.test.*" already does).
 export function normalizeConfig(cfg: LintConfig): LintConfig {
+  // a mistyped enum silently reverting to the default would green-wash (or over-warn) exactly the
+  // advisory the author meant to tune — same fail-loud rule as a malformed spexcode.json.
+  if (cfg.scopedCodeMiss !== 'warn' && cfg.scopedCodeMiss !== 'ignore')
+    throw new Error(`spexcode.json lint.scopedCodeMiss must be "warn" or "ignore", got ${JSON.stringify(cfg.scopedCodeMiss)}`)
   const dedot = (xs: string[]) => xs.map((x) => x.replace(/^\.+/, ''))
   return {
     ...cfg,
@@ -132,15 +140,25 @@ export async function specLint(): Promise<Finding[]> {
   const specs = await loadSpecs()
   const out: Finding[] = []
 
-  // integrity + build the file -> owners map.
+  // integrity + build the file -> owners map. A relation's STRUCTURAL problems (a duplicate entry,
+  // bare/scoped mixing on one base path, a selector on a glob — all from parseRelation,
+  // [[code-anchor]]) are integrity errors: malformed edges block like broken ones.
   const owners = new Map<string, string[]>()
+  const claimed = new Set<string>()
   for (const s of specs) {
+    for (const p of s.relationProblems)
+      out.push({ level: 'error', rule: 'integrity', spec: s.id, msg: `'${s.id}' ${p}` })
+    const scopedPaths = new Set(s.codeScoped.map((e) => e.path))
     for (const f of s.code) {
       if (!existsSync(join(root, f)))
         out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing file: ${f}` })
-      owners.set(f, [...(owners.get(f) ?? []), s.id])
+      claimed.add(f)
+      // a selector-SCOPED entry claims named units, not the whole file, so it stays out of the owners
+      // bound below ([[code-anchor]]) — `spex spec owner` still displays it as a (scoped) governor.
+      if (!scopedPaths.has(f)) owners.set(f, [...(owners.get(f) ?? []), s.id])
     }
-    // one-govern: a node is source of truth for at most ONE file, so drift/eval/ack have a single
+    // one-govern: a node is source of truth for at most ONE file — DISTINCT base paths; several
+    // `path#symbol` selectors on the same file are one subject — so drift/eval/ack have a single
     // unambiguous subject (see [[governed-related]]). >1 is a defect — pick the true subject, demote the
     // rest to related. ERROR (the node-side twin of too-many-owners' file-side bound). 0 is fine.
     if (s.code.length > 1)
@@ -149,7 +167,6 @@ export async function specLint(): Promise<Finding[]> {
   // a file is COVERED if any node GOVERNS (code:) or merely REFERENCES (related:) it; integrity covers both.
   // `related:` is the coverage net: govern is a sharp ideally-one-file pointer, so most files are reached by
   // related, not govern (see [[governed-related]]). It carries coverage but never drift, never eval freshness.
-  const claimed = new Set<string>(owners.keys())
   for (const s of specs) for (const f of s.related) {
     if (!existsSync(join(root, f)))
       out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing related file: ${f}` })
@@ -277,14 +294,91 @@ export async function specLint(): Promise<Finding[]> {
     out.push({ level: 'warn', rule: 'owners', msg: `${over.length} file(s) are governed by > ${cfg.maxOwners} nodes — each holds more separately-specified functionality than one file should. Worst: ${top}. SPLIT the file so each governor owns its own module (or merge the nodes, or give it a single foundation owner + related:).` })
   }
 
+  // code anchors ([[code-anchor]]): a code:/related: entry may pin named units (`path#symbol` — any
+  // number per base file, OR'd). On code:, the anchor is the BLOCKING tier of drift: a window
+  // commit (spec's last version..HEAD, non-merge, touching the governed file) whose --unified=0 hunks
+  // intersect any pinned unit's line range — extracted from the file AS OF that commit, by the
+  // extension's ONE designated extractor — is ONE anchor-drift ERROR naming the hit selectors, unless a
+  // Spec-OK ack covers it. On related:, the SAME engine yields only a soft warn on a hit — a scoped
+  // related miss is silent (never blocks, no ack, no eval freshness). Resolution failures are never
+  // silent for either relation: a dead or ambiguous selector, a selector on a directory, an unparseable
+  // working-tree file, an extension with no designated extractor, and a designated extractor that can't
+  // run here (no host typescript) all ERROR with the repair spelled out.
+  const regs = extractors(root)
+  const [didx, hidx] = await Promise.all([driftIndex(root), historyIndex(root)])
+  const readyWarned = new Set<string>()
+  for (const s of specs) {
+    for (const { relation, entries } of [{ relation: 'code' as const, entries: s.codeScoped }, { relation: 'related' as const, entries: s.relatedScoped }]) {
+      for (const { path, selectors } of entries) {
+        const x = extractorFor(regs, extOf(path))
+        if (!x) {
+          out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${selectors.join(', #')} (${relation}:), but no extractor is designated for '.${extOf(path)}' files — this language has no anchor support yet: add a LangSpec row (anchors.ts) or drop the selector(s)` })
+          continue
+        }
+        const ready = x.ready()
+        if (ready !== true) {
+          // once per (extractor, reason), even across several anchored nodes — one repair, one message.
+          if (!readyWarned.has(x.id + ready)) { readyWarned.add(x.id + ready); out.push({ level: 'error', rule: 'integrity', msg: `anchor extractor '${x.id}' cannot run: ${ready}` }) }
+          continue
+        }
+        if (!existsSync(join(root, path))) continue // the missing FILE already errored above
+        if (statSync(join(root, path)).isDirectory()) {
+          out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' puts a selector on a directory (${relation}: ${path}#${selectors[0]}) — a selector scopes ONE real file` })
+          continue
+        }
+        let units
+        try { units = x.extract(readFileSync(join(root, path), 'utf8'), path) } catch (e: any) {
+          out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${selectors.join(', #')} ('${s.id}') is unverifiable — the current file does not parse: ${e?.message ?? e}` })
+          continue
+        }
+        // each selector resolves (or errors) on its own; only the live ones feed the window engine.
+        const live: string[] = []
+        for (const sym of selectors) {
+          const res = resolveAnchor(units, sym)
+          if ('dead' in res) {
+            out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${sym} ('${s.id}') names no unit on the current tree — the unit was deleted or renamed; update the spec's ${relation}: entry to follow it` })
+            continue
+          }
+          if ('ambiguous' in res) {
+            out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${sym} ('${s.id}') names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` })
+            continue
+          }
+          if (res.ok.typeOnly)
+            out.push({ level: 'warn', rule: 'anchor', spec: s.id, file: path, msg: `${path}#${sym} anchors a ${res.ok.kind} — anchoring a type is usually wrong (types reshape with every refactor); anchor the behaviour-bearing unit instead` })
+          live.push(sym)
+        }
+        if (!live.length) continue
+        const since = rowsFor(hidx, s.path)[0]?.hash || ''
+        const win = windowCommits(didx, since, path)
+        if (!win.length) continue
+        const hits = await anchorHitCommits(root, win, path, live, x)
+        if (!hits.length) continue
+        const hitSyms = [...new Set(hits.flatMap((h) => h.selectors))]
+        const shas = hits.map((h) => h.commit.slice(0, 8)).join(', ')
+        const unparseable = hits.filter((h) => h.unparseable)
+        const parseNote = unparseable.length ? ` (${unparseable.length} of these could not be parsed at that commit — counted as hits conservatively)` : ''
+        if (relation === 'code')
+          out.push({ level: 'error', rule: 'anchor-drift', spec: s.id, file: path, msg: `${path}#${hitSyms.join(', #')} was changed by ${hits.length} commit(s) since spec '${s.id}' v${s.version} [${shas}]${parseNote} — the anchored contract's code moved: update the spec, or 'spex spec ack ${s.id} --reason "…"' if the contract still holds` })
+        else
+          out.push({ level: 'warn', rule: 'related-drift', spec: s.id, file: path, msg: `related ${path}#${hitSyms.join(', #')} ('${s.id}') was changed by ${hits.length} commit(s) since v${s.version} [${shas}]${parseNote} — a scoped dependency shifted, worth a glance (SOFT: never blocks, no ack, no eval staleness)` })
+      }
+    }
+  }
+
   // drift: a governed file has commits NOT yet reflected in its spec. Judged by true git ancestry —
   // loadSpecs computes `driftFiles` via driftFor() over the one cached driftIndex walk (git.ts): a
   // commit to the file counts iff it is NOT reachable from the spec's latest version (in-memory
   // parent-edge reachability, the equivalent of `rev-list <version>..HEAD -- <file>`), never a
   // log-position or timestamp guess.
+  // A selector-SCOPED code file keeps this file-level advisory by default (a miss still nudges); the
+  // committed `lint.scopedCodeMiss: "ignore"` silences ONLY this advisory for scoped entries — the
+  // anchor engine's verdicts above (hit = block, resolution failures = integrity) are untouched.
   for (const s of specs) {
-    for (const d of s.driftFiles)
+    const scopedPaths = new Set(s.codeScoped.map((e) => e.path))
+    for (const d of s.driftFiles) {
+      if (cfg.scopedCodeMiss === 'ignore' && scopedPaths.has(d.file)) continue
       out.push({ level: 'warn', rule: 'drift', spec: s.id, file: d.file, msg: `${d.file} is ${d.behind} commit(s) ahead of spec '${s.id}' (v${s.version}) — may be stale` })
+    }
   }
 
   // related drift: the SOFT tier ([[governed-related]]). A referenced file moved ahead of the node's
@@ -321,22 +415,3 @@ Diagnose, then apply the one honest remedy:
                               maps to a node, or file an issue and link it (defer honestly)
 
 Never patch. A reasoned ack or a real fix are recorded and re-judged at review; a blind ack is a lie.`
-
-// commit-local: an empty staged index (CI, audit) → no blockers, drift stays advisory; non-empty → block
-// only when an OWN staged file belongs to a node already >= driftErrorThreshold behind. Sub-threshold drift
-// on a touched node is returned for an advisory nudge; the backlog on untouched nodes never blocks.
-export async function driftGate(): Promise<{ blocked: string[]; touched: { id: string; drift: number }[]; threshold: number }> {
-  const root = repoRoot()
-  const cfg = loadConfig(root)
-  const staged = stagedFiles(root)
-  if (!staged.length) return { blocked: [], touched: [], threshold: cfg.driftErrorThreshold }
-  const specs = await loadSpecs()
-  const owners = new Map<string, string[]>()
-  for (const s of specs) for (const f of s.code) owners.set(f, [...(owners.get(f) ?? []), s.id])
-  const byId = new Map(specs.map((s) => [s.id, s]))
-  const ids = new Set<string>()
-  for (const f of staged) for (const o of owners.get(f) ?? []) ids.add(o)
-  const touched = [...ids].map((id) => byId.get(id)!).filter((s) => s && s.drift > 0)
-    .map((s) => ({ id: s.id, drift: s.drift })).sort((a, b) => b.drift - a.drift)
-  return { blocked: touched.filter((t) => t.drift >= cfg.driftErrorThreshold).map((t) => t.id), touched, threshold: cfg.driftErrorThreshold }
-}

package/spec-cli/src/localIssues.ts

@@ -272,6 +272,25 @@ function writeStoreFile(p: Issue, message: string): boolean {
   return true
 }
 
+// @@@ the shared trunk-data commit — the committing half of the store discipline, exported for OTHER
+// git-tracked data writes that need a durable landing with no worktree ritual behind them (the eval
+// sidecar's human-ok, [[human-ok]]). Same rules as the issue store's own write: only the trunk checkout
+// itself commits (a linked-worktree caller gets 'not-primary' back and leaves its append for its own
+// session's ritual commit — the sidecar, unlike the issue store, legitimately lives per-branch and
+// merges); the commit is `--no-verify` and provably scoped to the one data path; the shared store lock
+// serializes it against every other trunk data write so racing writers never fight over the git index.
+export function commitTrunkData(relPath: string, message: string): 'committed' | 'no-op' | 'not-primary' {
+  if (overrideStoreDir()) return 'not-primary'   // a disposable-store test rig commits nothing, ever
+  if (!isPrimaryCheckout()) return 'not-primary'
+  return withStoreLock(() => {
+    const root = mainCheckout()
+    git(['-C', root, 'add', '--', relPath])
+    if (!git(['-C', root, 'status', '--porcelain', '--', relPath]).trim()) return 'no-op'
+    git(['-C', root, 'commit', '--no-verify', '-m', message, '--', relPath])
+    return 'committed'
+  })
+}
+
 // 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/close reads the
 // current thread, never a stale copy. A pre-rename store migrates first (before the lock — ensure takes it).

package/spec-cli/src/migrate-table.ts

@@ -6,11 +6,9 @@
 export type MigrateAsset = { rel: string; template: string; oldShas: string[] }
 export const TEMPLATE_ASSETS: MigrateAsset[] = [
   {
-    "rel": "clarify-before-code/spec.md",
-    "template": "templates/presets/careful/.plugins/clarify-before-code/spec.md",
-    "oldShas": [
-      "a1b9c7e189df9b75a27005d381b43682d717ee6f"
-    ]
+    "rel": "commands/spec.md",
+    "template": "templates/spec/project/.plugins/commands/spec.md",
+    "oldShas": []
   },
   {
     "rel": "core/idle/idle.sh",
@@ -162,7 +160,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "distill/digest.mjs",
-    "template": "templates/spec/project/.plugins/distill/digest.mjs",
+    "template": "templates/spec/project/.plugins/skills/distill/digest.mjs",
     "oldShas": [
       "b596d196d35688130157698ca90950d412bf527f",
       "faff3509b004e8529d5c7f3abd29512fb389ceb9"
@@ -170,7 +168,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "distill/spec.md",
-    "template": "templates/spec/project/.plugins/distill/spec.md",
+    "template": "templates/spec/project/.plugins/skills/distill/spec.md",
     "oldShas": [
       "3e3fd25db1d465f72b636e6af8bcd873c0ceb3c2",
       "4a0b547ad63e15aa80ed7f826581ad90ca02d0f4",
@@ -179,7 +177,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "extract/spec.md",
-    "template": "templates/spec/project/.plugins/extract/spec.md",
+    "template": "templates/spec/project/.plugins/commands/extract/spec.md",
     "oldShas": [
       "064efd8321925bd0cff7ee725771b500a7baf6e7",
       "45c2b0fe12224ebc124b5f5fecafd1e8d82de93e",
@@ -196,7 +194,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "forge-link/spec.md",
-    "template": "templates/spec/project/.plugins/forge-link/spec.md",
+    "template": "templates/spec/project/.plugins/prompts/forge-link/spec.md",
     "oldShas": [
       "2472c085e6f72364eea004ba1d1b1f8d6b4e13ac",
       "c86439c5a3fe6cb3ece2c40186da0f476d1c52d4"
@@ -204,14 +202,19 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "memory-hygiene/spec.md",
-    "template": "templates/spec/project/.plugins/memory-hygiene/spec.md",
+    "template": "templates/spec/project/.plugins/prompts/memory-hygiene/spec.md",
     "oldShas": [
       "2b5313e770c7d2e857817adcf7bb72aecaeca45f"
     ]
   },
+  {
+    "rel": "prompts/spec.md",
+    "template": "templates/spec/project/.plugins/prompts/spec.md",
+    "oldShas": []
+  },
   {
     "rel": "regroup/spec.md",
-    "template": "templates/spec/project/.plugins/regroup/spec.md",
+    "template": "templates/spec/project/.plugins/commands/regroup/spec.md",
     "oldShas": [
       "37f632450faba3e9c5290468b52535e766faf45e",
       "aa3097a1b7ff51c4a8a0bfab82ac06a585081caa",
@@ -220,7 +223,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "reproduce-before-fix/spec.md",
-    "template": "templates/spec/project/.plugins/reproduce-before-fix/spec.md",
+    "template": "templates/spec/project/.plugins/prompts/reproduce-before-fix/spec.md",
     "oldShas": [
       "28eef30893a83b634900e43dfe729043c8f60ea8",
       "2d056b7344cbc0c4eb0dbeb0ba69ccee0e8b47db",
@@ -229,6 +232,11 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
       "fc3c060af70b01b2073163880a42d002e285ddc5"
     ]
   },
+  {
+    "rel": "skills/spec.md",
+    "template": "templates/spec/project/.plugins/skills/spec.md",
+    "oldShas": []
+  },
   {
     "rel": "spec.md",
     "template": "templates/spec/project/.plugins/spec.md",
@@ -249,7 +257,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "supervisor/spec.md",
-    "template": "templates/spec/project/.plugins/supervisor/spec.md",
+    "template": "templates/spec/project/.plugins/commands/supervisor/spec.md",
     "oldShas": [
       "036d5602a038e2565cd968e4a8a443ce80026025",
       "05963c00bc1031ba0d4f91ea68d60b1731f475f2",
@@ -271,7 +279,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "tidy/spec.md",
-    "template": "templates/spec/project/.plugins/tidy/spec.md",
+    "template": "templates/spec/project/.plugins/commands/tidy/spec.md",
     "oldShas": [
       "096fc1dd48a1692aeb87614a93bcce2473f2050a",
       "16ccbf044e74765a5c9cc212fba38356950a7e69",
@@ -286,6 +294,9 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
 ]
 // old-world template assets the shipped package no longer carries (recognized → reported, not replaced):
 export const RETIRED_ASSETS: Record<string, string[]> = {
+  "clarify-before-code/spec.md": [
+    "a1b9c7e189df9b75a27005d381b43682d717ee6f"
+  ],
   "core/harness-session-id/harness-session-id.sh": [
     "32b3b963ba6c2c659f0543e82a2a34128c4860bf",
     "626d7f3c56d6430c5dafb7713880a606b4ee8b03"
@@ -296,11 +307,11 @@ export const RETIRED_ASSETS: Record<string, string[]> = {
     "c05f182fc92fcd224f4c7953dc118e59665971aa",
     "c617fc05780f921c55280b68d9f55e60110f74eb"
   ],
-  "core/stop-gate/yatsu.evals.ndjson": [  // dead-words-ok: the migrator names the old vocabulary it migrates from
+  "core/stop-gate/yatsu.evals.ndjson": [
     "268c06c27f3b2dc71da8c0aca4d0507a227829f9",
     "e681fe71b8519577c19bb4f13bc0f310fb92dc31"
   ],
-  "core/stop-gate/yatsu.md": [  // dead-words-ok: the migrator names the old vocabulary it migrates from
+  "core/stop-gate/yatsu.md": [
     "f83f6b2406eb359beb1181bf0145558241806116"
   ],
   "e2e-review/spec.md": [

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

@@ -3,7 +3,7 @@
 //
 // 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
+// after collision-qualification renames it (e.g. a colliding `probe` leaf → `a_probe`). A label may
 // also be written pre-qualified to pin one collision branch.
 import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
@@ -26,7 +26,7 @@ const CASES = [
   ['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']],
+  ['active-spec-search', 'an injected sub-agent that searches specs for the agent, the spec analog of Explore', ['spec-search']],
   ['declare-done', 'how does a worker declare it is done', ['state']],
 ]
 

package/spec-cli/src/session-timeline.ts

@@ -0,0 +1,148 @@
+import { watch, existsSync, readFileSync, appendFileSync, mkdirSync, type FSWatcher } from 'node:fs'
+import { sessionsRoot, sessionStoreDir, sessionArtifactPath, listSessionIds, readAliasedRawRecord } from './layout.js'
+import type { Lifecycle, Proposal } from './sessions.js'
+
+// @@@ session-timeline - the PERSISTED interaction history of a session: every authored-lifecycle
+// transition (status + proposal + the FULL note text) and every delivered prompt, timestamped, appended to
+// `timeline.ndjson` in the session's global store dir. This is what a TERMINAL-FREE surface (the phone face,
+// [[mobile-ui]]) renders instead of a live pane: without the terminal, the declaration notes ARE the agent's
+// replies, and the timeline is the whole conversation.
+//
+// WHY an observer, not writer instrumentation: the lifecycle has a writer the TS layer never sees — the
+// mark-active hook value-replaces status/proposal/note in session.json with pure-shell sed ([[state]]).
+// Instrumenting every writer would always miss that one, so the recorder OBSERVES the store instead: one
+// fs.watch on the sessions root (debounced) plus a slow reconcile tick (the fs.watch is best-effort, same
+// stance as [[graph-stream]]'s source 1), and on each tick it diffs every governed record's
+// (status, proposal, note) against the last seen and appends what moved. One mechanism covers every writer
+// by construction. Granularity is the debounce window — a flap faster than ~100ms can collapse, exactly like
+// the board itself.
+//
+// The recorder runs ONLY in the serve process (superviseTimeline is called from index.ts) so exactly one
+// process appends; timestamps are observation times, honest to within the debounce. Only the AUTHORED axis
+// is recorded — liveness (offline/starting/unknown) is a present-tense derivation ([[state]]), re-derived
+// per probe and never history, so it stays off the durable log; a surface shows the CURRENT liveness from
+// the board row. The timeline lives and dies with the session record (close sweeps the store dir), like
+// comms.ndjson. `sent` events are appended by sendText on a CONFIRMED delivery (all prompt deliveries flow
+// through it: dashboard/phone input, `spex session send`, the merge dispatch); `from` is the sending
+// session's id, null = a human surface.
+
+export type TimelineEvent =
+  | { ts: string; kind: 'status'; status: Lifecycle; proposal: Proposal | null; note: string | null; display?: string }
+  | { ts: string; kind: 'sent'; text: string; from: string | null; replyVia?: 'note' }
+
+const timelinePath = (id: string): string => sessionArtifactPath(id, 'timeline.ndjson')
+
+function append(id: string, ev: TimelineEvent): void {
+  try {
+    mkdirSync(sessionStoreDir(id), { recursive: true })
+    appendFileSync(timelinePath(id), JSON.stringify(ev) + '\n')
+  } catch { /* best-effort: a failed history append must never break the state machine or a delivery */ }
+}
+
+function readEvents(id: string): TimelineEvent[] {
+  try {
+    const p = timelinePath(id)
+    if (!existsSync(p)) return []
+    return readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
+      try { return JSON.parse(l) as TimelineEvent } catch { return null }
+    }).filter((e): e is TimelineEvent => e != null && (e.kind === 'status' || e.kind === 'sent'))
+  } catch { return [] }
+}
+
+// the display word for an authored state — the SAME composition reconcile uses for the authored axis
+// (awaiting → its proposal's label, active → working), duplicated here as a tiny read-time map rather than
+// importing the state machine (sessions.ts imports THIS module for recordSent; a value import back would
+// be a cycle — the Lifecycle/Proposal imports above are type-only, erased at runtime).
+const PROPOSAL_DISPLAY: Record<string, string> = { merge: 'review', nothing: 'done', close: 'close-pending' }
+const displayOf = (e: { status: Lifecycle; proposal: Proposal | null }): string =>
+  e.status === 'awaiting' ? (PROPOSAL_DISPLAY[e.proposal ?? 'nothing'] ?? 'done')
+  : e.status === 'active' ? 'working' : e.status
+
+// ---- the recorder (serve-process only) ----
+
+// id → fingerprint of the last recorded (status, proposal, note); seeded per id from the persisted last
+// status line so a server restart appends nothing for a session that didn't move while the server was down —
+// and DOES append (with an honest observed-now timestamp) when it did.
+const lastSeen = new Map<string, string>()
+const fpOf = (status: string, proposal: string | null, note: string | null): string => JSON.stringify([status, proposal, note])
+
+function lastStatusEvent(id: string): { status: string; proposal: string | null; note: string | null } | null {
+  const evs = readEvents(id)
+  for (let i = evs.length - 1; i >= 0; i--) { const e = evs[i]; if (e.kind === 'status') return e }
+  return null
+}
+
+function scan(): void {
+  let ids: string[] = []
+  try { ids = listSessionIds() } catch { return }
+  for (const id of ids) {
+    try {
+      const raw = readAliasedRawRecord(id)
+      if (!raw || !raw.governed) continue
+      const status = (raw.status || 'active') as Lifecycle
+      const proposal = (raw.proposal || null) as Proposal | null
+      const note = raw.note || null
+      const fp = fpOf(status, proposal, note)
+      if (lastSeen.get(id) === fp) continue
+      if (!lastSeen.has(id)) {
+        const last = lastStatusEvent(id)
+        if (last && fpOf(last.status, last.proposal ?? null, last.note ?? null) === fp) { lastSeen.set(id, fp); continue }
+      }
+      lastSeen.set(id, fp)
+      append(id, { ts: new Date().toISOString(), kind: 'status', status, proposal, note })
+    } catch { /* one bad record must not stall the sweep */ }
+  }
+  const live = new Set(ids)
+  for (const k of [...lastSeen.keys()]) if (!live.has(k)) lastSeen.delete(k)
+}
+
+let watcher: FSWatcher | null = null
+let debounce: ReturnType<typeof setTimeout> | null = null
+let reconcile: ReturnType<typeof setInterval> | null = null
+
+// start the recorder: one debounced fs.watch on the store (a lifecycle write lands as a session.json write)
+// backstopped by a slow reconcile tick, plus an immediate first sweep. Idempotent; never throws — the
+// timeline is an accessory record, and its failure must never take the server down.
+export function superviseTimeline(): void {
+  if (!reconcile) reconcile = setInterval(scan, 60000)
+  if (!watcher) {
+    const root = sessionsRoot()
+    try { mkdirSync(root, { recursive: true }) } catch { /* best-effort */ }
+    try {
+      watcher = watch(root, { recursive: true }, () => {
+        if (debounce) return
+        debounce = setTimeout(() => { debounce = null; scan() }, 100)
+      })
+    } catch { watcher = null /* the reconcile tick still covers */ }
+  }
+  scan()
+}
+
+// record a CONFIRMED prompt delivery (called by sendText after the harness accepted it). `text` is the
+// caller's message BEFORE any mechanism insert (the note-reply hint is transport, not conversation);
+// `replyVia` marks that the hint rode along so a surface can badge it.
+export function recordSent(id: string, text: string, from: string | null, replyVia?: 'note'): void {
+  try { if (!readAliasedRawRecord(id)?.governed) return } catch { return }
+  append(id, { ts: new Date().toISOString(), kind: 'sent', text, from, ...(replyVia ? { replyVia } : {}) })
+}
+
+// the read surface behind GET /api/sessions/:id/timeline: the last `limit` events, oldest first, each
+// status event carrying its composed display word. null = no such session (the route 404s).
+// Adjacent status lines with identical (status, proposal, note) fold into their first: TWO serve processes
+// observing one store (a throwaway worktree/eval serve beside the live one) each keep their own lastSeen,
+// so a single record move can append twice — cross-process write locking isn't worth buying, so the log
+// stays best-effort append-only and the read is where duplicates die, same stance as the board.
+export function readTimeline(id: string, limit = 500): { events: TimelineEvent[] } | null {
+  let raw: ReturnType<typeof readAliasedRawRecord>
+  try { raw = readAliasedRawRecord(id) } catch { return null }
+  if (!raw || !raw.governed) return null
+  const folded: TimelineEvent[] = []
+  for (const e of readEvents(id)) {
+    const prev = folded[folded.length - 1]
+    if (e.kind === 'status' && prev?.kind === 'status' && prev.status === e.status
+      && (prev.proposal ?? null) === (e.proposal ?? null) && (prev.note ?? null) === (e.note ?? null)) continue
+    folded.push(e)
+  }
+  const tail = folded.slice(Math.max(0, folded.length - Math.max(1, limit)))
+  return { events: tail.map((e) => (e.kind === 'status' ? { ...e, display: displayOf(e) } : e)) }
+}

package/spec-cli/src/sessions.ts

@@ -10,6 +10,7 @@ import { loadSpecs } from './specs.js'
 import { defaultHarness, defaultLauncher, harnessById, resolveLauncher, rvSock, rendezvousListening, type Harness, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
 import { materialize } from './materialize.js'
 import { mainBranch, gitCommonDir, readConfig, runtimeRoot, treeSlotDir, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, readAliasedRawRecord, envSessionId, type RawRecord } from './layout.js'
+import { recordSent } from './session-timeline.js'
 import { stripRefSigil } from './mentions.js'
 
 // @@@ sessions - the WORKTREE is the durable unit; tmux is a disposable runtime handle. The per-session
@@ -863,6 +864,14 @@ export function withSenderHint(text: string, sender: MsgSender | null): string {
   const who = sender.label && sender.label !== sender.id ? `session "${sender.label}" (${sender.id})` : `session ${sender.id}`
   return `${text}\n\n— from ${who}. To reply: spex session send ${sender.id} "<your reply>"`
 }
+// @@@ withNoteReplyHint - the TERMINAL-FREE sender's insert, withSenderHint's sibling: a phone (or any
+// no-terminal surface, [[mobile-ui]]) cannot read the pane, so the only text that ever reaches its human is
+// the declaration NOTE ([[session-timeline]]). This one-line insert tells the agent exactly that, so its
+// next stop carries the complete answer in `--note` instead of prose that dies in an unseen terminal.
+// Appended server-side (the input route passes replyVia:'note'), so the phrase lives in ONE place and any
+// surface — desktop included, later — can opt in with the same flag.
+export const withNoteReplyHint = (text: string): string =>
+  `${text}\n\n— sent from a terminal-free client: the sender CANNOT see your terminal output. When you next stop (done/ask/park), put your COMPLETE reply to this message in the declaration's --note (e.g. spex session done --note "<full answer>") — the note is the only text that reaches them.`
 async function postJSON(path: string, body: unknown): Promise<void> {
   try {
     await fetch(`${await apiBase()}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
@@ -1843,21 +1852,37 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
 }
 
 // @@@ sendText - PROMPT control for a session, delivered through the session's HARNESS ADAPTER
-// ([[harness-adapter]]) — claude the rendezvous control socket (optimistic-after-liveness: the reply line flushes
-// to a live socket), codex app-server JSON-RPC into the visible TUI's thread. Either way there is NO silent
+// ([[harness-adapter]]) — claude the rendezvous control socket (atomic reply+repaint chunk: repaint-done proves
+// the daemon parsed it, a kicked connection resends, wall expiry on a live connection is busy-not-lost → ok),
+// codex app-server JSON-RPC into the visible TUI's thread. Either way there is NO silent
 // fallback: a prompt that can't be delivered — no socket / dead agent (claude), no app-server/thread (codex) — FAILS LOUD, returning
 // ok:false with a reason that propagates to the caller (API non-2xx, `spex session send`, the merge dispatch),
 // instead of reporting a false success. The harness is resolved from the record; an unknown id fails before any
 // harness transport is addressed. (The separate RAW nav-key channel keeps its own `tmux send-keys` path — see rawKey.)
-export async function sendText(id: string, text: string, from?: string): Promise<DispatchResult> {
+export async function sendText(id: string, text: string, from?: string, opts: { replyVia?: 'note' } = {}): Promise<DispatchResult> {
   if (!text) return { ok: false, error: 'empty prompt — nothing to dispatch' }
   const rec = readRecord(id)
   if (!rec) return { ok: false, error: `no session record for ${id} — prompt NOT delivered` }
   const h = harnessById(rec.harness || defaultHarness.id)
-  const r = await h.deliver({ ...rec, runtimeDir: runtimeRoot() }, text)
+  // the pane guard ([[harness-adapter]] deliveryBlockedBy): the ONE pane state where the harness swallows a
+  // prompt its channel confirms (claude's sessions panel), checkable only from the pane — refuse loudly with
+  // the recovery named instead of reporting a false success. A missing pane (window gone, probe failure) skips
+  // the guard: the delivery channel itself is the authority on whether the agent is reachable.
+  if (h.deliveryBlockedBy) {
+    try {
+      const blocked = h.deliveryBlockedBy(await tmux(['capture-pane', '-p', '-t', id], TMUX_PROBE_TIMEOUT_MS))
+      if (blocked) return { ok: false, error: blocked }
+    } catch { /* no pane to consult — let the delivery channel decide */ }
+  }
+  // a terminal-free sender's dispatch carries the note-reply insert ([[session-timeline]]); appended here,
+  // beside the delivery, so every input surface shares the one phrase and the timeline records the message
+  // WITHOUT it (the hint is transport, not conversation).
+  const r = await h.deliver({ ...rec, runtimeDir: runtimeRoot() }, opts.replyVia === 'note' ? withNoteReplyHint(text) : text)
   // record the delivered agent-to-agent message ([[comms-edge]]): only when it carries a sender (an agent
   // send, not a raw human dispatch) and actually landed. Fire-and-forget — never gates the send result.
   if (r.ok && from) void recordComms(id, from)
+  // the durable interaction history ([[session-timeline]]): every confirmed delivery is a `sent` event.
+  if (r.ok) recordSent(id, text, from ?? null, opts.replyVia)
   return r
 }