spexcode 0.2.8 → 0.4.0

package/spec-cli/src/localIssues.ts

@@ -3,7 +3,7 @@
 // never written into it. One thread = one PLAIN markdown file at <main>/.spec/.issues/<id>.md; there is
 // deliberately no content-kind taxonomy (a change suggestion, an annotation, a Q&A are the same mechanism —
 // the prose says what it is). Others reply/discuss like an async chatroom; a supervisor drains it via
-// `spex issues` (reading is the port's job, issues.ts — this module owns only the store + its write verbs).
+// `spex issue ls` (reading is the port's job, issues.ts — this module owns only the store + its write verbs).
 // Because a thread file is NOT named spec.md, the spec walk never nodes it and isSpecMd ignores it —
 // invisible to lint / drift / deriveStatus / board with ZERO exemption. The store lives on the TRUNK, not
 // per-branch: reads and writes target the main checkout and commit STRAIGHT to it (--no-verify, provably
@@ -28,22 +28,12 @@ const LEGACY_STORE_REL = '.spec/.forum'
 // truth is `spexcode.json`'s `issues.enabled` (the same settings file that carries every other toggle),
 // read via readConfig so a machine-local `spexcode.local.json` can override it. OFF silences the post-merge
 // nudge (and, in the dashboard, hides the issues view); the raw write verbs stay usable, since running one
-// is explicit consent. `spex issues on|off` flips the flag on disk — effective immediately, no commit
-// needed, because readConfig reads the working tree. The dashboard toggle is a thin wrapper over this same
-// switch. (The key was historically `proposals.enabled`; a pre-rename value still reads, and the next
-// toggle write rewrites it under `issues` — the same self-heal-on-touch discipline as the store-dir rename.)
-export const issuesEnabled = (): boolean => {
-  const cfg = readConfig(mainCheckout())
-  return cfg.issues?.enabled ?? (cfg as { proposals?: { enabled?: boolean } }).proposals?.enabled ?? true
-}
-
-function setEnabled(on: boolean): void {
-  const f = join(mainCheckout(), 'spexcode.json')
-  const cfg = existsSync(f) ? JSON.parse(readFileSync(f, 'utf8')) : {}
-  cfg.issues = { ...(cfg.issues || {}), enabled: on }
-  delete cfg.proposals   // the pre-rename key, superseded by `issues` on this write
-  writeFileSync(f, JSON.stringify(cfg, null, 2) + '\n')
-}
+// is explicit consent. There is deliberately NO CLI toggle verb (v0.3.0 — "no `spex config set`" is this
+// project's standing rule): flip the key by editing the JSON, effective immediately because readConfig
+// reads the working tree. A legacy pre-rename `proposals.enabled` key is NOT read (no fallback — fail
+// toward the default); `spex doctor` reports it so an old settings file gets repaired, not silently obeyed.
+export const issuesEnabled = (): boolean =>
+  readConfig(mainCheckout()).issues?.enabled ?? true
 
 const list = (v: string | undefined): string[] =>
   v ? v.split(',').map((s) => s.trim()).filter(Boolean) : []
@@ -79,7 +69,7 @@ function requirePrimaryStore(action: string): void {
 }
 
 // the local issue store dir — a fixed path directly under the trunk's .spec (name-independent, unlike the
