spexcode 0.1.5 → 0.2.0

package/spec-cli/src/materialize.ts

@@ -1,22 +1,28 @@
-import { writeFileSync, mkdirSync } from 'node:fs'
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'node:fs'
 import { join, dirname, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
-import { loadSystemConfig, loadSkillConfig } from './specs.js'
+import { loadSystemConfig, loadSkillConfig, loadAgentConfig, loadConfig } from './specs.js'
 import { compileManifest } from './hooks.js'
-import { HARNESSES, writeManagedBlock } from './harness.js'
-import { runtimeRoot } from './layout.js'
+import { writeManagedBlock, removeManagedBlock, type HarnessArtifacts } from './harness.js'
+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
 // 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 as a managed <spexcode> block in each harness's contract file(s) — user content
-// preserved, (3) the thin SHIMS (every event → dispatch.sh), (4) the per-harness TRUST (Codex's deterministic
-// trusted_hash; Claude none) so the self-launch is zero-prompt. EVERY harness-specific fact is owned by the
-// [[harness-adapter]] (harness.ts) — this file just loops over HARNESSES, so adding a harness adds an adapter,
-// not a branch here. All writes are idempotent + scoped. The content-hash marker is stamped last.
+// (2) the CONTRACT — the tracked docs guide (docs/AGENT_GUIDE.md) FOLLOWED BY the surface:system bodies —
+// written WHOLE into each harness's contract file(s), which are GENERATED, gitignored artifacts (like the
+// shims + skills): regenerated per clone/launch, never committed, so a self-launched agent still discovers
+// guide + contract while the repo tracks only the guide source, (3) the thin SHIMS (every event → dispatch.sh),
+// (4) the per-harness TRUST (Codex's deterministic trusted_hash; Claude none) so the self-launch is zero-prompt.
+// EVERY harness-specific fact is owned by the [[harness-adapter]] (harness.ts) — this file just loops over
+// HARNESSES, so adding a harness adds an adapter, not a branch here. All writes are idempotent + scoped. The
+// content-hash marker is stamped last.
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
@@ -35,54 +41,203 @@ export function contentHash(proj: string): string {
   } catch { return '' }
 }
 
+// @@@ private overlay ([[private-overlay]]) - the DEFAULT render commits .spec + spexcode.json and ignores its
+// generated wiring through a managed block in the TRACKED <repo>/.gitignore; that only truly hides a file that
+// is wholly ours, so on a host that ALREADY tracks CLAUDE.md/AGENTS.md/.gitignore the folded-in block still
+// lands in a tracked file and leaks. Private mode (spexcode.local.json `private:true`) closes that: it moves the
+// ignore block to the per-clone `.git/info/exclude` (never committed), widens it to hide .spec + spexcode.json
+// too, and `skip-worktree`s any TRACKED contract file so the block sits in the working copy (the harness still
+// discovers it) yet never stages. Every step has an inverse the DEFAULT mode re-asserts, so the toggle is
+// reversible and idempotent. It hides UNTRACKED paths; a pre-existing tracked .spec must be `git rm --cached`d
+// once (the render can't untrack for you — reported, not silently ignored).
+function gitCommonDirOf(proj: string): string {
+  return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
+}
+function infoExcludePath(proj: string): string {
+  return join(gitCommonDirOf(proj), 'info', 'exclude')
+}
+function isTracked(proj: string, file: string): boolean {
+  try { git(['-C', proj, 'ls-files', '--error-unmatch', file]); return true } catch { return false }
+}
+// mark/unmark a TRACKED file skip-worktree (a no-op on an untracked path — info/exclude hides those instead).
+// Best-effort: an index race or a non-repo must not fail the render.
+function setSkipWorktree(proj: string, file: string, on: boolean): void {
+  if (!isTracked(proj, file)) return
+  try { git(['-C', proj, 'update-index', on ? '--skip-worktree' : '--no-skip-worktree', file]) } catch { /* best-effort */ }
+}
+
 // the whole pay-per-change render. proj defaults to cwd. Returns the new content-hash it stamped.
 export function materialize(proj = process.cwd()): string {
   const rt = runtimeRoot(proj)                                            // global per-project store, not the worktree
   mkdirSync(rt, { recursive: true })
   // (1) hook manifest (persistent — the dispatcher reads it; regenerated only here, on change).
   writeFileSync(join(rt, 'hooks-manifest'), compileManifest())
-  // (2) the contract = the surface:system bodies, in name order, written into EACH harness's contract file(s)
-  //     + (3) each harness's thin shim → dispatch.sh + (4) its trust. All owned by the adapter.
-  const contract = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean).join('\n\n')
+  // (2) the contract = the tracked docs guide (the hand-written agent/contributor notes — the ONE piece of
+  //     in-tree prose) FOLLOWED BY the surface:system bodies (in name order), written WHOLE into EACH harness's
+  //     contract file(s) + (3) each harness's thin shim → dispatch.sh + (4) its trust. All owned by the adapter.
+  //     The contract files are generated artifacts (gitignored below), so the guide is the single source a
+  //     self-launched agent reads from — assembling it in keeps guide + contract reaching the agent together.
+  const guidePath = join(proj, 'docs', 'AGENT_GUIDE.md')
+  const guide = existsSync(guidePath) ? readFileSync(guidePath, 'utf8').trim() : ''
+  const systemBodies = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean)
+  const contract = [guide, ...systemBodies].filter(Boolean).join('\n\n')
+  // WHICH harnesses to deliver into ([[harness-select]]): the spexcode.json `harnesses` set (default = every
+  // native harness). resolveHarnessTargets FAILS LOUD on an illegal set (plugin+native, plugin w/o folder).
+  // selected harnesses are write()n below; unselected ones are clean()ed (pruned) after — so dropping a harness
+  // from the config removes its products on the next re-materialize. The plugin EMITTER is a later node.
+  const cfg = readConfig(mainCheckout(proj))
+  const targets = resolveHarnessTargets(cfg.harnesses)
+  const priv = !!cfg.private                                              // [[private-overlay]] — hide in .git/info/exclude + skip-worktree, not the tracked .gitignore
+  const { selected, unselected, plugins } = partitionHarnesses(targets)
+  const skillNodes = loadSkillConfig()
+  const agentNodes = loadAgentConfig()
+  const commandNodes = loadConfig()
   // a skill node → the agentskills.io SKILL.md primitive: `name`+`description` frontmatter (the load-trigger)
   // over the body instructions. One pure render shared by every harness — divergence is only its skillDir.
   const renderSkill = (sk: { name: string; desc: string; body: string }) =>
     `---\nname: ${sk.name}\ndescription: ${JSON.stringify(sk.desc)}\n---\n\n${sk.body}\n`
