spexcode 0.4.0 → 0.4.3

package/spec-cli/src/materialize.ts

@@ -11,6 +11,12 @@ import { resolveHarnessTargets, partitionHarnesses } from './harness-select.js'
 import { emitPlugin, cleanPlugin, pluginBundleDir, pluginVersion } from './plugin-harness.js'
 import { plantContractFilter, removeContractFilter, settleIndexStat } from './contract-filter.js'
 
+export type MaterializedArtifact = {
+  kind: 'hook manifest' | 'contract' | 'shim' | 'skill' | 'agent' | 'plugin bundle' | 'trust'
+  path: string
+}
+export type MaterializeResult = { contentHash: string; planted: MaterializedArtifact[] }
+
 // @@@ materialize - the materialize step (≈0.85s), anchored on GIT-NATIVE events only ([[commit-surgery]]):
 // spex verbs (init/materialize), session-worktree creation, and the planted git hooks (pre-commit,
 // post-checkout, post-merge) — never a harness event; the harness is a READER of the materialized files, not
@@ -156,22 +162,36 @@ export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { s
   // and even unfiltered the phantom-`M` lingers) — settle the index stat, content-guarded so a user's real
   // unstaged edit is never staged ([[content-filter]] edge 2).
   try { settleIndexStat(proj, HARNESSES.flatMap((h) => h.contractFiles(proj))) } catch { /* not a git repo */ }
-  // leaving nothing behind: drop the now-EMPTY dirs the assert phase mkdir'ed (.claude/.codex and their
-  // skills/agents subdirs — children listed before parents). rmdirSync is NON-recursive, so a dir holding
+  // leaving nothing behind: drop the now-EMPTY dirs the assert phase mkdir'ed (.claude/.codex/.opencode/.pi
+  // and their skills/agents/plugins/extensions subdirs). Each dir AND its parent are swept deepest-first,
+  // because a harness may nest its shim a level below its home (opencode's .opencode/plugins/, pi's
+  // .pi/extensions/) — but never the checkout roots themselves. rmdirSync is NON-recursive, so a dir holding
   // any user file survives untouched; `.git/spexcode/` is deliberately NOT swept (shared per-clone home).
   for (const h of HARNESSES) {
     const anchor = h.worktreeHookAnchor(proj)
-    for (const d of [h.skillDir(proj), h.agentDir(proj), dirname(h.shimFile(proj)), anchor ? dirname(anchor) : null])
-      if (d) { try { rmdirSync(d) } catch { /* non-empty or absent — keep */ } }
+    const dirs = [h.skillDir(proj), h.agentDir(proj), dirname(h.shimFile(proj)), anchor ? dirname(anchor) : null]
+      .filter((d): d is string => !!d)
+    const roots = new Set([proj, mainCheckout(proj)])
+    const sweep = [...new Set([...dirs, ...dirs.map((d) => dirname(d))])]
+      .filter((d) => !roots.has(d))
+      .sort((a, b) => b.length - a.length)
+    for (const d of sweep) { try { rmdirSync(d) } catch { /* non-empty or absent — keep */ } }
   }
 }
 
-// the whole pay-per-change materialize. proj defaults to cwd. Returns the new content-hash it stamped.
-export function materialize(proj = process.cwd()): string {
+// the whole pay-per-change materialize. proj defaults to cwd. Its receipt is populated at each successful
+// write so callers report the actual selected footprint instead of maintaining a second artifact inventory.
+export function materialize(proj = process.cwd()): MaterializeResult {
   const rt = treeSlotDir(proj)                                            // this tree's slot in the global store, not the worktree
   mkdirSync(rt, { recursive: true })
+  const planted: MaterializedArtifact[] = []
+  const record = (kind: MaterializedArtifact['kind'], path: string) => {
+    if (!planted.some((a) => a.kind === kind && a.path === path)) planted.push({ kind, path })
+  }
   // (1) hook manifest (persistent — the dispatcher reads it; regenerated only here, on change).
-  writeFileSync(join(rt, 'hooks-manifest'), compileManifest())
+  const manifest = join(rt, 'hooks-manifest')
+  writeFileSync(manifest, compileManifest())
+  record('hook manifest', manifest)
   // (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.
@@ -216,17 +236,18 @@ export function materialize(proj = process.cwd()): string {
   const machinePaths: string[] = []
   const contractPaths: string[] = []
   for (const h of selected) {
-    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); contractPaths.push(f) }
+    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); contractPaths.push(f); record('contract', f) }
     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)
