spexcode 0.6.0 → 0.6.2

package/spec-cli/src/help.ts

@@ -19,7 +19,8 @@ none (or @all) means every session.`
 
 const ROUTING_NOTE = `Backend routing: every backend-touching verb accepts --api <url> (--port <n> = localhost sugar) to name
 its backend explicitly — the flag always wins. Bare, it resolves: worker env / the cwd project's live
-recorded backend / fallback / :8787 (spex guide settings → BACKEND ROUTING).`
+recorded backend / fallback / :8787 (spex guide settings → BACKEND ROUTING). A password-gated explicit
+gateway accepts --password <pw> (or SPEXCODE_PASSWORD); its self-signed certificate needs explicit --insecure.`
 
 const DOT_NOTE = `\`.\` as a node argument means the node THIS worktree works on (the session's bound node, else the
 node/<id> branch). One-shot payload reads (graph · spec search · session ls/show/review · eval ls ·
@@ -36,16 +37,23 @@ type SessionVerbHelp = readonly [usage: string | readonly string[], detail: stri
 // Keeping the behavioral prose here prevents a compact probe from becoming a second, drifting manual.
 function sessionHelpDefinitions(): Record<string, SessionVerbHelp> {
   return {
-    new: ['spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>]',
+    new: ['spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>] [--name <name>] [--base <commit-ish>]',
       `Launch a worker in its own node worktree. The materialized system contract reaches it
 automatically; the prompt supplies the task context. Its first [[id]] mention binds the
 session to that node. --prompt-file <path>|- carries a long prompt without shell quoting
-(exclusive with the inline prompt). The successful receipt names what to read, monitor, and reply on.`],
+(exclusive with the inline prompt). --name sets the session's initial display name without changing the prompt.
+--base <commit-ish> pins the fork point instead of the source-of-truth branch's current head, so a run can be
+reproduced against a frozen commit; a base that names no commit is refused before anything is created.
+The successful receipt names what to read, monitor, and reply on.`],
     ls: ['spex session ls [SEL…] [--status a,b] [--all] [--json]',
       'One-shot table of living sessions. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it.', ['selector']],
     resources: ['spex session resources [--json]', 'Read-only host/process ownership, budgets, shared refs, and findings.'],
-    watch: ['spex session watch [SEL…] [--as NAME] [--idle] [--interval N=1]',
-      'Streams lifecycle transitions and blocks until killed; `session wait` is the one-shot alternative.', ['selector']],
+    files: [['spex session files add <path>', 'spex session files ls', 'spex session files retract <path>'],
+      'Publish, list, or withdraw YOUR session’s live file paths. Posting stores an absolute path beside the session record without copying bytes; the dashboard downloads it only when the human clicks.'],
+    web: [['spex session web add <url>', 'spex session web ls', 'spex session web retract <url>'],
+      'Publish, list, or withdraw YOUR session’s live loopback web-service URLs. Posting records no bytes and does not contact the service; the dashboard proxies the current HTTP/WebSocket service only when the human opens its preview.'],
+    watch: [['spex session watch <SEL…>', 'spex session watch list', 'spex session watch cancel <SEL…>', 'spex session watch stream [SEL…] [--as NAME] [--idle] [--interval N=1]'],
+      'With a governed caller, watch registers durable send-backed state delivery and exits. list/cancel manage those relations. Without a governed caller it names the background `session wait` fallback. stream is the human-only continuous log view and blocks until killed.', ['selector']],
     wait: ['spex session wait [SEL…] [--timeout S=1200] [--interval S=1] [--idle]',
       `EDGE-TRIGGERED wait: follows the selected sessions' logs AND your own log, and exits 0 on
 the FIRST thing worth waking for — a followed session TRANSITIONING from a non-actionable
@@ -58,8 +66,10 @@ It reads files only, so it needs no \`spex serve\` and costs the sessions it fol
 session's store is gone.`, ['selector']],
     review: ['spex session review <SEL> [--json]', 'Reports ahead · uncommitted · proposal · gates · merge-base diff.', ['selector']],
     merge: ['spex session merge <SEL>', 'Dispatches a gated merge to the session\'s own agent; it does not close the session.', ['selector', 'project-bound']],