+  // an agent node → a coding-agent sub-agent definition (the same primitive .claude/agents/*.md ships): the
+  // node's `desc` is the on-demand load-trigger, its `tools` the harness tool allowlist, its body the agent's
+  // system prompt. One pure render shared by every harness — divergence is only its agentDir.
+  const renderAgent = (ag: { name: string; desc: string; tools: string[]; body: string }) =>
+    `---\nname: ${ag.name}\ndescription: ${ag.desc}\ntools: ${ag.tools.join(', ')}\n---\n\n${ag.body}\n`
+  // a command node → a host `/`-menu command file: the node's `desc` as the dropdown description over its body
+  // (the preset prompt). Only the PLUGIN bundle ships these as files; the native path serves command presets via
+  // the dashboard /api/slash-commands instead, so this render is plugin-only.
+  const renderCommand = (cm: { desc: string; body: string }) =>
+    (cm.desc ? `---\ndescription: ${JSON.stringify(cm.desc)}\n---\n\n` : '') + `${cm.body}\n`
+  // shim ABSOLUTE paths; relativized into the managed .gitignore block below (checkout-invariant — see there).
   const shimPaths: string[] = []
-  for (const h of HARNESSES) {
-    if (contract) for (const f of h.contractFiles(proj)) writeManagedBlock(f, contract)
+  for (const h of selected) {
+    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); shimPaths.push(f); setSkipWorktree(proj, f, priv) }
     const shimFile = h.shimFile(proj)
     mkdirSync(dirname(shimFile), { recursive: true })
     const shim = h.shim(DISPATCH, SPEX)
     writeFileSync(shimFile, shim.json)
     h.writeTrust(proj, shim.cmd)
-    shimPaths.push(relative(proj, shimFile))
+    shimPaths.push(shimFile)
+    // a linked-worktree ANCHOR copy of the shim, when the harness needs one (codex: the shim lives at the main
+    // checkout, so the worktree gets no `.codex/` unless we place one — and codex only discovers a worktree
+    // thread's hooks if a `.codex/` under the worktree root anchors the project layer). One adapter line; null
+    // for a harness whose shim already sits in the worktree (claude) or on the main checkout itself.
+    const anchor = h.worktreeHookAnchor(proj)
+    if (anchor) { mkdirSync(dirname(anchor), { recursive: true }); writeFileSync(anchor, shim.json); shimPaths.push(anchor) }
   }
   // (6) skills - each `surface: skill` node → a SKILL.md the harness auto-discovers, written into every
   //     harness's own skillDir (Claude .claude/skills, Codex .codex/skills). Generated wiring, so the paths
   //     join the same managed .gitignore block below. A harness with no skill primitive (skillDir null) is skipped.