+    writeFileSync(shimFile, shim.content)
+    record('shim', shimFile)
+    for (const f of h.writeTrust(proj, shim.cmd)) record('trust', f)
     machinePaths.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). One adapter line; null otherwise.
     const anchor = h.worktreeHookAnchor(proj)
-    if (anchor) { mkdirSync(dirname(anchor), { recursive: true }); writeFileSync(anchor, shim.json); machinePaths.push(anchor) }
+    if (anchor) { mkdirSync(dirname(anchor), { recursive: true }); writeFileSync(anchor, shim.content); machinePaths.push(anchor); record('shim', anchor) }
   }
   // (6) skills + (7) sub-agents — each surface node → the file the harness auto-discovers, one per selected
   //     harness that has the primitive (skillDir/agentDir null skips — the divergence is the adapter's line).
@@ -237,6 +258,7 @@ export function materialize(proj = process.cwd()): string {
       mkdirSync(dirname(f), { recursive: true })
       writeFileSync(f, skillArtifact(sk))
       artifactPaths.push(f)
+      record('skill', f)
     }
   }
   for (const ag of agentNodes) {
@@ -246,6 +268,7 @@ export function materialize(proj = process.cwd()): string {
       mkdirSync(dirname(f), { recursive: true })
       writeFileSync(f, agentArtifact(ag))
       artifactPaths.push(f)
+      record('agent', f)
     }
   }
   // (8) the PLUGIN target ([[plugin-harness]]): materialize the whole system into one self-contained Claude-plugin
@@ -271,7 +294,10 @@ export function materialize(proj = process.cwd()): string {
       spex: SPEX,
       version: pluginVersion(),
     }
-    for (const p of plugins) emitPlugin(proj, p.folder, bundle)
+    for (const p of plugins) {
+      emitPlugin(proj, p.folder, bundle)
+      record('plugin bundle', pluginBundleDir(proj, p.folder))
+    }
   }
   writeFileSync(ledger, curFolders.join('\n'))
   // (9) the ignore rules — ALWAYS the per-clone .git/info/exclude ([[residence]]): the exclude is not a
@@ -313,5 +339,5 @@ export function materialize(proj = process.cwd()): string {
   // (5) stamp the content-hash marker LAST (a diagnostic freshness record; a crash mid-materialize leaves it stale).
   const h = contentHash(proj)
   writeFileSync(join(rt, 'content-hash'), h)
-  return h
+  return { contentHash: h, planted }
 }

package/spec-cli/src/mentions.ts

@@ -9,8 +9,9 @@
 // `@<token>` at a word boundary is an actor; `[[<id>]]` is a topic. Token chars are any unicode
 // letter/number plus [_-] (a CJK session handle or node id is first-class — same charset the launch-side
 // MENTION and the dashboard's MENTION_RE use); a session id, a short label/prefix, or the literal `new`.
-// Both forms are deduped in first-seen order.
-const ACTOR_RE = /(?:^|\s)@([\p{L}\p{N}_-]+)/gu
+// Only `new` may carry `:<launcher>` ([[launcher-select]]); keeping that choice in the token makes the same
+// prose work from the CLI and dashboard, with no composer-only field. Both forms are deduped first-seen.
+const ACTOR_RE = /(?:^|\s)@([\p{L}\p{N}_-]+)(?::([\p{L}\p{N}_.-]+))?/gu
 const NODE_RE = /\[\[([^\]\s]+)\]\]/g
 
 const uniq = (xs: string[]): string[] => [...new Set(xs)]
@@ -30,7 +31,7 @@ export function stripRefSigil(token: string): string {
 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(ACTOR_RE)) actors.push(m[1] === 'new' && m[2] ? `new:${m[2]}` : m[1])
   for (const m of text.matchAll(NODE_RE)) nodes.push(m[1])
   return { actors: uniq(actors), nodes: uniq(nodes) }
 }
