spexcode 0.6.1 → 0.6.2

package/spec-cli/src/graph.ts

@@ -24,6 +24,8 @@ function resolveParent(path: string, byDir: Record<string, string>): string | nu
   return null
 }
 
+const OVERLAY_TO_PATH = Symbol('overlay-to-path')
+
 // The server-only review snapshot keeps latest readings verbatim. Graph JSON receives only counts.
 export function latestPerScenario<T extends { scenario: string }>(readings: T[]): T[] {
   const seen = new Set<string>()
@@ -51,12 +53,17 @@ const rowOps = (s: { path: string; archived?: boolean }, opsByPath: Record<strin
   (s.archived ? [] : opsByPath[s.path] || [])
 
 export async function buildBoard() {
-  // all three sources are warm-cheap and independent, so the board inherits their speed for free: loadSpecs
-  // REUSES the HEAD-keyed spec-history cache (the git-derived node data — see specs.ts/git.ts), resolveLayout
-  // reuses the per-worktree overlay cache and recomputes only the deltas that actually changed (the live
-  // OVERLAY), and listSessions takes its liveness from ONE batched tmux snapshot. Nothing here re-walks git.
+  // loadSpecs starts alongside the public session census and REUSES the HEAD-keyed spec-history cache. Layout
+  // then receives that census's projected-active ids so an archived runtime hazard contributes the same ops to
+  // the full producer that spliceSessions preserves. Its per-worktree cache still recomputes only changed deltas.
   const root = repoRoot()
-  const [layout, sessions, specs] = await Promise.all([resolveLayout(), listSessions(), loadSpecs()])
+  const sessionsPromise = listSessions()
+  const specsPromise = loadSpecs()
+  const sessions = await sessionsPromise
+  const [layout, specs] = await Promise.all([
+    resolveLayout({ activeSessionIds: sessions.map((session) => session.id) }),
+    specsPromise,
+  ])
   // the eval fold's freshness axes: WARM hits — loadSpecs already computed this HEAD's drift + history
   // indices, so these are the same cached walks, fetched once and reused for every measurable node (the history
   // index drives the rename-safe scenario axis, mirroring a spec node's own freshness).
@@ -88,6 +95,7 @@ export async function buildBoard() {
         op: op.op, source, label, branch: w.branch, seed,
         committed: op.committed, dirty: op.dirty,
         toParent: op.op === 'moved' ? resolveParent(op.toPath || op.path, byDir) : null,
+        [OVERLAY_TO_PATH]: op.op === 'moved' ? op.toPath || op.path : null,
       }
       if (op.op === 'added' && !byId[op.nodeId]) {
         if (ghostById[op.nodeId]) { ghostById[op.nodeId].overlays.push(ov); continue }
@@ -191,6 +199,7 @@ export async function buildBoard() {
 export async function spliceSessions(prev: Awaited<ReturnType<typeof buildBoard>>): Promise<Awaited<ReturnType<typeof buildBoard>>> {
   const sessions = await listSessions()
   const evalProjections = sessionEvalProjections(sessions)
+  const activeSources = new Set(sessions.map((session) => session.path))
   const opsByPath: Record<string, any[]> = {}
   for (const s of prev.sessions) opsByPath[s.source] = s.ops
   const sess = sessions.map((s) => ({
@@ -199,7 +208,48 @@ export async function spliceSessions(prev: Awaited<ReturnType<typeof buildBoard>
     ops: rowOps(s, opsByPath),
     evalSummary: evalProjections.get(s.id),
   }))
-  return { ...prev, sessions: sess }
+  // Archive and close are subtractive topology changes: their worktree leaves the working set, so its
+  // overlays must leave in the same cheap publication as its row. Filtering the already-built units is exact
+  // and forks nothing. A newly-active source is intentionally absent here; graphCache keeps a full obligation
+  // for additions/resume so resolveLayout can discover that worktree's current delta.
+  let nodeProjectionMoved = false
+  const projectedNodes = prev.nodes.flatMap((node: any) => {
+    const overlays = (node.overlays || []).filter((overlay: any) => activeSources.has(overlay.source))
+    if (node.ghost && overlays.length === 0) { nodeProjectionMoved = true; return [] }
+    if (overlays.length === (node.overlays || []).length) return [node]
+    nodeProjectionMoved = true
+    if (node.ghost) return [{ ...node, overlays, status: deriveStatus({ version: 0, drift: 0, hasOverlay: true }) }]
+    return [{ ...node, overlays, status: deriveStatus({
+      version: node.version,
+      drift: node.drift,
+      hasOverlay: overlays.length > 0,
+      hasCode: (node.code?.length ?? 0) > 0,
+      fmStatus: node.fmStatus ?? undefined,
+    }) }]
+  })
+  const nodes = nodeProjectionMoved ? projectedNodes : prev.nodes
+  if (nodeProjectionMoved) {
+    const byDir: Record<string, string> = {}
+    for (const node of nodes) if (node.path) byDir[node.path.replace(/\/spec\.md$/, '')] = node.id
+    const retainedIds = new Set(nodes.map((node: any) => node.id))
+    for (let index = 0; index < nodes.length; index++) {
+      const node: any = nodes[index]
+      let changed = false
+      let parent = node.parent
+      if (node.ghost) {
+        const next = resolveParent(node.path, byDir)
+        if (next !== parent) { parent = next; changed = true }
+      }
+      const overlays = (node.overlays || []).map((overlay: any) => {
+        if (!overlay.toParent || retainedIds.has(overlay.toParent)) return overlay
+        const toPath = overlay[OVERLAY_TO_PATH]
+        changed = true
+        return { ...overlay, toParent: typeof toPath === 'string' ? resolveParent(toPath, byDir) : null }
+      })
+      if (changed) nodes[index] = { ...node, parent, overlays }
+    }
+  }
+  return { ...prev, nodes, sessions: sess }
 }
 
 // A full producer may finish after the session lane has already shown a newer row. Reuse that published

package/spec-cli/src/graphCache.ts

@@ -27,9 +27,10 @@ type BoardInputRevision = {
   projections: string
   combined: string
   fullParts: Record<string, string>
+  worktreeParts: Record<string, string>
   projectionIds: string[]
 }
-type SessionInputRevision = Pick<BoardInputRevision, 'sessions' | 'projections' | 'projectionIds'>
+type SessionInputRevision = Pick<BoardInputRevision, 'sessions' | 'projections' | 'projectionIds'> & { activeRoots: string[] }
 const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1'
 
 function textOrNull(path: string): string | null {
@@ -144,28 +145,38 @@ function digest(value: unknown): string {
 // The hot/warm liveness signatures and eval generations remain graph-stream's canonical event-owned axes.
 function sessionInputRevision(): SessionInputRevision {
   const ids = listSessionIds().sort()
-  // listSessions projects both the structured record and the separately-stored originating prompt into each
-  // board row. Fold both exact artifacts so a missed store event cannot leave a stale label/prompt forever.
+  // listSessions projects the structured record plus a one-line preview of the separately-stored originating
+  // prompt into each board row. Fold both exact artifacts so a missed store event cannot leave a stale
+  // label/preview forever — the prompt file is folded because the preview is derived from it.
   const sessionInputs = ids.map((id) => [
     id,
     textOrNull(sessionRecordPath(id)),
     textOrNull(sessionArtifactPath(id, 'prompt')),
   ] as const)
   const projections = digest(ids.map((id) => [id, sessionEvalProjection(id)]))
-  return { sessions: digest(sessionInputs), projections, projectionIds: ids }
+  const activeRoots = [...new Set(ids.flatMap((id) => {
+    const entry = readPublicRecordEntry(id)
+    return entry.kind === 'ok' && entry.raw.governed && !entry.raw.archived ? [entry.raw.worktree_path] : []
+  }))].sort()
+  return { sessions: digest(sessionInputs), projections, projectionIds: ids, activeRoots }
 }
 
 function boardInputRevision(board: Board | null): BoardInputRevision {
   const root = repoRoot()
   const session = sessionInputRevision()
-  const records = listSessionIds().map(readPublicRecordEntry).flatMap((entry) => entry.kind === 'ok' ? [entry.raw] : [])
-  const governed = records.filter((record) => record.governed).sort((a, b) => a.session_id.localeCompare(b.session_id))
-  const activeRoots = [...new Set(governed.filter((record) => !record.archived).map((record) => record.worktree_path))].sort()
+  // Durable active records are the current root set; a cached ordinary row may be stale and must not replace
+  // them. The one projection-only addition is explicit: listSessions republishes an archived-runtime hazard
+  // into the working set, and that marked row keeps its root monitored until cold state is repaired.
+  const activeRoots = [...new Set([
+    ...session.activeRoots,
+    ...(board?.sessions.flatMap((row) => row.archiveHazard ? [row.path] : []) ?? []),
+  ])].sort()
   const main = mainCheckout()
   const base = mainBranch()
   const mainTip = refSha(main, base)
   const nodeIds = (board?.nodes ?? []).map((node) => node.id)
   const issuesStamp = boardThreads({ host: resolveForgeHost(), state: residentForgeState() }, nodeIds).stamp
+  const worktreeParts = Object.fromEntries(activeRoots.map((worktree) => [worktree, digest(worktreeRevision(worktree))]))
   const fullInputs = {
     root: worktreeRevision(root),
     config: [
@@ -175,7 +186,7 @@ function boardInputRevision(board: Board | null): BoardInputRevision {
       [join(main, 'spexcode.local.json'), textOrNull(join(main, 'spexcode.local.json'))],
     ],
     main: { root: main, branch: base, tip: mainTip },
-    worktrees: activeRoots.map((worktree) => worktreeRevision(worktree)),
+    worktrees: worktreeParts,
     issuesStamp,
     identity: resolveProjectIdentity(root, root),
   }
@@ -186,6 +197,7 @@ function boardInputRevision(board: Board | null): BoardInputRevision {
     ...session,
     combined: digest([full, session.sessions, session.projections]),
     fullParts,
+    worktreeParts,
   }
 }
 
@@ -204,13 +216,19 @@ function revisionCarriedByBoard(sample: BoardInputRevision, board: Board): Board
     projections,
     combined: digest([full, sample.sessions, projections]),
     fullParts,
+    worktreeParts: sample.worktreeParts,
     projectionIds: sample.projectionIds,
   }
 }
 
 // A sessions splice reuses its base topology. It may sample fresh record/projection inputs, but it must never
 // certify that those old nodes carry a full revision sampled after the base was built.
-function revisionCarriedBySessionSplice(base: BoardInputRevision, sample: SessionInputRevision, board: Board, stable: boolean): BoardInputRevision {
+function revisionCarriedBySessionSplice(
+  base: BoardInputRevision,
+  sample: Pick<SessionInputRevision, 'sessions' | 'projections' | 'projectionIds'>,
+  board: Board,
+  stable: boolean,
+): BoardInputRevision {
   const boardProjections = new Map(board.sessions.map((session) => [session.id, session.evalSummary ?? null]))
   const projections = stable
     ? digest(sample.projectionIds.map((id) => [id, boardProjections.get(id) ?? null]))
@@ -221,6 +239,7 @@ function revisionCarriedBySessionSplice(base: BoardInputRevision, sample: Sessio
     projections,
     combined: digest([base.full, sample.sessions, projections]),
     fullParts: base.fullParts,
+    worktreeParts: base.worktreeParts,
     projectionIds: sample.projectionIds,
   }
 }
@@ -236,10 +255,40 @@ function revisionCarriedByPublishedSessionRebase(full: BoardInputRevision, publi
     projections: published.projections,
     combined: digest([full.full, published.sessions, published.projections]),
     fullParts: full.fullParts,
+    worktreeParts: full.worktreeParts,
     projectionIds: published.projectionIds,
   }
 }
 
+function carrySubtractiveWorktrees(base: BoardInputRevision, activeRoots: readonly string[]): { revision: BoardInputRevision; added: boolean } {
+  const active = new Set(activeRoots)
+  const known = Object.keys(base.worktreeParts)
+  if (activeRoots.some((root) => !(root in base.worktreeParts))) return { revision: base, added: true }
+  if (known.every((root) => active.has(root))) return { revision: base, added: false }
+  const worktreeParts = Object.fromEntries(Object.entries(base.worktreeParts).filter(([root]) => active.has(root)))
+  const fullParts = { ...base.fullParts, worktrees: digest(worktreeParts) }
+  const full = digest(fullParts)
+  return {
+    revision: {
+      ...base,
+      full,
+      fullParts,
+      worktreeParts,
+      combined: digest([full, base.sessions, base.projections]),
+    },
+    added: false,
+  }
+}
+
+function isPureSubtractiveWorktreeMove(base: BoardInputRevision, sample: BoardInputRevision): boolean {
+  const moved = Object.keys(sample.fullParts).filter((key) => sample.fullParts[key] !== base.fullParts[key])
+  if (moved.length !== 1 || moved[0] !== 'worktrees') return false
+  const current = Object.keys(sample.worktreeParts)
+  const previous = Object.keys(base.worktreeParts)
+  return current.length < previous.length
+    && current.every((root) => sample.worktreeParts[root] === base.worktreeParts[root])
+}
+
 // a build slower than this is LOGGED, never silently tolerated — the fail-loud regression alarm. Sized
 // above a warm build (~sub-second once the fs walks yield) but below the cold two-walk first build, so a
 // genuinely-degraded hot path shouts while an ordinary cold start stays quiet-ish.
@@ -319,11 +368,16 @@ function startSessionSplice(): Flight | null {
       const board = await spliceSessions(base)
       const after = sessionInputRevision()
       if (base !== cached || revision !== cachedRevision || generation !== topologyGeneration) continue
-      const stable = before.sessions === after.sessions && before.projections === after.projections
+      const stable = before.sessions === after.sessions && before.projections === after.projections &&
+        JSON.stringify(before.activeRoots) === JSON.stringify(after.activeRoots)
+      const projectedRoots = [...new Set(board.sessions.map((row) => row.path))].sort()
+      const rootTransition = carrySubtractiveWorktrees(revision, projectedRoots)
+      const carried = stable ? rootTransition.revision : revision
       cached = board
       cachedJson = null
-      cachedRevision = revisionCarriedBySessionSplice(revision, before, board, stable)
+      cachedRevision = revisionCarriedBySessionSplice(carried, before, board, stable)
       sessionProjectionPublication++
+      if (rootTransition.added) mergeDirty('full')
       if (!stable) {
         sessionOwed = true
         sessionGeneration++
@@ -383,6 +437,7 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
   let buildSessionGeneration = sessionGeneration
   let buildSessionProjectionPublication = sessionProjectionPublication
   let buildStartedWithSessionOwed = false
+  let buildAddedSessionRoot = false
   let completedRevision: BoardInputRevision | null = null
   // Do not invoke the producer inline. buildBoard() has an asynchronous signature but performs a sizeable
   // synchronous setup before its first await (Promise.all evaluates its arguments immediately). A stale HTTP
@@ -420,21 +475,23 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
         // the watcher event was about; an invalidation arriving after the sample keeps its own dirty window.
         if (prev && anchor && gen === sampledGen) {
           const fullMoved = before.full !== anchor.full
+          const subtractiveWorktreeMove = fullMoved && isPureSubtractiveWorktreeMove(anchor, before)
+          const structuralMoved = fullMoved && !subtractiveWorktreeMove
           const projectionMoved = before.sessions !== anchor.sessions || before.projections !== anchor.projections
           // A projection move nobody signalled is this validation doing the patrol's repair job.
-          if (projectionMoved && !sessionOwed && dirty !== 'sessions') {
+          if ((projectionMoved || subtractiveWorktreeMove) && !sessionOwed && dirty !== 'sessions') {
             gen++
             sessionOwed = true
             sessionGeneration++
           }
-          const owed = fullMoved ? 'full' : (sessionOwed || dirty === 'sessions') ? 'sessions' : 'none'
+          const owed = structuralMoved ? 'full' : (sessionOwed || dirty === 'sessions') ? 'sessions' : 'none'
           if (DEBUG && owed !== 'none') {
             const moved = Object.keys(before.fullParts).filter((key) => before.fullParts[key] !== anchor.fullParts[key])
             console.warn(`spec-cli: graph refresh revision moved — signalled=${dirty} scope=${owed} inputs=[${moved.join(', ')}]`)
           } else if (DEBUG && dirty !== 'none') {
-            console.warn(`spec-cli: graph refresh discharged a ${dirty} signal — no board input moved`)
+            console.warn(`spec-cli: graph refresh discharged a ${dirty} signal — no graph input moved`)
           }
-          if (fullMoved) dirty = 'full'
+          if (structuralMoved) dirty = 'full'
           else if (sessionOwed || dirty === 'sessions') dirty = 'sessions'
           // Discharging CONSUMES the claim. Leaving it standing would make every later read re-enter this
           // validation, hold the board permanently stale/refreshing, and never converge.
@@ -474,7 +531,19 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
         // against a revision this board never carried, and the cache would converge on nothing. So a moved
         // half anchors on `before` — the conservative direction, which costs at most one extra rebuild and can
         // never certify unread bytes.
-        completedRevision = revisionCarriedByBoard(buildFullStable && buildSessionsStable ? after : before, board)
+        if (sessionsOnly && anchor) {
+          const projectedRoots = [...new Set(board.sessions.map((row) => row.path))].sort()
+          const rootTransition = carrySubtractiveWorktrees(anchor, projectedRoots)
+          buildAddedSessionRoot = rootTransition.added
+          completedRevision = revisionCarriedBySessionSplice(
+            rootTransition.revision,
+            before,
+            board,
+            buildFullStable && buildSessionsStable && !rootTransition.added,
+          )
+        } else {
+          completedRevision = revisionCarriedByBoard(buildFullStable && buildSessionsStable ? after : before, board)
+        }
         return board
       }))
         .then(resolveBuild, rejectBuild)
@@ -510,7 +579,7 @@ function startBuild(mode: FlightMode = 'dirty'): Flight | null {
       cachedRevision = completedRevision
       if (buildScope === 'full') topologyGeneration++
       else sessionProjectionPublication++
-      if (!buildFullStable) mergeDirty('full')
+      if (!buildFullStable || buildAddedSessionRoot) mergeDirty('full')
       traceCacheCommit(buildScope, buildStartedAt)
     }
     retryAt = 0

package/spec-cli/src/graphStream.ts

@@ -504,7 +504,7 @@ const REFS_OBSERVER = 'graph:refs'
 
 // @@@ the moved ref NAMES its scope - the watcher has always known which ref moved and threw it away, so
 // every ref movement anywhere invalidated every session's evaluation. On a host carrying dozens of branches
-// and a bot that commits continuously that means nothing is ever warm: observed on z-code as an input
+// and a bot that commits continuously that means nothing is ever warm: observed on adopter-a as an input
 // generation of 1208 against a last-known 254. A session's fingerprint reads exactly three refs — its own
 // tip, the base tip, and their merge-base — so a ref that is neither cannot move it. `packed-refs` and
 // `HEAD` stay broad on purpose: a packed update rewrites many refs behind ONE event, so it names nothing.

package/spec-cli/src/guide.ts

@@ -14,7 +14,7 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    startup commands.)
 
 2. Adopt a repo
-     cd <your-repo> && spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/ + git hooks (additive, never overwrites)
+     cd <your-repo> && spex init --harness claude,codex,opencode,pi,zcode,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/ + git hooks (additive, never overwrites)
    --harness is required and has no default — the explicit choice of which harness(es) materialize
    delivers into. The example lists every built-in; drop the ones you don't use (any one id or
    comma-separated subset is valid).
@@ -101,6 +101,13 @@ code does it. Two optional level-2 headings split ground truth from detail:
 Bodies without those headings are read whole. Link sibling nodes with [[node-id]] — every link must name
 a REAL node (lint's mention rule; backtick a placeholder like \`[[node]]\` so it reads as sample text).
 
+COMMENT ALTITUDE: specs own intent, invariants, policy, and observable contracts; comments only navigate
+non-obvious local decisions. Put contract or intent in the owning spec body, not a code comment. Keep a short
+nearby comment only for ordering, platform behavior, measured pitfalls, or why a plausible alternative is
+unsafe; delete commentary that merely translates code or repeats a name/type. Preserve measured values,
+version-specific behavior, and rejected alternatives not in the spec. \`@@@title - explanation\` is reserved for
+genuinely tricky surviving local reasoning.
+
 WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
   integrity  (error)  every code:/related: path exists — and every anchor RESOLVES: a dead anchor (unit
                       deleted/renamed), an ambiguous one (two same-named units in one file), a file that
@@ -144,7 +151,10 @@ Heuristic spec health is deliberately outside this production gate. Bare \`spex
 altitude and breadth findings; the tidy workflow consumes that report and adds semantic judgment.
 
 LIFECYCLE: author each node on a node/<id> branch, one node per commit; \`spex spec lint\` must reach 0 errors
-before merge. \`spex init\` seeds the first tree; \`spex guide eval\` covers the sibling eval.md, the measurement file.`
+before merge. \`spex init\` seeds the first tree; \`spex guide eval\` covers the sibling eval.md, the measurement file.
+
+SHARED LANDING: if the shared checkout is mid-merge, wait. Never abort or resolve someone else's merge; if your
+own landing stops half-merged, abort it and report.`
 
 const EVAL = `spex guide eval — the eval.md file format
 
@@ -187,6 +197,13 @@ pre-commit \`internal check-staged\` BLOCKS the commit.
 BODY (after the frontmatter): prose naming the measurement method — YATU ("You As The User"): the agent
 looks at / calls the real product surface, not an internal helper chosen to make the evidence easy.
 
+REPAIR PROOF: for a bug fix, use one scenario's fail→pass pair. A, BEFORE EDITING: find the violated scenario
+or add one to \`eval.md\`, run it against the old committed behavior, and file
+\`spex eval add <node> --scenario <s> --fail\` with evidence of the failure. B, AFTER EDITING: run that same
+scenario against the working tree until it passes; commit the verified tree; then file
+\`spex eval add <node> --scenario <s> --pass\`. The reading's \`codeSha\` must be that commit. New intent has no
+prior failure to reproduce.
+
 MEASURING AND FILING: the agent runs the scenario however it likes (a browser run, an API
 transcript, a by-hand pass), compares the result to \`expected\`, and files it:
   spex eval add <node> [--scenario <name>] (--pass | --fail) [--note <text>]
@@ -227,6 +244,31 @@ PICK THE EVIDENCE KIND BY WHAT THE BEHAVIOUR DOES OVER TIME:
                       \`data\` — rendered as a validatable data block, not flattened into scrolling transcript
                       text; free-form output stays a transcript. You pick the flag; the KIND follows the bytes.
 The flags combine in ONE filing — several stills can ride beside the clip of the same run.
+POPULATION DISCIPLINE: when \`expected\` quantifies over a set ("every X is Y", "nothing under Z"), the
+measurement reports the set's SIZE, not only the verdict. An empty set satisfies a universal claim
+VACUOUSLY, so a pass over nothing and a real pass are indistinguishable — and the universal form reads
+STRICTER than an enumeration, which is what makes it the hardest wrong-population case to catch. File
+\`N of N\`, never a bare boolean: \`0 of 0\` shows itself, \`true\` does not. The denominator must come from a
+source that can DISAGREE with the numerator — count the population off the surface that does NOT decide the
+outcome (a backend export, a ledger, the enumeration upstream of the thing under test) and the passing members
+off the surface under test. A ratio whose halves share one source says only "what I selected, I selected": a
+selector that silently drops half the population reports \`3 of 3\` when the truth is 6. Two weaker defences
+that do not substitute — a precondition sentence depends on the next author remembering it, a printed
+denominator depends on a reader noticing it. Nothing here enforces either (the schema has no population
+field), so treat a zero-population run as a NON-reading and do not file it. Cheaper than any of that, when
+you can get it: restate the claim over something the product CANNOT make empty. "every active node's name is
+readable" needs someone to arrange activity and goes vacuous when nobody does; "the rendered size never falls
+below the authored size" is a property of the viewport itself, true of a one-node graph, and has no
+population to get wrong. A claim with no population beats a well-reported one.
+RENDERED GEOMETRY (browser): measure the rendered BOX, never the authored STYLE. An ancestor CSS \`transform\`
+— the ordinary zoom/pan wrapper on a canvas or graph view — does NOT change computed style, so
+\`getComputedStyle(el).fontSize\` answers the AUTHORED size while the screen shows that size times the
+ancestor scale, and the reading is a SILENT FALSE PASS. (No numbers here on purpose: the authored size is
+whatever this project's stylesheet says today, and a manual that hard-codes one teaches a constant that
+drifts — read it off the tree you are measuring.) Go through \`getBoundingClientRect()\` (it carries the
+ancestor scale) and derive the effective size from the box, or from a known string's width. This is also why
+a geometric claim ships WITH its \`--image\`: a rect can be computed wrong, while "is that text legible" is
+human-judgeable, so the two evidences cover each other.
 ANCHOR DISCIPLINE: an eval's \`codeSha\` is HEAD at filing time, and a git sha names only a COMMIT — an
 uncommitted change has none. So measure the tree you are about to commit, COMMIT it, then file; confidence
 is earned on the working tree, but the anchor can only land after the commit. Filing from a dirty tree
@@ -285,7 +327,8 @@ see LAUNCHERS.
 ── LAYOUT (spexcode.json — portable; set only for a NON-DEFAULT repo layout) ──
   main          path to the source-of-truth checkout. Default: the \`main\` worktree.
   mainBranch    the stable source-of-truth BRANCH worktrees fork from. spex init stamps the root checkout's
-                branch at adoption; an older omitted value uses the conventional main.
+                branch at adoption and the stamped value stays put for every later checkout, so a clone or a
+                fresh worktree does not re-guess it; an older omitted value uses the conventional main.
   branchPrefix  how a node branch is named. Default "node/".
 Example — a repo whose trunk is \`staging\`, not \`main\`:
   { "mainBranch": "staging" }
@@ -575,7 +618,47 @@ not a flag flip.
                             elsewhere cannot be recalled.
   back out entirely         \`spex uninstall\` (add --hooks to also remove the spexcode git hooks).`
 
-const TOPICS: Record<string, string> = { spec: SPEC, eval: EVAL, settings: SETTINGS, footprint: FOOTPRINT }
+const FILES = `spex guide files — hand an agent artifact back to the human
+
+Use the session's file list when an artifact belongs in the human's hands:
+
+  spex session files add <path>      publish one current file path
+  spex session files ls              read your published paths
+  spex session files retract <path>  withdraw one path
+
+Posting resolves a relative path from your current directory and records its absolute path beside the global
+session record. It copies, moves, stages, and uploads NOTHING. The path is live: editing the file after
+posting changes what the human downloads. The reference is host-local; opening the session elsewhere cannot
+make its path point at another machine's file.
+
+The session page's top-right files icon is grey while the list is empty. Once live, it opens the posted list;
+choosing a path previews its current text or raster-image bytes in a pop-out, while the adjacent download tool
+downloads it through the backend at that moment. Previews are limited to 2 MiB, text and PNG/JPEG/GIF/WebP;
+other types and larger files say to download instead. A missing, moved, or unreadable target stays listed but
+reports that it no longer exists. The backend refuses a preview or download for any path not on that session's
+list.
+
+This is the reverse of a dashboard attachment: [[file-attach]] sends human bytes to an agent. Files publishes
+an agent-owned path for a human to download.`
+
+const WEB = `spex guide web — hand a running local web service to the human
+
+Use the session web list after starting a local page the human should inspect:
+
+  spex session web add http://127.0.0.1:5173/
+  spex session web ls
+  spex session web retract http://127.0.0.1:5173/
+
+Posting records the canonical loopback HTTP URL beside the global session record. It does not fetch the page,
+start a process, or move bytes. The dashboard uses its own same-origin gateway only when the human opens the
+preview, including WebSocket traffic, so changes to the running service are visible at that moment.
+
+Only loopback HTTP URLs with an explicit port are accepted: 127.0.0.1, localhost, or ::1. The service remains
+host-local and must stay running. A stopped service remains listed and reports that its upstream is unavailable.
+The proxy has a path prefix, so use relative asset/navigation URLs or configure your dev server's base path;
+hard-coded root-absolute Vite/Next assets cannot be made portable by a proxy guessing at JavaScript.`
+
+const TOPICS: Record<string, string> = { spec: SPEC, eval: EVAL, settings: SETTINGS, footprint: FOOTPRINT, files: FILES, web: WEB }
 
 // every guide page ends by naming the OTHER help layer, so a reader never dead-ends here: guide is
 // the skill layer (workflows · formats · settings); command usage lives in help.ts's two layers.
@@ -588,4 +671,10 @@ export function guideText(topic?: string): string | null {
   const t = TOPICS[topic]
   return t ? t + FOOTER : null
 }
+
+// @@@ the unknown-topic list is DERIVED, never re-typed - a hand-kept enumeration goes blind the moment a
+// topic is added beside it, and it did: `files` and `web` shipped while the error still named four.
+export function guideTopics(): string[] {
+  return Object.keys(TOPICS)
+}
 import { uploadPolicyDefaults } from './layout.js'

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

@@ -44,14 +44,14 @@ export function resolveHarnessTargets(raw: unknown): HarnessTarget[] {
   for (const m of raw) {
     if (typeof m === 'string') {
       if (m === 'plugin')
-        throw new Error(`spexcode.json "harnesses": a plugin target needs an EXPLICIT landing folder — write {"plugin":"<folder>"} (e.g. {"plugin":".zcode"}), not the bare string "plugin", because each host agent reads a different plugins dir.`)
+        throw new Error(`spexcode.json "harnesses": a plugin target needs an EXPLICIT landing folder — write {"plugin":"<folder>"} (e.g. {"plugin":".adopter-a"}), not the bare string "plugin", because each host agent reads a different plugins dir.`)
       if (!KNOWN.includes(m))
         throw new Error(`spexcode.json "harnesses": unknown harness id "${m}" — known native ids are ${KNOWN.join(', ')}, or use {"plugin":"<folder>"}.`)
       targets.push({ kind: 'native', id: m as HarnessId })
     } else if (m && typeof m === 'object' && !Array.isArray(m) && 'plugin' in m) {
       const folder = (m as { plugin?: unknown }).plugin
       if (typeof folder !== 'string' || !folder.trim())
-        throw new Error(`spexcode.json "harnesses": a {"plugin":…} target needs a NON-EMPTY folder string (e.g. {"plugin":".zcode"}) — each host agent reads a different plugins dir, so the folder must be explicit.`)
+        throw new Error(`spexcode.json "harnesses": a {"plugin":…} target needs a NON-EMPTY folder string (e.g. {"plugin":".adopter-a"}) — each host agent reads a different plugins dir, so the folder must be explicit.`)
       targets.push({ kind: 'plugin', folder: folder.trim() })
     } else {
       throw new Error(`spexcode.json "harnesses": each member must be a native id string (${KNOWN.join(', ')}) or a {"plugin":"<folder>"} object — got ${JSON.stringify(m)}.`)