spexcode 0.5.8 → 0.6.0

package/spec-cli/src/layout.ts

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { git, repoRoot, gitA, headSha, worktreeSpecSig, worktreeSpecDelta, type NodeOp } from './git.js'
 import { guardWorktree } from './resilience.js'
 import { HARNESSES, type HarnessId } from './harness.js'
@@ -31,6 +32,20 @@ export type Config = {
     icon?: string                  // project identity icon: a picker preset id; existing emoji/Iconify/URL values remain supported ([[identity-config]])
     showHeadlessLaunchers?: boolean // include headless harness profiles in the dashboard New Session picker (default false; [[launcher-visibility]])
   }
+  uploads?: {
+    // One resumable attachment policy. Values default from templates/spexcode.json so a project may omit this
+    // section, while spexcode.local.json can tune the whole top-level section for one machine.
+    maxBytes?: number               // maximum bytes in one attachment (default: templates/spexcode.json)
+    chunkBytes?: number             // raw PATCH payload cap and client slice size (default: templates/spexcode.json)
+    concurrency?: number            // simultaneous attachment streams in one dashboard batch (default: templates/spexcode.json)
+    requestTimeoutMs?: number       // browser timeout for one chunk/complete request (default: templates/spexcode.json)
+    retryLimit?: number             // automatic retries after the first failed transient chunk request (default: templates/spexcode.json)
+    retryDelayMs?: number           // wait between automatic transient-request retries (default: templates/spexcode.json)
+    incompleteTtlMs?: number        // idle staging lifetime before an unfinished transfer expires (default: templates/spexcode.json)
+    cleanupIntervalMs?: number      // reaper interval for stale staging bytes (default: templates/spexcode.json)
+    minFreeBytes?: number           // filesystem capacity retained while reserving attachments (default: templates/spexcode.json)
+    evidenceMaxBytes?: number       // retained ceiling for eval-evidence POST bodies (default: templates/spexcode.json)
+  }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)
     // named launcher profiles: a session picks ONE by name at create time ([[launcher-select]]), fixing both
@@ -67,7 +82,7 @@ export type Config = {
 // `serve`, `harnesses`, `render`, and `preset` are frontend/runtime/policy concerns (read separately via readConfig —
 // preset by init.ts at seed time, harnesses by [[harness-select]]; see api-endpoint / sessions.ts maxActive /
 // gateway.ts), NOT layout fields, so they stay out of the convention rather than forcing a default.
-type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'resources' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'forge' | 'private' | 'render'>>
+type Convention = Required<Omit<Config, 'dashboard' | 'uploads' | 'sessions' | 'resources' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'forge' | 'private' | 'render'>>
 
 export type Worktree = {
   path: string; branch: string | null; node: string | null
@@ -105,6 +120,53 @@ export function readConfig(root: string): Config {
   return out
 }
 
+export type UploadPolicy = Required<NonNullable<Config['uploads']>>
+
+const TEMPLATE_CONFIG = fileURLToPath(new URL('../templates/spexcode.json', import.meta.url))
+const MIN_POSITIVE_INTEGER = 1
+const MIN_NONNEGATIVE_INTEGER = 0
+
+function uploadConfigError(field: keyof UploadPolicy, rule: string): never {
+  const error = new Error(`uploads.${field} must be ${rule}`)
+  error.name = 'ConfigError'
+  throw error
+}
+
+function configuredInteger(value: unknown, field: keyof UploadPolicy, minimum: number): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum) {
+    uploadConfigError(field, minimum === MIN_POSITIVE_INTEGER ? 'a positive integer' : 'a non-negative integer')
+  }
+  return value
+}
+
+function resolveUploadPolicy(values: Record<keyof UploadPolicy, unknown>): UploadPolicy {
+  const policy: UploadPolicy = {
+    maxBytes: configuredInteger(values.maxBytes, 'maxBytes', MIN_POSITIVE_INTEGER),
+    chunkBytes: configuredInteger(values.chunkBytes, 'chunkBytes', MIN_POSITIVE_INTEGER),
+    concurrency: configuredInteger(values.concurrency, 'concurrency', MIN_POSITIVE_INTEGER),
+    requestTimeoutMs: configuredInteger(values.requestTimeoutMs, 'requestTimeoutMs', MIN_POSITIVE_INTEGER),
+    retryLimit: configuredInteger(values.retryLimit, 'retryLimit', MIN_NONNEGATIVE_INTEGER),
+    retryDelayMs: configuredInteger(values.retryDelayMs, 'retryDelayMs', MIN_NONNEGATIVE_INTEGER),
+    incompleteTtlMs: configuredInteger(values.incompleteTtlMs, 'incompleteTtlMs', MIN_POSITIVE_INTEGER),
+    cleanupIntervalMs: configuredInteger(values.cleanupIntervalMs, 'cleanupIntervalMs', MIN_POSITIVE_INTEGER),
+    minFreeBytes: configuredInteger(values.minFreeBytes, 'minFreeBytes', MIN_NONNEGATIVE_INTEGER),
+    evidenceMaxBytes: configuredInteger(values.evidenceMaxBytes, 'evidenceMaxBytes', MIN_POSITIVE_INTEGER),
+  }
+  if (policy.chunkBytes > policy.maxBytes) uploadConfigError('chunkBytes', 'no greater than uploads.maxBytes')
+  return policy
+}
+
+export function uploadPolicyDefaults(): UploadPolicy {
+  return resolveUploadPolicy(readJsonConfig(TEMPLATE_CONFIG).uploads as Record<keyof UploadPolicy, unknown>)
+}
+
+// The seed template is the sole default-value source. Existing projects may omit `uploads`; they receive this
+// policy, while a committed/local value overrides it through readConfig's existing one-level merge.
+export function readUploadPolicy(root: string): UploadPolicy {
+  const configured = readConfig(root).uploads
+  return resolveUploadPolicy({ ...uploadPolicyDefaults(), ...configured } as Record<keyof UploadPolicy, unknown>)
+}
+
 // the shared git common dir (env-stripped git() so a hook's exported GIT_DIR can't misdirect it). Memoized:
 // it's a process constant, but mainBranch()/mainRoot() resolve it per call (~60 git rev-parse forks per board build without the cache).
 let commonDirCache: string | null = null
