spexcode 0.4.1 → 0.4.3

package/spec-cli/src/layout.ts

@@ -3,7 +3,7 @@ import { join, dirname } from 'node:path'
 import { homedir } from 'node:os'
 import { git, repoRoot, gitA, headSha, worktreeSpecSig, worktreeSpecDelta, type NodeOp } from './git.js'
 import { guardWorktree } from './resilience.js'
-import { HARNESSES } from './harness.js'
+import { HARNESSES, type HarnessId } from './harness.js'
 
 type Config = {
   main?: string                    // path to the source-of-truth checkout (default: the `main` worktree)
@@ -20,13 +20,13 @@ type Config = {
   // RETIRED (residence compat): the old private-overlay toggle — ignored with the same loud notice;
   // its data-untrack semantics are long gone. See `spex guide footprint` MIGRATIONS.
   private?: boolean
-  // which harness targets `spex materialize` delivers into — native ids ('claude'|'codex') or a {plugin:"<folder>"}
-  // bundle; resolved + validated by [[harness-select]] (harness-select.ts). Default (omitted): all native harnesses.
+  // which harness targets `spex materialize` delivers into — a native HarnessId or a {plugin:"<folder>"}
+  // bundle; resolved + validated by [[harness-select]] (harness-select.ts). REQUIRED — no default set; `spex init --harness` stamps it.
   harnesses?: (string | { plugin?: string })[]
   dashboard?: {
     apiUrl?: string                // the per-project backend the board proxies to (read frontend-side; see api-endpoint)
     title?: string                 // override for the browser-tab name (default: the repo-root basename; see tab-title)
-    icon?: string                  // the browser-tab favicon: an emoji ("🔭") or an Iconify name ("mdi:rocket-launch"); see tab-icon
+    icon?: string                  // project identity icon: a picker preset id; existing emoji/Iconify/URL values remain supported ([[identity-config]])
   }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)
@@ -34,7 +34,7 @@ type Config = {
     // 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 } }
+    launchers?: { [name: string]: { harness?: HarnessId; cmd: string } }
     defaultLauncher?: string       // the launcher a create with no explicit --launcher/dropdown pick uses; required for no-choice creates
   }
   serve?: {

package/spec-cli/src/lint.ts

@@ -1,19 +1,19 @@
-import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs'
+import { readFileSync, existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { repoRoot, git, driftIndex, historyIndex, rowsFor } from './git.js'
 import { loadSpecs } from './specs.js'
 import { readJsonConfig } from './layout.js'
 import { extractors, extractorFor, extOf, resolveAnchor, windowCommits, anchorHitCommits } from './anchors.js'
+import { DEFAULT_TEST_GLOBS, sourcePolicyDescription, trackedSourceFiles } from './source-files.js'
 
 export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
 
 export type LintConfig = {
-  governedRoots: string[]       // dirs whose source files must each be governed by a spec (coverage). '.' = whole project (safe: only git-TRACKED files, so node_modules/build/nested worktrees never count).
-  sourceExtensions: string[]    // extensions coverage treats as source files
-  testGlobs: string[]           // globs EXCLUDED from coverage — tests aren't governed product (default ['**/*.test.*']; set [] to govern tests too)
-  identifierExtensions: string[]// extensions the altitude bare-filename signal recognises (see IDENT below)
-  altitude: { lineBudget: number; charBudget: number; sizeable: number; dense: number; steps: number }
-  maxChildren: number        // breadth budget: warn at >= this many direct children
+  governedRoots: string[]       // dirs whose tracked source files must each be governed by a spec. '.' = whole project.
+  sourceIncludeGlobs: string[] | null // null includes every tracked regular text file; [] intentionally includes none
+  sourceExcludeGlobs: string[]  // explicit source-policy subtraction
+  sourceExtensions: string[] | null // compatibility shorthand compiled into sourceIncludeGlobs
+  testGlobs: string[]           // globs EXCLUDED from coverage; set [] to govern tests too
   maxOwners: number          // warn when a file is governed (code:) by > this many nodes
   scenarioTags: string[]     // the closed vocabulary an eval scenario's `tags:` must draw from; extend it to mint a new tag
   scopedCodeMiss: 'warn' | 'ignore' // the file-level drift ADVISORY on a selector-scoped code: file whose window has no
@@ -23,11 +23,10 @@ export type LintConfig = {
 }
 const DEFAULT_CONFIG: LintConfig = {
   governedRoots: ['spec-dashboard/src', 'spec-cli/src'],
-  sourceExtensions: ['ts', 'tsx', 'js', 'jsx'],
-  testGlobs: ['**/*.test.*'],
-  identifierExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'md'],
-  altitude: { lineBudget: 50, charBudget: 4200, sizeable: 35, dense: 1.3, steps: 3 },
-  maxChildren: 8,
+  sourceIncludeGlobs: null,
+  sourceExcludeGlobs: [],
+  sourceExtensions: null,
+  testGlobs: DEFAULT_TEST_GLOBS,
   maxOwners: 3,
   scenarioTags: ['frontend-e2e', 'backend-api', 'cli', 'desktop', 'mobile'],
   scopedCodeMiss: 'warn',
@@ -36,107 +35,36 @@ export function loadConfig(root: string): LintConfig {
   // Absent spexcode.json → tuned defaults; a MALFORMED one throws LOUD (readJsonConfig) rather than
   // silently reverting the author's budgets to defaults and green-washing the very warnings they tuned.
   const c = readJsonConfig(join(root, 'spexcode.json'))?.lint ?? {}
-  const merged = { ...DEFAULT_CONFIG, ...c, altitude: { ...DEFAULT_CONFIG.altitude, ...(c.altitude ?? {}) } }
+  const merged = { ...DEFAULT_CONFIG, ...c }
   return normalizeConfig(merged)
 }
 
-// canonicalize two adopter-input footguns that would otherwise SILENTLY match ZERO files (the same failure
-// class as an unset governedRoots — a green board that governs nothing). Both are natural mistakes a non-web
-// adopter makes reading the prose, so we accept-what-they-meant rather than reject:
-//  - a LEADING DOT on an extension: the matcher is `\.(ext)$`, so a literal ".ts" becomes `\..ts$` and never
-//    matches. Strip leading dots → ["ts"] and [".ts"] both work (prose historically showed ".ts").
-//  - a testGlob with NO "/": globs anchor to the full repo-relative path, so a bare "*.test.ts" matches only
-//    ROOT-level files and leaks every nested test into coverage. A slash-less glob is a basename intent →
-//    prepend "**/" so it matches that basename at any depth (the default "**/*.test.*" already does).
+// Compile every author-facing source selector into one include-minus-exclude/test policy. In particular,
+// sourceExtensions is compatibility syntax only: it contributes include globs and never reaches discovery.
 export function normalizeConfig(cfg: LintConfig): LintConfig {
   // a mistyped enum silently reverting to the default would green-wash (or over-warn) exactly the
   // advisory the author meant to tune — same fail-loud rule as a malformed spexcode.json.
   if (cfg.scopedCodeMiss !== 'warn' && cfg.scopedCodeMiss !== 'ignore')
     throw new Error(`spexcode.json lint.scopedCodeMiss must be "warn" or "ignore", got ${JSON.stringify(cfg.scopedCodeMiss)}`)
   const dedot = (xs: string[]) => xs.map((x) => x.replace(/^\.+/, ''))
+  const anyDepth = (xs: string[]) => xs.map((g) => (g.includes('/') ? g : `**/${g}`))
+  const extensions = cfg.sourceExtensions === null ? null : dedot(cfg.sourceExtensions)
+  const includes = cfg.sourceIncludeGlobs === null && extensions === null
+    ? null
+    : [...new Set([...anyDepth(cfg.sourceIncludeGlobs ?? []), ...(extensions ?? []).map((ext) => `**/*.${ext}`)])]
   return {
     ...cfg,
-    sourceExtensions: dedot(cfg.sourceExtensions),
-    identifierExtensions: dedot(cfg.identifierExtensions),
-    testGlobs: cfg.testGlobs.map((g) => (g.includes('/') ? g : `**/${g}`)),
+    sourceIncludeGlobs: includes,
+    sourceExcludeGlobs: anyDepth(cfg.sourceExcludeGlobs),
+    sourceExtensions: extensions,
+    testGlobs: anyDepth(cfg.testGlobs),
   }
 }
 
-// the source-file matcher, built from the configurable `sourceExtensions` knob. Coverage uses it to decide
-// which tracked files must be governed; eval lint's `eval-coverage` reuses THE SAME knob so ONE setting
-// defines "source" for both coverage axes — a non-web project (Rust/Go/Python .rs/.go/.py) sets it once and
-// both the coverage warning and the loss-signal blind-spot check follow, with no second web-only allowlist.
-export const sourceExtRe = (extensions: string[]) => new RegExp(`\\.(${extensions.join('|')})$`)
-
-// a minimal glob → RegExp anchored to the full repo-relative path: `**` = any dirs, `*` = within a segment.
-function globToRe(glob: string): RegExp {
-  const body = glob.split(/(\*\*\/|\*\*|\*|\?)/).map((seg) => {
-    if (seg === '**/') return '(?:.*/)?'
-    if (seg === '**') return '.*'
-    if (seg === '*') return '[^/]*'
-    if (seg === '?') return '[^/]'
-    return seg.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  }).join('')
-  return new RegExp(`^${body}$`)
-}
-
-// coverage enumerates source via GIT-TRACKED files (`git ls-files`, through git() which strips the hook's
-// GIT_DIR), NOT a raw fs walk. Tracked-only auto-excludes node_modules + build output (gitignored), nested
-// or linked worktrees + submodules (a separate index), `.git`, and anything untracked — so governedRoots
-// '.' means "all tracked source" with no fs explosion and no hand-maintained skip list (git IS the database).
-// Test files drop per cfg.testGlobs (default *.test.*; set [] to govern tests too).
-function trackedSourceFiles(root: string, roots: string[], src: RegExp, testGlobs: string[]): string[] {
-  const testRes = testGlobs.map(globToRe)
-  const out = new Set<string>()
-  for (const r of roots) {
-    let listed = ''
-    try { listed = git(['-C', root, 'ls-files', '-z', '--', r]) } catch { continue }
-    for (const f of listed.split('\0')) {
-      if (!f || !src.test(f) || testRes.some((re) => re.test(f))) continue
-      out.add(f)
-    }
-  }
-  return [...out]
-}
-
-// code-identifier signals: camelCase | snake_case | foo( | `backticked` | /a/path.ext | bare file.ext. Only
-// the bare-filename branch needs the extension allowlist (config, so a non-TS project recognises its own
-// sources) — without it a bare `word.word` would match ordinary prose like "e.g".
-function identRe(extensions: string[]): RegExp {
-  const ext = extensions.join('|')
-  return new RegExp(`[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*|\\b[a-z]+_[a-z0-9_]+\\b|\\b\\w+\\(|\`[^\`]+\`|\\/[\\w./-]+\\.\\w+|\\b[\\w-]+\\.(${ext})\\b`, 'g')
-}
-// step-by-step how-to phrasing: numbered steps, or sequencing connectives that walk through mechanics.
-const STEP_LINE = /^\s*(\d+[.)]\s|[-*]\s*(first|then|next|finally)\b)|(^|[,;]\s*)(first|then|next|finally),/i
-// returns a one-line reason naming whichever low-altitude proxy(ies) tripped (length / identifier density /
-// step-by-step), or null when the body is at altitude.
-function altitude(body: string, cfg: LintConfig, ident: RegExp): string | null {
-  const a = cfg.altitude
-  const lines = body.split('\n')
-  const nb = lines.filter((l) => l.trim()).length
-  const chars = body.length
-  // identifiers and step phrasing are read from PROSE only — a fenced code sample is acknowledged code,
-  // not low-altitude narration, so it inflates length but not density.
-  let inFence = false, signals = 0, steps = 0
-  for (const l of lines) {
-    if (/^\s*```/.test(l)) { inFence = !inFence; continue }
-    if (inFence || !l.trim()) continue
-    signals += l.match(ident)?.length ?? 0
-    if (STEP_LINE.test(l)) steps++
-  }
-  const density = signals / Math.max(1, nb)
-  const why: string[] = []
-  if (nb > a.lineBudget || chars > a.charBudget) why.push(`${nb} non-blank lines / ${chars} chars over budget (${a.lineBudget}/${a.charBudget})`)
-  if (nb > a.sizeable && density > a.dense) why.push(`code-identifier density ${density.toFixed(2)}/line over ${a.dense}`)
-  if (nb > a.sizeable && steps >= a.steps) why.push(`${steps} step-by-step how-to lines`)
-  return why.length ? why.join('; ') : null
-}
-
 export async function specLint(): Promise<Finding[]> {
   const root = repoRoot()
   const cfg = loadConfig(root)
-  const ident = identRe(cfg.identifierExtensions)
-  const srcRe = sourceExtRe(cfg.sourceExtensions)
+  const governed = trackedSourceFiles(root, cfg.governedRoots, cfg)
   const specs = await loadSpecs()
   const out: Finding[] = []
 
@@ -252,33 +180,9 @@ export async function specLint(): Promise<Finding[]> {
     }
   }
 
-  // altitude: a body that re-narrates mechanics instead of stating contract/intent (WARN — soft budget).
-  for (const s of specs) {
-    const why = altitude(s.body, cfg, ident)
-    if (why) out.push({ level: 'warn', rule: 'altitude', spec: s.id, msg: `'${s.id}' body reads low-altitude (mechanics, not contract): ${why}` })
-  }
-
-  // breadth: a node with too many DIRECT children is altitude's structural twin — splitting a node to pass
-  // altitude shouldn't just relocate the sprawl into a wide flat fan-out (WARN — soft, advisory). Children
-  // are derived from the parent links loadSpecs already computes; no explicit child array to keep in sync.
-  const childCount = new Map<string, number>()
-  for (const s of specs) if (s.parent) childCount.set(s.parent, (childCount.get(s.parent) ?? 0) + 1)
-  for (const s of specs) {
-    const n = childCount.get(s.id) ?? 0
-    if (n >= cfg.maxChildren)
-      out.push({ level: 'warn', rule: 'breadth', spec: s.id, msg: `'${s.id}' has ${n} direct child nodes (>= ${cfg.maxChildren}) — is an intermediate grouping layer missing? (a flat list of genuine peers is sometimes right — ignore if so)` })
-  }
-
   // coverage: every governed source file must be claimed by at least one spec.
-  const governed = trackedSourceFiles(root, cfg.governedRoots, srcRe, cfg.testGlobs)
-  // no governed source found at all → make it a SELF-EXPLANATORY repair entrypoint, not a dead end. The two
-  // knobs governing this are BOTH web-tuned by default (extensions ts/tsx/js/jsx; roots this repo's own dirs),
-  // so a non-web adopter (Rust/Go/Python) hits zero source two ways: right dir but wrong extension, or an
-  // unset root. Naming BOTH knobs, echoing their CURRENT values (so the mismatch is visible — "searching .ts
-  // in a .py tree"), and stating the `lint`-key nesting (a top-level key silently no-ops) turns the warning
-  // into the fix. Concrete non-web extension examples so the repair is copy-pasteable, not a schema hunt.
   if (governed.length === 0)
-    out.push({ level: 'warn', rule: 'coverage', msg: `governing NOTHING — 0 source files matched extensions [${cfg.sourceExtensions.join(', ')}] under governedRoots [${cfg.governedRoots.join(', ')}]. Both knobs live under the "lint" key in spexcode.json (a top-level key is ignored): set governedRoots to your source dir(s) (e.g. ["src"]) AND sourceExtensions to your language (e.g. ["rs"] / ["go"] / ["py"]).` })
+    out.push({ level: 'warn', rule: 'coverage', msg: `governing NOTHING — 0 source candidates under governedRoots [${cfg.governedRoots.join(', ')}]; ${sourcePolicyDescription(cfg)}. Repair these knobs under the "lint" key in spexcode.json (top-level keys are ignored): governedRoots, sourceIncludeGlobs, sourceExcludeGlobs, testGlobs; sourceExtensions remains compatibility shorthand for include globs.` })
   for (const f of governed)
     if (!claimed.has(f)) out.push({ level: 'warn', rule: 'coverage', file: f, msg: `no spec governs: ${f}` })
 

package/spec-cli/src/login-page.ts

@@ -1,8 +1,15 @@
 // @@@ login page - the gateway's gate is a DESIGNED page, not the browser's Basic-auth dialog (which can't
 // be styled and feels like a 1998 intranet). Self-contained: inline CSS + SVG, zero external assets, so it
 // renders before anything is authorised. Dark, calm, a single password field; an error state when the
-// password is wrong. The form POSTs to /login (same-origin), which mints the auth cookie and redirects.
-export function loginPage(error = false): string {
+// password is wrong. The form POSTs to `action` (same-origin), which mints the auth cookie and redirects.
+// One page serves every gate: the single-project gateway's /login (the defaults) and the multi-project
+// hub's admin + per-project logins ([[gateway-hub]] passes action/heading/sub). Every option is
+// HTML-escaped at this sink — projectIds are path-derived, attacker-influencable strings.
+export function loginPage(error = false, opts: { action?: string; heading?: string; sub?: string } = {}): string {
+  const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!))
+  const action = esc(opts.action ?? '/login')
+  const heading = esc(opts.heading ?? 'Restricted access')
+  const sub = esc(opts.sub ?? 'This is a private agent workspace. Enter the access password to continue.')
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -58,7 +65,7 @@ export function loginPage(error = false): string {
 </style>
 </head>
 <body>
-  <form class="card" method="POST" action="/login" autocomplete="off">
+  <form class="card" method="POST" action="${action}" autocomplete="off">
     <div class="mark">
       <svg viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
         <rect x="2" y="2" width="28" height="28" rx="8" fill="#0e1626" stroke="#3f6fe0" stroke-opacity="0.5"/>
@@ -66,8 +73,8 @@ export function loginPage(error = false): string {
       </svg>
       <b>Spex<span>Code</span></b>
     </div>
-    <h1>Restricted access</h1>
-    <p class="sub">This is a private agent workspace. Enter the access password to continue.</p>
+    <h1>${heading}</h1>
+    <p class="sub">${sub}</p>
     ${error ? '<div class="err">Incorrect password — try again.</div>' : ''}
     <label for="password">Password</label>
     <input id="password" name="password" type="password" autofocus required placeholder="••••••••••">

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))
+    },
+  }
+}
+`
+}