spexcode 0.1.5 → 0.2.0

package/spec-cli/src/issues.ts

@@ -0,0 +1,250 @@
+// @@@ issues - ONE Issue object over every store ([[issues]]). An Issue is a recorded concern bound to
+// spec node(s), carrying its OWN lifecycle, living beside the graph and never as node state. WHERE it is
+// stored — the local git store ([[local-issues]]) or a remote forge (spec-forge) — is a per-issue property
+// (`store`), not a project mode: a project holds both at once, mixed. This module owns the core type, the
+// forge→Issue translation (the ONLY place a host's node-naming conventions become `nodes[]` — platform
+// differences stay at the adapter boundary), the merged read every surface consumes (CLI `spex issues`,
+// GET /api/issues, the board fold), the STORE-ROUTED reply/close verbs, and the CLI itself. Content writes are
+// owned per store: local ones live in localIssues.ts; a forge write goes through the driver's write verbs
+// (createIssue/createComment/closeIssue — the driver stays the only network toucher; the tracer stays read-only).
+import type { ForgeIssue, ForgePR } from '../../spec-forge/src/port.js'
+import { resolveLinks } from '../../spec-forge/src/links.js'
+import { loadLocalIssues, loadOne, reply, resolve, issuesEnabled, replyLocalIssue, runIssueWrite, ISSUE_WRITE_SUBS } from './localIssues.js'
+import { dispatchMentions, type DispatchOutcome, type LoopIn } from './mentions.js'
+import { envSessionId } from './layout.js'
+import { loadSpecsLite } from './specs.js'
+
+// A Reply is a plain thread post `{by, at, body}` — OR, when it carries the fields below, a REMARK
+// ([[remark-substrate]]): a reply that pins a RESOLVABLE concern to its host (an issue or a scenario). A
+// remark is not a new record type: it is a reply with the mutable `resolved` bit, a stable `rid` (so it is
+// addressable across retracts), and the `targetCodeSha` it was authored against (the reading it judges). A
+// plain reply omits them all and parses/serializes unchanged (backward compatible). `isRemark` = rid set.
+export type Reply = {
+  by: string
+  at: string
+  body: string
+  rid?: string            // stable per-remark id; a reply is a remark iff this is set. Ref: `<thread-id>#<rid>`
+  targetCodeSha?: string  // the reading/codeSha the remark was authored against (worktree HEAD by default)
+  resolved?: boolean      // the ONE mutable teeth bit — false at author, true after a deliberate `spex resolve`
+  resolvedAt?: string
+  resolvedBy?: string
+}
+export const isRemark = (r: Reply): boolean => r.rid !== undefined
+export type Issue = {
+  id: string
+  store: string      // 'local' | a forge host ('github') — the adapter that holds it
+  concern: string
+  by: string
+  status: string     // its own lifecycle: local open|accepted|rejected|landed; forge open|closed
+  nodes: string[]
+  signers: string[]
+  created: string
+  body: string
+  replies: Reply[]
+  evidence: string[] // yatsu content-addressed blob hashes — the typed cross-node finding reference
+  url?: string       // a forge permalink; a local issue has none
+}
+
+export type ForgeState = { issues: ForgeIssue[]; prs: ForgePR[] }
+export type ForgeSlice = { host: string; state: ForgeState }
+
+// ── the (node, scenario) ↔ eval-thread join ([[remark-teeth]]) ────────────────────────────────────────
+// A scenario's remark track lives ONCE in trunk, keyed by its `eval: <node> · <scenario>` concern thread
+// (R4). This is the ONE server-side overlay: the same join the dashboard's Annotator used to compute
+// client-side (concern-key matching), lifted here so the CLI, the board fold, the session proof, and the
+// annotator all read ONE join. It returns, per pair, the thread plus its REMARK replies (the resolvable
+// ones — a plain comment on the thread is not a remark). The teeth ([[remark-teeth]]) read the remark
+// signals; the annotator reads the thread.
+export type RemarkTrack = { threadId: string; node: string; scenario: string; thread: Issue; remarks: Reply[] }
+
+// `eval: <node> · <scenario>` — node first (never contains ' · '), then the scenario (may). One thread per
+// pair (EventDetail.jsx evalConcern / localIssues.ts resolveRemarkHost mint it), so the last write wins is fine.
+const EVAL_CONCERN_RE = /^eval: (.+?) · (.+)$/
+export const trackKey = (node: string, scenario: string): string => `${node} · ${scenario}`
+
+// an eval-remark thread is the eval scoreboard's data, NOT a drain-worthy issue (I1: a scenario-scoped
+// concern is a remark, never an issue). Its `eval: <node> · <scenario>` concern is the tell — the SAME key
+// loadEvalRemarkTracks isolates them by. The two reads are complementary over one store: mergedIssues (the
+// ISSUE surfaces) excludes these; loadEvalRemarkTracks (the EVAL surfaces) keeps only these.
+export const isEvalConcern = (concern: string): boolean => EVAL_CONCERN_RE.test(concern)
+
+// read the whole local store ONCE and split the eval-concern threads out (directive 3): trunk-scoped,
+// read-time, no branch write. A remark whose scenario no longer exists still LOADS here (it just keys a pair
+// no reading joins) — never a crash, per [[remark-teeth]]'s dangling clause.
+export function loadEvalRemarkTracks(): Map<string, RemarkTrack> {
+  const out = new Map<string, RemarkTrack>()
+  for (const t of loadLocalIssues()) {
+    const m = EVAL_CONCERN_RE.exec(t.concern)
+    if (!m) continue
+    const node = m[1].trim(), scenario = m[2].trim()
+    out.set(trackKey(node, scenario), { threadId: t.id, node, scenario, thread: t, remarks: t.replies.filter(isRemark) })
+  }
+  return out
+}
+
+// forge → Issue, at the adapter boundary: the host's node-naming conventions (`Spec:` body marker +
+// transitive PR links — spec-forge links.ts) become plain `nodes[]` HERE, validated against the real node
+// ids, so nothing downstream ever knows a marker existed. Every raw issue maps — linked or not — because
+// the merged list is the whole set, not just the per-node view.
+export function fromForge(slice: ForgeSlice, nodeIds: string[]): Issue[] {
+  const nodesByNumber = new Map<number, string[]>()
+  for (const link of resolveLinks(slice.state.issues, slice.state.prs, nodeIds))
+    for (const i of link.issues) {
+      const arr = nodesByNumber.get(i.number) ?? []
+      arr.push(link.node)
+      nodesByNumber.set(i.number, arr)
+    }
+  return slice.state.issues.map((i) => ({
+    id: `${slice.host}#${i.number}`,
+    store: slice.host,
+    concern: i.title,
+    by: i.author,
+    status: (i.state || '').toLowerCase(),
+    nodes: nodesByNumber.get(i.number) ?? [],
+    signers: [],
+    created: i.createdAt,
+    body: i.body,
+    // the forge comments ARE the thread — the same Reply shape a local thread carries, so nothing
+    // downstream renders two kinds of discussion.
+    replies: (i.comments ?? []).map((c) => ({ by: c.author, at: c.createdAt, body: c.body })),
+    evidence: [],
+    url: i.url,
+  }))
+}
+
+// the one merged read: local issue-store threads + the caller-supplied forge slice, ONE time line — the
+// stores are the same abstraction, so they interleave by creation time, newest first (never
+// store-grouped; a reader's eye lands on what just happened, whatever store holds it). CALLERS own
+// freshness — the server passes the resident cache's state (instant, background reconcile), the CLI a
+// live pull — so the merge itself stays pure. Eval-remark threads are SPLIT OUT read-time (isEvalConcern):
+// they are the eval scoreboard's data, not issues, so every issue surface this feeds — the Threads tab, the
+// board issue badge, the `spex issues` drain — is free of them by construction (they reach the EVAL side
+// through loadEvalRemarkTracks / the reading overlay instead).
+export function mergedIssues(forge: ForgeSlice | null, nodeIds: string[]): Issue[] {
+  const remote = forge ? fromForge(forge, nodeIds) : []
+  return [...loadLocalIssues(), ...remote]
+    .filter((i) => !isEvalConcern(i.concern))
+    .sort((a, b) => b.created.localeCompare(a.created))
+}
+
+// @@@ promote - the ONE cross-store verb ([[issues]]): a local concern that outgrew the repo moves to the
+// forge as one recorded action. The forge issue is composed from the thread itself — concern → title;
+// body + the `Spec: <nodes>` marker (the round-trip: the existing tracer read links it straight back to
+// the same nodes, no new linking code) + the evidence hashes + a provenance footer — and created through
+// the driver (the only network toucher). ORDER makes failure safe: create the forge issue FIRST; only
+// then close the local thread out (a reply carrying the permalink, then resolve `landed`) — an
+// unreachable forge throws with the local thread untouched, and only an `open` thread promotes.
+export async function promote(id: string): Promise<{ url: string; number: number; host: string }> {
+  const t = loadOne(id)
+  if (t.status !== 'open') throw new Error(`'${id}' is ${t.status} — only an open local issue promotes`)
+  const { githubDriver } = await import('../../spec-forge/src/drivers/github.js')
+  const body = [
+    t.body,
+    t.nodes.length ? `\nSpec: ${t.nodes.join(', ')}` : '',
+    t.evidence.length ? `\nEvidence: ${t.evidence.join(', ')} (yatsu blob hashes)` : '',
+    `\n---\nPromoted from the local issue \`${id}\` (opened by ${t.by} @ ${t.created}; promoted by ${envSessionId() || 'unknown'}).`,
+  ].filter(Boolean).join('\n')
+  const { number, url } = await githubDriver.createIssue({ title: t.concern, body })
+  reply(id, `promoted to the forge: ${url}`)
+  resolve(id, 'landed')
+  return { url, number, host: githubDriver.host }
+}
+
+// @@@ replyIssue - ONE reply verb, store-routed ([[issues]]): store is a property of the issue, so
+// replying doesn't fork by surface — a local id goes through the store's committed write (localIssues.ts,
+// unchanged), a forge id (`<host>#<n>`) posts a REAL comment through the driver's createComment (the same
+// seam discipline as promotion — no second network call-site). Either way the reply TEXT then dispatches
+// its @-mentions (mentions.ts is store-agnostic: the mention fires on the words, and the mention IS the
+// assign — no separate assign machinery). Callers own freshness: the server refreshes its resident forge
+// slice after a forge write; the CLI's next read is a live pull anyway.
+export async function replyIssue(
+  id: string,
+  body: string,
+  opts: { author?: string; node?: string | null; evidence?: string[] } = {},
+): Promise<{ store: string; replies?: Reply[]; url?: string; outcomes: DispatchOutcome[]; loopIn: LoopIn | null }> {
+  const author = opts.author || envSessionId() || 'unknown'
+  const forge = /^([A-Za-z0-9-]+)#(\d+)$/.exec(id)
+  if (!forge) {
+    // evidence hashes accrue onto the local thread's typed evidence[] (a forge thread has no such field —
+    // an annotation's frame rides its comment body's image link there, the driver the only network toucher);
+    // replyLocalIssue also loops in the thread's originator ([[mentions]]) after the @-dispatch.
+    const { thread, outcomes, loopIn } = await replyLocalIssue(id, body, author, opts.evidence)
+    return { store: 'local', replies: thread.replies, outcomes, loopIn }
+  }
+  const { githubDriver } = await import('../../spec-forge/src/drivers/github.js')
+  if (forge[1] !== githubDriver.host) throw new Error(`unknown forge host '${forge[1]}' — this repo's driver is '${githubDriver.host}'`)
+  const { url } = await githubDriver.createComment({ number: parseInt(forge[2], 10), body })
+  const outcomes = await dispatchMentions(body, { threadId: id, node: opts.node ?? null, author })
+  // a forge issue's author is a github login, not a live session → no reachable originator to loop in (silent).
+  return { store: forge[1], url, outcomes, loopIn: null }
+}
+
+// @@@ closeIssue - ONE lifecycle close over every store ([[issues]]): the issue owns its status, so the
+// dashboard Close button routes by id and never writes node state. Local closes resolve the local thread
+// `landed`; forge closes call the driver's close verb and let the forced read-back reveal the closed state.
+export async function closeIssue(id: string): Promise<{ store: string; status: string; url?: string }> {
+  const forge = /^([A-Za-z0-9-]+)#(\d+)$/.exec(id)
+  if (!forge) return { store: 'local', status: resolve(id, 'landed') }
+  const { githubDriver } = await import('../../spec-forge/src/drivers/github.js')
+  if (forge[1] !== githubDriver.host) throw new Error(`unknown forge host '${forge[1]}' — this repo's driver is '${githubDriver.host}'`)
+  const { url } = await githubDriver.closeIssue({ number: parseInt(forge[2], 10) })
+  return { store: forge[1], status: 'closed', url }
+}
+
+// ───────────────────────── CLI ─────────────────────────
+const fl = (args: string[], name: string): string | undefined => {
+  const i = args.indexOf(`--${name}`)
+  return i >= 0 ? args[i + 1] : undefined
+}
+const hasFlag = (args: string[], name: string) => args.includes(`--${name}`)
+
+// `spex issues …` — the ONE issues surface. Bare (with filters) it is THE read over every store: the
+// drain view a supervisor/human works from, `[--node id] [--store local|<host>] [--all] [--json]`. A write
+// first-positional (open|reply|sign|resolve|on|off|status|nudge — localIssues.ts) routes to the store's
+// write verbs; `promote` is the one cross-store verb. The list imposes NO salience ranking — recurrence
+// (signers, replies) is a signal the drain WEIGHS by judgment, never an automatic priority order. The forge
+// slice is a LIVE pull; an unreachable forge degrades loudly to local-only (one stderr note) — local
+// reading never hostages on a network.
+export async function runIssues(args: string[]): Promise<number> {
+  if (ISSUE_WRITE_SUBS.has(args[0])) return runIssueWrite(args)
+  if (args[0] === 'promote') {
+    const id = args[1]
+    if (!id || id.startsWith('--')) { console.error('usage: spex issues promote <local-issue-id>'); return 2 }
+    try {
+      const r = await promote(id)
+      console.log(`promoted '${id}' → ${r.host}#${r.number}  ${r.url}\n  local thread resolved landed (permalink recorded in its reply trail)`)
+      return 0
+    } catch (e) {
+      console.error(`spex issues promote: ${e instanceof Error ? e.message : e}`)
+      return 1
+    }
+  }
+  const nodeIds = loadSpecsLite().map((s) => s.id)
+  let forge: ForgeSlice | null = null
+  try {
+    const { githubDriver } = await import('../../spec-forge/src/drivers/github.js')
+    const [issues, prs] = await Promise.all([githubDriver.listIssues(), githubDriver.listPRs()])
+    forge = { host: githubDriver.host, state: { issues, prs } }
+  } catch (e) {
+    console.error(`spex issues: forge unreachable — listing local only (${e instanceof Error ? e.message.split('\n')[0] : e})`)
+  }
+  let issues = mergedIssues(forge, nodeIds)
+  const node = fl(args, 'node')
+  const store = fl(args, 'store')
+  if (node) issues = issues.filter((p) => p.nodes.includes(node))
+  if (store) issues = issues.filter((p) => p.store === store)
+  if (!hasFlag(args, 'all')) issues = issues.filter((p) => p.status === 'open')
+  if (hasFlag(args, 'json')) { console.log(JSON.stringify(issues, null, 2)); return 0 }
+  if (!issues.length) { console.log(node ? `no issues for node '${node}'` : 'no open issues'); return 0 }
+  console.log(`issues — ${issues.length} ${hasFlag(args, 'all') ? 'total' : 'open'}${store ? ` in '${store}'` : ''}${node ? ` for '${node}'` : ''}\n`)
+  for (const p of issues) {
+    const tags = [p.store, p.status !== 'open' ? `[${p.status}]` : '', p.nodes.length ? `re: ${p.nodes.join(', ')}` : '', p.by ? `by ${p.by}` : ''].filter(Boolean).join('  ·  ')
+    console.log(`• ${p.concern}  [${p.id}]`)
+    console.log(`    ${tags}`)
+    if (p.signers.length) console.log(`    +${p.signers.length} signed: ${p.signers.join(', ')}`)
+    if (p.replies.length) console.log(`    ${p.replies.length} reply(ies) in thread`)
+    if (p.url) console.log(`    ${p.url}`)
+  }
+  if (!issuesEnabled()) console.log('\n(the issues workflow is OFF — `spex issues on` to re-enable writes/nudges)')
+  return 0
+}