-    send: [['spex session send <SEL> "<msg>"', 'spex session send <SEL> --keys "<keys>"'],
-      `Plain send delivers a message once its timeline append succeeds; a dead adapter only delays its context. --keys is the LAST RESORT:
+    reparent: ['spex session reparent <child-SEL...> --to <parent-SEL>',
+      'Move one or more governed children to a replacement parent, replacing only the former parent\'s managed watch relation. It never restarts a child and works when the former parent is offline.', ['selector', 'project-bound']],
+    send: [['spex session send <SEL> "<msg>"', 'spex session send <SEL> [--api <url> | --port <n>] -- <option-shaped-msg>', 'spex session send <SEL> --keys "<keys>"'],
+      `Plain send delivers a message once its timeline append succeeds; a dead adapter only delays its context. Routing flags may precede or follow ordinary text; use -- before a message that begins with --. --keys is the LAST RESORT:
 raw nav-mode keystrokes to a TUI dialog ("Up Up Enter", C-/M-/S- combos). The raw key surface
 is UNSTABLE and can confirm dangerous dialogs — try a plain send first; use keys only when text
 provably cannot land.`, ['selector', 'project-bound']],
@@ -79,7 +89,7 @@ you are running in, mid-turn. Your own ending is a declaration: \`done --propose
     done: ['spex session done --propose merge|nothing|close [--note T]',
       '`merge` declares review: committed work ready for human review, and it is the ONLY declaration that offers a clickable merge. `nothing` declares done: committed work, but no merge proposal. `close` declares close-pending: PROPOSE discarding this worktree — the human closes it. This declaration is how a session ends itself; never run `session close` on your own id.'],
     park: ['spex session park --note <what-you-await>',
-      'Declare parked only when a real background task will wake your own session. It self-resumes; waiting for a human is asking, not parked.'],
+      'Declare parked only when a managed watch delivery or real background task will wake your own session. It self-resumes; waiting for a human is asking, not parked.'],
     ask: ['spex session ask --note <your-question>',
       'Declare asking when the session needs a human reply or direction. It resumes only when the human replies; a background wake-up is parked instead.'],
     attach: ['spex session attach <SEL>', `Attaches the current terminal to the worker's tmux (detach: C-b d) and blocks until detached.
@@ -88,13 +98,13 @@ LOCAL-only (fails loud on a remote backend); show --capture and send are non-int
 }
 
 const SESSION_HELP_GROUPS = [
-  { title: 'Manager verbs (dispatch, monitor, land)', verbs: ['new', 'ls', 'resources', 'watch', 'wait', 'review', 'merge'] },
+  { title: 'Manager verbs (dispatch, monitor, land)', verbs: ['new', 'ls', 'resources', 'watch', 'wait', 'review', 'merge', 'reparent'] },
   { title: 'Control another session', verbs: ['send', 'interrupt', 'rename', 'show', 'resume', 'stop', 'archive', 'unarchive', 'close', 'quarantine'] },
-  { title: 'Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on)', verbs: ['done', 'park', 'ask'] },
+  { title: 'Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on)', verbs: ['done', 'park', 'ask', 'files', 'web'] },
   { title: 'Human escape hatch', verbs: ['attach'] },
 ] as const
 
-const SESSION_WRITE_NOTE = `Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge) are PROJECT-BOUND: a backend serving
+const SESSION_WRITE_NOTE = `Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
 another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.`
 
 function indent(text: string, spaces: number): string {
@@ -235,7 +245,7 @@ an admin password exists, and ungated projects serve open.`,
     line: 'spec <verb>           the governance graph: search · owner · lint · ack',
     body: `Usage: spex spec search <query…> [--limit N=10] [--json]
        spex spec owner <path> [--actionable]
-       spex spec lint
+       spex spec lint [--json]
        spex spec ack <node-id>… --reason "<why the contract still holds>"
 
 search — which spec node GOVERNS a topic, ranked by user-story relevance (which surfaces user-facing
@@ -259,7 +269,9 @@ leaf id reused) · mention (a [[id]] naming no node). Warns: coverage · drift
 "ignore"\` may silence it) · anchor (anchoring a type) · related-drift (a scoped related row warns
 per selector HIT, misses silent) · owners (whole-file governors only; scoped don't count) ·
 confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the prepared reference hook; bypass SPEXCODE_SKIP_LINT=1);
-contrast \`spex eval lint\`, which is pure advisory and never blocks anyone.
+contrast \`spex eval lint\`, which is pure advisory and never blocks anyone. \`--json\` writes the
+versioned machine report to stdout (source candidates + structured findings); its exit code still blocks
+on errors.
 
 ack — stamp Spec-OK on HEAD (an empty stamp commit): the drift remedy when only MECHANICS changed
 and the spec's contract still holds. --reason is required and recorded in the ack commit's body
@@ -273,7 +285,7 @@ edit the spec instead — same commit as the code.`,
     see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
   },
   eval: {
-    line: 'eval <verb>           the measurement system: add · ls · scenario ls/write · matrix · lint · ok · retract · clean',
+    line: 'eval <verb>           the measurement system: add · ls · scenario ls/write · lint · ok · retract · clean',
     body: `Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
                     [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
        spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
@@ -281,7 +293,6 @@ edit the spec instead — same commit as the code.`,
        spex eval ls --session <SEL> --export [--open | --out <path>]
        spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; JSON = canonical index
        spex eval scenario write --mutation <json> < eval.md       propose one canonical metadata mutation
-       spex eval matrix <launcher> [--node <id>] [--rows k1,k2]   the harness live-behavior matrix
        spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
        spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest measurement
        spex eval retract [<node>|.] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
@@ -305,12 +316,6 @@ scenario write — the fixed-tree declaration writer for an external measurement
 eval.md, --mutation is one closed JSON insert/delete request for one scenario's test metadata, and stdout is only
 the proposed eval.md bytes. It reads no worktree or runner and fails without stdout on malformed or ambiguous input.
 
-matrix — run the eight-row harness live-behavior matrix against a REAL dispatched session of the named
-launcher (the harness-adapter acceptance rule, defined once in spec-eval/src/matrix.ts): it syncs the
-rows into the \`<harness>-harness\` node's eval.md scenarios, drives one worker through undeclared-stop ·
-pretooluse-block · ask-note · deliver-steer · resume · liveness · commit-gate · close-residue, and files
-a per-row measurement with its evidence transcript. A new harness needs only its launcher + spec node.
-
 lint — the measurement layer's findings: malformed eval.md (eval-schema) · unmeasured (eval-missing) ·
 stale (eval-drift) · orphaned remark tracks (eval-dangling) · governed source with no eval.md
 (eval-coverage — the same name and shape as spec lint's coverage, one rule per layer) · over-owned
@@ -439,10 +444,12 @@ export function commandHelp(name: string, verb?: string): string | null {
   return `${header}${e.body}${e.see ? `\n\nsee also: ${e.see}` : ''}\n\nmap: spex help · skills: spex guide`
 }
 
-export function sessionLaunchReceipt(id: string): string {
+export function sessionLaunchReceipt(id: string, managedWatch = false): string {
   return `spex: launched session ${id}
   current result: the session JSON is on stdout now; \`spex session ls ${id}\` is the later one-shot snapshot
-  next lifecycle change: background \`spex session wait ${id}\` (edge-triggered; exits on the next non-actionable→actionable transition); \`spex session watch ${id}\` streams and NEVER EXITS
+  next lifecycle change: ${managedWatch
+    ? `managed watch registered — this parent receives ${id}'s state changes through its normal send queue; \`spex session watch cancel ${id}\` ends it`
+    : `background \`spex session wait ${id}\` (edge-triggered; exits on the next non-actionable→actionable transition); \`spex session watch ${id}\` registers send-backed delivery when the caller is governed`}; \`spex session watch stream ${id}\` NEVER EXITS
   response channel: \`spex session send ${id} "<msg>"\`; \`send --keys\` is an UNSTABLE LAST RESORT after a plain send cannot land`
 }
 