@@ -39,17 +40,19 @@ export function parseMentions(text: string): { actors: string[]; nodes: string[]
 // 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: 'new'; launcher?: string }
   | { 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.
+// Resolve each actor token to a `new` sentinel (optionally carrying its explicit launcher), an ONLINE
+// session (never a dead one — you don't summon a closed agent; `@new` acts on its behalf), or unresolved.
+// Match order: new/new:<launcher> → 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 fresh = /^new(?::(.+))?$/.exec(token)
+    if (fresh) return { token, kind: 'new', ...(fresh[1] ? { launcher: fresh[1] } : {}) }
     const t = token.toLowerCase()
     const label = (s: ActorSession) => (s.name || s.title || '').toLowerCase()
     const hit =
@@ -84,7 +87,9 @@ function mentionPrompt(threadId: string, node: string | null, author: string, te
 // 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}` : ''
+  // Keep inherited scope inside the text the worker receives: newSession derives its node only from the
+  // raw prompt's first [[id]] mention, so issue dispatch gets no private node-binding argument.
+  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 ` +
@@ -115,7 +120,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), spawnParent(ctx.author, sessions))
+        const s = await newSession(newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status), spawnParent(ctx.author, sessions), r.launcher)
         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
@@ -205,7 +210,7 @@ export function summarize(outcomes: DispatchOutcome[], loopIn?: LoopIn | null):
   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 === 'spawned') return `${o.token}→${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})`

package/spec-cli/src/opencode.ts

@@ -0,0 +1,145 @@
+import { shimRuntimeSource } from './shim-runtime.js'
+
+// @@@ opencode plugin generator - the opencode adapter's "shim" is not a settings JSON but a generated
+// opencode PLUGIN (.opencode/plugins/spexcode.ts, auto-loaded by opencode from the project tree) that runs
+// inside the agent process. It is a THIN HOST over the shared shim runtime ([[shim-runtime]], embedded
+// verbatim): this generator declares opencode's event-bus mapping (session.created → SessionStart,
+// chat.message → UserPromptSubmit, tool.execute.before/after → Pre/PostToolUse, session.idle → Stop) and its
+// host bindings; the payload synthesis, the block verdict (exit 2 + stdout decision:block JSON), and the
+// rendezvous server come from the runtime. opencode's host-specific verdict consumers ([[opencode-harness]]):
+// a PreToolUse block THROWS (opencode aborts the tool call); a Stop block re-injects the gate's reason as a
+// follow-up prompt via the SDK client, closing the stop-gate loop. What re-enters is always the parsed
+// REASON, never the escaped wire JSON. The rendezvous inject is client.session.prompt into the ROOT session,
+// gated by canInject (a plugin with no adopted session reply-rejects instead of confirming an undeliverable
+// prompt). What genuinely stays opencode-only below: session tracking (root vs subagent children, the
+// agent_id stamp), the minted-id capture, and the two resume seeds.
+// This module is a PURE content producer (no imports from harness.ts — the adapter object lives there, in the
+// one HARNESSES seam) so there is no import cycle.
+
+// the lifecycle events the generated plugin can emit (drives the shim + hooks-manifest binding). opencode's
+// bus has no failed-stop and no idle/attention notification event, so StopFailure/Notification are genuinely
+// absent — the same five codex binds.
+export const OPENCODE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'] as const
+
+// opencode tool name → Claude tool name, so [[inject-spec-first]] / [[inject-spec-of-file]] and every other
+// claude-family handler read the payload with zero opencode knowledge. Unknown tools pass through untouched
+// (opencode's names are lowercase). Exported for tests.
+export const OPENCODE_TOOL_NAMES: Record<string, string> = {
+  bash: 'Bash', edit: 'Edit', write: 'Write', read: 'Read', grep: 'Grep', glob: 'Glob', list: 'LS',
+  patch: 'Edit', todowrite: 'TodoWrite', todoread: 'TodoRead', webfetch: 'WebFetch', task: 'Task',
+}
+
+// the generated plugin source. `dispatch` and `spex` are absolute paths baked at materialize time (same as
+// every shim); the 'dispatch.sh' substring doubles as the identity stamp cleanHarness gates removal on. The
+// file is plain TS with no @opencode-ai/plugin type import, so it loads regardless of the host project's
+// node_modules; opencode calls every exported function with its plugin context.
+export function opencodePluginSource(dispatch: string, spex: string): string {
+  return `// spexcode: GENERATED by spex materialize — do not edit (regenerated per clone; see [[opencode-harness]])
+// Bridges opencode's event bus into SpexCode's dispatch.sh (claude-shaped payloads) and serves the
+// per-session rendezvous socket for prompt delivery + liveness.
+import { spawn } from "node:child_process"
+${shimRuntimeSource('opencode', dispatch, spex)}
+
+const TOOL_NAMES = ${JSON.stringify(OPENCODE_TOOL_NAMES)}
+
+export const SpexcodePlugin = async (ctx) => {
+  const client = ctx && ctx.client
+  const cwd = (ctx && (ctx.directory || (ctx.app && ctx.app.path && ctx.app.path.cwd))) || process.cwd()
+  const recordId = (process.env.SPEXCODE_SESSION_ID || "").trim()
+  const rt = spexShimRuntime({ sessionId: () => recordId, cwd: () => cwd })
+
+  // session tracking: the ROOT opencode session is this worker's conversation; child sessions (subagents)
+  // are stamped agent_id so a parent's declared state stays out of its subagents' reach (the same
+  // discriminator claude's Task subagents carry). A RESUMED session re-fires no bus event until poked, so
+  // event-driven adoption alone leaves a resumed worker unreachable (the daemon reply-rejects every
+  // delivery): a --session resume seeds rootSession from the launch env (the resume marker's id), and a
+  // --continue resume falls back to asking the SDK for the newest root session.
+  let rootSession = (process.env.SPEXCODE_OPENCODE_RESUME_ID || "").trim()
+  const children = new Set()
+  const stamp = (sid) => (sid && children.has(sid) ? { agent_id: sid } : {})
+  // opencode MINTS its own session id — report it once so the backend stores it as harness_session_id
+  // (the id session resume passes to \`opencode --session <id>\`). Fire-and-forget; a failure only costs resume-by-id.
+  let captured = !!rootSession   // a seeded (resumed) id is already on the record — don't re-report it
+  const capture = (sid) => {
+    if (captured || !sid || !recordId) return
+    captured = true
+    try { spawn(SPEX, ["internal", "opencode-capture", sid], { cwd, env: process.env, stdio: "ignore" }) } catch { /* resume falls back to --continue */ }
+  }
+  const adopt = (sid) => { if (!rootSession && sid) { rootSession = sid; capture(sid) } }
+  const injectPrompt = async (text) => {
+    if (!client || !rootSession) throw new Error("no session to prompt")
+    await client.session.prompt({ path: { id: rootSession }, body: { parts: [{ type: "text", text }] } })
+  }
+
+  // --continue resume: no owned id was ever captured, and a reattached session fires no bus event until
+  // poked — ask the SDK for the newest root session (what --continue itself reattached) so deliveries can
+  // inject. Gated on the launch marker so a FRESH launch can never adopt a stale session; best-effort with
+  // bounded retries (the server may still be loading at plugin init), shape-defensive, and adopt() ignores
+  // the late result if a real event won the race.
+  if (!rootSession && process.env.SPEXCODE_OPENCODE_CONTINUE && client && client.session && typeof client.session.list === "function") {
+    (async () => {
+      for (let i = 0; i < 10 && !rootSession; i++) {
+        try {
+          const res = await client.session.list()
+          const arr = (res && (res.data || res)) || []
+          const roots = (Array.isArray(arr) ? arr : []).filter((s) => s && s.id && !s.parentID)
+          const at = (s) => (s.time && (s.time.updated || s.time.created)) || 0
+          roots.sort((a, b) => at(b) - at(a))
+          if (roots.length) { adopt(roots[0].id); return }
+        } catch { /* not up yet — retry */ }
+        await new Promise((r) => setTimeout(r, 1000))
+      }
+    })()
+  }
+
+  // the rendezvous daemon, from the shared runtime: {type:"reply"} injects into the root session (a plugin
+  // that adopted no session yet reply-rejects synchronously, BEFORE repaint-done, so the sender fails loud
+  // instead of confirming a prompt that can never inject); {type:"repaint"} answers repaint-done in the same
+  // synchronous parse pass — confirmation means PARSED, not processed. The injection itself (a whole model
+  // turn: the SDK prompt call resolves only when the TURN ends) runs BEHIND the confirm.
+  rt.serveRendezvous(injectPrompt, { canInject: () => !!(client && rootSession) })
+
+  const toolPayload = (input, output) => {
+    const sid = (input && input.sessionID) || ""
+    return {
+      ...stamp(sid),   // agent_id must precede tool_input — hp_is_subagent checks keys only before tool_input
+      tool_name: TOOL_NAMES[(input && input.tool) || ""] || ((input && input.tool) || ""),
+      tool_input: rt.toolInput(output && output.args, "filePath"),
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      const t = event && event.type
+      const p = (event && event.properties) || {}
+      if (t === "session.created") {
+        const info = p.info || {}
+        if (info.parentID) children.add(info.id)
+        else if (!rootSession) { adopt(info.id); await rt.dispatchEvent("SessionStart", { source: "startup" }) }
+      } else if (t === "session.idle") {
+        const sid = p.sessionID || ""
+        if (sid && rootSession && sid !== rootSession) return   // a subagent going idle is not this worker's Stop
+        adopt(sid)
+        // the stop-gate loop closes in-process via the runtime's dispatchStop: stop_hook_active rides the
+        // payload (the gate's loop-termination bit) and the gate's parsed reason re-enters as a follow-up
+        // prompt; an inject the host can no longer take is reported loud.
+        await rt.dispatchStop((reason) => injectPrompt(reason), "blocked by a spexcode hook")
+      }
+    },
+    "chat.message": async (input, output) => {
+      const sid = (output && output.message && output.message.sessionID) || (input && input.sessionID) || ""
+      if (!(sid && children.has(sid))) adopt(sid)
+      const text = ((output && output.parts) || []).filter((x) => x && x.type === "text").map((x) => x.text).join("\\n")
+      await rt.dispatchEvent("UserPromptSubmit", { ...stamp(sid), prompt: text })
+    },
+    "tool.execute.before": async (input, output) => {
+      const r = await rt.dispatchEvent("PreToolUse", toolPayload(input, output))
+      if (rt.blocked(r)) throw new Error(rt.blockReason(r, "blocked by a spexcode hook"))   // aborts the tool call — the PreToolUse block contract
+    },
+    "tool.execute.after": async (input, output) => {
+      await rt.dispatchEvent("PostToolUse", toolPayload(input, output))
+    },
+  }
+}
+`
+}

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

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { shimRuntimeSource } from './shim-runtime.js'
+
+// @@@ pi-harness helpers - the pi-ONLY machinery behind harness.ts's piHarness adapter: the generated
+// extension source (pi's shim is a TypeScript extension, not a hooks JSON — pi has no external hook binding;
+// its lifecycle surface IS the extension API) and the trust writer (pi's project-trust store,
+// ~/.pi/agent/trust.json). Kept out of harness.ts so the adapter table stays scannable; imports NOTHING from
+// harness.ts at runtime (no cycle — harness.ts imports us).
+
+// ---------------------------------------------------------------------------------------------------------
+// the pi shim = a generated extension at .pi/extensions/spexcode.ts (pi runs .ts extensions natively). It is
+// a THIN HOST over the shared shim runtime ([[shim-runtime]], embedded verbatim): this generator declares
+// only pi's event-name mapping and its ExtensionAPI bindings —
+//   session_start → SessionStart · input → UserPromptSubmit · tool_call → PreToolUse (blockable) ·
+//   tool_result → PostToolUse · agent_end + agent_settled → Stop (dual binding, one shared bit)
+// — while the payload synthesis, the block-verdict parse (exit 2 + stdout decision:block JSON), and the
+// rendezvous server all come from the runtime. pi's two host-specific verdict consumers: a tool_call block
+// returns pi's typed { block: true, reason }; a Stop block has no blocking return, so Stop rides the
+// runtime's dispatchStop on a DUAL binding — agent_end (awaited in the run loop: a queued teach drains as
+// the same prompt's continuation, never an orphan) plus agent_settled (fires once per prompt after every
+// drain: the terminal backstop whose flagged dispatch guarantees the gate's escape runs before settlement
+// completes) — with stop_hook_active synthesized across both and the gate's reason SENT BACK IN as a user
+// message; a no-longer-injectable host is reported loud — never silently dropped (a dropped rejection is
+// a session stuck `active` forever).
+// The rendezvous inject is pi.sendUserMessage({deliverAs: steer}), always able → no canInject gate.
+export function piExtensionSource(dispatch: string, spex: string): string {
+  return `// generated by spexcode materialize — DO NOT EDIT (regenerated per clone; identity: dispatch.sh)
+// SpexCode's pi shim: forwards pi lifecycle events to dispatch.sh as Claude-shaped hook payloads, and serves
+// this session's rendezvous socket for prompt delivery + liveness.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+${shimRuntimeSource('pi', dispatch, spex)}
+
+// pi tool names → the Claude tool vocabulary harness.sh parses (unknown names pass through untouched).
+const TOOL: Record<string, string> = { read: "Read", edit: "Edit", write: "Write", bash: "Bash" }
+
+export default function spexcode(pi: ExtensionAPI) {
+  let sessionId = process.env.SPEXCODE_SESSION_ID || ""
+  const rt = spexShimRuntime({ sessionId: () => sessionId })
+  const toolFields = (toolName: string, input: unknown) =>
+    ({ tool_name: TOOL[toolName] ?? toolName, tool_input: rt.toolInput(input, "path") })
+
+  // bound as soon as the extension loads so liveness reads online early; only a governed launch carries the
+  // socket env (sessions.ts rvEnv) — a self-launched bare \`pi\` skips this.
+  const rv = rt.serveRendezvous((text: string) => pi.sendUserMessage(text, { deliverAs: "steer" }))
+
+  pi.on("session_start", async (_event, ctx) => {
+    sessionId = ctx.sessionManager.getSessionId() || sessionId
+    process.env.PI_SESSION_ID = sessionId   // tool subprocesses inherit it → spex CLI knows its session
+    await rt.dispatchEvent("SessionStart")
+  })
+  pi.on("input", async (event) => { await rt.dispatchEvent("UserPromptSubmit", { prompt: event.text }) })
+  pi.on("tool_call", async (event) => {
+    const r = await rt.dispatchEvent("PreToolUse", toolFields(event.toolName, event.input))
+    if (rt.blocked(r)) return { block: true, reason: rt.blockReason(r, "blocked by a SpexCode hook") }
+  })
+  pi.on("tool_result", async (event) => { await rt.dispatchEvent("PostToolUse", toolFields(event.toolName, event.input)) })
+  // Stop rides the runtime's dispatchStop on TWO bindings that never duplicate: agent_end performs the
+  // NORMAL dispatch (pi awaits its listeners inside the run loop and drains a queued teach as the SAME
+  // awaited prompt's continuation — never the orphaned settle-time prompt whose late inject threw
+  // "extension ctx is stale"), while agent_settled — which fires exactly once per prompt, after every
+  // drain — consumes AT MOST ONE PENDING BLOCKED stop (measured gap: in real dispatched runs the drained
+  // continuation's own agent_end does not reliably re-reach the extension, so without the backstop the
+  // flagged escape never runs). A naturally allowed agent_end leaves no
+  // pending state and settle dispatches NOTHING (exactly one gate entry per stop); only a blocked
+  // agent_end arms it, and the flagged settle dispatch always ends allowed (the gate's continuation paths
+  // terminate), clearing the pending bit through a subprocess write with no duplicate inject. An
+  // uninjectable host stays caught-loud.
+  const stop = () => rt.dispatchStop(
+    async (reason: string) => pi.sendUserMessage(reason, { deliverAs: "steer" }),
+    "a SpexCode Stop hook blocked this stop without giving a reason",
+  )
+  pi.on("agent_end", async () => { await stop() })
+  pi.on("agent_settled", async () => { if (rt.stopPending()) await stop() })
+  pi.on("session_shutdown", async () => { rv?.close() })
+}
+`
+}
+
+// ---------------------------------------------------------------------------------------------------------
+// pi trust — make a dispatched/self-launched pi load our project-local extension with zero prompts. pi gates
+// EVERY project-local resource (.pi/extensions, .pi/skills, .pi/prompts, .pi/settings.json) behind project
+// trust: saved decisions live in ~/.pi/agent/trust.json as a flat { "<canonical dir>": true|false } map, and
+// the CLOSEST saved decision on the cwd's parent chain wins (pi trust-manager findNearestTrustEntry). So ONE
+// entry keyed by the MAIN CHECKOUT covers every .worktrees/<id> worktree beneath it. The launch additionally
+// carries `--approve` (one-run trust) as defence for a worktree living OUTSIDE the checkout. Writes are
+// idempotent and surgical: other projects' decisions are untouched; a corrupt trust.json FAILS LOUD rather
+// than being clobbered; remove only deletes a `true` we could have written, never a user's saved "false".
+
+// pi has no config-dir env of its own (hardcoded ~/.pi/agent) — SPEXCODE_PI_AGENT_DIR is OUR test seam only.
+const piAgentDir = () => process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent')
+// pi canonicalizes trust keys (realpath); mirror it so our key matches its lookup.
+const canonical = (p: string) => { try { return realpathSync(p) } catch { return p } }
+
+function readTrust(file: string): Record<string, unknown> {
+  if (!existsSync(file)) return {}
+  const raw = readFileSync(file, 'utf8')
+  try { return JSON.parse(raw) as Record<string, unknown> } catch (e) {
+    throw new Error(`${file} is not valid JSON — refusing to rewrite pi's trust store: ${String(e)}`)
+  }
+}
+
+export function writePiTrust(proj: string): string {
+  const dir = piAgentDir()
+  const file = join(dir, 'trust.json')
+  const key = canonical(proj)
+  const data = readTrust(file)
+  if (data[key] === true) return file   // already trusted — no churn
+  data[key] = true
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+  return file
+}
+
+export function removePiTrust(proj: string): void {
+  const file = join(piAgentDir(), 'trust.json')
+  if (!existsSync(file)) return
+  const key = canonical(proj)
+  const data = readTrust(file)
+  if (data[key] !== true) return   // absent, or a user's own "do not trust" — never touch it
+  delete data[key]
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+}