package/spec-cli/src/layout.ts

@@ -9,15 +9,32 @@ type Config = {
   main?: string                    // path to the source-of-truth checkout (default: the `main` worktree)
   mainBranch?: string              // source-of-truth BRANCH worktrees fork from (default: auto-detected — see mainBranch())
   branchPrefix?: string            // how a branch names its node (default: "node/")
+  preset?: string                  // the SELECTED init preset — which cumulative .config tier `spex init` seeds (default 'default'; seed-time only, no launcher gate; read by init.ts; see [[init-preset]])
+  // PRIVATE-OVERLAY mode ([[private-overlay]]) — belongs in the gitignored spexcode.local.json, NEVER the
+  // committed spexcode.json. When true, `spex materialize` leaves ZERO trace in the host's TRACKED files /
+  // shared history: the managed ignore entries (incl .spec + spexcode.json, which the DEFAULT mode commits —
+  // "git is the database") go to the per-clone `.git/info/exclude`, and any host-tracked contract file
+  // (CLAUDE.md/AGENTS.md) the system block folds into is marked `skip-worktree` so that block never stages.
+  // The dogfood becomes invisible to collaborators, trading away git-derived spec version history ([[source-of-truth]]).
+  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.
+  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
   }
   sessions?: {
-    maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 6; see sessions.ts maxActive)
-    claudeCmd?: string             // worker launcher for Claude (default 'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides. A host-specific ABS path belongs in the gitignored spexcode.local.json, not here.
-    codexCmd?: string              // worker launcher for Codex (default 'codex --yolo'); env SPEXCODE_CODEX_CMD overrides. Same host-path rule.
+    maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)
+    claudeCmd?: string             // the UNNAMED default worker launcher for Claude (default 'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides. A host-specific ABS path belongs in the gitignored spexcode.local.json, not here.
+    codexCmd?: string              // the UNNAMED default worker launcher for Codex (default 'codex --yolo'); env SPEXCODE_CODEX_CMD overrides. Same host-path rule.
+    // named launcher profiles: a session picks ONE by name at create time ([[launcher-select]]), fixing both
+    // its harness AND its exact launch command; the chosen NAME is persisted on the record so resume reuses the
+    // same auth. `harness` defaults to 'claude'. Host-specific `cmd`s (abs wrapper paths) belong in the
+    // gitignored spexcode.local.json — the name is portable, the cmd is a machine fact.
+    launchers?: { [name: string]: { harness?: 'claude' | 'codex'; cmd: string } }
+    defaultLauncher?: string       // the launcher a create with no explicit --launcher/dropdown pick uses (else the unnamed claudeCmd/codexCmd path)
   }
   serve?: {
     // public-exposure config for `spex serve --public` (resolved gateway-side; see [[public-mode]] / gateway.ts).
@@ -28,11 +45,15 @@ type Config = {
       tls?: { cert?: string; key?: string }   // PATHS to your own cert/key; omit for a cached self-signed default
     }
   }