-  for (const sk of loadSkillConfig()) {
-    for (const h of HARNESSES) {
+  for (const sk of skillNodes) {
+    for (const h of selected) {
       const dir = h.skillDir(proj); if (!dir) continue
       const f = join(dir, sk.name, 'SKILL.md')
       mkdirSync(dirname(f), { recursive: true })
       writeFileSync(f, renderSkill(sk))
-      shimPaths.push(relative(proj, f))   // reuse the same managed .gitignore block
+      shimPaths.push(f)   // reuse the same managed .gitignore block (absolute; relativized below)
+    }
+  }
+  // (7) sub-agents - each `surface: agent` node → a <name>.md the harness auto-discovers, written into every
+  //     harness's own agentDir (Claude .claude/agents). The SAME pattern as skills: generated wiring, so the
+  //     paths join the same managed .gitignore block below. A harness with no agent primitive (agentDir null,
+  //     e.g. Codex) is skipped — no `if (codex)`, the divergence is the adapter's agentDir line.
+  for (const ag of agentNodes) {
+    for (const h of selected) {
+      const dir = h.agentDir(proj); if (!dir) continue
+      const f = join(dir, `${ag.name}.md`)
+      mkdirSync(dirname(f), { recursive: true })
+      writeFileSync(f, renderAgent(ag))
+      shimPaths.push(f)   // reuse the same managed .gitignore block (absolute; relativized below)
+    }
+  }
+  // (8) PRUNE every UNSELECTED harness — clean() is the surgical inverse of the write above, removing ONLY this
+  //     harness's own managed block + generated shim + trust + named skill/agent files. So narrowing the
+  //     spexcode.json `harnesses` set (or switching to a plugin, which excludes all natives) removes the
+  //     dropped harness's products here, the user's own prose/data untouched. The names tell clean exactly
+  //     which on-demand artifacts were its to remove ([[harness-select]] / [[harness-adapter]]).
+  const arts: HarnessArtifacts = { skills: skillNodes.map((s) => s.name), agents: agentNodes.map((a) => a.name) }
+  for (const h of unselected) h.clean(proj, arts)
+  // (8b) the PLUGIN target ([[plugin-harness]]): render the whole system into one self-contained Claude-plugin
+  //      bundle per selected folder. A plugin is EXCLUSIVE (so `selected` is already empty — every native was
+  //      pruned above). Pruning a DESELECTED plugin folder (plugin→native, or folder A→B) needs the PREVIOUS
+  //      folder set, which the live config no longer names — so a tiny ledger in the global store records the
+  //      folders emitted last run; any prev folder absent from the current set is clean()ed (the bundle's
+  //      inverse), then the current folders are emitted and the ledger rewritten. Bounded + surgical: cleanPlugin
+  //      is identity-gated on the bundle's own plugin.json.
+  const ledger = join(rt, 'plugin-folders')
+  const prevFolders = existsSync(ledger) ? readFileSync(ledger, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean) : []
+  const curFolders = plugins.map((p) => p.folder)
+  for (const f of prevFolders) if (!curFolders.includes(f)) cleanPlugin(proj, f)
+  if (plugins.length) {
+    const render = {
+      contract,
+      skills: skillNodes.map((s) => ({ name: s.name, content: renderSkill(s) })),
+      agents: agentNodes.map((a) => ({ name: a.name, content: renderAgent(a) })),
+      commands: commandNodes.map((c) => ({ name: c.name, content: renderCommand(c) })),
+      spex: SPEX,
+      version: pluginVersion(),
     }
+    for (const p of plugins) emitPlugin(proj, p.folder, render)
+  }
+  writeFileSync(ledger, curFolders.join('\n'))
+  // (4b) every artifact this render writes IN-TREE is generated wiring, so gitignore it — regenerated per
+  // clone/launch by this same gate, never committed. That now includes the CONTRACT files (CLAUDE.md/AGENTS.md):
+  // their whole content is the generated guide+system block, so they are artifacts exactly like the shims +
+  // skills + sub-agents — the only tracked prose is the guide SOURCE (docs/AGENT_GUIDE.md), which this render
+  // reads. Derived from the adapters' own contractFiles()/shimFile()/skillDir/agentDir, not hardcoded; written
+  // as a managed `#` block so the user's own .gitignore is preserved.
+  // The managed block must be CHECKOUT-INVARIANT: `.gitignore` is ONE tracked, committed file shared by the
+  // main checkout and every worktree, so if the block differed by where materialize ran, whichever flavor got
+  // committed would leave the OTHER checkout dirtying it on every render. The only artifact that varies is the
+  // codex hooks shim, which materializes at the MAIN checkout (a linked worktree's codex reads the root's
+  // hooks — see harness.ts): from main it is `.codex/hooks.json` (inside proj), from a worktree it is `../…`
+  // (escapes proj). So an ignore entry is anchored to the checkout it LIVES under — proj-relative when inside
+  // proj, else MAIN-checkout-relative — which resolves the codex shim to `.codex/hooks.json` from any checkout
+  // (a pattern naming a main-only path is a harmless no-op in a worktree). Every checkout now emits the same
+  // set → the committed `.gitignore` is stable, never re-dirtied. A path under neither root is not ignorable
+  // here (dropped).
+  const mc = mainCheckout(proj)
+  const anchor = (abs: string): string | null => {
+    const p = relative(proj, abs); if (!p.startsWith('..')) return p
+    const m = relative(mc, abs); if (!m.startsWith('..')) return m
+    return null
   }
-  // (4b) the shims are machine-specific generated wiring (they bake this machine's absolute install path), so
-  // gitignore them — regenerated per-machine by this same gate. Derived from the adapters' shimFile(), not
-  // hardcoded; written as a managed `#` block so the user's own .gitignore is preserved. Keeps the worktree
-  // free of tracked machine-specific files (the contract md files stay tracked — they carry the user's prose).
-  // only ignore paths that live INSIDE proj. The codex hooks shim now materializes at the MAIN checkout (codex
-  // reads a linked worktree's hooks from the root checkout — see harness.ts); from a linked worktree that path
-  // escapes proj (`../…`) and is gitignored by the main checkout's OWN materialize, not the worktree's.
   // spexcode.local.json — the machine-local config overlay (host-specific values, e.g. an absolute worker
   // launcher path; see portable-layout) — joins the SAME block on the same rationale: machine-specific, must
   // never be committed. Without it an adopter who follows our own guidance to put a host path there would
   // `git add -A` and leak it — the exact thing the overlay exists to prevent.
-  const ignorable = [...shimPaths.filter((p) => !p.startsWith('..')), 'spexcode.local.json']
-  if (ignorable.length) writeManagedBlock(join(proj, '.gitignore'), ignorable.sort().join('\n'), ['# ', ''])
+  // each emitted plugin bundle is a generated, machine-local artifact too (its hooks.json bakes THIS install's
+  // SPEX path), so its dir joins the same managed block — regenerated per clone/launch, never committed.
+  const bundlePaths = curFolders.map((f) => pluginBundleDir(proj, f))
+  // SpexCode's own SESSION artifacts also join the managed block: a launch creates a worktree under
+  // `.worktrees/` (hardcoded in sessions.ts) plus a per-worktree `.session` state file the layout linker
+  // reads. Neither is the adopter's code, both are per-clone/never-committed — but until now materialize
+  // never ignored them, so an ADOPTED project leaked its session worktrees into `git status` (a `git add -A`
+  // would commit them). Static strings, so they stay checkout-invariant. The dogfood hand-lists these; every
+  // other repo gets them here, in the default `.gitignore` block AND (widened) the private `.git/info/exclude`.
+  const sessionIgnores = ['.worktrees/', '.session']
+  const ignorable = [...[...shimPaths, ...bundlePaths].map(anchor).filter((p): p is string => p !== null), 'spexcode.local.json', ...sessionIgnores]
+  const gitignore = join(proj, '.gitignore')
+  if (priv) {
+    // PRIVATE ([[private-overlay]]): hide EVERYTHING — including the .spec tree + spexcode.json the DEFAULT
+    // mode commits ("git is the database") — in the per-clone `.git/info/exclude` (never committed, never
+    // shared), and strip any managed block a prior DEFAULT render left in the tracked .gitignore so switching
+    // INTO private mode leaves the host's shared history clean.
+    const entries = [...new Set([...ignorable, '.spec/', 'spexcode.json'])].sort().join('\n')
+    writeManagedBlock(infoExcludePath(proj), entries, ['# ', ''])
+    removeManagedBlock(gitignore, ['# ', ''], true)
+    // the ONE manual step private mode can't do for you: .git/info/exclude hides UNTRACKED paths only, so a
+    // .spec/spexcode.json ALREADY committed (a repo that adopted DEFAULT mode first) stays visible until
+    // un-tracked. Surface it loudly rather than leaving a silent leak — the agent doing setup acts on this.
+    const stillTracked = ['.spec', 'spexcode.json'].filter((p) => isTracked(proj, p))
+    if (stillTracked.length) console.error(
+      `spexcode private: ${stillTracked.join(' + ')} still git-tracked — private mode hides UNTRACKED paths only.\n` +
+      `  → run once:  git rm -r --cached ${stillTracked.join(' ')}   (keeps the files on disk, stops tracking them; then commit on your branch)`,
+    )
+  } else {
+    // DEFAULT: the checkout-invariant managed block in the TRACKED .gitignore (rationale above); strip any
+    // private exclude block so switching OUT of private mode is equally clean.
+    if (ignorable.length) writeManagedBlock(gitignore, [...new Set(ignorable)].sort().join('\n'), ['# ', ''])
+    removeManagedBlock(infoExcludePath(proj), ['# ', ''], false)
+  }
   // (5) stamp the content-hash marker LAST (so a crash mid-render leaves it stale → re-renders next gate).
   const h = contentHash(proj)
   writeFileSync(join(rt, 'content-hash'), h)

package/spec-cli/src/mentions.ts

@@ -0,0 +1,192 @@
+// @@@ mentions - the two universal in-text reference primitives ([[mentions]]): `[[node]]` (a TOPIC — a spec
+// 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
+// separate, and sessions.ts is imported LAZILY so a mention-free post pays nothing.
+
+// ── parse (pure) ──────────────────────────────────────────────────────────────────────────────────────
+// `@<token>` at a word boundary is an actor; `[[<id>]]` is a topic. Tokens are [A-Za-z0-9_-]; a session id,
+// a short label/prefix, or the literal `new`. Both forms are deduped in first-seen order.
+const ACTOR_RE = /(?:^|\s)@([A-Za-z0-9_-]+)/g
+const NODE_RE = /\[\[([^\]\s]+)\]\]/g
+
+const uniq = (xs: string[]): string[] => [...new Set(xs)]
+
+export function parseMentions(text: string): { actors: string[]; nodes: string[] } {
+  const actors: string[] = []
+  const nodes: string[] = []
+  for (const m of text.matchAll(ACTOR_RE)) actors.push(m[1])
+  for (const m of text.matchAll(NODE_RE)) nodes.push(m[1])
+  return { actors: uniq(actors), nodes: uniq(nodes) }
+}
+
+// ── resolve actors against live sessions (pure) ───────────────────────────────────────────────────────
+// A minimal shape of what dispatchMentions needs from a Session (so this stays testable without sessions.ts).
+export type ActorSession = { id: string; node: string | null; name: string | null; title: string | null; liveness: string }
+export type Resolved =
+  | { token: string; kind: 'new' }
+  | { token: string; kind: 'session'; session: ActorSession }
+  | { token: string; kind: 'unresolved' }
+
+// Resolve each actor token to a `new` sentinel, an ONLINE session (never a dead one — you don't summon a
+// closed agent; `@new` acts on its behalf), or unresolved. Match order: literal `new` → exact id → id prefix
+// → name/title (case-insensitive) → name/title prefix. First online match wins.
+export function resolveActors(tokens: string[], sessions: ActorSession[]): Resolved[] {
+  const online = sessions.filter((s) => s.liveness === 'online')
+  return tokens.map((token): Resolved => {
+    if (token === 'new') return { token, kind: 'new' }
+    const t = token.toLowerCase()
+    const label = (s: ActorSession) => (s.name || s.title || '').toLowerCase()
+    const hit =
+      online.find((s) => s.id === token) ||
+      online.find((s) => s.id.startsWith(token)) ||
+      online.find((s) => label(s) === t) ||
+      online.find((s) => label(s).startsWith(t) && t.length >= 2)
+    return hit ? { token, kind: 'session', session: hit } : { token, kind: 'unresolved' }
+  })
+}
+
+// ── dispatch (integration) ─────────────────────────────────────────────────────────────────────────────
+export type DispatchOutcome = { token: string; result: 'sent' | 'spawned' | 'offline' | 'unresolved' | 'failed'; detail?: string; note?: string }
+
+// The prompt an @-mentioned actor receives: the comment verbatim + a pointer back to the thread. It is a
+// nudge to look, never a rigid command — what to do is up to the comment's words.
+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 -\`.`
+}
+// 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.
+export function newWorkerPrompt(threadId: string, node: string | null, author: string, text: string, status?: string | null): string {
+  const on = node ? ` on node ${node}` : ''
+  const settled = status && status !== 'open'
+    ? `NOTE: this thread is already resolved (status: ${status}) — the work it describes has likely LANDED. ` +
+      `Verify the current state on main FIRST; if main already satisfies the thread, reply with that finding ` +
+      `instead of re-implementing.\n\n`
+    : ''
+  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}` : ''}.`
+}
+
+// Parse a committed issue post's text for `@` actors and deliver to each. Best-effort and LOUD: the thread is
+// already committed, so a failed dispatch never fails the post — it is reported. sessions.ts is imported
+// lazily; with no actor mentions this returns [] without loading it or hitting the backend.
+export async function dispatchMentions(
+  text: string,
+  ctx: { threadId: string; node: string | null; author: string; status?: string | null },
+): Promise<DispatchOutcome[]> {
+  const { actors } = parseMentions(text)
+  if (!actors.length) return []
+  const { sendKeys, listSessions, newSession } = await import('./sessions.js')
+  const sessions = await listSessions()
+  const resolved = resolveActors(actors, sessions as unknown as ActorSession[])
+  const out: DispatchOutcome[] = []
+  for (const r of resolved) {
+    if (r.kind === 'unresolved') { out.push({ token: r.token, result: 'unresolved' }); continue }
+    if (r.kind === 'new') {
+      // the drain guard ([[mentions]]): @new on a settled thread still spawns (the summons may be a
+      // 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))
+        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
+    }
+    const res = await sendKeys(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 })
+  }
+  return out
+}
+
+// ── implicit originator loop-in + the dispatch fallback chain ([[mentions]] / [[remark-substrate]] R3) ────
+// 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`,
+// 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 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
+// needless escalation). Store-agnostic: a forge issue's author is a github login, resolves to no live session,
+// and the chain runs dry silently — exactly right.
+export type LoopIn = { originator: string }   // the candidate we actually reached (a filer OR a governing-session fallback)
+
+// The courtesy prompt — framed as a heads-up, never a command (that is what an @-mention's mentionPrompt is).
+function originatorPrompt(threadId: string, node: string | null, replier: string, text: string): 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 -\`.`
+}
+
+// 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.
+export type LoopInPick =
+  | { kind: 'deliver'; originator: string; session: ActorSession }
+  | { kind: 'reached' }
+  | { kind: 'none' }
+export function pickLoopIn(
+  chain: (string | null)[],
+  replier: string,
+  sessions: ActorSession[],
+  alreadyDelivered?: Set<string>,
+): LoopInPick {
+  const seen = new Set<string>()
+  const candidates = chain.filter((c): c is string => !!c && c !== replier && !seen.has(c) && (seen.add(c), true))
+  for (const originator of candidates) {
+    const [resolved] = resolveActors([originator], sessions)
+    if (resolved.kind !== 'session') continue                 // offline / no live session → try the next fallback link
+    if (alreadyDelivered?.has(resolved.session.id)) return { kind: 'reached' }   // already an explicit @-target: stop
+    return { kind: 'deliver', originator, session: resolved.session }
+  }
+  return { kind: 'none' }
+}
+
+// `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).
+export async function notifyOriginator(
+  chain: (string | null)[],
+  replier: string,
+  text: string,
+  ctx: { threadId: string; node: string | null; alreadyDelivered?: Set<string> },
+): 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 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')
+  return res.ok ? { originator: pick.originator } : null      // a failed send behaves like offline: silent
+}
+
+// The set of session ids a dispatch ALREADY reached (sent or spawned) — what the loop-in skips to avoid a
+// double-delivery to an originator who was also an explicit @-target.
+export function deliveredIds(outcomes: DispatchOutcome[]): Set<string> {
+  return new Set(outcomes.filter((o) => (o.result === 'sent' || o.result === 'spawned') && o.detail).map((o) => o.detail!))
+}
+
+// A one-line human summary of what a dispatch did, for the CLI to echo after a post. The optional loop-in is
+// noted DISTINCT from the @-dispatch — a courtesy copy, not an assignment.
+export function summarize(outcomes: DispatchOutcome[], loopIn?: LoopIn | null): string {
+  const parts: string[] = []
+  if (outcomes.length) parts.push('@ ' + outcomes.map((o) => {
+    if (o.result === 'sent') return `${o.token}→sent`
+    if (o.result === 'spawned') return `new→${o.detail}${o.note ? ` ⚠ ${o.note} — likely already landed` : ''}`
+    if (o.result === 'offline') return `${o.token}→offline (stored)`
+    if (o.result === 'unresolved') return `${o.token}→? (no live session; stored)`
+    return `${o.token}→failed (${o.detail})`
+  }).join('  ·  '))
+  if (loopIn) parts.push(`↩ looped in originator @${loopIn.originator} (online)`)
+  return parts.join('  ·  ')
+}