package/spec-cli/src/host-resources.ts

@@ -3,7 +3,7 @@ import { execFileSync } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
 import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { defaultHarness, HARNESSES, harnessById, sessionIdentityEnvVars, type HarnessLivenessRecord, type SharedRuntimeDescriptor, type SharedRuntimeProbe } from './harness.js'
+import { defaultHarness, HARNESSES, harnessById, harnessByIdOrNull, sessionIdentityEnvVars, type HarnessLivenessRecord, type SharedRuntimeDescriptor, type SharedRuntimeProbe } from './harness.js'
 import { listSessionIds, readConfig, readJsonConfig, readPublicRecordEntry, readRawRecord, runtimeRoot, type PublicRecordEntry, type RawRecord } from './layout.js'
 import { repoRoot } from './git.js'
 import { endpointRecordPath } from './host.js'
@@ -219,6 +219,31 @@ const runtimePid = (file: string): number | null => {
   catch { return null }
 }
 type SharedEntry = { descriptor: SharedRuntimeDescriptor; recs: RawRecord[] }
+// A session record outlives the config that created it, so a removed plugin harness or a renamed harness id
+// leaves a governed record this registry cannot resolve. That is a normal long-lived state for a host-wide
+// sweep, not a request naming a bad id: the sweep reports the record and keeps every other owner's findings.
+const unresolvableHarness = (rec: RawRecord): string | null => {
+  const id = rec.harness || defaultHarness.id
+  return harnessByIdOrNull(id) ? null : id
+}
+// Mirrors the corrupt-record owner: a record the sweep could not fully read stays a public owner so its
+// absence from a process-derived group cannot read as health. Here the unknown half is the harness, so
+// lifecycle is unknown and reclaim is closed rather than guessed from the record's own status field.
+const unresolvedHarnessOwners = (recs: RawRecord[], budgets: ResourceBudgets, have: (sessionId: string) => boolean): ResourceOwner[] => {
+  const out: ResourceOwner[] = []
+  for (const rec of recs) {
+    const unresolved = unresolvableHarness(rec)
+    if (!unresolved || !rec.governed || rec.stopped || have(rec.session_id)) continue
+    out.push({
+      kind: 'session', id: rec.session_id, label: `session ${rec.session_id.slice(0, 8)}`, status: rec.status, liveness: 'unknown',
+      processes: [], rssMiB: 0, pssMiB: null, cpuPercent: 0,
+      budget: { rssMiB: budgets.sessionRssMiB, idleCpuPercent: budgets.idleCpuPercent },
+      findings: [`harness-unresolved:${unresolved}`],
+      reclaim: { eligible: false, reason: `harness '${unresolved}' is not resolvable by this registry; shared-runtime stop safety cannot be proven` },
+    })
+  }
+  return out
+}
 const sharedDescriptors = (recs: RawRecord[], retainRegistry = false): Map<string, SharedEntry> => {
   const out = new Map<string, { descriptor: SharedRuntimeDescriptor; recs: RawRecord[] }>()
   for (const harness of HARNESSES) for (const descriptor of harness.sharedRuntimes?.(runtimeRoot()) ?? []) {
@@ -229,7 +254,8 @@ const sharedDescriptors = (recs: RawRecord[], retainRegistry = false): Map<strin
     // reported as an archive hazard. Clean archived records carry stopped:true and no loaded reference, so they
     // contribute nothing to the active set while still preserving exact ownership if the invariant is violated.
     if (!rec.governed) continue
-    const harness = harnessById(rec.harness || defaultHarness.id)
+    const harness = harnessByIdOrNull(rec.harness || defaultHarness.id)
+    if (!harness) continue   // joined to no descriptor; surfaced as a finding on that record's own session owner
     const exactKey = harness.targetDescriptorKey?.({ session: rec.session_id, harnessSessionId: rec.harness_session_id }) ?? null
     for (const descriptor of harness.sharedRuntimes?.(runtimeRoot()) ?? []) {
       if (exactKey && descriptor.key !== exactKey) continue
@@ -381,6 +407,22 @@ const probeRuntime = async (descriptor: SharedRuntimeDescriptor): Promise<Shared
   catch (error) { return { healthy: false, references: [], error: (error as Error).message } }
 }
 
+const sessionOwnerBlocker = (id: string, harnessId: string | null, recs: RawRecord[]): string | null => {
+  const targetRecord = recs.find((rec) => rec.session_id === id)
+  const targetHarness = harnessId ? harnessById(harnessId) : null
+  const targetThread = targetRecord?.harness_session_id
+  if (!targetHarness || !targetThread) return null
+  const ownerCount = recs.filter((rec) => rec.governed && (rec.harness || defaultHarness.id) === targetHarness.id && rec.harness_session_id === targetThread).length
+  if (ownerCount === 1) return null
+  const label = targetHarness.sharedRuntimes?.(runtimeRoot())[0]?.label ?? targetHarness.id
+  return `${label} target thread ${targetThread} has no one exact governed session owner`
+}
+
+export function assertSessionOwnerSafe(id: string, harnessId: string): void {
+  const blocker = sessionOwnerBlocker(id, harnessId, rawRecords())
+  if (blocker) throw new ResourceConflict(blocker)
+}
+
 const sessionStopBlocker = async (
   id: string,
   harnessId: string | null,
@@ -390,6 +432,9 @@ const sessionStopBlocker = async (
 ): Promise<string | null> => {
   const targetRecord = recs.find((rec) => rec.session_id === id)
   const targetHarness = harnessId ? harnessById(harnessId) : null
+  const targetThread = targetRecord?.harness_session_id
+  const ownerBlocker = sessionOwnerBlocker(id, harnessId, recs)
+  if (ownerBlocker) return ownerBlocker
   const exactKey = targetHarness?.targetDescriptorKey?.({ session: id, harnessSessionId: targetRecord?.harness_session_id }) ?? null
   const targetDescriptors = targetHarness?.sharedRuntimes?.(runtimeRoot()) ?? []
   if (targetHarness && targetDescriptors.length === 0) return null
@@ -404,9 +449,9 @@ const sessionStopBlocker = async (
     const pid = runtimePid(descriptor.pidFile)
     const ownerCounts = new Map<string, number>()
     for (const rec of entry.recs) if (rec.harness_session_id) ownerCounts.set(rec.harness_session_id, (ownerCounts.get(rec.harness_session_id) ?? 0) + 1)
-    const targetThread = entry.recs.find((rec) => rec.session_id === id)?.harness_session_id
-    if (targetThread && ownerCounts.get(targetThread) !== 1)
-      return `${descriptor.label} target thread ${targetThread} has no one exact governed session owner`
+    const entryTargetThread = entry.recs.find((rec) => rec.session_id === id)?.harness_session_id
+    if (entryTargetThread && ownerCounts.get(entryTargetThread) !== 1)
+      return `${descriptor.label} target thread ${entryTargetThread} has no one exact governed session owner`
     if (!knownProbes && descriptor.mutationGuard) {
       if (!targetThread) return `${descriptor.label} target has no exact governed thread identity`
       if (!pid) return `${descriptor.label} target-scoped mutation guard has no readable owner PID`
@@ -506,6 +551,7 @@ export async function collectResourceReport(opts: { procRoot?: string; persist?:
       budget: { rssMiB: budgets.sessionRssMiB, idleCpuPercent: budgets.idleCpuPercent },
       findings: [`session-record-corrupt:${entry.error}`], reclaim: { eligible: false, reason: 'session record is corrupt; ownership and lifecycle are unknown' },
     })
+    owners.push(...unresolvedHarnessOwners(recs, budgets, (sessionId) => owners.some((owner) => owner.kind === 'session' && owner.id === sessionId)))
     const report: ResourceReport = { version: 1, measuredAt: new Date().toISOString(), projectRoot: root, platform: platform(), available: false, unavailableReason: `host process metrics are unavailable on ${platform()}; shared runtime references remain visible`, host: { memoryTotalMiB: null, memoryUsedMiB: null, memoryAvailableMiB: null, swapTotalMiB: null, swapUsedMiB: null, cpuPercent: null }, budgets, owners, totals: { rssMiB: 0, pssMiB: null, cpuPercent: 0 }, findings: owners.reduce((n, o) => n + o.findings.length, 0) }
     if (opts.persist !== false) atomicJson(join(runtimeRoot(), 'resource-report.json'), report)
     return report
@@ -562,8 +608,15 @@ export async function collectResourceReport(opts: { procRoot?: string; persist?:
       if (rec?.archived) findings.push('archived-runtime-hazard:leaf-still-resident')
       if (totals.rssMiB > rssBudget) findings.push(`rss-over-budget:${Math.round((totals.rssMiB - rssBudget) * 10) / 10}MiB`)
       if (status !== 'active' && status !== 'queued' && totals.cpuPercent > idleBudget) findings.push(`idle-cpu-over-budget:${Math.round((totals.cpuPercent - idleBudget) * 10) / 10}%`)
-      const stopBlocker = rec ? await sessionStopBlocker(id, rec.harness || defaultHarness.id, inv.recs, sharedProbes) : null
-      if (terminal(rec) && totals.cpuPercent <= idleBudget && !stopBlocker) {
+      // The stop guard resolves the record's harness fail-loud, which is right for a stop REQUEST and wrong
+      // here: this sweep reads rows nobody named. An unresolvable harness makes stop safety unprovable, so it
+      // is reported and reclaim stays closed — never a resolvable-looking zero, never a lost report.
+      const unresolved = rec ? unresolvableHarness(rec) : null
+      if (unresolved) findings.push(`harness-unresolved:${unresolved}`)
+      const stopBlocker = rec && !unresolved ? await sessionStopBlocker(id, rec.harness || defaultHarness.id, inv.recs, sharedProbes) : null
+      if (unresolved) {
+        reclaim = { eligible: false, reason: `harness '${unresolved}' is not resolvable by this registry; shared-runtime stop safety cannot be proven` }
+      } else if (terminal(rec) && totals.cpuPercent <= idleBudget && !stopBlocker) {
         reclaim = { eligible: true, reason: `terminal lifecycle ${rec!.status}/${rec!.proposal}; a future exact action must revalidate every fact` }
       } else reclaim = { eligible: false, reason: stopBlocker ? `shared runtime unsafe: ${stopBlocker}` : terminal(rec) ? 'terminal record is still consuming CPU; liveness contradicts safe retirement' : 'owner is not terminal; budget age/status alone never authorizes stop' }
     } else if (owner.startsWith('shared:')) {
@@ -621,6 +674,8 @@ export async function collectResourceReport(opts: { procRoot?: string; persist?:
       findings: [`session-record-corrupt:${entry.error}`], reclaim: { eligible: false, reason: 'session record is corrupt; ownership and lifecycle are unknown' },
     })
 
+  owners.push(...unresolvedHarnessOwners(inv.recs, budgets, (sessionId) => owners.some((owner) => owner.kind === 'session' && owner.id === sessionId)))
+
   // A referenced shared runtime with no readable process is still operationally important: keep its live or
   // unknown refcount visible instead of silently omitting it from a process-derived report.
   for (const [key, shared] of inv.shared) if (!owners.some((o) => o.kind === 'shared-runtime' && o.id === key)) {

package/spec-cli/src/identity-presets.js

@@ -1,18 +1,28 @@
 // One browser-safe identity registry shared by backend validation and every dashboard projection.
 // Geometry is data so the React renderer and favicon serializer cannot drift into separate drawings.
+//
+// @@@ shape keys travel through two renderers - a shape's own attributes override the group's
+// fill/stroke, which is how a multi-colour mark fits a single-fg registry. Both consumers pass the keys
+// through verbatim: the string serializer spreads them as attributes, React spreads them as JSX props.
+// So a key must be valid in BOTH, which rules out hyphenated names (React wants strokeWidth) - hence a
+// painted seam outline rather than a stroked line, since per-shape stroke-width cannot be expressed.
 
 export const DEFAULT_PROJECT_ICON = 'spexcode'
 export const DEFAULT_GATEWAY_ICON = 'gateway'
 
 export const IDENTITY_PRESETS = Object.freeze([
   {
-    id: 'spexcode', label: 'SpexCode', bg: '#166534', fg: '#f0fdf4',
+    // The brand mark: two brackets holding one file, cleft corner to corner and regenerated on the
+    // upper-right of the cleft. Painted rather than stroked — see the paint note below. Geometry is
+    // docs/brand/mark-dark.svg scaled by 24/512; the two surface gradients flatten to their midpoints
+    // because a 24-unit chip has no room for a ramp and the format carries no defs.
+    id: 'spexcode', label: 'SpexCode', bg: '#12161C', fg: '#EFE8D8',
     shapes: [
-      { tag: 'circle', cx: 12, cy: 6.2, r: 2.2 },
-      { tag: 'circle', cx: 6.2, cy: 17.5, r: 2 },
-      { tag: 'circle', cx: 17.8, cy: 17.5, r: 2 },
-      { tag: 'path', d: 'M12 8.4v2.1c0 2.2-5.8 1.8-5.8 5' },
-      { tag: 'path', d: 'M12 10.5c0 2.2 5.8 1.8 5.8 5' },
+      { tag: 'path', d: 'M 4.500,4.500 L 9.750,4.500 L 9.750,6.656 L 6.656,6.656 L 6.656,17.344 L 9.750,17.344 L 9.750,19.500 L 4.500,19.500 Z', fill: '#EFE8D8', stroke: 'none' },
+      { tag: 'path', d: 'M 19.500,4.500 L 14.250,4.500 L 14.250,6.656 L 17.344,6.656 L 17.344,17.344 L 14.250,17.344 L 14.250,19.500 L 19.500,19.500 Z', fill: '#EFE8D8', stroke: 'none' },
+      { tag: 'path', d: 'M 15.281,15.281 L 11.731,13.057 L 12.269,10.943 L 8.719,8.719 L 8.719,15.281 Z', fill: '#327D95', stroke: 'none' },
+      { tag: 'path', d: 'M 8.719,8.719 L 12.269,10.943 L 11.731,13.057 L 15.281,15.281 L 15.281,12.000 L 12.000,8.719 Z', fill: '#82C3D6', stroke: 'none' },
+      { tag: 'path', d: 'M 8.569,8.957 L 11.946,11.073 L 11.408,13.186 L 15.132,15.520 L 15.431,15.043 L 12.054,12.927 L 12.592,10.814 L 8.868,8.480 Z', fill: '#E4F7FD', stroke: 'none' },
     ],
   },
   {

package/spec-cli/src/index.ts

@@ -1,6 +1,8 @@
 import { serve } from '@hono/node-server'
 import type { Server as HttpServer, ServerResponse as HttpServerResponse } from 'node:http'
 import { randomUUID } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { Readable } from 'node:stream'
 import { installConnectionReaper } from './reaper.js'
 import { Hono } from 'hono'
 import { cors } from 'hono/cors'
@@ -15,23 +17,26 @@ import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { summarizeLoopIn } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './graphCache.js'
-import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
+import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged, flushDeferredWorktreeRegistryChange } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
 import { cockpitReview } from './cockpit.js'
 import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, quarantineCorruptRecord, restoreQuarantinedRecord, archiveSession, resumeSession, mergeSession, captureSessionResult, sessionPrompt, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, superviseTurnFailures, superviseDelivery, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
 import { readTimeline } from './session-timeline.js'
+import { readSessionExecution, sessionExecutionStream } from './session-execution.js'
 import { defaultHarness, HARNESSES, dashboardLauncherList, launcherDefault } from './harness.js'
-import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
+import { readBlobByHash } from '../../spec-eval/src/evaltab.js'
 import { putBlob } from '../../spec-eval/src/cache.js'
 import { fileHumanReading } from '../../spec-eval/src/filing.js'
 import { fileHumanOk } from '../../spec-eval/src/humanok.js'
-import { buildExportModel, renderExportHtml, SessionEvalUnavailableError } from '../../spec-eval/src/sessioneval.js'
+import { buildExportModel, renderExportHtml, buildSessionEvals, SessionEvalUnavailableError } from '../../spec-eval/src/sessioneval.js'
 import { appendUpload, cancelUpload, completeUpload, createUpload, evidenceMaxBytes, startUploadReaper, UploadError, uploadStatus } from './uploads.js'
+import { listSessionFiles, openSessionFile, SESSION_FILE_PREVIEW_MAX_BYTES, sessionFilePreviewKind, SessionFileError } from './session-files.js'
 import { attachViewer, detachViewer, resizeBridge, hideViewer, forwardInput, superviseBridges, type Viewer } from './pty-bridge.js'
 import { installProcessGuards } from './resilience.js'
 import { resolveProjectIdentity } from './project-identity.js'
 import { evalDetailReview, evalsReview, issuesReview } from './reviews.js'
 import { collectResourceReport, ResourceConflict } from './host-resources.js'
+import { reparentRequest, SessionReparentRequestError } from './session-reparent.js'
 
 // last-resort net: an unforeseen async throw (e.g. a worktree vanishing mid-read during a worker
 // self-merge) is logged and the server KEEPS SERVING instead of exiting and dropping the public port.
@@ -47,6 +52,7 @@ app.onError((error, c) => {
   // stack would hide exactly the sentence the human needs.
   if (error instanceof SessionRecordUnusable) return c.json({ error: error.message, code: error.code }, 409)
   if (error instanceof ResourceConflict) return c.json({ error: error.message, code: error.code }, 409)
+  if (error instanceof SessionReparentRequestError) return c.json({ error: error.message }, 400)
   console.error(error)
   return c.text('Internal Server Error', 500)
 })
@@ -137,10 +143,7 @@ app.get('/api/edit', async (c) => {
   }
   return c.json({ patch })
 })
-// a node's eval timeline (read half of `spex eval`): eval-sidecar readings joined with a live freshness
-// flag, newest-first; `hasEvalFile:false` when none declared. Contract belongs to [[spec-eval]].
-app.get('/api/specs/:id/evals', async (c) => c.json(await evalTimeline(c.req.param('id'))))
-// the eval seam's WRITE half over HTTP ([[spec-eval]] filing.ts) — the REST pair of the GET above: a
+// the eval seam's WRITE half over HTTP ([[spec-eval]] filing.ts): a
 // programmatic caller files a reading (verdict + optional transcript) through the SAME append the CLI
 // uses. The dashboard does not call this — [[event-detail]] reads readings and hosts remarks, never files.
 app.post('/api/specs/:id/evals', async (c) => {
@@ -230,15 +233,27 @@ app.get('/api/evals', etag(), async (c) => {
   const page = await evalsReview(c.req.query('q'), c.req.query('page'), { view: c.req.query('view') })
   return page ? c.json(page) : c.json({ error: 'no such review source' }, 404)
 })
+// The exact impact graph proves a scope's membership and selector decisions. It is deliberately a named
+// read: paged Evals rows retain their own reasons but never transport this scope-sized projection.
+app.get('/api/evals/impact', etag(), async (c) => {
+  const scope = c.req.query('scope')?.trim()
+  if (!scope) return c.json({ error: 'scope is required' }, 400)
+  await ensureBoardFileWatchers(scope)
+  const model = await buildSessionEvals(scope)
+  return model
+    ? c.json({ scope, impact: model.impact, evalRevision: model.evalRevision })
+    : c.json({ error: 'no such review source' }, 404)
+})
 // ONE bounded detail response for both source roots: the selected scenario's complete A/B history and at
-// most five lightweight neighbors. It never serializes another scenario's history or the scoped model.
+// most five lightweight neighbors. A missing worktree scope resolves explicitly to trunk; it never
+// serializes another scenario's history or the scoped model.
 app.get('/api/evals/detail', etag(), async (c) => {
   await ensureBoardFileWatchers(c.req.query('scope')?.trim() || undefined)
   const node = c.req.query('node')?.trim()
   const scenario = c.req.query('scenario')?.trim()
   if (!node || !scenario) return c.json({ error: 'node and scenario are required' }, 400)
   const detail = await evalDetailReview(node, scenario, c.req.query('scope')?.trim() || null)
-  return detail ? c.json(detail) : c.json({ error: 'no such review source' }, 404)
+  return c.json(detail)
 })
 // the single-thread read ([[issues]]) behind `spex issue show <id>` — the SAME findIssue lookup, from the
 // resident forge slice (instant view, background reconcile — the list route's freshness contract). A local
@@ -455,12 +470,19 @@ app.post('/api/sessions', async (c) => {
   try {
     const body = await c.req.json().catch(() => null)
     const result = await sessionCreateRequest(body, { requestKey, signal: controller.signal })
+    // The durable row is now public. Nudge the cheap session projection explicitly so a dashboard does not
+    // wait for the best-effort store watcher; any held candidate worktree event remains a separate full claim.
+    if (result.status === 201) notifyBoardChanged('sessions')
+    // A candidate registry event is intentionally held while Git creates the private worktree. Once the
+    // transaction has published or cleaned up its record, release the one deferred full refresh.
+    flushDeferredWorktreeRegistryChange()
     if (result.status === 201) {
       c.header('Idempotency-Key', requestKey)
       return c.json(result.session, 201)
     }
     return c.json({ error: result.error, ...(result.code ? { code: result.code } : {}), ...(result.phase ? { phase: result.phase } : {}) }, result.status as any)
   } finally {
+    flushDeferredWorktreeRegistryChange()
     rawSignal.removeEventListener('abort', cancelFromRequest)
     outgoing?.off('close', cancel)
   }
@@ -489,6 +511,14 @@ app.get('/api/sessions/:id/capture', async (c) => {
   if (r.reason === 'offline') return c.text('session offline (no live pane)', 409)
   return c.text('capture failed', 502)
 })
+// A live adapter-owned execution observation, intentionally distinct from the durable conversation timeline.
+// The response carries only the backend-normalized latest working note and typed tool rows; no transcript bytes
+// or parser schema cross this API boundary.
+app.get('/api/sessions/:id/execution', (c) => {
+  const execution = readSessionExecution(c.req.param('id') || '')
+  return execution ? c.json(execution) : c.json({ error: 'no such session' }, 404)
+})
+app.get('/api/sessions/:id/execution/stream', (c) => sessionExecutionStream(c))
 // the session's persisted interaction history ([[session-timeline]]): authored status transitions (with the
 // FULL note text) + delivered prompts, timestamped, oldest first — what a terminal-free surface renders as
 // the conversation. `?limit=<n>` caps the tail (default 500). 404 for an unknown/non-governed id.
@@ -506,6 +536,39 @@ app.get('/api/sessions/:id', async (c) => {
   if (!row) return c.json({ error: 'no such session' }, 404)
   return c.json({ ...row, prompt: await sessionPrompt(id) })
 })
+app.get('/api/sessions/:id/files', (c) => {
+  try { return c.json({ files: listSessionFiles(c.req.param('id')) }) }
+  catch (error) {
+    if (error instanceof SessionFileError) return c.json({ error: error.message }, error.status)
+    throw error
+  }
+})
+const sessionFileDownload = (c: any) => {
+  try {
+    const requested = c.req.query('path')
+    if (!requested) return c.json({ error: 'download needs a posted path' }, 400)
+    const file = openSessionFile(c.req.param('id'), requested)
+    const preview = c.req.query('preview') === '1'
+    const previewType = preview ? sessionFilePreviewKind(file.path) : null
+    if (preview && !previewType) return c.json({ error: 'no preview for this file type; download it instead' }, 415)
+    if (preview && file.size > SESSION_FILE_PREVIEW_MAX_BYTES)
+      return c.json({ error: `preview is limited to ${SESSION_FILE_PREVIEW_MAX_BYTES / (1024 * 1024)} MiB; download this ${file.size}-byte file instead` }, 413)
+    const headers: Record<string, string> = {
+      'Cache-Control': 'no-store',
+      'Content-Disposition': `${preview ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(file.name)}`,
+      'Content-Length': String(file.size),
+      'Content-Type': previewType?.contentType ?? 'application/octet-stream',
+    }
+    if (previewType) headers['X-Spexcode-Preview-Kind'] = previewType.kind
+    if (c.req.method === 'HEAD') return c.body(null, 200, headers)
+    return c.body(Readable.toWeb(createReadStream(file.path)) as ReadableStream, 200, headers)
+  } catch (error) {
+    if (error instanceof SessionFileError) return c.json({ error: error.message }, error.status)
+    throw error
+  }
+}
+app.get('/api/sessions/:id/files/download', sessionFileDownload)
+app.on('HEAD', '/api/sessions/:id/files/download', sessionFileDownload)
 // lifecycle transitions (thin callers of the session state machine)
 // relaunch ONLY if confirmed offline; demotes working→idle, keeps any declaration. The RESUME GUARD refuses
 // (409) when the agent is alive or its liveness is unproven — restore-on-alive was the incident's kill-shot.
@@ -516,11 +579,37 @@ app.post('/api/sessions/:id/resume', async (c) => {
   const r = await resumeSession(c.req.param('id'), { force })
   return c.json(r, r.ok ? 200 : (r.refused ? 409 : 404))
 })
-// a dispatch to the session's own agent (it runs the merge), never a server merge — the server never touches
-// main's tree. 200 {dispatched:true} once the prompt is accepted, 409 {dispatched:false} if the agent is unreachable.
+// A reviewed dispatch to the session's own agent (it runs the merge), never a server merge. The caller returns
+// the exact branch/base OIDs with a durable key; sessions.ts validates and accepts them once before ensure-live.
 app.post('/api/sessions/:id/merge', async (c) => {
-  const r = await mergeSession(c.req.param('id'))
-  return c.json(r, r.dispatched ? 200 : 409)
+  const requestKey = c.req.header('idempotency-key')
+  if (requestKey === undefined) {
+    return c.json({ dispatched: false, reason: 'Idempotency-Key is required with reviewed merge authority', code: 'session_merge_invalid_request' }, 400)
+  }
+  const rawBody = await c.req.text()
+  let body: unknown = {}
+  if (rawBody.trim()) {
+    try { body = JSON.parse(rawBody) }
+    catch { return c.json({ dispatched: false, reason: 'body must be valid JSON', code: 'session_merge_invalid_request' }, 400) }
+  }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return c.json({ dispatched: false, reason: 'body must be a JSON object', code: 'session_merge_invalid_request' }, 400)
+  }
+  const input = body as Record<string, unknown>
+  const keys = Object.keys(input)
+  const allowed = new Set(['expectedBranchHead', 'expectedBaseHead'])
+  if (keys.some((key) => !allowed.has(key))) {
+    return c.json({ dispatched: false, reason: `unknown session-merge field(s): ${keys.filter((key) => !allowed.has(key)).join(', ')}`, code: 'session_merge_invalid_request' }, 400)
+  }
+  if (typeof input.expectedBranchHead !== 'string' || typeof input.expectedBaseHead !== 'string') {
+    return c.json({ dispatched: false, reason: 'expectedBranchHead and expectedBaseHead must be strings', code: 'session_merge_invalid_request' }, 400)
+  }
+  const r = await mergeSession(c.req.param('id'), {
+    requestKey,
+    expectedBranchHead: input.expectedBranchHead,
+    expectedBaseHead: input.expectedBaseHead,
+  })
+  return c.json(r, r.dispatched ? 200 : (r.status ?? 409))
 })
 
 // one WS owns one native tmux client (pty-bridge): server→client = that client's rendered PTY bytes (binary);
@@ -626,6 +715,11 @@ app.post('/api/sessions/:id/input', async (c) => {
   }
   return c.json({ error: 'input needs kind: "text" | "command" | "keys"' }, 400)
 })
+app.post('/api/sessions/reparent', async (c) => {
+  const result = await reparentRequest(await c.req.json().catch(() => null))
+  notifyBoardChanged('sessions')
+  return c.json(result)
+})
 // soft stop: kill the agent's tmux + socket but KEEP the worktree (resumable). Distinct from close, which
 // removes the worktree. {ok:false} = no such session.
 app.post('/api/sessions/:id/stop', async (c) => {
@@ -639,7 +733,8 @@ app.post('/api/sessions/:id/interrupt', async (c) => {
 })
 app.post('/api/sessions/:id/close', async (c) => {
   const sessionId = c.req.param('id')
-  const ok = await closeSession(sessionId)
+  const body = await c.req.json().catch(() => ({}))
+  const ok = await closeSession(sessionId, body?.source)
   // The close route owns its write's visible boundary: filesystem watchers can be unavailable, so cache
   // invalidation must happen before the success response rather than leaving the confirming board to patrol.
   if (ok) notifyBoardChanged('sessions')

package/spec-cli/src/init.ts

@@ -1,29 +1,20 @@
 import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, renameSync, rmSync, statSync, chmodSync, writeFileSync } from 'node:fs'
-import { createHash } from 'node:crypto'
 import { join, resolve, relative, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
 import { resolveHarnessTargets, parseHarnessFlag, NATIVE_HARNESS_IDS } from './harness-select.js'
+import { gitBinary } from './git.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).
 const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
 const TEMPLATES = join(pkgRoot, 'templates')
 const MANAGED_HOOK_HEADER = '# spexcode-managed-hook-v1'
-const LEGACY_MANAGED_HOOKS: Record<string, Set<string>> = {
-  'pre-commit': new Set(['fc33a6ff2b444fa47210a2594b6a714613d9c62fd8ec77a9a13aec81143de8a7']),
-  'prepare-commit-msg': new Set(['08b26ad8ffb305a64b7cddc868231854c84d539b8e5e9324702bd2c293044183']),
-}
-
-function hookDigest(path: string): string {
-  return createHash('sha256').update(readFileSync(path)).digest('hex')
-}
 
-function isManagedHook(path: string, name: string): boolean {
+function isManagedHook(path: string): boolean {
   const source = readFileSync(path, 'utf8')
   return source.split('\n').slice(0, 4).includes(MANAGED_HOOK_HEADER)
-    || LEGACY_MANAGED_HOOKS[name]?.has(createHash('sha256').update(source).digest('hex')) === true
 }
 
 function replaceHook(source: string, dest: string): void {
@@ -71,7 +62,7 @@ function copyTreeNoClobber(srcDir: string, destDir: string, base: string): strin
 // hooks/ (shared across all worktrees). Returns null (with a loud reason) when <dir> isn't a git repo.
 function resolveHooksDir(dir: string): string | null {
   try {
-    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    const common = execFileSync(gitBinary(process.env), ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'], // swallow git's own "fatal: not a git repository" — our warning is the signal
     }).trim()
@@ -86,8 +77,8 @@ function resolveHooksDir(dir: string): string | null {
 // turn that feature branch into trunk).
 function adoptionMainBranch(dir: string): string {
   try {
-    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
-    const branch = execFileSync('git', ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
+    const common = execFileSync(gitBinary(process.env), ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
+    const branch = execFileSync(gitBinary(process.env), ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
     if (branch) return branch
   } catch { /* render the one product-level repair below */ }
   const error = new Error('cannot determine the source-of-truth branch at adoption — check out the trunk in the root checkout, or set "mainBranch" in spexcode.json before re-running `spex init`')
@@ -113,7 +104,7 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
   // NOT `git init` for them: creating a repo is a side effect beyond init's remit (a subdir, a dir not
   // meant as a repo root), and `git init` is one deliberate command.
   try {
-    execFileSync('git', ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { stdio: ['ignore', 'ignore', 'ignore'] })
+    execFileSync(gitBinary(process.env), ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { stdio: ['ignore', 'ignore', 'ignore'] })
   } catch {
     console.error(`spex init: ${targetDir} is not a git repository. SpexCode is git-backed (git is the version database; the hooks live in .git). Run \`git init\` there first, then \`spex init\`.`)
     process.exit(1)
@@ -210,8 +201,8 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
       const source = join(hooksSrc, e.name)
       const dest = join(hooksDir, e.name)
       if (existsSync(dest)) {
-        if (hookDigest(dest) === hookDigest(source)) continue
-        if (isManagedHook(dest, e.name)) {
+        if (readFileSync(dest).equals(readFileSync(source))) continue
+        if (isManagedHook(dest)) {
           replaceHook(source, dest)
           refreshed.push(e.name)
         } else {