+  issues?: {
+    enabled?: boolean                // the [[local-issues]] issues-workflow on/off switch (default ON). OFF silences the post-merge nudge + hides the dashboard view; flip with `spex issues on|off`. (Pre-rename `proposals.enabled` still reads — localIssues.ts issuesEnabled.)
+  }
 }
 // the resolved LAYOUT convention — main/mainBranch/branchPrefix filled to defaults. `dashboard`, `sessions`,
-// and `serve` are frontend/runtime concerns (read separately via readConfig; see api-endpoint / sessions.ts
-// maxActive / gateway.ts), NOT layout fields, so they stay out of the convention rather than forcing a default.
-type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'serve'>>
+// `serve`, `harnesses`, and `preset` are frontend/runtime/policy concerns (read separately via readConfig —
+// preset by init.ts at seed time, harnesses by [[harness-select]]; see api-endpoint / sessions.ts maxActive /
+// gateway.ts), NOT layout fields, so they stay out of the convention rather than forcing a default.
+type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'private'>>
 
 export type Worktree = {
   path: string; branch: string | null; node: string | null
@@ -41,17 +62,26 @@ export type Worktree = {
 }
 export type Layout = { main: string; convention: Convention; worktrees: Worktree[] }
 
-function readJsonOr(p: string): any {
+// Read an OPTIONAL JSON config file. An ABSENT file is the legitimate default (return {}); a
+// PRESENT-but-malformed one is a user error we must NOT swallow — a typo would otherwise silently
+// drop every tuned setting the file holds (lint budgets, launchers, layout) and revert to defaults
+// with no diagnostic. Fail LOUD, naming the file and the parse error, so the author sees what broke.
+export function readJsonConfig(p: string): any {
   if (!existsSync(p)) return {}
-  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return {} }
+  try { return JSON.parse(readFileSync(p, 'utf8')) }
+  catch (e) {
+    const err = new Error(`malformed ${p}: ${(e as Error).message}\n  → its settings were NOT applied. Fix the JSON syntax (an absent file is a fine default; a broken one is not).`)
+    err.name = 'ConfigError'   // rendered message-only at the CLI boundary (like BackendError), not as a stack dump
+    throw err
+  }
 }
 // committed `spexcode.json` with an OPTIONAL machine-local `spexcode.local.json` layered on top (gitignored).
 // The local layer is the durable home for HOST-SPECIFIC values that must never be committed — e.g. an
 // absolute worker-launcher path (the host-path leak the repo otherwise warns against). Precedence per field:
 // local over committed; an env var (e.g. SPEXCODE_CLAUDE_CMD) still overrides both at its read site.
 export function readConfig(root: string): Config {
-  const committed = readJsonOr(join(root, 'spexcode.json'))
-  const local = readJsonOr(join(root, 'spexcode.local.json'))
+  const committed = readJsonConfig(join(root, 'spexcode.json'))
+  const local = readJsonConfig(join(root, 'spexcode.local.json'))
   const out: any = { ...committed }
   for (const k of Object.keys(local)) {
     const b = committed[k], o = local[k]
@@ -105,13 +135,6 @@ export function spexcodeHome(): string {
 export function encodeProject(root: string): string {
   return root.replace(/[/.]/g, '-')
 }
-// the project a store groups by = the MAIN checkout root (dirname of the shared git common dir). It resolves
-// IDENTICALLY from the main checkout OR any linked worktree, so the board (running at main) and a hook
-// (running in a worktree) agree on the key — unlike `git rev-parse --show-toplevel`, which in a worktree is
-// the worktree path and would scatter a session under a per-worktree key the board never reads.
-export function projectKey(): string {
-  return encodeProject(dirname(gitCommonDir()))
-}
 // this project's per-PROJECT runtime tier — the materialized hook manifest + content-hash marker (and the
 // gate's lock) — living alongside sessions/ under the SAME global per-project dir, so NOTHING SpexCode renders
 // stays in the worktree (not even the manifest; the worktree holds only the harness-discovered CLAUDE.md/
@@ -135,18 +158,37 @@ export function sessionArtifactPath(id: string, name: string): string { return j
 // with sed and never needs jq. Read here for the overlay; sessions.ts owns the full typed read/write.
 export type RawRecord = {
   session_id: string; governed: boolean; worktree_path: string; branch: string | null
-  node: string | null; title: string | null; name: string | null
+  node: string | null; title: string | null; name: string | null; parent?: string | null
   status: string; proposal: string | null; merges: number; note: string | null
   sortkey: number | null; createdAt: number; harness?: string; harness_session_id?: string
+  launcher?: string   // the named launcher profile this session was created under ([[launcher-select]]); absent/empty → the unnamed global default
+  launch_cmd?: string // the RESOLVED base launcher command PINNED at creation, so a resume replays the EXACT launcher (and its config-dir env) that made the conversation, never a since-changed default ([[launcher-select]] resume-launcher-pin); absent → old record, fall back to the launcher name / ambient
 }
 // the agent's OWN session id from the environment — the only locator now that the record left the worktree.
-// SPEXCODE_SESSION_ID (the GOVERNED record id the launcher bakes in) wins, EXACTLY mirroring the shell hooks'
-// `hp_session_id` — this matters for codex, whose own CODEX_THREAD_ID is its un-pinnable minted id and does NOT
-// equal the governed record id, so resolving the harness var first would point a governed codex agent's own
-// `spex session …` at the wrong/nonexistent record. Else each adapter's env var (Claude CLAUDE_CODE_SESSION_ID
-// — already == the record id; Codex CODEX_THREAD_ID for a self-launched, non-governed agent). No worktree
-// fallback. (sessions.ts's `ownSessionId` delegates here; spec-yatsu reads it to resolve the current node.)
+// Three tiers, in order:
+//   (1) a harness's per-thread env var (`sessionEnvVar`) RESOLVED VIA THE ALIAS — when it lands on a governed
+//       record (directly, or through that record's `harness_session_id`), that record's SpexCode id is the
+//       answer. This MUST win: codex's design-C runs ONE shared per-project app-server whose env carries the
+//       FIRST launched session's `SPEXCODE_SESSION_ID`, and the agent's shell tool (its `spex session
+//       done/park/ask`) runs INSIDE that app-server process, so `SPEXCODE_SESSION_ID` is contaminated with the
+//       wrong session. But codex injects the ACTING thread's id into every spawned command's env as
+//       CODEX_THREAD_ID (== codex's `sessionEnvVar`), so the per-thread var aliases to the RIGHT record while
+//       the shared `SPEXCODE_SESSION_ID` does not.
+//   (2) else `SPEXCODE_SESSION_ID` (the GOVERNED record id the launcher bakes in) — the claude path and the
+//       non-shared baseline.
+//   (3) else a harness's env var RAW — a self-launched, non-governed agent's own minted id, which has no
+//       governed record to alias to (codex CODEX_THREAD_ID / claude CLAUDE_CODE_SESSION_ID). The RAW form must
+//       stay BELOW (2): an un-aliased codex thread id is not a record key, so it must never beat a real
+//       `SPEXCODE_SESSION_ID`.
+// Claude is UNCHANGED: its `sessionEnvVar` (CLAUDE_CODE_SESSION_ID) already EQUALS its record id, so tier (1)
+// resolves to that very id — the same value `SPEXCODE_SESSION_ID` would have returned; there is no shared
+// app-server to contaminate it. No worktree fallback. (sessions.ts's `ownSessionId` delegates here; spec-yatsu
+// reads it to resolve the current node.)
 export function envSessionId(): string | null {
+  for (const h of HARNESSES) {
+    const v = process.env[h.sessionEnvVar]
+    if (v && v.trim()) { const r = readAliasedRawRecord(v.trim()); if (r) return r.session_id }
+  }
   const o = process.env.SPEXCODE_SESSION_ID
   if (o && o.trim()) return o.trim()
   for (const h of HARNESSES) { const v = process.env[h.sessionEnvVar]; if (v && v.trim()) return v.trim() }
@@ -158,10 +200,10 @@ export function readRawRecord(id: string): RawRecord | null {
     return raw && typeof raw === 'object' && raw.session_id ? raw as RawRecord : null
   } catch { return null }
 }
-// resolve a possibly-ALIASED session id to its raw record. A codex hook fires from the shared per-project
-// app-server (no SPEXCODE_SESSION_ID in its env), so the id it carries is the codex THREAD id — the payload
-// session_id — not the SpexCode record id the store is keyed by. Direct id wins; else the one record that
-// captured this id as `harness_session_id` (the backend stored it at thread/start, before any tool turn).
+// resolve a possibly-ALIASED session id to its raw record. A codex hook or spawned command can carry the codex
+// THREAD id — payload session_id / CODEX_THREAD_ID — not the SpexCode record id the store is keyed by. Direct id
+// wins; else the one record that captured this id as `harness_session_id` (the backend stored it at thread/start,
+// before any tool turn).
 // Null when neither resolves. Mirrors the shell `hp_store_dir` alias grep — one resolution rule, both layers.
 export function readAliasedRawRecord(id: string): RawRecord | null {
   const direct = readRawRecord(id)

package/spec-cli/src/lint.ts

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { repoRoot, stagedFiles, git } from './git.js'
 import { loadSpecs } from './specs.js'
+import { readJsonConfig } from './layout.js'
 
 export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
 
@@ -14,6 +15,7 @@ export type LintConfig = {
   maxChildren: number        // breadth budget: warn at >= this many direct children
   driftErrorThreshold: number// commit-local gate HARD-BLOCKS a commit touching a node >= this many commits behind
   maxOwners: number          // warn when a file is governed (code:) by > this many nodes
+  scenarioTags: string[]     // the closed vocabulary a yatsu scenario's `tags:` must draw from; extend it to mint a new tag
 }
 const DEFAULT_CONFIG: LintConfig = {
   governedRoots: ['spec-dashboard/src', 'spec-cli/src'],
@@ -24,15 +26,13 @@ const DEFAULT_CONFIG: LintConfig = {
   maxChildren: 8,
   driftErrorThreshold: 3,
   maxOwners: 3,
+  scenarioTags: ['frontend-e2e', 'backend-api', 'cli', 'desktop', 'mobile'],
 }
 export function loadConfig(root: string): LintConfig {
-  try {
-    const raw = JSON.parse(readFileSync(join(root, 'spexcode.json'), 'utf8'))
-    const c = raw?.lint ?? {}
-    return { ...DEFAULT_CONFIG, ...c, altitude: { ...DEFAULT_CONFIG.altitude, ...(c.altitude ?? {}) } }
-  } catch {
-    return DEFAULT_CONFIG   // no file (or unreadable) → tuned defaults; lint is the same as before.
-  }
+  // 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 ?? {}
+  return { ...DEFAULT_CONFIG, ...c, altitude: { ...DEFAULT_CONFIG.altitude, ...(c.altitude ?? {}) } }
 }
 
 // a minimal glob → RegExp anchored to the full repo-relative path: `**` = any dirs, `*` = within a segment.
@@ -178,9 +178,11 @@ export async function specLint(): Promise<Finding[]> {
     out.push({ level: 'warn', rule: 'owners', msg: `${over.length} file(s) are governed by > ${cfg.maxOwners} nodes — each holds more separately-specified functionality than one file should. Worst: ${top}. SPLIT the file so each governor owns its own module (or merge the nodes, or give it a single foundation owner + related:).` })
   }
 
-  // drift: a governed file has commits NOT yet reflected in its spec. Rigorous by git ancestry —
-  // loadSpecs computes `driftFiles` via `git rev-list <spec's last version>..HEAD -- <file>` (see
-  // commitsSince in git.ts), so each warning is "N commit(s) ahead", not a timestamp guess.
+  // drift: a governed file has commits NOT yet reflected in its spec. Judged by true git ancestry —
+  // loadSpecs computes `driftFiles` via driftFor() over the one cached driftIndex walk (git.ts): a
+  // commit to the file counts iff it is NOT reachable from the spec's latest version (in-memory
+  // parent-edge reachability, the equivalent of `rev-list <version>..HEAD -- <file>`), never a
+  // log-position or timestamp guess.
   for (const s of specs) {
     for (const d of s.driftFiles)
       out.push({ level: 'warn', rule: 'drift', spec: s.id, file: d.file, msg: `${d.file} is ${d.behind} commit(s) ahead of spec '${s.id}' (v${s.version}) — may be stale` })

package/spec-cli/src/listen.ts

@@ -0,0 +1,28 @@
+import type { Server } from 'node:net'
+
+// @@@ listenOrExit - the shared "I own this port; if I cannot bind it, I have failed" contract for the two
+// public-port listeners: the supervisor's raw-TCP proxy (supervise.ts) and the dashboard/public gateway
+// (gateway.ts). A bind failure is the ONE thing neither may survive — it is the opposite of the keep-serving
+// process guard, which rides out transient throws once the port is already held. So instead of leaving the
+// listen error unhandled (under `serve` the supervisor's uncaughtException guard would SWALLOW it into a
+// portless zombie on a random child port; under `dashboard`, with no guard, it would crash with a raw stack),
+// we attach one handler that fails loudly the same way on both surfaces: name the busy port and the repair,
+// reap any child booted for this bind so none is orphaned, and exit non-zero.
+//
+// http.Server / https.Server both extend net.Server, so this one signature covers every caller.
+export function listenOrExit(
+  server: Server,
+  port: number,
+  opts: { host?: string; label: string; cleanup?: () => void; onListen: () => void },
+): void {
+  server.once('error', (err: NodeJS.ErrnoException) => {
+    opts.cleanup?.()
+    const why = err.code === 'EADDRINUSE' ? `port ${port} is already in use`
+      : err.code === 'EACCES' ? `permission denied binding port ${port}`
+      : err.code ?? err.message
+    console.error(`spec-cli: ${opts.label} cannot bind — ${why}. Free :${port} (e.g. lsof -i :${port}) or pick another port, then retry.`)
+    process.exit(1)
+  })
+  if (opts.host) server.listen(port, opts.host, opts.onListen)
+  else server.listen(port, opts.onListen)
+}