@@ -130,6 +192,20 @@ export function mainCheckout(proj?: string): string {
   return dirname(gcd)
 }
 
+// @@@ main root - identity checks need creation's configured-main answer without the record/overlay work in resolveLayout.
+export function mainRoot(proj?: string): string {
+  if (proj) {
+    const checkout = mainCheckout(proj)
+    const configured = readConfig(checkout).main?.trim()
+    return configured ? resolve(checkout, configured) : checkout
+  }
+  try {
+    const checkout = mainCheckout()
+    const configured = readConfig(checkout).main?.trim()
+    return configured ? resolve(checkout, configured) : checkout
+  } catch { return repoRoot() }
+}
+
 // @@@ global per-session store - Fork A: NO SpexCode files live in the worktree any more, so the worktree's
 // spec/code tree is pristine (zero per-session pollution). Every per-session runtime artifact — the
 // structured record (session.json) AND the launcher products (prompt, launch, launch.sh) AND the recorded comms AND

package/spec-cli/src/lint.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path'
 import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText, type DriftPathEvent } from './git.js'
 import { loadSpecs, parseFrontmatter } from './specs.js'
 import { readJsonConfig } from './layout.js'
-import { extractors, extractorFor, extOf, parseCodeEntry, relationClaimsPath, resolveAnchor, windowEvents, anchorHitQueries } from './anchors.js'
+import { extractors, extractorFor, extOf, parseCodeEntry, relationClaimsPath, resolveAnchor, resolveSelectors, windowEvents, anchorHitQueries } from './anchors.js'
 import { DEFAULT_TEST_GLOBS, sourcePolicyDescription, trackedSourceFiles } from './source-files.js'
 
 export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
@@ -355,9 +355,11 @@ export async function specLint(root = repoRoot(), regs = extractors(root), optio
           continue
         }
         // each selector resolves (or errors) on its own; only the live ones feed the window engine.
+        // The dead/ambiguous verdict itself comes from the ONE shared classifier ([[code-anchor]]); only the
+        // wording of the gate's findings lives here.
         const live: string[] = []