-// .config system which nests under the named root node), OR the disposable override. Every read and write goes here.
+// .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'
@@ -183,7 +173,7 @@ export function loadLocalIssues(): Issue[] {
 export function loadOne(id: string): Issue {
   ensureStoreMigrated()
   const f = join(localStoreDir(), `${id}.md`)
-  if (!existsSync(f)) throw new Error(`no local issue '${id}' (see \`spex issues --all --store local\`)`)
+  if (!existsSync(f)) throw new Error(`no local issue '${id}' (see \`spex issue ls --all --store local\`)`)
   return parse(id, readFileSync(f, 'utf8'))
 }
 
@@ -282,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).
@@ -368,13 +377,13 @@ export async function replyLocalIssue(id: string, body: string, author: string,
 // 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 resolve`). Non-eval threads pay nothing (no yatsu/specs/sessions import).
+// `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-yatsu/src/filing.js')
+  const { evalReadingFiler } = await import('../../spec-eval/src/filing.js')
   const chain: (string | null)[] = [evalReadingFiler(node, scenario)]
   try {
     const { listSessions } = await import('./sessions.js')
@@ -453,7 +462,7 @@ function resolveRemarkHost(host: { issue?: string; node?: string; scenario?: str
   return loadOne(host.issue).id   // throws loudly if the issue doesn't exist
 }
 
-// author a remark on a host — the ONE write both the CLI (`spex remark`) and the server call. Stamps the
+// author a remark on a host — the ONE write both the CLI (`spex remark add`) and the server call. Stamps the
 // codeSha it was authored against (the worktree HEAD by default — R2). Returns the `<thread-id>#<rid>` ref.
 export async function remarkOnHost(
   host: { issue?: string; node?: string; scenario?: string },
@@ -471,7 +480,7 @@ export async function remarkOnHost(
 // a remark ref is `<thread-id>#<rid>`; the thread id (a store slug) never contains '#', so split on the last.
 function parseRemarkRef(ref: string): { id: string; rid: string } {
   const i = ref.lastIndexOf('#')
-  if (i <= 0 || i === ref.length - 1) throw new Error(`bad remark ref '${ref}' — expected <thread-id>#<rid> (the id \`spex remark\` printed)`)
+  if (i <= 0 || i === ref.length - 1) throw new Error(`bad remark ref '${ref}' — expected <thread-id>#<rid> (the id \`spex remark add\` printed)`)
   return { id: ref.slice(0, i), rid: ref.slice(i + 1) }
 }
 
@@ -525,15 +534,15 @@ export function nudge(node: string): string {
     '',
     '1. CLOSE what you finished. An issue whose work just landed is closed, not',
     '   left open — the open set is the OUTSTANDING work, so a stale open reads as a',
-    '   lie:  spex issues --store local     then   spex issues close <id>',
+    '   lie:  spex issue ls --store local     then   spex issue close <id>',
     '',
     '2. RECORD only what OUTLIVES this task — a concern you are NOT acting on now:',
     '   an off-mainline smell / awkward boundary / wish, or a trivial-but-must-not-',
     "   forget to-do that doesn't earn a spec node. NOT a bug tracker (that is the",
     '   spec graph + the forge), NOT your assigned task or a fix you are about to',
     '   make — those need no issue. Only the taste that would otherwise evaporate:',
-    '     spex issues                              # read first — reply if already raised',
-    '     spex issues open "<concern>" [--node <id>]   # else open one',
+    '     spex issue ls                            # read first — reply if already raised',
+    '     spex issue open "<concern>" [--node <id>]   # else open one',
     'A supervisor drains the store later. (Advisory — skip if nothing is owed.)',
     '───────────────────────────────────────────────────────────────────',
   ].join('\n')
@@ -553,7 +562,7 @@ export function closeoutNudge(sessionId: string | null | undefined): string {
     t.status === 'open' && !EVAL_CONCERN_RE.test(t.concern) &&
     (t.by === sessionId || t.replies.some((r) => r.by === sessionId)))
   if (!mine.length) return ''
-  return `\n\nIssue closeout — ${mine.length} still-open local issue(s) you touched (opened or replied): ${mine.map((t) => t.id).join(', ')}. For each, close it now if its work is finished (\`spex issues close <id>\`), or reply why it should stay open past this session (\`spex issues reply <id> --body "<why>"\`). Some issues rightly outlive their session — this is a reminder to sweep, not a gate.`
+  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 ─────────────────────────
@@ -582,24 +591,16 @@ function readBody(args: string[]): string | undefined {
 const repeated = (args: string[], name: string): string[] =>
   args.flatMap((a, i) => (a === `--${name}` ? [args[i + 1]] : [])).filter(Boolean) as string[]
 
-// the local-issue WRITE verbs, folded into the one issues surface (`spex issues <sub>` — the read routes
-// here when its first positional is a write sub): open "<concern>" [--store local|<host>] [--node id…]
-// [--evidence hash…] [--body -|text], the id-based reply, and the feature toggle
-// on | off | status. `nudge` is internal (the post-merge hook's caller). Store is a property of the issue,
+// 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 === 'on' || sub === 'off') {
-      setEnabled(sub === 'on')
-      console.log(`issues workflow ${sub.toUpperCase()} — spexcode.json issues.enabled = ${sub === 'on'}${sub === 'on' ? '' : ' (post-merge nudge silenced; dashboard issues view hidden)'}`)
-      return 0
-    }
-    if (sub === 'status') { console.log(`issues workflow is ${issuesEnabled() ? 'ON' : 'OFF'}`); return 0 }
     if (sub === 'reply') {
       const id = bare(args.slice(1))[0]
       const body = readBody(args)
-      if (!id || !body) { console.error('usage: spex issues reply <issue-id> --body -|<text> [--evidence <hash>…]'); return 2 }
+      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') })
@@ -610,19 +611,13 @@ export async function runIssueWrite(args: string[]): Promise<number> {
       if (s) console.log(`  ${s}`)
       return 0
     }
-    if (sub === 'nudge') {
-      // internal: the post-merge hook calls this to print the (toggle-aware) nudge for a merged node.
-      const text = nudge(bare(args.slice(1))[0] || '')
-      if (text) console.log(text)
-      return 0
-    }
     // `open`: start a new issue — STORE-ROUTED through the one creation port ([[issues]] createIssue, the
     // same routine POST /api/issues runs): default local commits to the trunk store; `--store <host>`
     // creates the real forge issue through that store's driver (no promote round-trip when the concern is
     // born forge-visible). The concern is the bare positional(s) after the sub.
     const concern = sub === 'open' ? bare(args.slice(1)).join(' ').trim() : ''
     if (!concern) {
-      console.error('usage: spex issues open "<concern>" [--store local|<host>] [--node <id>…] [--evidence <hash>…] [--body -|<text>]\n       spex issues reply|close|promote <issue-id> …  |  on|off|status')
+      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, {
@@ -633,23 +628,25 @@ export async function runIssueWrite(args: string[]): Promise<number> {
     })
     const re = r.nodes.length ? ` (re: ${r.nodes.join(', ')})` : ''
     console.log(r.store === 'local'
-      ? `opened '${r.id}'${re} — committed to the local issue store; read it with \`spex issues\``
+      ? `opened '${r.id}'${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 issues: ${e instanceof Error ? e.message : e}`)
+    console.error(`spex issue: ${e instanceof Error ? e.message : e}`)
     return 1
   }
 }
 
-// the first positionals runIssueWrite handles — the issues command routes these to it, everything else is
-// the read. Exported so the router and the runner can never drift.
-export const ISSUE_WRITE_SUBS = new Set(['open', 'reply', 'on', 'off', 'status', 'nudge'])
+// 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 <host> --body -|<text> [--code-sha <sha>] [--scenario <name>] [--evidence <hash>…]`
+// `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 {
@@ -657,40 +654,44 @@ export async function runRemark(args: string[]): Promise<number> {
     const positional = bare(args)[0]
     const body = readBody(args)
     if (!positional || !body) {
-      console.error('usage: spex remark <issue-id | node --scenario name> --body -|<text> [--code-sha <sha>] [--evidence <hash>…]')
+      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 issues --all\``)
+    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: ${e instanceof Error ? e.message : e}`)
+    console.error(`spex remark add: ${e instanceof Error ? e.message : e}`)
     return 1
   }
 }
 
-// `spex resolve <remark-ref>` — flip resolved=true (agent-only, never the author, monotonic — see resolveRemark).
+// `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 resolve <remark-ref>   (the <thread-id>#<rid> `spex remark` printed)'); return 2 }
+  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 resolve: ${e instanceof Error ? e.message : e}`); return 1 }
+  } catch (e) { console.error(`spex remark resolve: ${e instanceof Error ? e.message : e}`); return 1 }
 }
 
-// `spex retract <remark-ref>` — the author withdraws their OWN remark, removing it (author-only — see retractRemark).
+// `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 retract <remark-ref>'); return 2 }
+  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 retract: ${e instanceof Error ? e.message : e}`); return 1 }
+  } catch (e) { console.error(`spex remark retract: ${e instanceof Error ? e.message : e}`); return 1 }
 }

package/spec-cli/src/materialize.ts

@@ -39,7 +39,7 @@ const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
 const SPEX = join(PKG, 'bin', 'spex.mjs')
 // the manifest + content-hash marker + plugin-folder ledger land in the materialized TREE's own slot of the
 // GLOBAL per-project store (layout.treeSlotDir — trees/<enc-worktree>), NOT the worktree and NOT one shared
-// per-project file: each is a pure function of ONE tree's .config, and the old single slot let the last-
+// per-project file: each is a pure function of ONE tree's .plugins, and the old single slot let the last-
 // materialized tree's hook set reach every other tree's dispatch ([[hook-dispatch]]). The worktree keeps
 // zero SpexCode-materialized runtime; only the harness-discovered contract files + shims (which the harness
 // must find in-tree) are written under proj below.

package/spec-cli/src/mentions.ts

@@ -2,7 +2,7 @@
 // node) and `@session` (an ACTOR — a live session, or `@new` for a fresh worker). The same parser resolves
 // them in ANY input box; the resolve+dispatch live HERE (CLI-first) so the issues page, the composer, and an agent's
 // own prompt share one implementation. An `@` "just auto-sends a prompt": resolve it against the live board
-// sessions and dispatch via [[dispatch]]'s sendKeys / [[launch]]'s newSession — storage and delivery stay
+// sessions and dispatch via [[dispatch]]'s sendText / [[launch]]'s newSession — storage and delivery stay
 // separate, and sessions.ts is imported LAZILY so a mention-free post pays nothing.
 
 // ── parse (pure) ──────────────────────────────────────────────────────────────────────────────────────
@@ -17,8 +17,8 @@ const uniq = (xs: string[]): string[] => [...new Set(xs)]
 
 // ── CLI sigil tolerance ───────────────────────────────────────────────────────────────────────────────
 // In FREE TEXT the sigils are required — they are what marks a reference apart from prose. In a CLI
-// ARGUMENT the whole token IS the reference, so the sigil is optional: `spex review @graph` ≡
-// `spex review graph`, `spex yatsu eval [[cli-surface]]` ≡ `spex yatsu eval cli-surface`. One shared strip,
+// ARGUMENT the whole token IS the reference, so the sigil is optional: `spex session review @graph` ≡
+// `spex session review graph`, `spex eval add [[cli-surface]]` ≡ `spex eval add cli-surface`. One shared strip,
 // applied by the session-selector matcher and every node-arg read site, so the habit a user learns in the
 // dashboard's input boxes works verbatim on the CLI — never a second grammar to learn.
 export function stripRefSigil(token: string): string {
@@ -78,8 +78,8 @@ export type DispatchOutcome = { token: string; result: 'sent' | 'spawned' | 'off
 function mentionPrompt(threadId: string, node: string | null, author: string, text: string): string {
   const re = node ? ` (re: ${node})` : ''
   return `You were @-mentioned in issue thread "${threadId}"${re} by ${author}:\n\n  ${text.trim()}\n\n` +
-    `Read the thread and act as the comment asks (often just a look): \`spex issues --all\` lists them; ` +
-    `reply with \`spex issues reply ${threadId} --body -\`.`
+    `Read the thread and act as the comment asks (often just a look): \`spex issue ls --all\` lists them; ` +
+    `reply with \`spex issue reply ${threadId} --body -\`.`
 }
 // A non-open thread is settled work: a fresh worker spawned onto it must not re-implement what already
 // landed, so the prompt leads with the status and a verify-on-main-first instruction.
@@ -92,7 +92,7 @@ export function newWorkerPrompt(threadId: string, node: string | null, author: s
     : ''
   return `Issue thread "${threadId}"${on} @-mentioned @new (by ${author}) for a fresh look:\n\n  ${text.trim()}\n\n` +
     settled +
-    `Read the thread (\`spex issues --all\`, find ${threadId}) and act on it${node ? `; the relevant node is ${node}` : ''}.`
+    `Read the thread (\`spex issue ls --all\`, find ${threadId}) and act on it${node ? `; the relevant node is ${node}` : ''}.`
 }
 
 // Parse a committed issue post's text for `@` actors and deliver to each. Best-effort and LOUD: the thread is
@@ -104,7 +104,7 @@ export async function dispatchMentions(
 ): Promise<DispatchOutcome[]> {
   const { actors } = parseMentions(text)
   if (!actors.length) return []
-  const { sendKeys, listSessions, newSession } = await import('./sessions.js')
+  const { sendText, listSessions, newSession } = await import('./sessions.js')
   const sessions = await listSessions()
   const resolved = resolveActors(actors, sessions as unknown as ActorSession[])
   const out: DispatchOutcome[] = []
@@ -120,7 +120,7 @@ export async function dispatchMentions(
       } catch (e) { out.push({ token: r.token, result: 'failed', detail: e instanceof Error ? e.message : String(e) }) }
       continue
     }
-    const res = await sendKeys(r.session.id, mentionPrompt(ctx.threadId, ctx.node, ctx.author, text), 'issues')
+    const res = await sendText(r.session.id, mentionPrompt(ctx.threadId, ctx.node, ctx.author, text), 'issues')
     out.push(res.ok ? { token: r.token, result: 'sent', detail: r.session.id }
                     : { token: r.token, result: 'offline', detail: res.error })
   }
@@ -131,9 +131,9 @@ export async function dispatchMentions(
 // A committed reply is ALSO auto-delivered as a COURTESY — never an assignment — to a FALLBACK CHAIN of
 // candidates, in order, stopping at the FIRST one that can be reached: for a remark this is the reading's
 // filer session, then the node's governing session, then nobody (it still surfaces on the board via the
-// teeth). This is a NOTIFICATION chain only — it resolves NOTHING (resolve stays a deliberate `spex resolve`,
+// teeth). This is a NOTIFICATION chain only — it resolves NOTHING (resolve stays a deliberate `spex remark resolve`,
 // R3); it just reaches an agent who can act. It is the same delivery pipe as dispatchMentions (one
-// online-resolution + one sendKeys), with the same cuts that keep courtesy ≠ assignment: deliver ONLY to an
+// online-resolution + one sendText), with the same cuts that keep courtesy ≠ assignment: deliver ONLY to an
 // ONLINE session (an unreachable link is skipped for the next, NEVER spawns a worker, NEVER drains — only an
 // explicit @new spawns); SKIP a candidate that is the replier (no self-notify); a candidate already reached by
 // an explicit @-target of this same text counts as delivered, so the chain STOPS (no double-delivery, no
@@ -146,14 +146,14 @@ function originatorPrompt(threadId: string, node: string | null, replier: string
   const re = node ? ` (re: ${node})` : ''
   return `A new reply landed on a thread you originated — "${threadId}"${re}, from ${replier}:\n\n  ${text.trim()}\n\n` +
     `This is a courtesy heads-up (you started this thread), not an assignment. Look if it concerns you; ` +
-    `\`spex issues --all\` lists them, reply with \`spex issues reply ${threadId} --body -\`.`
+    `\`spex issue ls --all\` lists them, reply with \`spex issue reply ${threadId} --body -\`.`
 }
 
 // The pure fallback decision (testable without sessions.ts): walk the ordered chain (nulls/dupes/the-replier
 // pruned) and return the FIRST link that resolves to an online session — that is who the courtesy goes to. A
 // link already reached by an explicit @-target of this same text short-circuits to `reached` (stop, no
 // double-delivery — the actor already has it); an offline/absent link falls through to the next. `none` means
-// the chain ran dry (nobody online). This is the whole fallback logic; delivery is a thin sendKeys around it.
+// the chain ran dry (nobody online). This is the whole fallback logic; delivery is a thin sendText around it.
 export type LoopInPick =
   | { kind: 'deliver'; originator: string; session: ActorSession }
   | { kind: 'reached' }
@@ -177,7 +177,7 @@ export function pickLoopIn(
 
 // `chain` is the ordered fallback list. We deliver the courtesy to the first online link and STOP; an
 // offline/failed link falls through to the next. NOTIFICATION ONLY — this never touches a `resolved` bit
-// (resolve is a deliberate `spex resolve`), never spawns (only `@new` spawns).
+// (resolve is a deliberate `spex remark resolve`), never spawns (only `@new` spawns).
 export async function notifyOriginator(
   chain: (string | null)[],
   replier: string,
@@ -186,10 +186,10 @@ export async function notifyOriginator(
 ): Promise<LoopIn | null> {
   const seen = new Set<string>()
   if (!chain.some((c) => c && c !== replier && !seen.has(c) && (seen.add(c), true))) return null   // nothing to do → no session load
-  const { sendKeys, listSessions } = await import('./sessions.js')
+  const { sendText, listSessions } = await import('./sessions.js')
   const pick = pickLoopIn(chain, replier, await listSessions() as unknown as ActorSession[], ctx.alreadyDelivered)
   if (pick.kind !== 'deliver') return null                    // reached via @ / nobody online → silent
-  const res = await sendKeys(pick.session.id, originatorPrompt(ctx.threadId, ctx.node, replier, text), 'issues')
+  const res = await sendText(pick.session.id, originatorPrompt(ctx.threadId, ctx.node, replier, text), 'issues')
   return res.ok ? { originator: pick.originator } : null      // a failed send behaves like offline: silent
 }