@skitterbyte/skitterspec 21.0.0 → 22.1.0

package/src/env/serve.js

@@ -36,7 +36,10 @@ const {
   resolveSpec,
   resolveBaseBranch,
 } = require('./resolve.js')
+const { readRegistry } = require('./registry.js')
 const { loadEnvConfig } = require('./config.js')
+const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
+const { liveStateFor } = require('./live.js')
 const {
   rawGitReader,
   collectReview,
@@ -45,10 +48,13 @@ const {
   reviewOutPath,
   validateNotesBlob,
   readPending,
+  passState: readPassState,
   writePending,
   addPending,
   readNotes,
   readGate,
+  readRenderRecord,
+  DEFAULT_BUTTON_SET,
 } = require('./review.js')
 
 /**
@@ -84,6 +90,15 @@ function routeFor(url, { token = null } = {}) {
   if (segments.length === 0) return { kind: 'index' }
   if (segments.length > 1) return { kind: 'notfound' }
 
+  // `?pass=<code>` asks what became of ONE pass, and it is checked BEFORE
+  // `?branch` because it is not a view of the diff at all — it is the page
+  // finding out whether the verdict it sent was picked up. Deliberately only
+  // ever one code wide: a route that listed what is waiting would hand a
+  // prober exactly what the six digits are bought to withhold, and the POST
+  // route was kept from being that oracle for the same reason.
+  const pass = query.get('pass')
+  if (pass !== null) return { kind: 'pass', spec: segments[0], code: pass }
+
   // `?branch` and `?branch=1` both mean the whole-spec view; `?branch=0` does
   // not, so a link can turn it off as well as on.
   const raw = query.get('branch')
@@ -167,19 +182,181 @@ ${body}
 }
 
 /**
- * Resolve the specs worth listing: every spec with a worktree of its own.
+ * WHICH VIEW A SPEC GETS, decided in one place so every route agrees.
+ *
+ * `worktree` — it has one, so the page is its branch's diff, exactly as before.
+ * `docs` — it has none, so the page is its own uncommitted documents read from
+ *   the checkout this server is anchored to. That is the authoring page
+ *   `spec-env review --docs` writes, and this is what lets it be SERVED: a
+ *   `file://` page has no server to POST to, so without this the authoring page
+ *   exists and its verdict buttons have nowhere to go.
+ * `null` — neither: no worktree and nothing uncommitted of its own, which is
+ *   the ordinary state of most of `specs/` and a 404 rather than an error.
+ *
+ * WHAT WOULD FOOL A WORKTREE-ONLY VERSION of this — which is what shipped, and
+ * what 404'd a page rendered minutes earlier: an authoring page belongs to a
+ * spec with no worktree BY DEFINITION, so gating the route on a worktree
+ * excludes precisely the specs the docs view exists for.
+ */
+/**
+ * Is this worktree a spec being WRITTEN rather than built?
+ *
+ * Returns the owned document paths when it is, and null for every other
+ * answer — including the ones we cannot work out. Never throws: a page is a
+ * convenience and a git that will not read is not evidence of anything.
+ */
+function docsWorktree(wt, spec, config) {
+  if (!spec || spec.bucket !== 'backlog') return null
+  const paths = dirtyPaths(trimmedGitReader(wt))
+  // Cannot tell — not "no documents".
+  if (paths === null) return null
+  const { owned, foreign } = classifyDirtyTree(spec, paths, config)
+  if (!owned.length || foreign.length) return null
+  return { owned }
+}
+
+function viewFor(dir, config, spec, git, { fallback = false } = {}) {
+  if (!spec) return null
+  // LIVE COMES FIRST, because while a spec is live its worktree still exists —
+  // detached — and would win the check below while holding none of the work.
+  // `live take` checks the branch out HERE, and a fix made while live is made
+  // here too, so this checkout is the tree that answers.
+  if (spec.branch && headBranchOf(git) === spec.branch) return { kind: 'live', tree: dir }
+  const wt = spec.worktreePath
+  if (wt && wt !== dir && fs.existsSync(wt)) {
+    // A DOCS WORKTREE IS NOT A CODE WORKTREE, and this used to be unreachable.
+    //
+    // `/spec` once wrote into the primary checkout, so a backlog spec had no
+    // worktree at all and fell through to the docs branch below. It now
+    // provisions the spec's own `--docs` worktree and writes there — so this
+    // check began winning for exactly the specs the docs branch exists to
+    // serve, and their pages were served the COMMITTING set. A reader pressed
+    // `Commit & Continue` on a backlog spec that has no phase to continue.
+    //
+    // Asked as a POSITIVE SIGNAL and never as "no code yet"
+    // (`.claude/rules/negative-checks.md` rule 1), and it takes BOTH halves:
+    //
+    //   - the spec is in the BACKLOG, which is what `authoring` means. Without
+    //     this, the window right after `/spec-start` — where the `git mv` and
+    //     the header edit are uncommitted and no phase code exists yet — reads
+    //     as documents-only and would offer `Commit & Start` for a spec
+    //     already in flight.
+    //   - the worktree holds NOTHING BUT this spec's own documents. Without
+    //     this, a backlog spec whose tree had been used for anything else
+    //     would have that work rendered under an authoring verdict.
+    //
+    // Anything else is the ordinary worktree view, including every cannot-tell:
+    // an unresolvable bucket, a git that will not read, an empty tree.
+    const docs = docsWorktree(wt, spec, config)
+    if (docs) return { kind: 'docs', tree: wt, owned: docs.owned }
+    return { kind: 'worktree', tree: wt }
+  }
+  const found = specDocsIn(dir, spec, config, trimmedGitReader(dir))
+  // `error` is cannot-tell — not a page, and not an error page either (rule 4:
+  // the harmless branch).
+  if (found.error) return null
+  if (!found.empty) return { kind: 'docs', tree: found.tree, owned: found.owned }
+
+  // NOTHING UNCOMMITTED IS NOT NOTHING TO SHOW, on this route. A `--docs` page
+  // renders a spec's uncommitted documents, so HONOURING THE VERDICT PRESSED ON
+  // IT is what removes them: the reader presses `Commit`, the agent commits, and
+  // a reload 404s. The link was valid, the server was up and the network was
+  // fine — the page had been deliberately destroyed by the thing it asked for.
+  //
+  // So fall back to what the spec now IS, which mirrors the phase page's
+  // clean-tree fallback for the same reason: the page is rendered before the
+  // commit and read after it.
+  //
+  // ONLY FOR A NAMED PAGE, never for the index. The two routes ask different
+  // questions: the index is a menu of what AWAITS review, and every completed
+  // spec in the repo falling back would fill it with dozens of finished ones —
+  // the doorway would be wrong about a healthy repo, which is the reason it
+  // omits them in the first place. A direct request is someone opening an
+  // address they were given, and that has to keep resolving.
+  if (!fallback) return null
+  const committed = committedDocsFor(dir, config, spec)
+  if (!committed) return null
+  return { kind: 'docs-committed', tree: dir, owned: committed }
+}
+
+/**
+ * The spec's committed document paths at `HEAD`, or null when it has none.
+ *
+ * KEPT ONLY WHERE IT FINDS SOMETHING, exactly as the branch fallback is: a name
+ * that is no spec at all must stay a 404 rather than render an empty page with
+ * a commit button on it.
+ */
+function committedDocsFor(dir, config, spec) {
+  const git = trimmedGitReader(dir)
+  const out = git(['ls-files', '--', `specs/*/${spec.folder}/*`])
+  if (out == null) return null
+  const paths = String(out)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+  return paths.length ? paths : null
+}
+
+/**
+ * The tier rows the PAGE needs, from config alone.
+ *
+ * DELIBERATELY NOT `reviewTierStack`. That stack answers "where can this be
+ * read", which needs the server's bind, the machine's addresses and any
+ * published URL. The page needs only the half it can act on: which tiers are
+ * OFF, so it can offer the press that turns one on. An `off` tier has no URL by
+ * definition, so none of that machinery is required — and an `on` tier
+ * contributes nothing here, because the reader is standing on one of them.
+ */
+function pageTiers(config) {
+  const r = (config && config.review) || {}
+  return [
+    { tier: 'network', off: !r.allowNetwork },
+    { tier: 'remote', off: !r.allowRemote },
+  ]
+}
+
+/**
+ * The branch name a git reader's checkout is on, or null.
+ *
+ * NULL FOR A DETACHED HEAD, which `rev-parse --abbrev-ref` spells `HEAD` — a
+ * name no branch has, and one that must never compare equal to a spec's.
+ * Returning it verbatim would make a detached checkout look like a spec called
+ * `HEAD`; the cannot-tell answer is null (`.claude/rules/negative-checks.md`).
+ */
+function headBranchOf(git) {
+  const out = git ? git(['rev-parse', '--abbrev-ref', 'HEAD']) : null
+  if (out == null) return null
+  const name = String(out).trim()
+  return name && name !== 'HEAD' ? name : null
+}
+
+// `specDocsIn` wants a reader that TRIMS, because it compares whole paths.
+function trimmedGitReader(treePath) {
+  const git = rawGitReader(treePath)
+  return (argv) => {
+    const out = git(argv)
+    return out == null ? null : String(out).trim()
+  }
+}
+
+/**
+ * Resolve the specs worth listing: every spec this server can render a page for.
+ *
+ * A spec with neither a worktree nor uncommitted documents of its own is
+ * OMITTED, not listed as an error — that is the ordinary state of most of
+ * `specs/`, and a doorway listing them as failures would be wrong about a
+ * healthy repo.
  *
- * A spec with no worktree is OMITTED, not listed as an error. An unstarted spec
- * has nothing to diff, which is the ordinary state of most of `specs/` — and a
- * doorway that lists them as failures would be wrong about a healthy repo.
+ * IT INCLUDES WORKTREE-LESS SPECS NOW, and both halves are needed together: a
+ * page that serves but is absent from the index is a page nobody finds.
  */
-function servableSpecs(dir, config, git) {
+function servableSpecs(dir, config, git, specless = {}) {
   const worktreePaths = liveWorktreePaths(git)
-  return allSpecs(dir, config, worktreePaths)
-    .filter((s) => {
-      const wt = s.worktreePath
-      return wt && wt !== dir && worktreePaths.has(path.resolve(wt))
-    })
+  // `allSpecs` scans `specs/**`, where a specless branch is by definition not —
+  // so it takes the registry's map and adds them. Defaulted to empty, because
+  // every caller that has no concept of them should behave exactly as before.
+  return allSpecs(dir, config, worktreePaths, specless)
+    .filter((s) => Boolean(viewFor(dir, config, s, git)))
     .sort((a, b) => a.folder.localeCompare(b.folder))
 }
 
@@ -207,7 +384,15 @@ function servableSpecs(dir, config, git) {
  * which is the harmless direction.
  */
 function receivePass(dir, config, spec, blob) {
-  if (!spec || !fs.existsSync(spec.worktreePath)) return null
+  // A VIEW, NOT A WORKTREE. The pending store lives in the checkout this server
+  // is anchored to, so accepting a pass needs no worktree — and requiring one
+  // rejected every verdict sent from an authoring page, which is the one page
+  // whose spec never has a worktree.
+  // `fallback: true` so the POST follows the PAGE. A reader who reloads a
+  // committed docs page gets buttons; rejecting what they press would be the
+  // failure this whole area keeps producing — a control that appears to do
+  // nothing. Whether the verdict is worth acting on is the routing's call.
+  if (!spec || !viewFor(dir, config, spec, rawGitReader(dir), { fallback: true })) return null
   let parsed
   try {
     parsed = validateNotesBlob(blob, spec.folder)
@@ -233,10 +418,96 @@ function receivePass(dir, config, spec, blob) {
   return { code: added.code, accepted: parsed.accepted.length, comments: parsed.comments.length }
 }
 
+/**
+ * The button set a SERVED page shows.
+ *
+ * Two sources, and each answers only what it knows.
+ *
+ * THE TREE ANSWERS THE FAMILY, and it answers it better than any record can,
+ * because a record is as old as the last render while the tree is now. A spec's
+ * uncommitted documents are `authoring`; a branch with no spec at all is
+ * `nospec`; a phase in a worktree is `committing`. Those three are exactly the
+ * sets that describe what the work IS, so they are read off what the work is.
+ *
+ * THE RECORD ANSWERS WHETHER THE RUN HAD FINISHED, which no tree can show.
+ * `midrun` and `refresh` exist for that — one offers `Continue` in place of the
+ * committing pair, the other drops the start verdict — and only the caller that
+ * rendered knew. So they, and nothing else, are taken from the record.
+ *
+ * WHICH MAKES THE RECORD NARROWING-ONLY. A word it does not recognise, a word
+ * that would WIDEN the offer, an unreadable file, no file at all: every one of
+ * them falls through to the tree (`.claude/rules/negative-checks.md` rule 4).
+ * The cost of a stale record is therefore a reader shown `Continue` where they
+ * could have been shown `Commit` — one refresh away from the right page — and
+ * never a specless branch handed a `Commit & Start` for a spec that does not
+ * exist. That was the bug: `renderSpecPage` took `{ branch }` and no set at all,
+ * so every `/no-spec` page served over http offered to put nothing in flight,
+ * and the pass came back naming a verdict its own skill could not act on.
+ */
+const NARROWING_SETS = ['midrun', 'refresh']
+
+function buttonsForView(viewKind, spec, recorded) {
+  if (NARROWING_SETS.includes(recorded)) return recorded
+  if (viewKind === 'docs' || viewKind === 'docs-committed') return 'authoring'
+  if (spec && spec.specless) return 'nospec'
+  return DEFAULT_BUTTON_SET
+}
+
+// What the last CLI render of this spec declared, or null when it declared
+// nothing readable. Never throws: the page is a convenience, and a sidecar is
+// not what it is for.
+function recordedButtons(dir, spec) {
+  try {
+    return readRenderRecord(reviewOutPath(dir, spec.folder, null), spec.folder).buttons
+  } catch {
+    return null
+  }
+}
+
 function renderSpecPage(dir, config, spec, { branch = false } = {}) {
-  if (!spec || !fs.existsSync(spec.worktreePath)) return null
+  const view = viewFor(dir, config, spec, rawGitReader(dir), { fallback: true })
+  if (!view) return null
+
+  // Resolved once, for BOTH paths below. The docs path used to hard-code
+  // `authoring` here and everything else took the default by saying nothing —
+  // which is how a specless branch ended up offering `Commit & Start`.
+  const buttons = buttonsForView(view.kind, spec, recordedButtons(dir, spec))
+
+  // THE DOCS VIEW IS A DIFFERENT TREE AND A DIFFERENT FILE SET. Its buttons
+  // come from `buttonsForView` above like every other view's — it used to name
+  // `authoring` here itself, which was right for this one case and left every
+  // other case with no answer at all.
+  if (view.kind === 'docs' || view.kind === 'docs-committed') {
+    const docsGit = rawGitReader(view.tree)
+    const out = reviewOutPath(dir, spec.folder, null)
+    const notes = readNotes(out, spec.folder).notes
+    const gateRead = readGate(out, spec.folder)
+    const data = collectReview({
+      spec,
+      git: docsGit,
+      mode: view.kind,
+      // A committed view diffs against the commit BEFORE HEAD's spec content —
+      // there is nothing uncommitted to compare, so the whole document is the
+      // content, exactly as an untracked file renders.
+      ref: view.kind === 'docs-committed' ? 'HEAD~1' : 'HEAD',
+      now: new Date().toISOString(),
+      notes,
+      gate: gateRead.corrupt ? null : gateRead.gate,
+      buttons,
+      only: view.owned,
+      treePath: view.tree,
+    })
+    return {
+      html: renderReviewPage(data, { reviewHtml: renderReviewBlock(data.review) }),
+      totals: data.totals,
+      mode: data.mode,
+      fellBack: false,
+    }
+  }
 
-  const git = rawGitReader(spec.worktreePath)
+  // `view.tree` rather than `spec.worktreePath`: the two differ for a live
+  // spec, whose branch is checked out here instead.
+  const git = rawGitReader(view.tree || spec.worktreePath)
   const trimmed = (argv) => {
     const out = git(argv)
     return out == null ? null : String(out).trim() || null
@@ -270,12 +541,40 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
   // is a convenience and the gate is not what it is for.
   const gate = gateRead.corrupt ? null : gateRead.gate
 
-  let data = collectReview({ spec, git, mode, ref, base: baseName, now, notes, gate })
+  // WHERE ELSE THIS REVIEW LIVES, and whether it is also running — the block
+  // above the verdicts. Worktree views only: a `--docs` page returns above,
+  // because a spec with no branch has nothing to put live.
+  const live = liveStateFor(spec, {
+    isolated: true,
+    onBase: headBranchOf(rawGitReader(dir)) !== spec.branch,
+    primaryBranch: headBranchOf(rawGitReader(dir)),
+    receipt: null,
+    worktreeExists: Boolean(spec.worktreePath && fs.existsSync(spec.worktreePath)),
+  })
+  const tiers = pageTiers(config)
+
+  let data = collectReview({
+    spec,
+    git,
+    mode,
+    ref,
+    base: baseName,
+    now,
+    notes,
+    gate,
+    buttons,
+    live,
+    tiers,
+  })
 
   if (!branch && data.totals.files === 0) {
     const fallbackBase = base()
     const mergeBase = trimmed(['merge-base', fallbackBase, 'HEAD'])
     if (mergeBase) {
+      // THE SET SURVIVES THE FALLBACK, and forgetting it here is not a smaller
+      // version of the same mistake — it is the one that fires most. A clean
+      // worktree is the state a phase ENDS in: the page is rendered, the commit
+      // lands, and from then on every render of that spec comes through here.
       const wider = collectReview({
         spec,
         git,
@@ -285,6 +584,9 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
         now,
         notes,
         gate,
+        buttons,
+        live,
+        tiers,
         fellBack: true,
       })
       if (wider.totals.files > 0) {
@@ -311,9 +613,51 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
  * same question in one call per spec; untracked files are counted separately
  * because `git diff` cannot see them.
  */
-function specSummary(spec) {
-  if (!spec || !fs.existsSync(spec.worktreePath)) return null
-  const git = rawGitReader(spec.worktreePath)
+/**
+ * Counts for a docs view: numstat over just this spec's owned paths.
+ *
+ * Untracked files are counted with `--no-index` against /dev/null, which is the
+ * only way git will diff a file it does not track — and a brand-new spec is
+ * entirely untracked, so without that half the index would show a spec with
+ * four documents as `0 files`.
+ */
+function docsSummary(view) {
+  const git = rawGitReader(view.tree)
+  const totals = { files: 0, additions: 0, deletions: 0 }
+  const add = (row) => {
+    const [a, d] = String(row).split('\t')
+    totals.files += 1
+    if (a === '-' || d === '-') return
+    totals.additions += Number(a) || 0
+    totals.deletions += Number(d) || 0
+  }
+  for (const rel of view.owned) {
+    const tracked = git(['diff', '--numstat', 'HEAD', '--', rel])
+    const rows = String(tracked || '').split('\n').filter(Boolean)
+    if (rows.length) {
+      rows.forEach(add)
+      continue
+    }
+    const untracked = git(['diff', '--no-index', '--numstat', '--', '/dev/null', rel])
+    String(untracked || '')
+      .split('\n')
+      .filter(Boolean)
+      .forEach(add)
+  }
+  return totals
+}
+
+function specSummary(spec, dir = null, config = null) {
+  // The index counts whatever the page would show, so it takes the same view.
+  // `dir`/`config` are optional so an existing caller counting a worktree spec
+  // is unchanged; without them only the worktree view can be counted.
+  const view = dir ? viewFor(dir, config, spec, rawGitReader(dir)) : null
+  if (view && view.kind === 'docs') return docsSummary(view)
+  // The tree the page would read, which for a live spec is this checkout. The
+  // worktree fallback keeps the callers that pass no `dir` working unchanged.
+  const tree = view && view.tree ? view.tree : spec && spec.worktreePath
+  if (!tree || !fs.existsSync(tree)) return null
+  const git = rawGitReader(tree)
 
   const totals = { files: 0, additions: 0, deletions: 0 }
   const add = (row) => {
@@ -388,7 +732,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
   })
 }
 
-function createReviewServer({ resolveEntries, render, receive = null, token = null }) {
+function createReviewServer({ resolveEntries, render, receive = null, passState = null, token = null }) {
   return http.createServer((req, res) => {
     const send = (code, body, type = 'text/html; charset=utf-8') => {
       res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
@@ -425,6 +769,22 @@ function createReviewServer({ resolveEntries, render, receive = null, token = nu
       return
     }
 
+    // THE READ THAT IS NOT A RENDER. It answers three words and never a diff,
+    // so a page polling it costs the server a file read rather than a patch.
+    //
+    // A SERVER BUILT WITHOUT THE LOOKUP SAYS SO, rather than 404ing or falling
+    // through to the diff page. An older daemon still running beside a newer
+    // page is the ordinary way here, and both of those answers would be read as
+    // something they are not — a 404 as "that pass does not exist", HTML as a
+    // parse failure. `unknown` is the one answer that keeps the command on the
+    // reader's screen, which is where it belongs when nothing can be
+    // established.
+    if (route.kind === 'pass') {
+      const out = passState ? passState(route.spec, route.code) : null
+      const state = out && typeof out.state === 'string' ? out.state : 'unknown'
+      return send(200, JSON.stringify({ state }), 'application/json; charset=utf-8')
+    }
+
     try {
       if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token }))
       const out = render(route.spec, { branch: route.branch })
@@ -496,10 +856,98 @@ function engineVersionFor(scriptPath) {
  * (a bundled build, an odd install layout). Both are answered `unknown`, and
  * neither is evidence of anything.
  */
-function staleServer(recorded, running) {
+function staleServer(recorded, running, recordedMtime, runningMtime) {
   if (typeof recorded !== 'string' || !recorded) return 'unknown'
   if (typeof running !== 'string' || !running) return 'unknown'
-  return recorded === running ? 'current' : 'stale'
+  if (recorded !== running) return 'stale'
+
+  // SAME VERSION IS NOT SAME CODE, which is the whole of this addition. The
+  // daemon runs a built copy of the engine — in this repo a symlink to the
+  // gitignored dist — so a rebuild moves the file without moving the version,
+  // and a version-only comparison adopted a process running last week's code.
+  // It cost two confidently wrong diagnoses in one session: a page reported as
+  // 404ing that the new code serves, and a regression reported as unfixed that
+  // had already been fixed.
+  //
+  // CANNOT TELL ADOPTS. A settings file written before this existed records no
+  // mtime, and an unreadable script has none to offer — restarting a healthy
+  // server over an absent field is the destructive reading, so an absent half
+  // falls back to the version verdict (rule 4).
+  const both = Number.isFinite(recordedMtime) && Number.isFinite(runningMtime)
+  if (both && recordedMtime !== runningMtime) return 'stale'
+  return 'current'
+}
+
+/**
+ * The hooks `createReviewServer` needs, built once.
+ *
+ * WHY THIS IS A FUNCTION AND NOT INLINE IN THE ENTRY POINT. It used to be
+ * inline, and the test suite built its own copy the same way — so the two
+ * drifted independently, and a suite standing up its own wiring could be green
+ * about a server nobody was shipping. That is exactly what happened: both
+ * copies called `resolveSpec` with no `specless` map, every `/no-spec` page
+ * 404'd, and nothing failed.
+ *
+ * THE SPECLESS MAP IS THE POINT. A `/no-spec` branch has a worktree and a
+ * branch and no document anywhere under `specs/**`, so it can only ever be
+ * resolved on the registry's word — which is a POSITIVE SIGNAL, and the reason
+ * a typo still 404s (`.claude/rules/negative-checks.md` rule 1). Both resolvers
+ * already took it; the server simply never passed it.
+ */
+function serverHooks(dir, config) {
+  const git = rawGitReader(dir)
+  const trimmedGit = (argv) => {
+    const out = git(argv)
+    return out == null ? null : String(out).trim() || null
+  }
+
+  // READ PER REQUEST, never cached. A branch provisioned after the daemon
+  // started must be servable without restarting it — the same reason `dir` is
+  // all the settings file stores. An unreadable registry is cannot-tell and
+  // yields an empty map: the specless branches lose their pages, and every
+  // ordinary spec carries on being served.
+  const specless = () => {
+    try {
+      return readRegistry(dir, config).specless || {}
+    } catch {
+      return {}
+    }
+  }
+
+  const resolveOne = (folder) => {
+    try {
+      return resolveSpec(folder, dir, config, {
+        searchDirs: [...liveWorktreePaths(trimmedGit)],
+        specless: specless(),
+      })
+    } catch {
+      return null
+    }
+  }
+
+  const resolveEntries = () =>
+    servableSpecs(dir, config, trimmedGit, specless()).map((s) => {
+      const one = resolveOne(s.folder)
+      return {
+        folder: s.folder,
+        branch: one ? one.branch : '',
+        totals: specSummary(one, dir, config),
+      }
+    })
+
+  return {
+    resolveEntries,
+    render: (folder, opts) => renderSpecPage(dir, config, resolveOne(folder), opts),
+    receive: (folder, blob) => receivePass(dir, config, resolveOne(folder), blob),
+    // A spec this daemon cannot resolve is not a pass that was claimed — it is
+    // a lookup that could not see, so it says nothing rather than reporting the
+    // comfortable answer. Same rule the engine's own three states follow.
+    passState: (folder, code) => {
+      const one = resolveOne(folder)
+      if (!one) return { state: 'unknown' }
+      return readPassState(reviewOutPath(dir, one.folder, null), one.folder, code)
+    },
+  }
 }
 
 module.exports = {
@@ -509,10 +957,15 @@ module.exports = {
   engineVersionFor,
   staleServer,
   specSummary,
+  viewFor,
+  headBranchOf,
+  pageTiers,
   routeFor,
   renderIndex,
   servableSpecs,
+  serverHooks,
   renderSpecPage,
+  buttonsForView,
   receivePass,
   createReviewServer,
   startReviewServer,
@@ -530,36 +983,7 @@ if (require.main === module) {
   }
   const { dir, port, host, token } = JSON.parse(fs.readFileSync(settingsFile, 'utf-8'))
   const { config } = loadEnvConfig(dir)
-  const git = rawGitReader(dir)
-  const trimmedGit = (argv) => {
-    const out = git(argv)
-    return out == null ? null : String(out).trim() || null
-  }
-
-  const resolveOne = (folder) => {
-    try {
-      return resolveSpec(folder, dir, config, { searchDirs: [...liveWorktreePaths(trimmedGit)] })
-    } catch {
-      return null
-    }
-  }
-
-  const resolveEntries = () =>
-    servableSpecs(dir, config, trimmedGit).map((s) => {
-      const one = resolveOne(s.folder)
-      return {
-        folder: s.folder,
-        branch: one ? one.branch : '',
-        totals: specSummary(one),
-      }
-    })
-
-  const server = createReviewServer({
-    resolveEntries,
-    render: (folder, opts) => renderSpecPage(dir, config, resolveOne(folder), opts),
-    receive: (folder, blob) => receivePass(dir, config, resolveOne(folder), blob),
-    token,
-  })
+  const server = createReviewServer({ ...serverHooks(dir, config), token })
   startReviewServer(server, { port, host }).then(
     () => {},
     (err) => {

package/src/env/supervise.js

@@ -147,4 +147,11 @@ async function waitHealthy(
   return false
 }
 
-module.exports = { startProcess, stopProcess, waitHealthy, isAlive, readPid }
+// `signalGroup` is exported for TESTS that need to simulate a process dying.
+// Killing the recorded pid alone is not that simulation: the pid is the detached
+// `sh -c` leader, and where the shell forks rather than execs, the real server
+// is its child and survives. A test that reaches for `process.kill(pid, …)`
+// therefore kills the wrapper, leaves the server holding its port, and then
+// blames whatever it asserts next. Killing the group is what `stopProcess` does
+// and what a test must do to mean "it died".
+module.exports = { startProcess, stopProcess, waitHealthy, isAlive, readPid, signalGroup }