-        for (const sym of selectors) {
-          const res = resolveAnchor(units, sym)
+        for (const res of resolveSelectors(units, selectors)) {
+          const sym = res.selector
           if ('dead' in res) {
             anchorSteps.push({ finding: { 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

package/spec-cli/src/localIssues.ts

@@ -17,7 +17,7 @@ import { readdirSync, existsSync, mkdirSync, writeFileSync, readFileSync, rmdirS
 import { join, dirname, resolve as resolvePath } from 'node:path'
 import { git, headSha, repoRoot } from './git.js'
 import { mainCheckout, envSessionId, readConfig } from './layout.js'
-import { parseMentions, dispatchMentions, notifyOriginator, deliveredIds, summarize, type DispatchOutcome, type LoopIn } from './mentions.js'
+import { parseMentions } from './mentions.js'
 import type { Issue, Reply } from './issues.js'
 
 const LOCAL_STORE_REL = '.spec/.issues'
@@ -72,7 +72,7 @@ function requirePrimaryStore(action: string): void {
 // .plugins system which nests under the named root node), OR the disposable override. Every read and write goes here.
 const localStoreDir = (): string => overrideStoreDir() ?? join(mainCheckout(), LOCAL_STORE_REL)
 // the author's signature: the effective governed session id (envSessionId handles the claude/codex split).
-const currentSession = (): string => envSessionId() || 'unknown'
+export const currentSession = (): string => envSessionId() || 'unknown'
 // a synchronous sleep for the commit-retry backoff (Date/timers-free, safe in any runtime).
 const sleep = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
 
@@ -356,64 +356,21 @@ export function reply(id: string, body: string, author?: string, evidence?: stri
 
 // @@@ the PROGRAMMATIC store write surface — the dashboard's human write path calls these (author `'human'`).
 // The store is git-native data, so a human's write goes through the SAME open/reply the CLI uses (committed
-// straight to the trunk), and — because the store is the programmatic surface — a human's @-mention DOES
-// dispatch (a human summons an agent from the issues page, per [[mentions]]). Each returns the written thread
-// plus the @-dispatch outcomes so a caller can echo who was notified.
-// The two reply deliveries are orthogonal: `evidence?` (f15b) carries a video annotation's frame blobs onto
-// the thread; the originator loop-in ([[mentions]]) notifies who raised the thread. Both apply on every reply.
-export async function replyLocalIssue(id: string, body: string, author: string, evidence?: string[], remark?: { targetCodeSha: string }): Promise<{ thread: Issue; outcomes: DispatchOutcome[]; loopIn: LoopIn | null }> {
+// straight to the trunk). @session remains text in that committed discussion; it never summons an agent.
+// Originator courtesy is composed above this store because it needs eval-aware candidate resolution.
+export async function replyLocalIssue(id: string, body: string, author: string, evidence?: string[], remark?: { targetCodeSha: string }): Promise<{ thread: Issue }> {
   const thread = reply(id, body, author, evidence, remark)
-  const node = thread.nodes[0] || null
-  const outcomes = await dispatchMentions(body, { threadId: id, node, author, status: thread.status })
-  // implicit originator loop-in ([[mentions]] / [[remark-substrate]] R3): a courtesy copy down the fallback
-  // chain — the reading's filer, then the node's governing session — delivered to the first online link.
-  const loopIn = await notifyOriginator(await threadOriginators(thread), author, body,
-    { threadId: id, node, alreadyDelivered: deliveredIds(outcomes) })
-  return { thread, outcomes, loopIn }
+  return { thread }
 }
 
-// The FALLBACK CHAIN of candidates a reply loops in ([[mentions]] loop-in / [[remark-substrate]] R3's dispatch
-// clause), tried in order until one is online. A plain thread's only candidate is its author (`by`). An
-// EVAL-COMMENT thread (concern `eval: <node> · <scenario>`, the eval-remark track) chains: the agent who FILED
-// the reading the remark judges FIRST — resolved from the TRUNK sidecar, then from each LIVE session's
-// WORKTREE (an in-flight reading, filed on an unmerged branch, is invisible to the trunk — exactly the
-// review-time case, when the filer sits online awaiting review and the remark must reach them) — then, when
-// every filer is offline/absent, the NODE's governing session, so an unresolved remark still REACHES an agent
-// who can act on it. A broken/absent worktree sidecar falls through silently — one bad worktree never fails
-// the remark write. This is notification only; it resolves nothing (R3: resolve is a deliberate
-// `spex remark resolve`). Non-eval threads pay nothing (no eval/specs/sessions import).
-const EVAL_CONCERN_RE = /^eval: (.+?) · (.+)$/   // node first (never contains ' · '), then the scenario (may)
-async function threadOriginators(thread: Issue): Promise<(string | null)[]> {
-  const m = EVAL_CONCERN_RE.exec(thread.concern)
-  if (!m) return [thread.by]
-  const node = m[1].trim(), scenario = m[2].trim()
-  const { evalReadingFiler } = await import('../../spec-eval/src/filing.js')
-  const chain: (string | null)[] = [evalReadingFiler(node, scenario)]
-  try {
-    const { listSessions } = await import('./sessions.js')
-    for (const s of await listSessions()) {
-      try { if (s.path) chain.push(evalReadingFiler(node, scenario, s.path)) } catch { /* one unreadable worktree → next link */ }
-    }
-  } catch { /* sessions unavailable (bare store, no tmux) → trunk-only chain, as before */ }
-  chain.push(await nodeGoverningSession(node))
-  return chain
-}
 
-// A node's governing session — the `session` its spec resolves to (the Session: trailer of its latest version,
-// else the frontmatter `session:` fallback; specs.ts owns that derivation). The fallback link when a reading's
-// filer is unreachable. null when the node is unknown or has no governing session.
-async function nodeGoverningSession(nodeId: string): Promise<string | null> {
-  const { loadSpecs } = await import('./specs.js')
-  return (await loadSpecs()).find((s) => s.id === nodeId)?.session ?? null
-}
 
 export async function postLocalIssue(
   concern: string,
   opts: { nodes?: string[]; body?: string; evidence?: string[]; author: string },
-): Promise<{ thread: Issue; outcomes: DispatchOutcome[] }> {
+): Promise<{ thread: Issue }> {
   const thread = openIssue(concern, { nodes: opts.nodes, body: opts.body, evidence: opts.evidence, author: opts.author })
-  const outcomes = await dispatchMentions(opts.body || concern, { threadId: thread.id, node: thread.nodes[0] || null, author: opts.author, status: thread.status })
-  return { thread, outcomes }
+  return { thread }
 }
 
 export function closeLocalIssue(id: string): { status: 'landed'; already: boolean } {
@@ -430,7 +387,16 @@ export function closeLocalIssue(id: string): { status: 'landed'; already: boolea
 // (node, scenario). The scenario track is NOT a new store — it is the annotator's lazy eval thread, keyed by
 // its `eval: <node> · <scenario>` concern; a remark reuses it, creating it on first remark as a stub
 // container (every remark is a reply, never the thread body, so the resolved bit always lives in one place).
+// @@@ the eval-concern format, once - composer and parser side by side. The parser existed in two copies while
+// a CLI surface down here had to recognise the format without being able to import the module that composes it;
+// [[issues-cli]] removed that constraint, so the format is one pair now. `node` is matched non-greedily because
+// it can never contain ' · ' while a scenario name may.
 const evalConcernKey = (node: string, scenario: string): string => `eval: ${node} · ${scenario}`
+const EVAL_CONCERN_RE = /^eval: (.+?) · (.+)$/
+export const parseEvalConcern = (concern: string): { node: string; scenario: string } | null => {
+  const m = EVAL_CONCERN_RE.exec(concern)
+  return m ? { node: m[1].trim(), scenario: m[2].trim() } : null
+}
 
 // find-or-create the ONE scenario thread for (node, scenario), keyed by its eval concern, ATOMICALLY under
 // the store lock. R4 says a scenario's remark track lives ONCE — but a concurrent first-remark burst is a
@@ -438,7 +404,7 @@ const evalConcernKey = (node: string, scenario: string): string => `eval: ${node
 // two racers could both read "absent" and both create, minting a second thread whose remarks are invisible
 // to the concern key (a silent teeth blind spot). Holding one lock across both the find AND the create closes
 // that window: a racer either sees the thread the first created, or is the first. The stub is a pure
-// container (its body carries a [[wiki-link]], never an @-mention), so it needs no async dispatch — a
+// container (its body carries a [[wiki-link]], never an @-reference), so it needs no async notification — a
 // synchronous create suffices, and staying sync is exactly what lets it share the lock hold.
 function findOrCreateEvalThread(node: string, scenario: string, author: string): Issue {
   ensureStoreMigrated()   // migrate before the lock (ensure takes it itself; never nest a store-lock hold)
@@ -472,13 +438,13 @@ export async function remarkOnHost(
   host: { issue?: string; node?: string; scenario?: string },
   body: string,
   opts: { codeSha?: string; author?: string; evidence?: string[] } = {},
-): Promise<{ ref: string; rid: string; codeSha: string; thread: Issue; outcomes: DispatchOutcome[]; loopIn: LoopIn | null }> {
+): Promise<{ ref: string; rid: string; codeSha: string; thread: Issue; author: string }> {
   const author = opts.author || currentSession()
   const codeSha = opts.codeSha || headSha(repoRoot())
   const id = resolveRemarkHost(host, author)
-  const { thread, outcomes, loopIn } = await replyLocalIssue(id, body, author, opts.evidence, { targetCodeSha: codeSha })
+  const { thread } = await replyLocalIssue(id, body, author, opts.evidence, { targetCodeSha: codeSha })
   const rid = thread.replies[thread.replies.length - 1].rid!
-  return { ref: `${id}#${rid}`, rid, codeSha, thread, outcomes, loopIn }
+  return { ref: `${id}#${rid}`, rid, codeSha, thread, author }
 }
 
 // a remark ref is `<thread-id>#<rid>`; the thread id (a store slug) never contains '#', so split on the last.
@@ -563,139 +529,10 @@ export function nudge(node: string): string {
 export function closeoutNudge(sessionId: string | null | undefined): string {
   if (!sessionId || sessionId === 'unknown' || !issuesEnabled()) return ''
   const mine = loadLocalIssues().filter((t) =>
-    t.status === 'open' && !EVAL_CONCERN_RE.test(t.concern) &&
+    t.status === 'open' && !parseEvalConcern(t.concern) &&
     (t.by === sessionId || t.replies.some((r) => r.by === sessionId)))
   if (!mine.length) return ''
   return `\n\nIssue closeout — ${mine.length} still-open local issue(s) you touched (opened or replied): ${mine.map((t) => t.id).join(', ')}. For each, close it now if its work is finished (\`spex issue close <id>\`), or reply why it should stay open past this session (\`spex issue reply <id> --body "<why>"\`). Some issues rightly outlive their session — this is a reminder to sweep, not a gate.`
 }
 
 // ───────────────────────── CLI ─────────────────────────
-const fl = (args: string[], name: string): string | undefined => {
-  const i = args.indexOf(`--${name}`)
-  return i >= 0 ? args[i + 1] : undefined
-}
-const VALUE_FLAGS = new Set(['--node', '--body', '--evidence', '--scenario', '--code-sha', '--store'])
-// bare positionals, skipping flags + their values.
-function bare(args: string[]): string[] {
-  const out: string[] = []
-  for (let i = 0; i < args.length; i++) {
-    const t = args[i]
-    if (t.startsWith('--')) { if (VALUE_FLAGS.has(t)) i++; continue }
-    out.push(t)
-  }
-  return out
-}
-// `--body -` reads stdin; `--body "text"` is literal; absent → undefined.
-function readBody(args: string[]): string | undefined {
-  const v = fl(args, 'body')
-  if (v === undefined) return undefined
-  return v === '-' ? readFileSync(0, 'utf8') : v
-}
-// a repeatable value flag: every `--<name> <value>` pair, in order.
-const repeated = (args: string[], name: string): string[] =>
-  args.flatMap((a, i) => (a === `--${name}` ? [args[i + 1]] : [])).filter(Boolean) as string[]
-
-// the local-issue WRITE verbs of the issue drawer (`spex issue <verb>`): open "<concern>" [--store local|<host>] [--node id…]
-// [--evidence hash…] [--body -|text], and the id-based reply. Store is a property of the issue,
-// never a second command — open and reply route by it (issues.ts createIssue/replyIssue).
-export async function runIssueWrite(args: string[]): Promise<number> {
-  const sub = args[0]
-  try {
-    if (sub === 'reply') {
-      const id = bare(args.slice(1))[0]
-      const body = readBody(args)
-      if (!id || !body) { console.error('usage: spex issue reply <issue-id> --body -|<text> [--evidence <hash>…]'); return 2 }
-      // the ONE store-routed reply verb ([[issues]]): a forge id posts a real comment through the driver,
-      // a local id commits to the store — the same command either way (dynamic import: no static cycle).
-      const r = await (await import('./issues.js')).replyIssue(id, body, { evidence: repeated(args, 'evidence') })
-      console.log(r.store === 'local'
-        ? `replied to '${id}' — ${r.replies?.length} post(s) in thread`
-        : `commented on '${id}' — ${r.url}`)
-      const s = summarize(r.outcomes, r.loopIn)
-      if (s) console.log(`  ${s}`)
-      return 0
-    }
-    // `open`: start a new issue — STORE-ROUTED through the one creation port ([[issues]] createIssue, the
-    // same routine POST /api/issues runs): default local commits to the trunk store; `--store <host>`
-    // creates the real forge issue through that store's driver (no promote round-trip when the concern is
-    // born forge-visible). The concern is the bare positional(s) after the sub.
-    const concern = sub === 'open' ? bare(args.slice(1)).join(' ').trim() : ''
-    if (!concern) {
-      console.error('usage: spex issue open "<concern>" [--store local|<host>] [--node <id>…] [--evidence <hash>…] [--body -|<text>]\n       spex issue reply|close|promote <issue-id> …')
-      return 2
-    }
-    const r = await (await import('./issues.js')).createIssue(concern, {
-      store: fl(args, 'store'),
-      nodes: repeated(args, 'node'),
-      body: readBody(args),
-      evidence: repeated(args, 'evidence'),
-    })
-    const re = r.nodes.length ? ` (re: ${r.nodes.join(', ')})` : ''
-    console.log(r.store === 'local'
-      ? `opened '${r.id}'${re} — committed to the local issue store; read it with \`spex issue ls\``
-      : `opened '${r.id}' on ${r.store}${re} — ${r.url}`)
-    const s = summarize(r.outcomes)
-    if (s) console.log(`  ${s}`)
-    return 0
-  } catch (e) {
-    console.error(`spex issue: ${e instanceof Error ? e.message : e}`)
-    return 1
-  }
-}
-
-// the first positionals runIssueWrite handles — the issue drawer routes these to it. Exported so the
-// router and the runner can never drift. (`nudge` is not here: it is machine plumbing, called only by the
-// post-merge hook as `spex internal nudge`; the on|off|status toggle verbs died in v0.3.0 — the switch is
-// the `issues.enabled` settings key.)
-export const ISSUE_WRITE_SUBS = new Set(['open', 'reply'])
-
-// ── remark CLI ([[remark-substrate]]) — CLI-first: the whole author→resolve→retract loop, no server needed ──
-// `spex remark add <issue-id | <node> --scenario <name>> --body -|<text> [--code-sha <sha>] [--evidence <hash>…]`
-// host = a local issue id, OR a <node> with --scenario <name>. Records targetCodeSha (default: worktree HEAD).
-export async function runRemark(args: string[]): Promise<number> {
-  try {
-    const scenario = fl(args, 'scenario')
-    const positional = bare(args)[0]
-    const body = readBody(args)
-    if (!positional || !body) {
-      console.error('usage: spex remark add <issue-id | node --scenario name> --body -|<text> [--code-sha <sha>] [--evidence <hash>…]')
-      return 2
-    }
-    // THE FLAG DECIDES THE PARSE ([[cli-surface]] §1): `--scenario` present ⇒ the positional is a NODE id
-    // (the remark pins to that node's scenario track); absent ⇒ it is an ISSUE id. Never type-sniffed —
-    // a node id and an issue id are both bare slugs, so any "looks like" guess would misroute; the flag
-    // is the one unambiguous discriminator, and a wrong host fails loud downstream (unknown issue/node).
-    const host = scenario ? { node: positional, scenario } : { issue: positional }
-    const r = await remarkOnHost(host, body, { codeSha: fl(args, 'code-sha'), evidence: repeated(args, 'evidence') })
-    console.log(`remark ${r.ref}  (against ${r.codeSha.slice(0, 7) || 'HEAD'}) — read it with \`spex issue ls --all\``)
-    const s = summarize(r.outcomes, r.loopIn)
-    if (s) console.log(`  ${s}`)
-    return 0
-  } catch (e) {
-    console.error(`spex remark add: ${e instanceof Error ? e.message : e}`)
-    return 1
-  }
-}
-
-// `spex remark resolve <remark-ref>` — flip resolved=true (agent-only, never the author, monotonic — see resolveRemark).
-export async function runResolve(args: string[]): Promise<number> {
-  const ref = bare(args)[0]
-  if (!ref) { console.error('usage: spex remark resolve <remark-ref>   (the <thread-id>#<rid> `spex remark add` printed)'); return 2 }
-  try {
-    const by = currentSession()
-    resolveRemark(ref, by)
-    console.log(`resolved remark ${ref} — by ${by}`)
-    return 0
-  } catch (e) { console.error(`spex remark resolve: ${e instanceof Error ? e.message : e}`); return 1 }
-}
-
-// `spex remark retract <remark-ref>` — the author withdraws their OWN remark, removing it (author-only — see retractRemark).
-export async function runRetract(args: string[]): Promise<number> {
-  const ref = bare(args)[0]
-  if (!ref) { console.error('usage: spex remark retract <remark-ref>'); return 2 }
-  try {
-    retractRemark(ref, currentSession())
-    console.log(`retracted remark ${ref}`)
-    return 0
-  } catch (e) { console.error(`spex remark retract: ${e instanceof Error ? e.message : e}`); return 1 }
-}

package/spec-cli/src/loop-in.ts

@@ -0,0 +1,78 @@
+import { notifyOriginator, type LoopIn } from './mentions.js'
+import { replyIssue, type Issue } from './issues.js'
+import { parseEvalConcern, remarkOnHost } from './localIssues.js'
+
+// @@@ loop-in - the originator loop-in's eval-aware half, at the one altitude that can hold it
+// ([[mentions]] / [[remark-substrate]] R3). The MECHANISM never moved: `notifyOriginator`, `summarizeLoopIn` and
+// `LoopIn` live in `mentions.ts`, genuine substrate, and they stay there. What lived at the wrong height was a
+// single INPUT — resolving WHICH candidates to try, which for an eval-remark thread means asking the eval
+// package who filed the reading under judgement. That resolution sat in `localIssues.ts`, a module the eval
+// package imports, so it could only reach eval through a deferred `await import()` whose own comment explained
+// why it had to be wrong. A correct mechanism with one mis-layered input is the hardest shape to see: every
+// piece you read is where it belongs.
+//
+// This module sits above both the store modules and the eval layer, so the import is an ordinary static one.
+
+// @@@ ONE composer per path - the loop-in is reachable from four call sites: the CLI's `issue reply` and
+// `remark add`, and the HTTP routes for each. If each composed its own chain, the same verb would report
+// different candidates depending on which door it came through, and no gate we have would notice the drift.
+// So the four sites call these two functions, and these two are the only places a chain is built.
+
+// A node's governing session — the `session` its spec resolves to (the Session: trailer of its latest version,
+// else the frontmatter `session:` fallback; specs.ts owns that derivation). The fallback link when a reading's
+// filer is unreachable. null when the node is unknown or has no governing session.
+async function nodeGoverningSession(nodeId: string): Promise<string | null> {
+  const { loadSpecs } = await import('./specs.js')
+  return (await loadSpecs()).find((s) => s.id === nodeId)?.session ?? null
+}
+
+// The FALLBACK CHAIN of candidates a reply loops in, tried in order until one is online.
+// A plain thread's only candidate is its author. An EVAL-COMMENT thread (concern `eval: <node> · <scenario>`)
+// chains: the agent who FILED the reading the remark judges FIRST — resolved from the TRUNK sidecar, then from
+// each LIVE session's worktree sidecar (the review-time case, when the filer sits online awaiting review) —
+// then the NODE's governing session, so an unresolved remark still reaches an agent who can act on it. A
+// broken/absent worktree sidecar falls through silently: one bad worktree never fails the remark write.
+// Non-eval threads pay nothing — no eval, specs or sessions module is touched for them.
+async function threadOriginators(thread: Issue): Promise<(string | null)[]> {
+  const parsed = parseEvalConcern(thread.concern)
+  if (!parsed) return [thread.by]
+  const { node, scenario } = parsed
+  const { evalReadingFiler } = await import('../../spec-eval/src/filing.js')
+  const chain: (string | null)[] = [evalReadingFiler(node, scenario)]
+  try {
+    const { listSessions } = await import('./sessions.js')
+    for (const s of await listSessions()) {
+      try { if (s.path) chain.push(evalReadingFiler(node, scenario, s.path)) } catch { /* one unreadable worktree → next link */ }
+    }
+  } catch { /* sessions unavailable (bare store, no tmux) → trunk-only chain, as before */ }
+  chain.push(await nodeGoverningSession(node))
+  return chain
+}
+
+// the implicit courtesy copy every reply carries: a copy down the fallback chain, delivered to the first online
+// link, notification only — it resolves nothing (R3 keeps resolve a deliberate second-party act).
+const loopInFor = async (thread: Issue, author: string, body: string, threadId: string) =>
+  notifyOriginator(await threadOriginators(thread), author, body, { threadId, node: thread.nodes[0] || null })
+
+/** `issue reply` for every store, with the originator loop-in composed on top. */
+export async function replyIssueWithLoopIn(
+  id: string,
+  body: string,
+  opts: { author?: string; node?: string | null; evidence?: string[] } = {},
+): Promise<Awaited<ReturnType<typeof replyIssue>> & { loopIn: LoopIn | null }> {
+  const r = await replyIssue(id, body, opts)
+  // a forge thread's author is a host login, not a live session, so there is no reachable originator and no
+  // local thread to read one from — silent by design, exactly as before.
+  const loopIn = r.thread ? await loopInFor(r.thread, r.author, body, id) : null
+  return { ...r, loopIn }
+}
+
+/** `remark add` on a host, with the same loop-in composed by the same code. */
+export async function remarkWithLoopIn(
+  host: { issue?: string; node?: string; scenario?: string },
+  body: string,
+  opts: { codeSha?: string; author?: string; evidence?: string[] } = {},
+): Promise<Awaited<ReturnType<typeof remarkOnHost>> & { loopIn: LoopIn | null }> {
+  const r = await remarkOnHost(host, body, opts)
+  return { ...r, loopIn: await loopInFor(r.thread, r.author, body, r.thread.id) }
+}

package/spec-cli/src/materialize.ts

@@ -17,27 +17,6 @@ export type MaterializedArtifact = {
 }
 export type MaterializeResult = { contentHash: string; planted: MaterializedArtifact[] }
 
-// @@@ materialize - the materialize step (≈0.85s), anchored on GIT-NATIVE events only ([[commit-surgery]]):
-// spex verbs (init/materialize), session-worktree creation, and the planted git hooks (pre-commit,
-// post-checkout, post-merge) — never a harness event; the harness is a READER of the materialized files, not
-// a trigger. It turns the spec tree's surface nodes into the flat artifacts each consumer reads
-// cheaply, so a USER-self-launched claude/codex (no SpexCode process in the launch) gets the whole system via
-// harness-auto-discovered files: (1) the hook MANIFEST (our dispatcher reads it), (2) the CONTRACT — the
-// surface:system plugin bodies (in name order) — written WHOLE into each
-// harness's contract file(s), (3) the thin SHIMS (every event → dispatch.sh), (4) the per-harness TRUST
-// (Codex's deterministic trusted_hash; Claude none). EVERY harness-specific fact is owned by the
-// [[harness-adapter]] (harness.ts) — this file just loops over HARNESSES.
-//
-// THE FORGETTING LAW ([[harness-delivery]]): materialize(P₂) ∘ materialize(P₁) = materialize(P₂) — one pass
-// under the current policy fully forgets every prior policy's artifacts; idempotence is the special case
-// P₂ = P₁, and dematerialize (= materialize(∅), what `spex uninstall` builds on) is the empty policy. The
-// implementation is ERASE-THEN-ASSERT over a CLOSED set of landing points: each is first erased
-// unconditionally by its IDENTITY STAMP (sentinel blocks, the shim's dispatch.sh command line, the generated
-// mark on skills/agents, the filter config namespace, the skip-worktree bit), then rewritten per the current
-// policy (possibly to nothing). There are no policy-pair branches. The one cross-tree migration receipt below
-// preserves old common ignore entries until every registered tree owns its local projection; it never reads or
-// reconstructs a sibling policy.
-
 const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
 // the ONE spex entry: the launcher (bin/spex.mjs), never a raw `tsx cli.ts` pair — the launcher owns tsx
@@ -62,14 +41,6 @@ export function contentHash(proj: string): string {
   } catch { return '' }
 }
 
-// @@@ footprint kinds ([[residence]]) - the vote axis is RETIRED: materialized artifacts carry no facts, so
-// they are NEVER tracked — there is exactly ONE residence behavior, not three. `.spec` + `spexcode.json` are ALWAYS
-// tracked (git is the database — no knob can untrack them); machine facts (shims, spexcode.local.json),
-// run residue (.worktrees/) stays in the common exclude; tree-selected artifacts are hidden by a managed
-// working .gitignore block whose tracked bytes stay pristine through the content filter. A contract file the host TRACKS — or one the user has begun
-// writing THEIR OWN prose into — is covered by the clean/smudge content filter ([[content-filter]]). An
-// environment without the generator (a teammate's clone, CI, a cloud agent) runs `spex materialize` in its
-// setup step — there is no committed-artifact delivery mode.
 export function retiredAxisNotice(cfg: { render?: string; private?: boolean }): void {
   if (!cfg.render?.trim() && !cfg.private) return
   const field = cfg.render?.trim() ? `"render": "${cfg.render.trim()}"` : '"private": true'
@@ -123,12 +94,6 @@ function publishSelection(path: string, body: string): void {
   renameSync(prepared, path)
 }
 
-// @@@ contract kind detection ([[residence]]) - a contract file's residence is a LIVE CONTENT FACT, not
-// an install-time choice, re-judged on every materialize: TRACKED → filter domain; untracked + wholly ours
-// (nothing left after stripping our sentinel block) → exclude domain; untracked + HOST CONTENT present (the
-// user began writing their own prose into it) → neither hidden nor tracked-for-them: the exclude entry is
-// withheld (hiding user content would make their prose invisible to git — data-loss shaped) and the clean
-// filter is pre-armed so their eventual, entirely-their-own `git add` strips our block automatically.
 const SENTINEL_RE = /\n*<!-- spexcode:start -->[\s\S]*?<!-- spexcode:end -->\n*/
 export function stripSpexcodeBlock(text: string): string {
   const m = SENTINEL_RE.exec(text)
@@ -170,13 +135,6 @@ function sweepGeneratedAgents(dir: string | null): void {
   }
 }
 
-// @@@ dematerialize - materialize(∅): the ERASE phase, also the whole of a backout ([[spex-uninstall]] adds
-// only the global store + plugin sweep + optional git hooks on top). Every removal is gated on an identity
-// stamp, so it deletes ONLY what a materialize wrote — never the user's prose, settings, or any .spec data. Order
-// matters once: the managed blocks leave the WORKING contract files before the content filter's config goes
-// (edge ③ in [[content-filter]] — a block outliving its clean filter surfaces as an uncommitted change).
-// `arts` (live skill/agent node names) widens the sweep to pre-stamp legacy files; the GENERATED_MARK sweep
-// covers everything materialized since, including products of renamed/deleted nodes.
 function eraseTree(proj: string, arts: HarnessArtifacts, preserveProject: boolean): void {
   for (const h of HARNESSES) {
     // h.clean = the adapter's surgical inverse: contract block (sentinels, deleteIfEmpty), the dispatch.sh-