package/spec-cli/src/plugin-harness.ts

@@ -0,0 +1,145 @@
+import { writeFileSync, mkdirSync, readFileSync, existsSync, rmSync, copyFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// @@@ plugin-harness - the PLUGIN BUNDLE emitter: render the whole SpexCode system into ONE self-contained
+// Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.zcode` /
+// `.claude` → <folder>/plugins/spexcode/). It is the plugin-target counterpart of the native per-harness
+// write [[harness-adapter]] does — chosen INSTEAD of the natives (plugin exclusivity), so [[harness-delivery]]'s
+// materialize prunes every native first, then emits this. The bundle follows the de-facto Claude-plugin schema
+// (a `.claude-plugin/plugin.json` pointing at hooks/skills/commands/agents); the host's discovery order is
+// `.zcode-plugin > .claude-plugin > .codex-plugin` and z-code/Claude both read a `.claude-plugin` directly, so
+// the ONE `.claude-plugin` bundle reaches ZCode, Claude, and (future) Codex from a single emit.
+//
+// The contract is NOT delivered by an always-on CLAUDE.md block here (the bundle never touches the repo's own
+// files) — it maps to a SessionStart hook that emits hookSpecificOutput.additionalContext (the harness-neutral
+// injection Claude/z-code normalize, the superpowers pattern), so a plugin host gets the contract with no
+// --append-system-prompt. The hooks reuse the SAME dispatch.sh wiring as the natives, located via the host's
+// ${CLAUDE_PLUGIN_ROOT} variable; dispatch.sh's first arg is the harness id `plugin`, so its shell mirror
+// (harness.sh) parses payloads as the claude family (z-code/Claude share Claude's tool names + file_path).
+
+const PKG = fileURLToPath(new URL('..', import.meta.url))   // installed spec-cli root
+const HOOKS_SRC = join(PKG, 'hooks')                        // the canonical dispatch.sh + harness.sh source
+const PLUGIN_NAME = 'spexcode'
+// the host substitutes ${CLAUDE_PLUGIN_ROOT} with the bundle's own absolute path before running a hook command
+// (the same variable z-code's hook-compat honours), so dispatch.sh/inject-contract.sh resolve regardless of
+// where the host scanned the bundle from.
+const PLUGIN_ROOT = '${CLAUDE_PLUGIN_ROOT}'
+// the lifecycle events the bundle binds — the Claude/z-code superset; a host that fires fewer (Codex) simply
+// never invokes the extras, so binding all is harmless and one emit serves every host.
+const PLUGIN_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'] as const
+
+// the gathered surface artifacts this render writes into the bundle. contract = the assembled guide+system
+// block (the SAME string the native path folds into CLAUDE.md, here delivered as additionalContext); skills/
+// agents/commands are the already-rendered file CONTENTS (reusing materialize's renderSkill/renderAgent), keyed
+// by node name; spex is the baked tsx+cli invocation the dispatcher gate calls; version stamps plugin.json.
+export type PluginRender = {
+  contract: string
+  skills: { name: string; content: string }[]
+  agents: { name: string; content: string }[]
+  commands: { name: string; content: string }[]
+  spex: string
+  version: string
+}
+
+// the bundle dir for a plugin folder: <proj>/<folder>/plugins/spexcode — `<folder>` is the host's plugins-scan
+// root ([[harness-select]] requires it explicit), `plugins/<name>` the conventional bundle location under it.
+export function pluginBundleDir(proj: string, folder: string): string {
+  return join(proj, folder, 'plugins', PLUGIN_NAME)
+}
+
+// the de-facto Claude-plugin manifest: name (the bundle identity clean() gates on), version, description, and
+// the component pointers Claude/z-code discover (hooks.json + the skills/commands/agents dirs).
+function pluginManifest(version: string): string {
+  return JSON.stringify({
+    name: PLUGIN_NAME,
+    version,
+    description: 'SpexCode — spec-driven dev-flow contract, hooks, skills, commands & agents as one self-contained plugin.',
+    hooks: './hooks/hooks.json',
+    commands: './commands',
+    agents: './agents',
+    skills: './skills',
+  }, null, 2)
+}
+
+// hooks.json in the Claude/z-code-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
+// event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited for the gate); SessionStart
+// ALSO runs inject-contract.sh first, so the contract additionalContext lands alongside the normal dispatch.
+function pluginHooksJson(spex: string): string {
+  const dispatch = (e: string) => `SPEX='${spex}' bash "${PLUGIN_ROOT}/hooks/dispatch.sh" plugin ${e}`
+  const inject = `bash "${PLUGIN_ROOT}/hooks/inject-contract.sh"`
+  const hooks: Record<string, unknown> = {}
+  for (const e of PLUGIN_EVENTS) {
+    const cmds = e === 'SessionStart'
+      ? [{ type: 'command', command: inject }, { type: 'command', command: dispatch(e) }]
+      : [{ type: 'command', command: dispatch(e) }]
+    hooks[e] = [{ hooks: cmds }]
+  }
+  return JSON.stringify({ hooks }, null, 2)
+}
+
+// the SessionStart hook OUTPUT carrying the contract as additionalContext. JSON-encoded HERE, at render time,
+// so the runtime hook is a trivial `cat` — never a fragile shell escaping of arbitrary contract prose.
+function contractContextJson(contract: string): string {
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: contract } }, null, 2)
+}
+
+// the SessionStart contract injector: print the pre-encoded additionalContext payload (the harness-neutral
+// stand-in for --append-system-prompt). A bare cat — all the encoding happened at materialize time.
+const INJECT_SH = `#!/usr/bin/env bash
+# Emit the SpexCode contract as SessionStart additionalContext — the harness-neutral contract injection (the
+# superpowers pattern; Claude/z-code normalize hookSpecificOutput.additionalContext) that replaces a plugin
+# host's missing --append-system-prompt. The JSON was rendered at materialize time, so this is a trivial cat.
+here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+[ -f "$here/contract-context.json" ] && cat "$here/contract-context.json"
+exit 0
+`
+
+// emit (or idempotently re-emit) the whole bundle into <folder>/plugins/spexcode.
+export function emitPlugin(proj: string, folder: string, r: PluginRender): void {
+  const bundle = pluginBundleDir(proj, folder)
+  const meta = join(bundle, '.claude-plugin')
+  const hooksDir = join(bundle, 'hooks')
+  mkdirSync(meta, { recursive: true })
+  mkdirSync(hooksDir, { recursive: true })
+  writeFileSync(join(meta, 'plugin.json'), pluginManifest(r.version))
+  // hooks: the SHARED dispatcher + its shell mirror (copied verbatim — the exact native wiring), the contract
+  // injector + its pre-encoded payload, and the event→dispatch binding.
+  copyFileSync(join(HOOKS_SRC, 'dispatch.sh'), join(hooksDir, 'dispatch.sh'))
+  copyFileSync(join(HOOKS_SRC, 'harness.sh'), join(hooksDir, 'harness.sh'))
+  writeFileSync(join(hooksDir, 'inject-contract.sh'), INJECT_SH)
+  writeFileSync(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract))
+  writeFileSync(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex))
+  // skills / agents / commands — the Claude-plugin layout, the SAME rendered contents as the native dirs.
+  for (const s of r.skills) writeBundleFile(join(bundle, 'skills', s.name, 'SKILL.md'), s.content)
+  for (const a of r.agents) writeBundleFile(join(bundle, 'agents', `${a.name}.md`), a.content)
+  for (const c of r.commands) writeBundleFile(join(bundle, 'commands', `${c.name}.md`), c.content)
+}
+
+function writeBundleFile(f: string, content: string): void {
+  mkdirSync(dirname(f), { recursive: true })
+  writeFileSync(f, content)
+}
+
+// the INVERSE of emitPlugin — prune the bundle when its folder is DESELECTED ([[harness-delivery]] tracks the
+// previously-emitted folders and cleans any the current set dropped, e.g. switching plugin→native or folder A→B).
+// Identity-gated on the bundle's own plugin.json `name`, so it removes ONLY a spexcode bundle, never a folder
+// the user populated with another plugin.
+export function cleanPlugin(proj: string, folder: string): void {
+  const bundle = pluginBundleDir(proj, folder)
+  const manifest = join(bundle, '.claude-plugin', 'plugin.json')
+  if (!existsSync(manifest)) return
+  try {
+    if (String(JSON.parse(readFileSync(manifest, 'utf8'))?.name) !== PLUGIN_NAME) return
+  } catch { return }
+  rmSync(bundle, { recursive: true, force: true })
+}
+
+// the bundle version stamped into plugin.json — the monorepo root `spexcode` package version (the published
+// artifact's version), falling back to the spec-cli package, then 0.0.0.
+export function pluginVersion(): string {
+  for (const p of [join(PKG, '..', 'package.json'), join(PKG, 'package.json')]) {
+    try { const v = JSON.parse(readFileSync(p, 'utf8'))?.version; if (v) return String(v) } catch { /* keep trying */ }
+  }
+  return '0.0.0'
+}