spexcode 0.4.1 → 0.5.0

package/spec-cli/src/init.ts

@@ -3,7 +3,7 @@ import { join, resolve, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
-import { resolveHarnessTargets } from './harness-select.js'
+import { resolveHarnessTargets, parseHarnessFlag, NATIVE_HARNESS_IDS } from './harness-select.js'
 
 // this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
 // launch paths use, never a hardcoded repo path (so a relocated/installed package still finds its data).
@@ -54,7 +54,7 @@ function resolveHooksDir(dir: string): string | null {
   }
 }
 
-export async function specInit(targetArg: string | undefined, presetArg?: string): Promise<void> {
+export async function specInit(targetArg: string | undefined, presetArg?: string, harnessArg?: string): Promise<void> {
   const targetDir = resolve(targetArg ?? process.cwd())
 
   // the preset the NEW adopter gets — `--preset <name>` wins, else an existing target spexcode.json's
@@ -78,6 +78,24 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     process.exit(1)
   }
 
+  // the harness DELIVERY TARGET set ([[harness-select]]) is a REQUIRED, explicit choice — `--harness <ids>`
+  // stamps it into spexcode.json; absent the flag, a pre-existing explicit `harnesses` field IS the choice.
+  // Neither → abort BEFORE writing anything: with many harnesses, a silent "deliver to all" would litter the
+  // adopter's tree (and global tool configs) with artifacts for harnesses they never installed. Legality
+  // (unknown ids, plugin exclusivity, empty set) fails loud here too, not as a soft materialize warning.
+  const flagRaw = (harnessArg ?? '').trim() ? parseHarnessFlag(harnessArg!.trim()) : null
+  const chosenHarnesses = flagRaw ?? readConfig(targetDir).harnesses ?? null
+  if (chosenHarnesses === null) {
+    console.error(`spex init: --harness is required — name the harness(es) this repo delivers into, e.g. \`spex init --harness claude\`. Known native ids: ${NATIVE_HARNESS_IDS.join(', ')} (comma-separate several; a plugin bundle: --harness plugin:<folder>). A pre-existing spexcode.json "harnesses" field also satisfies this.`)
+    process.exit(1)
+  }
+  try {
+    resolveHarnessTargets(chosenHarnesses)
+  } catch (e) {
+    console.error(`spex init: ${(e as Error).message}`)
+    process.exit(1)
+  }
+
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true })
   console.log(`spex init → ${targetDir}`)
 
@@ -100,27 +118,35 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     }
   }
 
-  // 1b. plant a starter spexcode.json (the lint/layout knob). The success message reports the value the
-  // template ACTUALLY ships (read from the planted file, never restated as a string literal here — the two
-  // once drifted: the message claimed ["src"] while the template seeded ["."]).
+  // 1b. plant a starter spexcode.json (the lint/layout knob) carrying the CHOSEN `harnesses` set. The
+  // template ships launchers for every native harness; seeding keeps only the SELECTED ones (a launcher for
+  // a tool the adopter didn't pick is exactly the litter --harness exists to prevent) — a plugin-only
+  // selection keeps them all, since the bundle serves the HOST agent while dispatched sessions still need a
+  // launcher. The success message reports values read back from the planted file, never restated literals.
   const cfgDest = join(targetDir, 'spexcode.json')
+  const nativeChosen = (chosenHarnesses as unknown[]).filter((m): m is string => typeof m === 'string')
   if (existsSync(cfgDest)) {
-    console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched.`)
+    if (flagRaw) {
+      // an explicit --harness on a re-init is a deliberate command: restamp THAT field, touch nothing else.
+      const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
+      cfg.harnesses = flagRaw
+      writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
+      console.log(`✓ stamped "harnesses": ${JSON.stringify(flagRaw)} into the existing spexcode.json (other fields untouched)`)
+    } else {
+      console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched (harnesses: ${JSON.stringify(chosenHarnesses)}).`)
+    }
   } else {
-    copyFileSync(join(TEMPLATES, 'spexcode.json'), cfgDest)
+    const cfg = (readJsonConfig(join(TEMPLATES, 'spexcode.json')) ?? {}) as Record<string, any>
+    cfg.harnesses = chosenHarnesses
+    if (nativeChosen.length && cfg.sessions?.launchers) {
+      cfg.sessions.launchers = Object.fromEntries(
+        Object.entries(cfg.sessions.launchers as Record<string, { harness?: string }>).filter(([, l]) => nativeChosen.includes(l.harness ?? 'claude')))
+      const names = Object.keys(cfg.sessions.launchers)
+      if (names.length) cfg.sessions.defaultLauncher = names[0]
+    }
+    writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
     const roots = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
-    console.log(`✓ planted spexcode.json — lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded); curate explicit roots later if you want a narrower graph`)
-  }
-
-  // validate the harness DELIVERY TARGET set ([[harness-select]]) up front: a bad `harnesses` set (plugin +
-  // native, or a plugin with no folder) must fail LOUD here, not be silently swallowed by the materialize
-  // try/catch below. A fresh starter spexcode.json omits the field (defaults to all natives), so this only
-  // bites a hand-edited or re-init'd config — exactly where a clear error belongs.
-  try {
-    resolveHarnessTargets(readConfig(targetDir).harnesses)
-  } catch (e) {
-    console.error(`spex init: ${(e as Error).message}`)
-    process.exit(1)
+    console.log(`✓ planted spexcode.json — harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
   }
 
   // 2. install the git hooks: templates/hooks/* -> <repo>/<common-git-dir>/hooks/* (skip any that exist).
@@ -145,18 +171,20 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     if (installed.length) console.log(`✓ installed git hooks (${installed.join(', ')}) → ${hooksDir}`)
   }
 
-  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched claude/codex works with zero further
-  // steps: the hook manifest (in the GLOBAL per-project store, not the worktree), the AGENTS.md/CLAUDE.md
-  // <spexcode> contract block (user content preserved), the .claude/.codex shims, and the Codex trust (global,
-  // scoped) so codex self-launch is prompt-free. Runs with cwd = the target so the loaders read the just-seeded
+  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched harness works with zero further
+  // steps. Runs with cwd = the target so the loaders read the just-seeded
   // .plugins. Idempotent — the planted git hooks (pre-commit/post-checkout/post-merge) keep it fresh
   // thereafter on the git-native anchors ([[commit-surgery]]); no harness event ever triggers a materialize.
   const prevCwd = process.cwd()
   try {
     process.chdir(targetDir)
     const { materialize } = await import('./materialize.js')
-    materialize(targetDir)
-    console.log('✓ materialized harness artifacts (global hook manifest, AGENTS.md/CLAUDE.md block, harness shims, Codex trust)')
+    const result = materialize(targetDir)
+    const display = (path: string) => {
+      const local = relative(targetDir, path)
+      return local && local !== '..' && !local.startsWith('../') && !local.startsWith('..\\') ? local : path
+    }
+    console.log(`✓ materialized harness artifacts (${result.planted.map((a) => `${a.kind}: ${display(a.path)}`).join(', ')})`)
   } catch (e) {
     console.warn(`• materialize skipped (${(e as Error).message}) — run \`spex materialize\` once the packages are installed.`)
   } finally {

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,14 @@ 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]])
+    showHeadlessLaunchers?: boolean // include headless harness profiles in the dashboard New Session picker (default false; [[launcher-visibility]])
   }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)
@@ -34,7 +35,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})`