package/spec-cli/src/project-identity.ts

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { spexcodeHome } from './layout.js'
+import {
+  resolvedIdentityIcon, DEFAULT_GATEWAY_ICON, DEFAULT_PROJECT_ICON, requireIdentityChoice,
+} from './identity-presets.js'
+
+export type ResolvedIdentity = { title: string; icon: string }
+export type GatewayIdentitySource = { identity: ResolvedIdentity; revision: string }
+
+const revisionOf = (raw: string | null): string =>
+  createHash('sha256').update(raw === null ? 'missing' : `present\0${raw}`).digest('hex')
+
+function readObject(file: string): { value: Record<string, any>; raw: string | null } {
+  if (!existsSync(file)) return { value: {}, raw: null }
+  const raw = readFileSync(file, 'utf8')
+  let value: unknown
+  try { value = JSON.parse(raw) }
+  catch (e) { throw new Error(`malformed ${file}: ${(e as Error).message}`) }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${file} must contain one top-level JSON object`)
+  return { value: value as Record<string, any>, raw }
+}
+
+export function resolveProjectIdentity(configRoot: string, canonicalRoot = configRoot): ResolvedIdentity {
+  const { value } = readObject(join(configRoot, 'spexcode.json'))
+  const dashboard = value.dashboard && typeof value.dashboard === 'object' && !Array.isArray(value.dashboard)
+    ? value.dashboard as Record<string, unknown>
+    : {}
+  const configuredTitle = typeof dashboard.title === 'string' ? dashboard.title.trim() : ''
+  return {
+    title: configuredTitle || basename(canonicalRoot),
+    icon: resolvedIdentityIcon(dashboard.icon, DEFAULT_PROJECT_ICON),
+  }
+}
+
+export const hostConfigPath = (): string => join(spexcodeHome(), 'config.json')
+
+export function readGatewayIdentity(): GatewayIdentitySource {
+  const { value, raw } = readObject(hostConfigPath())
+  const gateway = value.gateway && typeof value.gateway === 'object' && !Array.isArray(value.gateway)
+    ? value.gateway as Record<string, unknown>
+    : {}
+  return {
+    identity: { title: 'Projects', icon: resolvedIdentityIcon(gateway.icon, DEFAULT_GATEWAY_ICON) },
+    revision: revisionOf(raw),
+  }
+}
+
+export function writeGatewayIcon(icon: unknown, revision: string): GatewayIdentitySource {
+  const canonical = requireIdentityChoice(icon)
+  const file = hostConfigPath()
+  const current = readObject(file)
+  if (revision !== revisionOf(current.raw)) {
+    const error = new Error('host config changed on disk — reload before saving') as Error & { status?: number }
+    error.status = 409
+    throw error
+  }
+  const gateway = current.value.gateway && typeof current.value.gateway === 'object' && !Array.isArray(current.value.gateway)
+    ? current.value.gateway as Record<string, unknown>
+    : {}
+  const next = { ...current.value, gateway: { ...gateway, icon: canonical } }
+  const raw = `${JSON.stringify(next, null, 2)}\n`
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+  const tmp = `${file}.${process.pid}.tmp`
+  try {
+    writeFileSync(tmp, raw, { mode: 0o600 })
+    renameSync(tmp, file)
+  } finally {
+    try { rmSync(tmp) } catch { /* rename consumed it / write never created it */ }
+  }
+  return { identity: { title: 'Projects', icon: canonical }, revision: revisionOf(raw) }
+}