spexcode 0.2.0 → 0.2.2

package/spec-cli/src/issues.ts

@@ -9,8 +9,9 @@
 // (createIssue/createComment/closeIssue — the driver stays the only network toucher; the tracer stays read-only).
 import type { ForgeIssue, ForgePR } from '../../spec-forge/src/port.js'
 import { resolveLinks } from '../../spec-forge/src/links.js'
-import { loadLocalIssues, loadOne, reply, resolve, issuesEnabled, replyLocalIssue, runIssueWrite, ISSUE_WRITE_SUBS } from './localIssues.js'
-import { dispatchMentions, type DispatchOutcome, type LoopIn } from './mentions.js'
+import { DEFAULT_FORGE_HOST, FORGE_DRIVERS, forgeDriverFor, forgeIssueStores } from '../../spec-forge/src/drivers.js'
+import { closeLocalIssue, loadLocalIssues, loadOne, postLocalIssue, reply, issuesEnabled, replyLocalIssue, runIssueWrite, ISSUE_WRITE_SUBS } from './localIssues.js'
+import { dispatchMentions, parseMentions, type DispatchOutcome, type LoopIn } from './mentions.js'
 import { envSessionId } from './layout.js'
 import { loadSpecsLite } from './specs.js'
 
@@ -35,9 +36,8 @@ export type Issue = {
   store: string      // 'local' | a forge host ('github') — the adapter that holds it
   concern: string
   by: string
-  status: string     // its own lifecycle: local open|accepted|rejected|landed; forge open|closed
+  status: string     // its own lifecycle: local open|landed; forge open|closed
   nodes: string[]
-  signers: string[]
   created: string
   body: string
   replies: Reply[]
@@ -47,6 +47,26 @@ export type Issue = {
 
 export type ForgeState = { issues: ForgeIssue[]; prs: ForgePR[] }
 export type ForgeSlice = { host: string; state: ForgeState }
+export type IssueStore = { id: string; label: string; kind: 'local' | 'forge'; writable: true }
+
+export function issueStores(): IssueStore[] {
+  return [
+    { id: 'local', label: 'local', kind: 'local', writable: true },
+    ...forgeIssueStores().map((s) => ({ ...s, writable: true as const })),
+  ]
+}
+
+function inferNodes(concern: string, body: string | undefined, explicit: string[] = []): string[] {
+  return [...new Set([...explicit, ...parseMentions(`${concern}\n${body || ''}`).nodes])]
+}
+
+function forgeIssueBody(concern: string, body: string | undefined, nodes: string[], evidence: string[] = []): string {
+  return [
+    (body || `(no detail given — ${concern})`).trim(),
+    nodes.length ? `Spec: ${nodes.join(', ')}` : '',
+    evidence.length ? `Evidence: ${evidence.join(', ')} (yatsu blob hashes)` : '',
+  ].filter(Boolean).join('\n\n')
+}
 
 // ── the (node, scenario) ↔ eval-thread join ([[remark-teeth]]) ────────────────────────────────────────
 // A scenario's remark track lives ONCE in trunk, keyed by its `eval: <node> · <scenario>` concern thread
@@ -101,7 +121,6 @@ export function fromForge(slice: ForgeSlice, nodeIds: string[]): Issue[] {
     by: i.author,
     status: (i.state || '').toLowerCase(),
     nodes: nodesByNumber.get(i.number) ?? [],
-    signers: [],
     created: i.createdAt,
     body: i.body,
     // the forge comments ARE the thread — the same Reply shape a local thread carries, so nothing
@@ -127,27 +146,63 @@ export function mergedIssues(forge: ForgeSlice | null, nodeIds: string[]): Issue
     .sort((a, b) => b.created.localeCompare(a.created))
 }
 
+// @@@ createIssue - the ONE creation port, store-routed ([[issues]]): the dashboard's New form
+// (POST /api/issues) and `spex issues open [--store <store>]` run this SAME routine. Default local commits
+// to the trunk store; a forge store creates the REAL forge issue through that store's driver, its body
+// carrying the `Spec: <nodes>` marker so the existing tracer read links it straight back — no promote
+// round-trip needed when the concern is born forge-visible.
+export async function createIssue(
+  concern: string,
+  opts: { store?: string; nodes?: string[]; body?: string; evidence?: string[]; author?: string } = {},
+): Promise<{ store: string; id: string; nodes: string[]; url?: string; outcomes: DispatchOutcome[] }> {
+  const store = opts.store || 'local'
+  const author = opts.author || envSessionId() || 'unknown'
+  if (store === 'local') {
+    const { thread, outcomes } = await postLocalIssue(concern, {
+      nodes: opts.nodes,
+      body: opts.body,
+      evidence: opts.evidence,
+      author,
+    })
+    return { store: 'local', id: thread.id, nodes: thread.nodes, outcomes }
+  }
+
+  const driver = forgeDriverFor(store)
+  if (!driver) throw new Error(`unknown issue store '${store}' (known: ${issueStores().map((s) => s.id).join(', ')})`)
+  const nodes = inferNodes(concern, opts.body, opts.nodes)
+  const { number, url } = await driver.createIssue({
+    title: concern,
+    body: forgeIssueBody(concern, opts.body, nodes, opts.evidence),
+  })
+  const id = `${driver.host}#${number}`
+  const outcomes = await dispatchMentions(opts.body || concern, { threadId: id, node: nodes[0] || null, author, status: 'open' })
+  return { store: driver.host, id, nodes, url, outcomes }
+}
+
 // @@@ promote - the ONE cross-store verb ([[issues]]): a local concern that outgrew the repo moves to the
 // forge as one recorded action. The forge issue is composed from the thread itself — concern → title;
 // body + the `Spec: <nodes>` marker (the round-trip: the existing tracer read links it straight back to
 // the same nodes, no new linking code) + the evidence hashes + a provenance footer — and created through
 // the driver (the only network toucher). ORDER makes failure safe: create the forge issue FIRST; only
-// then close the local thread out (a reply carrying the permalink, then resolve `landed`) — an
+// then close the local thread out (a reply carrying the permalink, then status `landed`) — an
 // unreachable forge throws with the local thread untouched, and only an `open` thread promotes.
-export async function promote(id: string): Promise<{ url: string; number: number; host: string }> {
+// `author` mirrors the other write verbs: the effective session id by default, `'human'` from the dashboard.
+export async function promote(id: string, opts: { author?: string } = {}): Promise<{ url: string; number: number; host: string }> {
+  const author = opts.author || envSessionId() || 'unknown'
   const t = loadOne(id)
   if (t.status !== 'open') throw new Error(`'${id}' is ${t.status} — only an open local issue promotes`)
-  const { githubDriver } = await import('../../spec-forge/src/drivers/github.js')
+  const driver = forgeDriverFor(DEFAULT_FORGE_HOST)
+  if (!driver) throw new Error(`unknown default forge host '${DEFAULT_FORGE_HOST}'`)
   const body = [
     t.body,
     t.nodes.length ? `\nSpec: ${t.nodes.join(', ')}` : '',
     t.evidence.length ? `\nEvidence: ${t.evidence.join(', ')} (yatsu blob hashes)` : '',
-    `\n---\nPromoted from the local issue \`${id}\` (opened by ${t.by} @ ${t.created}; promoted by ${envSessionId() || 'unknown'}).`,
+    `\n---\nPromoted from the local issue \`${id}\` (opened by ${t.by} @ ${t.created}; promoted by ${author}).`,
   ].filter(Boolean).join('\n')
-  const { number, url } = await githubDriver.createIssue({ title: t.concern, body })
-  reply(id, `promoted to the forge: ${url}`)
-  resolve(id, 'landed')
-  return { url, number, host: githubDriver.host }
+  const { number, url } = await driver.createIssue({ title: t.concern, body })
+  reply(id, `promoted to the forge: ${url}`, author)
+  closeLocalIssue(id)
+  return { url, number, host: driver.host }
 }
 
 // @@@ replyIssue - ONE reply verb, store-routed ([[issues]]): store is a property of the issue, so
@@ -171,23 +226,23 @@ export async function replyIssue(
     const { thread, outcomes, loopIn } = await replyLocalIssue(id, body, author, opts.evidence)
     return { store: 'local', replies: thread.replies, outcomes, loopIn }
   }
-  const { githubDriver } = await import('../../spec-forge/src/drivers/github.js')
-  if (forge[1] !== githubDriver.host) throw new Error(`unknown forge host '${forge[1]}' — this repo's driver is '${githubDriver.host}'`)
-  const { url } = await githubDriver.createComment({ number: parseInt(forge[2], 10), body })
+  const driver = forgeDriverFor(forge[1])
+  if (!driver) throw new Error(`unknown forge host '${forge[1]}' — known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')}`)
+  const { url } = await driver.createComment({ number: parseInt(forge[2], 10), body })
   const outcomes = await dispatchMentions(body, { threadId: id, node: opts.node ?? null, author })
   // a forge issue's author is a github login, not a live session → no reachable originator to loop in (silent).
   return { store: forge[1], url, outcomes, loopIn: null }
 }
 
 // @@@ closeIssue - ONE lifecycle close over every store ([[issues]]): the issue owns its status, so the
-// dashboard Close button routes by id and never writes node state. Local closes resolve the local thread
+// dashboard Close button routes by id and never writes node state. Local closes mark the local thread
 // `landed`; forge closes call the driver's close verb and let the forced read-back reveal the closed state.
 export async function closeIssue(id: string): Promise<{ store: string; status: string; url?: string }> {
   const forge = /^([A-Za-z0-9-]+)#(\d+)$/.exec(id)
-  if (!forge) return { store: 'local', status: resolve(id, 'landed') }
-  const { githubDriver } = await import('../../spec-forge/src/drivers/github.js')
-  if (forge[1] !== githubDriver.host) throw new Error(`unknown forge host '${forge[1]}' — this repo's driver is '${githubDriver.host}'`)
-  const { url } = await githubDriver.closeIssue({ number: parseInt(forge[2], 10) })
+  if (!forge) return { store: 'local', status: closeLocalIssue(id).status }
+  const driver = forgeDriverFor(forge[1])
+  if (!driver) throw new Error(`unknown forge host '${forge[1]}' — known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')}`)
+  const { url } = await driver.closeIssue({ number: parseInt(forge[2], 10) })
   return { store: forge[1], status: 'closed', url }
 }
 
@@ -200,31 +255,55 @@ const hasFlag = (args: string[], name: string) => args.includes(`--${name}`)
 
 // `spex issues …` — the ONE issues surface. Bare (with filters) it is THE read over every store: the
 // drain view a supervisor/human works from, `[--node id] [--store local|<host>] [--all] [--json]`. A write
-// first-positional (open|reply|sign|resolve|on|off|status|nudge — localIssues.ts) routes to the store's
-// write verbs; `promote` is the one cross-store verb. The list imposes NO salience ranking — recurrence
-// (signers, replies) is a signal the drain WEIGHS by judgment, never an automatic priority order. The forge
-// slice is a LIVE pull; an unreachable forge degrades loudly to local-only (one stderr note) — local
-// reading never hostages on a network.
+// first-positional (open|reply|on|off|status|nudge — localIssues.ts) routes to the store's
+// write verbs (open and reply are themselves store-routed: `open --store <host>` / a `<host>#<n>` id go
+// through the driver); `close` is the store-routed lifecycle verb (the SAME closeIssue the dashboard's
+// Close button calls); `promote` is the one cross-store verb. The list imposes NO salience ranking —
+// replies are a signal the drain WEIGHS by judgment, never an automatic priority
+// order. The forge slice is a LIVE pull; an unreachable forge degrades loudly to local-only (one stderr
+// note) — local reading never hostages on a network.
 export async function runIssues(args: string[]): Promise<number> {
   if (ISSUE_WRITE_SUBS.has(args[0])) return runIssueWrite(args)
+  if (args[0] === 'close') {
+    // the CLI leg of the ONE close verb ([[issues]] closeIssue — the same routing POST /api/issues/:id/close
+    // runs): a local id resolves the thread `landed`, a forge id (`<host>#<n>`) closes the remote issue
+    // through the driver. Lifecycle on the issue object, never node state.
+    const id = args[1]
+    if (!id || id.startsWith('--')) { console.error('usage: spex issues close <issue-id>   (a local id, or a forge id like github#12)'); return 2 }
+    try {
+      const r = await closeIssue(id)
+      console.log(r.store === 'local'
+        ? `closed '${id}' — local thread landed`
+        : `closed '${id}' on ${r.store}${r.url ? `  ${r.url}` : ''}`)
+      return 0
+    } catch (e) {
+      console.error(`spex issues close: ${e instanceof Error ? e.message : e}`)
+      return 1
+    }
+  }
   if (args[0] === 'promote') {
     const id = args[1]
     if (!id || id.startsWith('--')) { console.error('usage: spex issues promote <local-issue-id>'); return 2 }
     try {
       const r = await promote(id)
-      console.log(`promoted '${id}' → ${r.host}#${r.number}  ${r.url}\n  local thread resolved landed (permalink recorded in its reply trail)`)
+      console.log(`promoted '${id}' → ${r.host}#${r.number}  ${r.url}\n  local thread closed landed (permalink recorded in its reply trail)`)
       return 0
     } catch (e) {
       console.error(`spex issues promote: ${e instanceof Error ? e.message : e}`)
       return 1
     }
   }
+  if (args[0] && !args[0].startsWith('--')) {
+    console.error(`spex issues: unknown subcommand '${args[0]}'`)
+    return 2
+  }
   const nodeIds = loadSpecsLite().map((s) => s.id)
   let forge: ForgeSlice | null = null
   try {
-    const { githubDriver } = await import('../../spec-forge/src/drivers/github.js')
-    const [issues, prs] = await Promise.all([githubDriver.listIssues(), githubDriver.listPRs()])
-    forge = { host: githubDriver.host, state: { issues, prs } }
+    const driver = forgeDriverFor(DEFAULT_FORGE_HOST)
+    if (!driver) throw new Error(`unknown default forge host '${DEFAULT_FORGE_HOST}'`)
+    const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
+    forge = { host: driver.host, state: { issues, prs } }
   } catch (e) {
     console.error(`spex issues: forge unreachable — listing local only (${e instanceof Error ? e.message.split('\n')[0] : e})`)
   }
@@ -241,7 +320,6 @@ export async function runIssues(args: string[]): Promise<number> {
     const tags = [p.store, p.status !== 'open' ? `[${p.status}]` : '', p.nodes.length ? `re: ${p.nodes.join(', ')}` : '', p.by ? `by ${p.by}` : ''].filter(Boolean).join('  ·  ')
     console.log(`• ${p.concern}  [${p.id}]`)
     console.log(`    ${tags}`)
-    if (p.signers.length) console.log(`    +${p.signers.length} signed: ${p.signers.join(', ')}`)
     if (p.replies.length) console.log(`    ${p.replies.length} reply(ies) in thread`)
     if (p.url) console.log(`    ${p.url}`)
   }

package/spec-cli/src/layout.ts

@@ -27,14 +27,14 @@ type Config = {
   }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)
-    claudeCmd?: string             // the UNNAMED default worker launcher for Claude (default 'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides. A host-specific ABS path belongs in the gitignored spexcode.local.json, not here.
-    codexCmd?: string              // the UNNAMED default worker launcher for Codex (default 'codex --yolo'); env SPEXCODE_CODEX_CMD overrides. Same host-path rule.
+    claudeCmd?: string             // the built-in `claude` launcher command (default 'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides. A host-specific ABS path belongs in the gitignored spexcode.local.json, not here.
+    codexCmd?: string              // the built-in `codex` launcher command (default 'codex --yolo'); env SPEXCODE_CODEX_CMD overrides. Same host-path rule.
     // named launcher profiles: a session picks ONE by name at create time ([[launcher-select]]), fixing both
     // its harness AND its exact launch command; the chosen NAME is persisted on the record so resume reuses the
     // same auth. `harness` defaults to 'claude'. Host-specific `cmd`s (abs wrapper paths) belong in the
     // gitignored spexcode.local.json — the name is portable, the cmd is a machine fact.
     launchers?: { [name: string]: { harness?: 'claude' | 'codex'; cmd: string } }
-    defaultLauncher?: string       // the launcher a create with no explicit --launcher/dropdown pick uses (else the unnamed claudeCmd/codexCmd path)
+    defaultLauncher?: string       // the launcher a create with no explicit --launcher/dropdown pick uses; required for no-choice creates
   }
   serve?: {
     // public-exposure config for `spex serve --public` (resolved gateway-side; see [[public-mode]] / gateway.ts).
@@ -161,7 +161,7 @@ export type RawRecord = {
   node: string | null; title: string | null; name: string | null; parent?: string | null
   status: string; proposal: string | null; merges: number; note: string | null
   sortkey: number | null; createdAt: number; harness?: string; harness_session_id?: string
-  launcher?: string   // the named launcher profile this session was created under ([[launcher-select]]); absent/empty → the unnamed global default
+  launcher?: string   // the launcher profile this session was created under ([[launcher-select]]); absent/empty only on old records predating launchers
   launch_cmd?: string // the RESOLVED base launcher command PINNED at creation, so a resume replays the EXACT launcher (and its config-dir env) that made the conversation, never a since-changed default ([[launcher-select]] resume-launcher-pin); absent → old record, fall back to the launcher name / ambient
 }
 // the agent's OWN session id from the environment — the only locator now that the record left the worktree.

package/spec-cli/src/localIssues.ts

@@ -2,7 +2,7 @@
 // [[mentions]]). A thread IS an Issue whose `store` is 'local' — membership implied by WHERE the file lives,
 // 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 sign/reply/discuss like an async chatroom; a supervisor drains it via
+// 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).
 // 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
@@ -87,10 +87,9 @@ const currentSession = (): string => envSessionId() || 'unknown'
 const sleep = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
 
 // ── file format ──────────────────────────────────────────────────────────────────────────────────────
-// frontmatter (concern/by/status/nodes/evidence/signers/created) + a prose body, then any replies — each
+// frontmatter (concern/by/status/nodes/evidence/created) + a prose body, then any replies — each
 // preceded by a `<!-- reply: <by> @ <iso> -->` sentinel: invisible in rendered markdown, unambiguous to
-// parse. Only the store writes these files, so a fixed shape is safe. Lists are `key: a, b` scalars so a
-// +1 sign is a one-line change.
+// parse. Only the store writes these files, so a fixed shape is safe.
 //
 // A REMARK ([[remark-substrate]]) is a reply carrying extra state, appended to the SAME sentinel as a
 // ` :: <space-joined k=v attrs>` tail (a plain reply has no tail → parses unchanged, backward compatible):
@@ -120,9 +119,8 @@ function parse(id: string, text: string): Issue {
     store: 'local',
     concern: fm.concern || id,
     by: fm.by || 'unknown',
-    status: fm.status || 'open',
+    status: fm.status === 'landed' ? 'landed' : 'open',
     nodes: list(fm.nodes),
-    signers: list(fm.signers),
     created: fm.created || '',
     body: body.join('\n').trim(),
     replies: replies.map((r) => ({ ...r, body: r.body.trim() })),
@@ -165,7 +163,6 @@ function serialize(p: Issue): string {
     `status: ${safeScalar(p.status)}`,
     p.nodes.length ? `nodes: ${p.nodes.join(', ')}` : '',
     p.evidence.length ? `evidence: ${p.evidence.join(', ')}` : '',
-    p.signers.length ? `signers: ${p.signers.join(', ')}` : '',
     `created: ${p.created}`,
   ].filter(Boolean)
   let out = `---\n${fm.join('\n')}\n---\n\n${safeBody(p.body)}\n`
@@ -259,7 +256,7 @@ function ensureStoreMigrated(): void {
 // structurally invisible to spec-lint, and the commit is provably store-only (one .spec/.issues/ path), so the
 // pre-commit gate would only pass anyway — running it just burns seconds (tsx cold-start) holding the lock.
 // A NO-CHANGE write is idempotent SUCCESS, never a failure: when the serialized bytes already equal the
-// stored state (a duplicate resolve/sign — the store IS the requested state), `git commit` would exit 1
+// stored state (a duplicate close — the store IS the requested state), `git commit` would exit 1
 // 'nothing to commit', so we detect the no-op after `add` (the staged path equals HEAD → status is silent)
 // and skip the commit. Returns whether the store actually changed, so a caller can say 'already <state>'.
 // MUST run while holding withStoreLock — it is the write half of a locked read-modify-write; its callers
@@ -286,7 +283,7 @@ function writeStoreFile(p: Issue, message: string): boolean {
 }
 
 // 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/sign/resolve reads the
+// 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).
 // `changed: false` = the store already held exactly this state (see writeStoreFile) — success, nothing committed.
 function commitStore(message: string, prepare: () => Issue): { issue: Issue; changed: boolean } {
@@ -312,7 +309,6 @@ export function openIssue(concern: string, opts: { nodes?: string[]; body?: stri
     by: opts.author || currentSession(),
     status: 'open',
     nodes,
-    signers: [],
     created: new Date().toISOString(),
     body: (opts.body || `(no detail given — ${concern})`).trim(),
     replies: [],
@@ -395,25 +391,13 @@ export async function postLocalIssue(
   return { thread, outcomes }
 }
 
-export function sign(id: string): string[] {
-  const by = currentSession()
-  return commitStore(`issue(${id}): signed by ${by}`, () => {
+export function closeLocalIssue(id: string): { status: 'landed'; already: boolean } {
+  const { changed } = commitStore(`issue(${id}): close`, () => {
     const p = loadOne(id)
-    if (!p.signers.includes(by)) p.signers.push(by)
-    return p
-  }).issue.signers
-}
-
-const RESOLUTIONS = new Set(['accepted', 'rejected', 'landed'])
-// `already` = the thread was in that state before this call — an idempotent success, nothing committed.
-export function resolve(id: string, as: string): { as: string; already: boolean } {
-  if (!RESOLUTIONS.has(as)) throw new Error(`resolution must be one of: ${[...RESOLUTIONS].join(' | ')}`)
-  const { changed } = commitStore(`issue(${id}): resolve ${as}`, () => {
-    const p = loadOne(id)
-    p.status = as
+    p.status = 'landed'
     return p
   })
-  return { as, already: !changed }
+  return { status: 'landed', already: !changed }
 }
 
 // ── remarks ([[remark-substrate]]) ──────────────────────────────────────────────────────────────────
@@ -439,7 +423,7 @@ function findOrCreateEvalThread(node: string, scenario: string, author: string):
     if (existing) return existing
     const p: Issue = {
       id: uniqueId(concern), store: 'local', concern, by: author, status: 'open',
-      nodes: [node], signers: [], created: new Date().toISOString(),
+      nodes: [node], created: new Date().toISOString(),
       body: `Remarks on the \`${scenario}\` eval of [[${node}]].`, replies: [], evidence: [],
     }
     writeStoreFile(p, `issue: ${concern}`)
@@ -479,16 +463,18 @@ function parseRemarkRef(ref: string): { id: string; rid: string } {
   return { id: ref.slice(0, i), rid: ref.slice(i + 1) }
 }
 
-// resolve a remark (R3): a DELIBERATE call, agent-only (the dashboard's `human` is rejected — a human
-// RETRACTS their own, resolve is a second party's judgment), NEVER the author (no self-resolve), and
-// MONOTONIC (no un-resolve — a regression is a NEW remark). `by` is the resolving party.
+// resolve a remark (R3): a DELIBERATE call by a SECOND PARTY — never the author (no self-resolve: an
+// identity comparison, so the dashboard's `human` cannot resolve a human-authored remark either), and
+// MONOTONIC (no un-resolve — a regression is a NEW remark). The resolver's identity is derived by the
+// SURFACE ([[remark-substrate]] LAW L): a governed session id from the CLI, the `human` sentinel from the
+// dashboard — both are real second parties, so the same rule runs on both. `by` is the resolving party.
 export function resolveRemark(ref: string, by: string): { thread: Issue; rid: string } {
   const { id, rid } = parseRemarkRef(ref)
   const { issue: thread } = commitStore(`remark(${id}#${rid}): resolved by ${by}`, () => {
     const p = loadOne(id)
     const r = p.replies.find((x) => x.rid === rid)
     if (!r) throw new Error(`no remark '${ref}' in that thread`)
-    if (!by || by === 'human' || by === 'unknown') throw new Error(`resolve is agent-only (needs a real session identity, got '${by || 'none'}'): a human withdraws their own remark with \`spex retract\`, not resolve`)
+    if (!by || by === 'unknown') throw new Error(`resolve needs a real identity (got '${by || 'none'}'): run it under a governed session, or from the dashboard (its actor is 'human')`)
     if (r.resolved) throw new Error(`remark '${ref}' is already resolved — monotonic: a regression is a NEW remark, never an un-resolve`)
     if (r.by === by) throw new Error(`refusing to self-resolve '${ref}': the author (${by}) may not resolve their own remark — resolve is a second party's deliberate judgment`)
     r.resolved = true; r.resolvedBy = by; r.resolvedAt = new Date().toISOString()
@@ -525,28 +511,45 @@ export function nudge(node: string): string {
     '── issues ─────────────────────────────────────────────────────────',
     `Your work (${node || 'this node'}) just landed. Two issue checks before you close:`,
     '',
-    '1. CLOSE what you finished. An issue whose work just landed is resolved, not',
+    '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 resolve <id> --as landed',
+    '   lie:  spex issues --store local     then   spex issues 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 — sign/reply if already raised',
+    '     spex issues                              # read first — reply if already raised',
     '     spex issues open "<concern>" [--node <id>]   # else open one',
     'A supervisor drains the store later. (Advisory — skip if nothing is owed.)',
     '───────────────────────────────────────────────────────────────────',
   ].join('\n')
 }
 
+// @@@ close-time issue closeout ([[local-issues]] / [[state]]) — the DATA half of the propose-close nudge:
+// appended to the `done --propose close` declaration BESIDE the resource-cleanup reminder (cli.ts, same
+// insertion point, same semantics — a nudge, never a gate). Data-driven so it earns its line: it lists the
+// still-open local threads THIS session touched (authored or replied; eval `eval: <node> · <scenario>`
+// containers excluded — they host remarks and outlive every session by design) and prints NOTHING when the
+// session owes nothing, when the feature is OFF, or when there is no session identity. Some issues rightly
+// outlive their session (a taste concern waiting for the drain), so the ask is close OR say why it stays
+// open — never a forced close.
+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.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.`
+}
+
 // ───────────────────────── 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', '--as', '--evidence', '--scenario', '--code-sha'])
+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[] = []
@@ -568,9 +571,10 @@ 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>" [--node id…] [--evidence hash…]
-// [--body -|text], the id-based reply | sign | resolve, and the feature toggle on | off | status. `nudge`
-// is internal (the post-merge hook's caller). Store is a property of the issue, never a second command.
+// 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,
+// 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 {
@@ -594,35 +598,32 @@ export async function runIssueWrite(args: string[]): Promise<number> {
       if (s) console.log(`  ${s}`)
       return 0
     }
-    if (sub === 'sign') {
-      const id = bare(args.slice(1))[0]
-      if (!id) { console.error('usage: spex issues sign <issue-id>'); return 2 }
-      console.log(`signed '${id}' — signers: ${sign(id).join(', ')}`)
-      return 0
-    }
-    if (sub === 'resolve') {
-      const id = bare(args.slice(1))[0]
-      const as = fl(args, 'as')
-      if (!id || !as) { console.error('usage: spex issues resolve <issue-id> --as accepted|rejected|landed'); return 2 }
-      const r = resolve(id, as)
-      console.log(r.already ? `'${id}' already ${r.as} — store unchanged` : `resolved '${id}' → ${r.as}`)
-      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 local issue. The concern is the bare positional(s) after the sub.
+    // `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>" [--node <id>…] [--evidence <hash>…] [--body -|<text>]\n       spex issues reply|sign|resolve <issue-id> …  |  on|off|status')
+      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')
       return 2
     }
-    const p = openIssue(concern, { nodes: repeated(args, 'node'), body: readBody(args), evidence: repeated(args, 'evidence') })
-    console.log(`opened '${p.id}'${p.nodes.length ? ` (re: ${p.nodes.join(', ')})` : ''} — committed to the local issue store; read it with \`spex issues\``)
-    const s = summarize(await dispatchMentions(p.body || concern, { threadId: p.id, node: p.nodes[0] || null, author: p.by, status: p.status }))
+    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 issues\``
+      : `opened '${r.id}' on ${r.store}${re} — ${r.url}`)
+    const s = summarize(r.outcomes)
     if (s) console.log(`  ${s}`)
     return 0
   } catch (e) {
@@ -633,7 +634,7 @@ export async function runIssueWrite(args: string[]): Promise<number> {
 
 // 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', 'sign', 'resolve', 'on', 'off', 'status', 'nudge'])
+export const ISSUE_WRITE_SUBS = new Set(['open', 'reply', 'on', 'off', 'status', 'nudge'])
 
 // ── 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>…]`

package/spec-cli/src/materialize.ts

@@ -9,7 +9,6 @@ import { git } from './git.js'
 import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
 import { resolveHarnessTargets, partitionHarnesses } from './harness-select.js'
 import { emitPlugin, cleanPlugin, pluginBundleDir, pluginVersion } from './plugin-harness.js'
-import { tsxBin } from './tsx-bin.js'
 
 // @@@ materialize - the "pay-per-change" node step (≈0.85s) the cheap shell gate invokes ONLY when the
 // .config content-hash moved. It renders the spec tree's surface nodes into the flat artifacts each
@@ -26,7 +25,10 @@ import { tsxBin } from './tsx-bin.js'
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
-const SPEX = `${tsxBin(PKG)} ${join(PKG, 'src', 'cli.ts')}`
+// the ONE spex entry: the launcher (bin/spex.mjs), never a raw `tsx cli.ts` pair — the launcher owns tsx
+// resolution AND the mid-merge guard (a conflicted source tree degrades to one line + exit 75, not an
+// esbuild stacktrace), so every hook-baked callback inherits both.
+const SPEX = join(PKG, 'bin', 'spex.mjs')
 // the manifest + content-hash marker render into the GLOBAL per-project store (layout.runtimeRoot), NOT the
 // worktree — the worktree keeps zero SpexCode-rendered 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

@@ -13,6 +13,18 @@ const NODE_RE = /\[\[([^\]\s]+)\]\]/g
 
 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,
+// 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 {
+  const wrapped = /^\[\[(.*)\]\]$/.exec(token)
+  if (wrapped) return wrapped[1]
+  return token.startsWith('@') ? token.slice(1) : token
+}
+
 export function parseMentions(text: string): { actors: string[]; nodes: string[] } {
   const actors: string[] = []
   const nodes: string[] = []
@@ -47,6 +59,15 @@ export function resolveActors(tokens: string[], sessions: ActorSession[]): Resol
   })
 }
 
+// Any spawn's parent = its originator ([[session-nesting]]): the `@new` worker nests under the session that
+// wrote the mention — but ONLY when the author IS a real board session id. A dashboard 'human', a CLI
+// 'unknown', or a forge login resolves to no session → null → a top-level worker, never a phantom nest.
+// Exact id match only (lineage is provenance, not addressing — no prefix/name resolution), any liveness:
+// a parent that later closes is auto-promoted at read time by the derived tree.
+export function spawnParent(author: string, sessions: { id: string }[]): string | null {
+  return sessions.some((s) => s.id === author) ? author : null
+}
+
 // ── dispatch (integration) ─────────────────────────────────────────────────────────────────────────────
 export type DispatchOutcome = { token: string; result: 'sent' | 'spawned' | 'offline' | 'unresolved' | 'failed'; detail?: string; note?: string }
 
@@ -92,7 +113,7 @@ export async function dispatchMentions(
       // deliberate audit/re-measure), but the worker prompt carries the status and the outcome line warns.
       const settled = ctx.status && ctx.status !== 'open' ? ctx.status : undefined
       try {
-        const s = await newSession(ctx.node, newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status))
+        const s = await newSession(ctx.node, newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status), spawnParent(ctx.author, sessions))
         out.push({ token: r.token, result: 'spawned', detail: s.id, ...(settled ? { note: `thread ${settled}` } : {}) })
       } catch (e) { out.push({ token: r.token, result: 'failed', detail: e instanceof Error ? e.message : String(e) }) }
       continue