@skitterbyte/skitterspec 20.0.0 → 22.0.0

package/src/cli.js

@@ -9,7 +9,38 @@ const {
   removeReleaseTooling,
   releaseToolingNotice,
 } = require('./deprecate.js')
-const { loadEnvConfig } = require('./env/config.js')
+const { loadEnvConfig, resolveServePort, servePortReason } = require('./env/config.js')
+
+// Named once so the advisory below and any future caller agree on the wording.
+const ENV_CONFIG_LABEL = 'env.config.json'
+
+// The `spec-env` verbs, in the order the usage line prints them. ONE list,
+// because two drifted: `live` and `stage` were each added to the dispatcher and
+// to this usage line while `--help` was left listing ten of twelve — separately,
+// months apart, which is what makes it a missing constraint rather than two
+// slips. An undocumented verb reads as a removed one.
+//
+// `cli-help-verbs.test.js` holds the three ends together: every verb here
+// appears in HELP, HELP names no verb that is not here, and this list matches
+// the `case` labels the dispatcher actually handles.
+//
+// The `review` SUB-ACTIONS (serve/arm/gate/skip) are deliberately absent — they
+// are arguments to `review`, not verbs, and the usage block spells them out on
+// their own lines below.
+const SPEC_ENV_VERBS = Object.freeze([
+  'up',
+  'down',
+  'prune',
+  'dev',
+  'connect',
+  'integrate',
+  'hotfix',
+  'live',
+  'review',
+  'stage',
+  'status',
+  'resolve',
+])
 const {
   readRegistry,
   writeRegistry,
@@ -39,6 +70,8 @@ const {
   summarizeReceipt,
   migrationsHit,
   planTake,
+  liveStateFor,
+  liveStateLine,
   planRelease,
   planAbort,
 } = require('./env/live.js')
@@ -46,6 +79,8 @@ const { ensureWorktreeDirTrusted } = require('./env/trust.js')
 const {
   rawGitReader,
   collectReview,
+  reviewTierStack,
+  reviewTierLine,
   renderReviewPage,
   renderReviewBlock,
   reviewOutPath,
@@ -61,6 +96,7 @@ const {
   reviewNotesPath,
   readNotes,
   writeNotes,
+  VERDICTS,
   validateNotesBlob,
   judgeVerdict,
   appendDecision,
@@ -69,6 +105,8 @@ const {
   writePending,
   claimPending,
   passesSince,
+  waitForPass,
+  waitingPasses,
   describePending,
   pendingAge,
   reviewPendingPath,
@@ -76,6 +114,8 @@ const {
   mergeNotes,
   applyResolutions,
   COMMITTING,
+  BUTTON_SETS,
+  DEFAULT_BUTTON_SET,
   reviewGatePath,
   readGate,
   writeGate,
@@ -84,7 +124,7 @@ const {
   gateState,
 } = require('./env/review.js')
 const { planUp, planCheckoutUp } = require('./env/provision.js')
-const { classifyDirtyTree } = require('./env/classify.js')
+const { classifyDirtyTree, dirtyPaths, specDocsIn } = require('./env/classify.js')
 const { isGitCommit } = require('./env/commitcmd.js')
 const { planDown, planDownCheckout } = require('./env/teardown.js')
 const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
@@ -93,7 +133,13 @@ const { planHotfixLand } = require('./env/hotfix.js')
 const { planDev } = require('./env/dev.js')
 const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
 const { renderRoutes, portsInUse, portsInUseOn, waitListening } = require('./env/proxy.js')
-const { mintToken, servableSpecs, engineVersionFor, staleServer } = require('./env/serve.js')
+const {
+  mintToken,
+  servableSpecs,
+  engineVersionFor,
+  staleServer,
+  pageTiers,
+} = require('./env/serve.js')
 
 const pkg = require('../package.json')
 
@@ -142,11 +188,16 @@ Usage:
                                 connect <spec>    expose a spec on the canonical ports (main = off)
                                 integrate <spec>  plan rebase + fast-forward onto the base branch
                                 hotfix land <spec>  tag + cherry-pick a hotfix (--also <tag>)
-                                status            list provisioned specs + port blocks
+                                live <spec>       check a spec out in the primary checkout so
+                                                  the running dev server serves it (take |
+                                                  release | abort | status; main hands it back)
                                 review <spec>     write an HTML page of the spec's diff
                                                   (--branch for the whole spec; --out, --json)
                                                   (--notes <json> merges a review pass back;
                                                    --resolve <json> records what was done)
+                                stage [spec]      split the uncommitted tree into this spec's
+                                                  documents and everything else
+                                status            list provisioned specs + port blocks
                                 resolve <spec>    print resolved slug/type/branch/paths
   skitterspec gating <cmd>    Release-gating check (opt-in; needs
                               specs/.core/gating.config.json). Subcommands:
@@ -269,6 +320,61 @@ async function cleanupReleaseTooling(dir, opts) {
  * `git worktree prune`) stays listed until pruned. That over-reports, which is
  * the harmless direction for a read-only report.
  */
+/**
+ * The reviews sidecar directory for this repo. Named once, because the scan and
+ * everything that renders it must agree on where to look.
+ */
+function reviewsDirFor(dir, config) {
+  return path.join(dir, stateDirLabel(config), 'reviews')
+}
+
+/**
+ * Render "what is waiting" for a human. Returns '' when nothing is — a repo
+ * with no waiting pass must read exactly as it did before this existed, so the
+ * heading is absent rather than printed over an empty list.
+ */
+function waitingSection(dir, config, now = new Date().toISOString()) {
+  const found = waitingPasses(reviewsDirFor(dir, config))
+  if (!found.passes.length && !found.unreadable.length) return ''
+  const width = Math.max(0, ...found.passes.map((p) => p.spec.length))
+  const rows = found.passes
+    .map(
+      (p) =>
+        `  ${p.spec.padEnd(width)}  ${p.code} · ${p.action || p.verdict || 'no verdict'} · ` +
+          `${pendingAge(p.at, now)}\n`,
+    )
+    .join('')
+  // Named, never counted as zero: an unreadable store holds someone's pass, and
+  // reporting "nothing waiting" over it is the one answer certainly wrong.
+  const broken = found.unreadable
+    .map((folder) => `  ${folder}: its pending store is not readable JSON — move it aside\n`)
+    .join('')
+  // The disown line only where there is something to disown. It is information
+  // beside a list, not an instruction to act on every pass in it.
+  const how = found.passes.length
+    ? '  disown one with: skitterspec spec-env review <spec> --drop <code>\n'
+    : ''
+  return `\nReviews waiting:\n${rows}${broken}${how}`
+}
+
+// `review waiting` — the same answer on its own, for a caller who wants only
+// this. It claims nothing and exits 0 whatever it finds: a waiting pass is
+// information, never an accusation.
+function specEnvReviewWaiting(dir, config, flags) {
+  const found = waitingPasses(reviewsDirFor(dir, config))
+  if (flags.json) {
+    // ABSENT, NOT EMPTY. A consumer that predates this must see a
+    // byte-identical object when there is nothing waiting.
+    const out = {}
+    if (found.passes.length) out.waiting = found.passes
+    if (found.unreadable.length) out.unreadable = found.unreadable
+    process.stdout.write(`${JSON.stringify(out, null, 2)}\n`)
+    return
+  }
+  const section = waitingSection(dir, config)
+  process.stdout.write(section ? `${section.replace(/^\n/, '')}` : 'spec-env review: nothing waiting.\n')
+}
+
 function specEnvStatus(dir, config) {
   const worktreePaths = liveWorktreePaths(gitReader(dir))
   const provisioned = allSpecs(dir, config, worktreePaths)
@@ -278,8 +384,11 @@ function specEnvStatus(dir, config) {
     .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
     .sort((a, b) => a.folder.localeCompare(b.folder))
 
+  // REACHED EITHER WAY. This used to return here, so a repo with nothing in
+  // flight could say nothing about a waiting pass — and a repo with nothing in
+  // flight is exactly where one hides longest.
   if (!provisioned.length) {
-    process.stdout.write('spec-env: no provisioned specs.\n')
+    process.stdout.write(`spec-env: no provisioned specs.\n${waitingSection(dir, config)}`)
     return
   }
 
@@ -294,6 +403,7 @@ function specEnvStatus(dir, config) {
     }
     process.stdout.write(`  ${folder}${ports}\n    ${path.relative(dir, wt) || wt}\n`)
   }
+  process.stdout.write(waitingSection(dir, config))
 }
 
 // Plan a provision: allocate the slot, persist the registry, and print the plan
@@ -301,49 +411,6 @@ function specEnvStatus(dir, config) {
 // This creates no worktree and starts no stack — the caller runs the
 // printed commands. Keep the output's verb honest about that.
 
-// git quotes a path containing unusual bytes and C-escapes it. Unquote what we
-// can; anything we cannot parse confidently is returned as-is, which makes it
-// fail the spec-folder comparison and land in `foreign` — a refusal, which is the
-// safe direction to be wrong in.
-function unquotePath(p) {
-  if (!p.startsWith('"') || !p.endsWith('"')) return p
-  try {
-    return JSON.parse(p)
-  } catch {
-    return p
-  }
-}
-
-/**
- * Repo-relative paths of everything uncommitted. Returns null when git could not
- * be read at all — the caller must treat that as "nobody looked", never "clean".
- *
- * Two prefix-free listings rather than `git status --porcelain`, deliberately.
- * Porcelain prefixes every path with a two-character status field, and the shared
- * git reader TRIMS its output — which eats the leading space of the first line
- * only, so a fixed-offset parse silently returned `EADME.md` for `README.md`.
- * These emit bare paths, so there is no offset to get wrong. `--others` also
- * lists untracked files INDIVIDUALLY, where porcelain collapses them into their
- * topmost untracked directory — reporting a brand-new spec as `specs/backlog/`,
- * an ancestor attributable to no single spec, and so refusing the very tree this
- * gate exists to accept. Both were found by running it, not by reading it.
- */
-function dirtyPaths(git) {
-  const lists = [
-    git(['diff', '--name-only', 'HEAD']),
-    git(['ls-files', '--others', '--exclude-standard']),
-  ]
-  if (lists.every((l) => l === null)) return null
-  const out = []
-  for (const list of lists) {
-    if (!list) continue
-    for (const line of list.split('\n')) {
-      const q = line.trim()
-      if (q) out.push(unquotePath(q))
-    }
-  }
-  return out
-}
 
 // Is this spec new to git? Asked directly, so the commit subject does not depend
 // on the shape of `git status` output.
@@ -1615,6 +1682,54 @@ function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
   process.stdout.write(out.join('\n') + '\n')
 }
 
+/**
+ * The tree and the file set behind `review --docs`: this spec's own uncommitted
+ * documents, in the checkout the caller is standing in.
+ *
+ * It is `stage`'s split, reused rather than re-derived — same tree resolution,
+ * same `classifyDirtyTree`. THE `owned` HALF IS WHAT MAKES THIS SAFE TO RENDER:
+ * a checkout is shared by every session standing in it, so the uncommitted tree
+ * routinely holds spec documents this spec has no claim on. Rendering the tree
+ * would put them on this page, and a committing verdict here would then commit
+ * them under this spec's ticket.
+ *
+ * WHAT WOULD FOOL THIS: nothing, for a path outside the spec's folder that the
+ * project declared a companion — those are owned by construction. What it
+ * cannot see is a document belonging to this spec that is already committed:
+ * `dirtyPaths` answers about the uncommitted tree only, so a spec whose files
+ * are all committed renders as nothing to review rather than as its own text.
+ * That is the intended reading — there is no change to review — and it is why
+ * the empty case says so instead of drawing an empty page.
+ *
+ * Three states, never two (`.claude/rules/negative-checks.md` rule 4). A git
+ * that could not be read is `cannot tell`, and must not become an empty file
+ * set: an empty set renders a page saying nothing changed, which is the one
+ * reading that is certainly wrong.
+ *
+ * @returns {{tree: string, owned: string[]}|{error: string}}
+ */
+function resolveSpecDocs(config, spec, invokedFrom) {
+  const git = gitReader(invokedFrom)
+  const tree = git(['rev-parse', '--show-toplevel']) || invokedFrom
+  // THE CLASSIFICATION IS SHARED with the review server's route for the same
+  // spec (`specDocsIn`), so the served page and the written page cannot
+  // disagree about which files they show. This function adds only the wording.
+  const found = specDocsIn(tree, spec, config, gitReader(tree))
+  if (found.error) {
+    return {
+      error:
+        `git could not be read at ${tree}, so ${spec.folder}'s documents were not classified — ` +
+        'nothing rendered. This is not "nothing to review".',
+    }
+  }
+  if (found.empty) {
+    return {
+      error: `${spec.folder} has no uncommitted documents in ${tree} — nothing to review.`,
+    }
+  }
+  return found
+}
+
 /**
  * Write a self-contained HTML review of a spec's diff.
  *
@@ -1633,6 +1748,14 @@ function verdictSaid(v) {
   // thing that will happen to the repo and the reader should see it coming.
   if (v.effective === 'commit') return `committing with ${v.commitWith}`
   if (v.effective === 'commit-continue') return `committing with ${v.commitWith}, then the next phase`
+  // EVERY COMMITTING VERDICT NEEDS A LINE HERE, and the fall-through below is
+  // why: a verdict this function does not know reads as `discuss first`, so a
+  // reader who pressed a green button would be told their review ended in a
+  // conversation. Adding one to `COMMITTING` and not to this list is silent.
+  if (v.effective === 'commit-start') return `committing with ${v.commitWith}, then putting it in flight`
+  // Names what it does NOT do, because the reader of a mid-run page has just
+  // pressed a green button and must not read it as a commit.
+  if (v.effective === 'continue') return 'read — carrying on, nothing committed'
   if (v.effective === 'changes') return 'changes requested'
   return 'discuss first'
 }
@@ -1657,6 +1780,97 @@ function gateTarget(dir, config, specArg) {
   }
 }
 
+/**
+ * `review wait` — block until a verdict arrives, so nobody has to improvise it.
+ *
+ * THE COMMAND EXISTS BECAUSE THE WAIT DID NOT. The skills said "watch the
+ * pending store and end your turn", so every run wrote its own watcher in
+ * shell — and one of them wrote `[ "$x" \> "$y" ]`, which is valid bash and a
+ * syntax error in zsh. It could never be true, spun for five minutes, and
+ * looked exactly like patience the whole time.
+ *
+ * So this says it started. A caller can then tell a live wait from a dead one,
+ * which is the one thing none of the improvised watchers could offer.
+ *
+ * It is a WAIT and not a claim: the pass is left in the holding area for
+ * `--claim-since` to take, so the rule that a pass is never claimed without a
+ * person asking (`/spec-diff` §0) is untouched by anything here.
+ */
+async function specEnvReviewWait(dir, config, specArg, flags) {
+  let spec
+  try {
+    spec = resolveSpecWithWorktree(dir, config, specArg)
+  } catch (err) {
+    process.stdout.write(`spec-env review wait: ${err.message}\n`)
+    process.exitCode = 1
+    return
+  }
+
+  // A WINDOW IS REQUIRED, and an absent one is not an open one. Without it
+  // there is no way to tell this sitting's pass from a stranger's, and waiting
+  // for "any pass at all" is how one gets swept up.
+  if (!flags.since) {
+    process.stdout.write(
+      'spec-env review wait: --since <iso> is required — it is the window that decides which pass is yours\n',
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const out = reviewOutPath(dir, spec.folder, flags.out)
+  const timeoutMs =
+    flags.timeout === undefined || flags.timeout === null ? null : Number(flags.timeout) * 1000
+  if (timeoutMs !== null && !Number.isFinite(timeoutMs)) {
+    process.stdout.write(`spec-env review wait: --timeout ${flags.timeout} is not a number of seconds\n`)
+    process.exitCode = 1
+    return
+  }
+
+  // SAID BEFORE THE FIRST POLL, not after it. The whole point is that a caller
+  // knows the wait is running; a line printed on the way out would arrive only
+  // for the waits that already worked.
+  if (!flags.json) {
+    process.stdout.write(
+      `spec-env review wait: ${spec.folder} — waiting for a verdict sent since ${flags.since}` +
+        `${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}\n`,
+    )
+  }
+
+  const result = await waitForPass(() => readPending(out, spec.folder), flags.since, { timeoutMs })
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify({ spec: spec.folder, since: flags.since, ...result }, null, 2)}\n`)
+  }
+
+  if (result.state === 'arrived') {
+    if (!flags.json) {
+      process.stdout.write(
+        `  arrived: ${result.code}\n` +
+          `  claim it: skitterspec spec-env review ${spec.folder} --claim-since ${flags.since}\n`,
+      )
+    }
+    return
+  }
+
+  process.exitCode = 1
+  if (flags.json) return
+
+  if (result.state === 'unusable') {
+    process.stdout.write(`  --since ${flags.since} is not a timestamp — nothing to wait inside\n`)
+    return
+  }
+  if (result.state === 'ambiguous') {
+    // NAMES THE COUNT, NEVER THE CODES — the same silence `--claim-since` keeps.
+    // Two in one window is two sittings or two people, and the operator has the
+    // codes; printing them here would hand a guesser the answer.
+    process.stdout.write(
+      `  ${result.count} passes arrived in that window — claim one by its code rather than guessing\n`,
+    )
+    return
+  }
+  process.stdout.write('  timed out — no verdict arrived in the window\n')
+}
+
 // `review arm` — a phase ended, and its diff is now owed a verdict.
 function specEnvReviewArm(dir, config, specArg, flags) {
   const target = gateTarget(dir, config, specArg)
@@ -1782,6 +1996,134 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
   if (flags.check && judged.state === 'armed') process.exitCode = 1
 }
 
+/**
+ * `review allow <network|remote> [--off]` — permit or withdraw a review tier.
+ *
+ * THE FIRST THING IN THIS ENGINE TO WRITE `env.config.json`, and that is why it
+ * is narrow: it reads, sets one key under `review`, and writes back with the
+ * indent the file already uses. It never reorders, never adds a key nobody
+ * asked for, and never touches another section.
+ *
+ * WHAT WOULD FOOL THIS: a config written with comments. `loadEnvConfig` parses
+ * it with `JSON.parse`, so such a file already fails to load and there is no
+ * comment-preserving case to protect — but a file indented with anything other
+ * than two spaces IS reformatted, which is cosmetic and worth knowing before it
+ * shows up in someone's diff.
+ *
+ * IT EDITS A COMMITTED FILE. Turning network reviews on for yourself turns them
+ * on for everyone who pulls, so the output says so rather than leaving it to be
+ * discovered by a colleague's render.
+ */
+function specEnvReviewAllow(dir, config, tier, flags) {
+  const TIERS = { network: 'allowNetwork', remote: 'allowRemote' }
+  const key = TIERS[String(tier || '').trim()]
+  if (!key) {
+    // Refused by name, never coerced to a default: silently permitting the
+    // wrong tier is the one outcome worth more than a round trip.
+    process.stdout.write(
+      `spec-env review allow: ${JSON.stringify(tier || '')} is not a tier — ` +
+        `one of ${Object.keys(TIERS).join(', ')}. Nothing changed.\n`,
+    )
+    process.exitCode = 1
+    return
+  }
+  // THREE WAYS TO SAY WHAT THE TIER SHOULD BE, and only the third is new.
+  // Bare `allow <tier>` turns it ON and `--off` turns it off, exactly as they
+  // always have — every existing caller and test reads those.
+  //
+  // `--set` exists because a SLASH COMMAND can only make one static
+  // substitution: `/spec-remote-review on` has to reach the engine as the word
+  // the person typed, not as a flag the command file worked out. An EMPTY value
+  // is the bare form of that command, and it toggles — which is the common case,
+  // because a reader flipping a tier is looking at the line that says which way
+  // it currently is.
+  let on = !flags.off
+  if (flags.set !== undefined) {
+    const said = String(flags.set).trim().toLowerCase()
+    if (said === '') {
+      // Toggle. Read through the same precedence the report below uses, so
+      // "turn it to the other thing" means the other thing the render showed.
+      const current = Boolean(
+        (() => {
+          try {
+            const now = JSON.parse(fs.readFileSync(path.resolve(dir, 'specs/.core/env.config.json'), 'utf8'))
+            return now.review && now.review[key] !== undefined ? now.review[key] : config.review[key]
+          } catch {
+            return config.review[key]
+          }
+        })(),
+      )
+      on = !current
+    } else if (said === 'on' || said === 'off') {
+      on = said === 'on'
+    } else {
+      // Refused by name, like an unknown tier. A misspelt state coerced to a
+      // default is the one outcome worth more than a round trip — and the
+      // wrong default here opens a port or permits a publish.
+      process.stdout.write(
+        `spec-env review allow: ${JSON.stringify(String(flags.set))} is not a state — ` +
+          'one of on, off, or nothing at all to toggle. Nothing changed.\n',
+      )
+      process.exitCode = 1
+      return
+    }
+  }
+  const file = path.resolve(dir, 'specs/.core/env.config.json')
+  let parsed
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (err) {
+    // Cannot tell what is in there, so write nothing. Overwriting a config we
+    // could not read is unrecoverable, and the alternative costs one message.
+    //
+    // NARROWER THAN IT LOOKS: `loadEnvConfig` already refuses the whole
+    // `spec-env` command on an unparseable config, naming the file and the
+    // parse position — so this branch is reachable only if the file changes
+    // between that load and this write. It is kept for that race rather than
+    // deleted as dead, and the upstream refusal is what the test asserts.
+    process.stdout.write(
+      `spec-env review allow: ${file} could not be read as JSON (${err.message}) — ` +
+        'nothing changed.\n',
+    )
+    process.exitCode = 1
+    return
+  }
+  const before = Boolean(
+    parsed.review && parsed.review[key] !== undefined ? parsed.review[key] : config.review[key],
+  )
+  parsed.review = { ...(parsed.review || {}), [key]: on }
+  fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + '\n')
+
+  const lines = [
+    `spec-env review allow: ${tier} reviews are now ${on ? 'ON' : 'OFF'}` +
+      (before === on ? ' (unchanged)' : ''),
+    // THE ABSOLUTE PATH, not one relative to `dir`. `dir` is re-anchored to the
+    // primary checkout, so run from inside a worktree this writes a file in a
+    // DIFFERENT TREE — and a relative path reads as the tree you are standing
+    // in. Found by running it from a worktree and reverting the surprise.
+    `  wrote: ${file}`,
+    '  that is the primary checkout, whichever tree you ran this from, and the file is',
+    '  COMMITTED — so it changes for everyone who pulls, and leaves that tree dirty.',
+  ]
+  if (key === 'allowNetwork') {
+    lines.push(
+      on
+        ? '  the next render binds every interface, so the page opens on your phone.'
+        : '  the next render binds 127.0.0.1 only, reachable from this machine.',
+    )
+  } else {
+    lines.push(
+      on
+        ? '  this PERMITS publishing; it publishes nothing. A published page cannot be\n' +
+          '  deleted by skitterspec, and a verdict there needs /spec-reviewed.\n' +
+          '  turn it back off with: /spec-remote-review'
+        : '  publishing is no longer permitted; any page already published stays up.\n' +
+          '  turn it back on with: /spec-remote-review',
+    )
+  }
+  process.stdout.write(lines.join('\n') + '\n')
+}
+
 // `review skip` — move on without a verdict, on the record.
 function specEnvReviewSkip(dir, config, reason, flags) {
   const said = String(reason || '').trim()
@@ -1826,26 +2168,89 @@ function specEnvReviewSkip(dir, config, reason, flags) {
   )
 }
 
-async function specEnvReview(dir, config, specArg, flags) {
+async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
+  // REFUSED BY NAME, never coerced to the default. A typo'd button set silently
+  // rendering the committing page is the same failure the verdict validator
+  // refuses for the same reason: a caller asking for the mid-run page and
+  // getting the committing one would offer a reader a commit on unfinished
+  // work, and nothing would have said so.
+  if (flags.buttons !== null && !BUTTON_SETS.includes(flags.buttons)) {
+    process.stdout.write(
+      `spec-env review: --buttons ${JSON.stringify(flags.buttons)} is not one of ` +
+        `${BUTTON_SETS.join(', ')} — nothing rendered.\n`,
+    )
+    return
+  }
+  const buttons = flags.buttons || DEFAULT_BUTTON_SET
+
   // An unknown name throws here rather than falling back to the branch: a review
   // of the wrong spec looks exactly like a review of the right one.
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
+  // `--docs` reviews the spec's OWN DOCUMENTS from the tree in hand, and so
+  // never consults a worktree — a spec in `backlog/` has none, which is exactly
+  // the case with no page today.
+  let docs = null
+  if (flags.docs) {
+    docs = resolveSpecDocs(config, spec, invokedFrom)
+    if (docs.error) {
+      process.stdout.write(`spec-env review: ${docs.error}\n`)
+      return
+    }
+  }
+
   // The worktree is what we read; without it there is nothing to say. This is an
   // absence that means something — `git worktree list` is the same source that
   // resolved the path — so it is safe to act on.
-  if (!fs.existsSync(spec.worktreePath)) {
+  //
+  // It names `--docs` because for a spec that has landed or has not yet started,
+  // provisioning a worktree is not what the reader wanted: they wanted to read
+  // the spec.
+  // A LIVE SPEC IS THE EXCEPTION, and it is not a loosening of this absence.
+  // `live take` moves the branch into the primary checkout, so the work is
+  // somewhere readable even when the worktree has gone — refusing here would
+  // refuse a spec whose diff is right there. Every other missing worktree still
+  // refuses exactly as before.
+  const liveHere = (() => {
+    try {
+      const st = assertPrimaryOnMain(config, gitReader(dir))
+      return st.onBase === false && st.branch === spec.branch
+    } catch {
+      return false
+    }
+  })()
+  if (!docs && !liveHere && !fs.existsSync(spec.worktreePath)) {
     process.stdout.write(
       `spec-env review: ${spec.folder} has no worktree at ${spec.worktreePath} — ` +
-        'run /spec-start to provision it.\n',
+        'run /spec-start to provision it, or --docs to review the spec itself.\n',
     )
     return
   }
 
-  const git = rawGitReader(spec.worktreePath)
-  const trimmed = gitReader(spec.worktreePath)
+  // WHERE THE BRANCH ACTUALLY IS. `live take` detaches the worktree and checks
+  // the branch out in the primary checkout, so while a spec is live the tree
+  // holding its work — including anything uncommitted, since a fix made while
+  // live is made there — is the primary checkout. Reading the worktree then
+  // reports a clean tree and shows the reader nothing.
+  //
+  // WHAT WOULD FOOL THIS: it trusts the branch the primary checkout is on, so a
+  // branch checked out there by hand with no receipt still reads as live. That
+  // is the right answer — the work IS there — and it is the same authority
+  // `assertPrimaryOnMain` and `liveStateFor` use.
+  const primaryState = assertPrimaryOnMain(config, gitReader(dir))
+  const live = liveStateFor(
+    spec,
+    liveContext(dir, config, spec, {
+      onBase: primaryState.onBase,
+      primaryBranch: primaryState.branch,
+    }),
+  )
+
+  const readFrom = docs ? docs.tree : live.state === 'on' ? dir : spec.worktreePath
+  const git = rawGitReader(readFrom)
+  const trimmed = gitReader(readFrom)
 
-  let mode = 'working'
+  let mode = docs ? 'docs' : 'working'
   let ref = 'HEAD'
   let base = null
 
@@ -1928,6 +2333,39 @@ async function specEnvReview(dir, config, specArg, flags) {
     claimCode = window.codes[0]
   }
 
+  // ONE VERDICT PER INVOCATION, and this refuses rather than reconciles. The
+  // three ways a verdict arrives can carry three different words, and there is
+  // no honest rule for picking between them: acting on either would commit
+  // somebody's work on the strength of a word they did not mean as the answer.
+  // Refused BEFORE anything is looked up, so a rejected combination cannot also
+  // spend a pending code or read a blob off disk.
+  if (flags.verdict && (flags.claim || flags.claimSince || flags.notes)) {
+    process.stdout.write(
+      'spec-env review: --verdict carries one verdict and so does ' +
+        `${flags.notes ? '--notes' : '--claim'} — send one, not both\n`,
+    )
+    return
+  }
+
+  // A VERDICT WITH NOTHING ATTACHED — the word a `file://` page hands over when
+  // the pass it would otherwise build carries nothing but the conclusion. It
+  // joins the same merge below rather than forking: `judgeVerdict` still
+  // refuses a commit over open comments, the log still records it, and the gate
+  // still clears. What it cannot carry is marks, and it does not pretend to —
+  // `merged` stays null, because nothing was.
+  if (flags.verdict) {
+    const word = String(flags.verdict).trim()
+    if (!VERDICTS.includes(word)) {
+      // The engine's own vocabulary, named in full. A word refused without the
+      // list is a typo the reader has to go looking for.
+      process.stdout.write(
+        `spec-env review: verdict "${word}" is not one of ${VERDICTS.join(', ')}\n`,
+      )
+      return
+    }
+    sentVerdict = word
+  }
+
   // A CLAIM IS A DELIVERY MECHANISM, not a second kind of review. It lifts a
   // pass out of the holding area and hands it to exactly the same merge a
   // pasted blob goes through, so nothing downstream can tell — or behave
@@ -2090,7 +2528,16 @@ async function specEnvReview(dir, config, specArg, flags) {
       // The log is appended only for a verdict that was ACTED ON. A refused
       // approval did not happen, and recording it as history would leave a
       // trail of decisions the repo never took.
-      notes = appendDecision(notes, { verdict: judged.effective, at: new Date().toISOString() })
+      // THE CODE GOES IN THE LOG, and it is the only present thing that lets
+      // the page conclude a pass was picked up. Without it `claimed` could only
+      // be read off the code being gone from the holding area — which `--drop`,
+      // a moved store and a mistyped folder all achieve without anyone claiming
+      // anything. Null for a pasted blob, which carried no code to record.
+      notes = appendDecision(notes, {
+        verdict: judged.effective,
+        at: new Date().toISOString(),
+        code: claimed ? claimed.code : null,
+      })
       writeNotes(out, notes)
     }
     verdictReport = {
@@ -2166,7 +2613,23 @@ async function specEnvReview(dir, config, specArg, flags) {
   const gate = gateNow.corrupt ? null : gateNow.gate
 
   const now = new Date().toISOString()
-  let data = collectReview({ spec, git, mode, ref, base, now, notes, gate })
+  // The surfaces block, on a worktree view only: a `--docs` page belongs to a
+  // spec with no branch to put live (decision 6), so it carries neither key and
+  // renders exactly as it did before this existed.
+  const surfaceArgs = docs ? {} : { live, tiers: pageTiers(config) }
+  let data = collectReview({
+    spec,
+    git,
+    mode,
+    ref,
+    base,
+    now,
+    notes,
+    gate,
+    buttons,
+    ...surfaceArgs,
+    ...(docs ? { only: docs.owned, treePath: docs.tree } : {}),
+  })
 
   // A CLEAN WORKING TREE IS NOT "NOTHING TO REVIEW". It is the state a phase
   // ends in: the page is rendered before the commit, the commit happens
@@ -2182,8 +2645,14 @@ async function specEnvReview(dir, config, specArg, flags) {
   // An explicit `--branch` is never re-interpreted, and a non-empty working tree
   // is never swapped out from under the reader. The swap only ever replaces an
   // empty view, so no information is lost by it.
+  //
+  // `--docs` NEVER FALLS BACK. Its file set is this spec's documents and the
+  // branch range is every file on the branch, so the swap would replace "the
+  // spec you asked for" with "everything this branch changed" — and on the base
+  // branch, where a backlog spec is read, that range is the whole of main. The
+  // empty case is already refused above, so there is nothing here to rescue.
   let fellBack = false
-  if (!flags.branch && data.totals.files === 0) {
+  if (!docs && !flags.branch && data.totals.files === 0) {
     const fallbackBase = reviewBase()
     const mergeBase = trimmed(['merge-base', fallbackBase, 'HEAD'])
     // Cannot tell -> do nothing, exactly as the `--branch` path refuses. No
@@ -2199,6 +2668,8 @@ async function specEnvReview(dir, config, specArg, flags) {
         now,
         notes,
         gate,
+        buttons,
+        ...surfaceArgs,
         fellBack: true,
       })
       if (wider.totals.files > 0) {
@@ -2249,8 +2720,41 @@ async function specEnvReview(dir, config, specArg, flags) {
   // nothing at all: the ordinary render must read exactly as it did before any
   // of this existed.
   let serverSaid = null
-  if (reader.reader === 'remote' && config.review.serveOnRemote) {
-    const up = await ensureReviewServer(dir, config, { host: '0.0.0.0' })
+  // EVERY RENDER SERVES, because a `file://` page has no server to POST to and
+  // so its verdict buttons have nowhere to go. The reader is not consulted here
+  // any more — that gate is what handed a local machine a page it could read
+  // and not answer.
+  //
+  // THE BIND STILL COMES FROM THE READER, and that is what makes this free of
+  // new exposure: a remote reader binds every interface exactly as before, and
+  // a local or unknown one binds loopback — `http://127.0.0.1` instead of
+  // `file://`, which opens on the machine holding the page and, unlike
+  // `file://`, can POST. Cannot-tell binds loopback, the harmless direction
+  // (`.claude/rules/negative-checks.md` rule 4).
+  // WHY THERE IS NO SERVED URL, when there is none. The `file://` line used to
+  // mean "nobody asked for serving"; now that every render asks, it can only
+  // mean the ask did not land — so the render says which: the operator turned
+  // it off, or it failed and here is the reason.
+  let noServeBecause = config.review.serve === 'never' ? 'review.serve is "never"' : null
+  if (config.review.serve === 'always') {
+    // THE BIND COMES FROM THE SETTING, not from a guess about the reader. That
+    // guess was the last decision detection had, and it was wrong every time the
+    // reader moved — a phone off the LAN, a local session reading a page whose
+    // buttons cannot POST. `allowNetwork` is the project saying which surfaces
+    // it permits, and the reader picks from what is listed.
+    const host = config.review.allowNetwork ? '0.0.0.0' : '127.0.0.1'
+    const up = await ensureReviewServer(dir, config, { host })
+    // TRANSLATED, because `error` is a code for a caller and this line is read
+    // by a person: `busy` alone does not say which port, and the port is the
+    // whole of what they can act on. An unmapped code is passed through rather
+    // than swallowed — a reason nobody anticipated still beats silence.
+    if (up.error === 'busy') {
+      noServeBecause = `port ${up.port} is already in use`
+    } else if (up.error === 'unreadable') {
+      noServeBecause = `a server is running (pid ${up.pid}) whose settings could not be read`
+    } else if (up.error) {
+      noServeBecause = String(up.error)
+    }
     if (up.replaced === 'engine') {
       serverSaid = up.error
         ? // BOTH facts. A reader told only "could not start" cannot see why it
@@ -2264,7 +2768,7 @@ async function specEnvReview(dir, config, specArg, flags) {
       // The URLs come from the bind the server HAS, not the one asked for just
       // above — adoption can hand back a loopback server whatever was
       // requested. See `reviewServedUrls`.
-      const urls = reviewServedUrls(up, lanAddresses(), spec.folder)
+      const urls = reviewServedUrls(up, offerableLanAddresses(), spec.folder)
       if (urls) {
         served = { ...urls, port: up.port, token: up.token, started: up.started }
       }
@@ -2277,20 +2781,47 @@ async function specEnvReview(dir, config, specArg, flags) {
         {
           spec: spec.folder,
           branch: spec.branch,
-          worktree: spec.worktreePath,
+          // The tree the diff was read from — `spec.worktreePath` for every
+          // mode but `docs`, where it would name a path that does not exist.
+          worktree: readFrom,
           mode,
           base,
           fellBack,
+          // The paths a committing verdict on this page must commit, so the
+          // skill that routes on it never recomputes the set the reader saw.
+          // Absent for every other mode, which keeps their output identical.
+          ...(docs ? { docs: { paths: docs.owned } } : {}),
           out,
           publishCopy,
           reader: reader.reader,
           readerWhy: reader.why,
           served,
+          // The same stack the text prints, so a skill reads the tiers rather
+          // than parsing prose — and the two can never disagree, because both
+          // come from `reviewTierStack`.
+          tiers: reviewTierStack({
+            served,
+            fileUrl: reviewFileUrl(out),
+            publishedUrl: url,
+            config,
+          }),
+          // The same answer `live status --json` gives, from the same function,
+          // so the page and the command cannot disagree. Always present, unlike
+          // the tiers' optional keys: `unavailable` is a state a consumer needs
+          // to see rather than an absence it has to interpret.
+          live,
+          // Absent when there IS a served URL, so a consumer that only ever
+          // saw a served render sees no new key.
+          ...(served ? {} : noServeBecause ? { notServed: noServeBecause } : {}),
           ...(serverSaid ? { server: serverSaid } : {}),
           fileUrl: reviewFileUrl(out),
           urlFile,
           url,
           notesFile: reviewNotesPath(out),
+          // Absent stays absent, exactly as it is in the page payload: the
+          // committing set is what a caller that did not ask always got, so
+          // reporting it would make every existing consumer see a new key.
+          ...(data.buttons ? { buttons: data.buttons } : {}),
           reviewed: Boolean(data.review),
           totals: data.totals,
           notes: data.notes,
@@ -2357,7 +2888,10 @@ async function specEnvReview(dir, config, specArg, flags) {
       (waiting.length
         ? `  pending: ${waiting.length} waiting\n` +
           waiting
-            .map((p) => `    ${p.code} · ${p.verdict || 'no verdict'} · ${pendingAge(p.at, now)}\n`)
+            .map(
+              (p) =>
+                `    ${p.code} · ${p.action || p.verdict || 'no verdict'} · ${pendingAge(p.at, now)}\n`,
+            )
             .join('')
         : '') +
       (outcomeSaid ? `  outcome: ${outcomeSaid}\n` : '') +
@@ -2373,39 +2907,45 @@ async function specEnvReview(dir, config, specArg, flags) {
         ? ''
         : `  reader: ${reader.reader}${reader.why ? ` (${reader.why})` : ''}\n`) +
       `  page: ${out}\n` +
-      // Served: the `open:` line is a URL the reader can actually use, and
-      // `page:` above still says where the file is. Not served — including every
-      // way serving can fail — falls back to exactly the output this printed
-      // before, dead link and all: that is the floor, never made worse.
-      (served
-        ? `  open: ${served.url}\n` +
-          // Said only when there is a runner-up. One address is not a choice,
-          // and an `also:` line naming nothing reads as a warning.
-          (served.alternates.length
-            ? served.alternates.map((u) => `  also: ${u}\n`).join('')
-            : '') +
-          // A loopback server is reachable from this machine and nowhere else.
-          // Said here rather than left to be discovered by a phone that cannot
-          // open the URL — and it names the command instead of describing it.
-          (served.loopback
-            ? '  local only: this server is bound to 127.0.0.1 — not reachable from your phone.\n' +
-              `  widen: ${served.widen}\n`
-            : '') +
-          (served.started && !served.loopback
-            ? '  serving: every provisioned spec, to anyone with this URL on your network.\n' +
-              '  stop:  skitterspec spec-env review serve --stop\n'
-            : '') +
-          // One line, and only when something was actually done on the reader's
-          // behalf. An action nobody asked for is reported, not hidden — the
-          // same rule teardown follows.
-          (serverSaid ? `  ${serverSaid}\n` : '')
-        : `  open: ${reviewFileUrl(out)}${
-            reader.reader === 'remote' ? '   (will not open where you are reading)' : ''
-          }\n` +
-          (serverSaid ? `  ${serverSaid}\n` : '') +
-          (reader.reader === 'remote'
-            ? '  serve: skitterspec spec-env review serve --host 0.0.0.0\n'
-            : '')) +
+      // THE STACK, in a fixed order, every tier named. The single `open:` line
+      // it replaces asked the engine to pick which surface the reader could
+      // use, and the engine cannot know — that guess failed three separate ways
+      // in one day. Now every tier is listed, labelled, and either a URL or the
+      // one command that turns it on.
+      reviewTierStack({
+        served,
+        fileUrl: reviewFileUrl(out),
+        publishedUrl: url,
+        config,
+      })
+        .map((t) => reviewTierLine(t) + '\n')
+        .join('') +
+      // The runners-up sit UNDER the network tier, because that is what they are
+      // alternatives to — and virtual adapters are gone from them entirely.
+      (served && !served.loopback && (served.alternates || []).length
+        ? served.alternates.map((u) => `    also:  ${u}\n`).join('')
+        : '') +
+      // WHICH TIERS THE WAIT COVERS, once, next to the stack. `local` and
+      // `network` are two doors into one room — the page POSTs to
+      // `location.pathname`, so both reach this server and this pending store.
+      // `remote` writes to the artifact's own store, which nothing here can see.
+      '  the wait covers local + network; a remote verdict needs /spec-reviewed.\n' +
+      // WHETHER IT IS ALSO RUNNING SOMEWHERE, which is the other way to judge a
+      // change. `unavailable` prints nothing — see `liveStateLine`.
+      (liveStateLine(live) ? `${liveStateLine(live)}\n` : '') +
+      // The reason there is no served URL, when there is none. A `file://` link
+      // with nothing said about it reads as the ordinary outcome, and it is not.
+      (!served && noServeBecause ? `  not served: ${noServeBecause}\n` : '') +
+      (served && served.loopback && config.review.allowNetwork
+        ? `  network permitted but the running server is loopback-bound — ${served.widen}\n`
+        : '') +
+      (served && served.started && !served.loopback
+        ? '  serving: every provisioned spec, to anyone with a URL on your network.\n' +
+          '  stop:  skitterspec spec-env review serve --stop\n'
+        : '') +
+      // One line, and only when something was actually done on the reader's
+      // behalf. An action nobody asked for is reported, not hidden.
+      (serverSaid ? `  ${serverSaid}\n` : '') +
       // Named on its own line so the skill never has to build the path itself.
       (publishCopy ? `  publish: ${publishCopy}\n` : '') +
       (url ? `  published: ${url}\n` : '') +
@@ -2481,6 +3021,61 @@ function stateDirLabel(config) {
   return path.posix.dirname(config.registry) || '.spec-env'
 }
 
+/**
+ * The engine script's mtime in ms, or null when it cannot be read.
+ *
+ * WHY MTIME AND NOT A CONTENT HASH: the dist is assembled from several files,
+ * so a hash needs a manifest to stay honest, and this answers the only question
+ * asked — is the code on disk newer than the process serving it? WHY NOT THE
+ * PROCESS START TIME: `ps -o lstart=` is platform-specific and needs parsing,
+ * while this is a number we write ourselves into a file we already write.
+ *
+ * Null is cannot-tell and adopts. See `staleServer`.
+ */
+function scriptMtimeOf(scriptPath) {
+  try {
+    return fs.statSync(scriptPath).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+/**
+ * This repo's serve token, minted once and then read.
+ *
+ * STORED, NOT DERIVED, and the asymmetry with the port is the point. The port
+ * is `PORT_BASE + hash(realpath(repo)) % PORT_SPAN` because a port is not a
+ * secret and a stable one keeps a handed-out link working. The token is the
+ * only guard on a non-loopback bind, and a repo path is guessable by anyone on
+ * the machine — so deriving it the same way would buy stability with the single
+ * property it exists for. It keeps all 48 random bits; only its lifetime moved.
+ *
+ * WHAT WOULD FOOL THIS: a token file someone has emptied or truncated. A short
+ * or non-hex value is treated as absent and replaced, because a malformed token
+ * cannot guard anything — and the alternative, refusing to serve, would take
+ * the page away over a file nobody reads.
+ */
+function repoToken(dir, config) {
+  const file = path.resolve(dir, `${stateDirLabel(config)}/review-token`)
+  try {
+    const found = String(fs.readFileSync(file, 'utf8')).trim()
+    if (/^[0-9a-f]{12}$/.test(found)) return found
+  } catch {
+    // Absent is the ordinary first-run state, not a problem.
+  }
+  const minted = mintToken()
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, minted + '\n')
+  } catch {
+    // UNWRITEABLE IS NOT FATAL. The server can still serve on this token for
+    // as long as it lives; what is lost is only the survival across a restart,
+    // which is exactly where this started. Taking the page away instead would
+    // be a worse answer to a read-only `.spec-env`.
+  }
+  return minted
+}
+
 // The supervised proxy process descriptor (paths relative to the checkout root).
 function proxyProcFor(config, routesFileAbs) {
   const sdir = stateDirLabel(config)
@@ -2615,6 +3210,27 @@ function lanAddresses(nets = require('node:os').networkInterfaces()) {
   return rankLanAddresses(nets).map((e) => e.address)
 }
 
+/**
+ * The addresses worth OFFERING as alternatives — physical and unknown
+ * interfaces, never virtual ones.
+ *
+ * The ranking already puts virtuals last, so the best guess was right; what was
+ * wrong was listing them at all. A render offered `10.211.55.2` and
+ * `10.37.129.2` — both Parallels adapters — as alternatives to a working link,
+ * and no phone can route to either. An alternative that cannot work is worse
+ * than no alternative: it reads as something to try when the first one fails.
+ *
+ * WHAT WOULD FOOL THIS: an interface named outside both patterns is `unknown`
+ * and therefore KEPT, because a machine with unusual naming is more likely to
+ * have a real address than a fake one — being wrong that way offers one dud,
+ * where the opposite hides the only address that works.
+ */
+function offerableLanAddresses(nets = require('node:os').networkInterfaces()) {
+  return rankLanAddresses(nets)
+    .filter((e) => !VIRTUAL_IFACE.test(e.iface))
+    .map((e) => e.address)
+}
+
 /**
  * Bring the review server up, or adopt the one already running.
  *
@@ -2655,11 +3271,16 @@ async function ensureReviewServer(dir, config, { host = '127.0.0.1', port, resta
     if (settings && settings.port) {
       if (serverScriptOk(settings)) {
         const now = engineVersionFor(proc.script)
-        const verdict = staleServer(settings.engine, now)
+        const verdict = staleServer(settings.engine, now, settings.scriptMtime, scriptMtimeOf(proc.script))
         if (verdict !== 'stale') {
           const lb = settings.host === '127.0.0.1' || settings.host === 'localhost'
           return {
             port: settings.port,
+            // How the RUNNING server's port was chosen, as it recorded it. A
+            // server from before this was written has no answer; `null` says so
+            // rather than recomputing one, because a recomputed answer could
+            // disagree with the port actually being served.
+            portSource: settings.portSource || null,
             token: settings.token || null,
             loopback: lb,
             pid: running,
@@ -2697,13 +3318,29 @@ async function ensureReviewServer(dir, config, { host = '127.0.0.1', port, resta
     }
   }
 
-  const usePort = Number(port || config.review.servePort)
+  // `--port` wins, then an explicit `review.servePort` number, then the
+  // derivation. `source` is recorded in the settings file below so `--status`
+  // can say WHY this port, rather than leaving the operator to read config.js.
+  const resolved = resolveServePort(config, dir, port)
+  const usePort = resolved.port
   const loopback = host === '127.0.0.1' || host === 'localhost'
   // The token is the ONLY guard on a non-loopback bind, so it is minted with the
-  // bind rather than offered as an option to forget — except when replacing a
-  // server on the same bind, where carrying the old one keeps a link that is
-  // already open on someone's phone alive.
-  const token = loopback ? null : reuseToken || mintToken()
+  // bind rather than offered as an option to forget. It is read from the repo's
+  // own store, so it OUTLIVES THIS PROCESS: the port beside it is a pure
+  // function of the repo path and stable across a restart by design, and a URL
+  // whose two halves disagree about that is a URL that dies for no reason the
+  // reader can see. Six were handed out for one repo in a single session.
+  //
+  // `reuseToken` still wins where a server is being replaced on the same bind —
+  // now redundant rather than wrong, and left alone as its own guarantee.
+  //
+  // EVERY BIND CARRIES IT, loopback included, and on loopback it guards nothing:
+  // a server reachable only from this machine needs no credential. It is there
+  // so the URL has ONE SHAPE. The bind comes from reader detection, and that
+  // detection flipped `unknown` → `remote` inside a single session — so a
+  // token-only-on-network rule meant the same repo's address gained and lost a
+  // path segment underneath whoever was holding it.
+  const token = reuseToken || repoToken(dir, config)
 
   if (running) await stopProcess(proc, { rootDir: dir })
 
@@ -2728,7 +3365,8 @@ async function ensureReviewServer(dir, config, { host = '127.0.0.1', port, resta
   // server refused to start on every Linux machine while macOS stayed green.
   // `portsInUseOn` owns the ordering; see its comment for the verification.
   const busy = await portsInUseOn(usePort, [host, '127.0.0.1'])
-  if (busy.length) return { error: 'busy', port: usePort, replaced, engineWas }
+  if (busy.length)
+    return { error: 'busy', port: usePort, portSource: resolved.source, replaced, engineWas }
 
   fs.mkdirSync(path.dirname(abs(settingsFile)), { recursive: true })
   fs.writeFileSync(
@@ -2740,7 +3378,18 @@ async function ensureReviewServer(dir, config, { host = '127.0.0.1', port, resta
     // — the process is alive, the file exists, and every page it renders is
     // drawn by code that was replaced underneath it.
     JSON.stringify(
-      { dir, port: usePort, host, token, script: proc.script, engine: engineVersionFor(proc.script) },
+      {
+        dir,
+        port: usePort,
+        portSource: resolved.source,
+        host,
+        token,
+        script: proc.script,
+        engine: engineVersionFor(proc.script),
+        // Recorded so the NEXT adoption can tell a rebuild from a restart. A
+        // version alone cannot: the dist is rebuilt at the same version all day.
+        scriptMtime: scriptMtimeOf(proc.script),
+      },
       null,
       2,
     ) + '\n',
@@ -2791,6 +3440,25 @@ async function specEnvReviewServe(dir, config, flags) {
   const pid = readPid(abs(proc.pidFile))
   const running = pid && isAlive(pid) ? pid : null
 
+  // ROTATION IS THE ONLY WAY TO CHANGE A TOKEN, and it says what it costs.
+  // Every other path reads the stored one; a silent mint is the whole bug this
+  // replaced, so the one place that mints deliberately announces it.
+  if (flags.rotateToken) {
+    const file = abs(`${sdir}/review-token`)
+    const minted = mintToken()
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, minted + '\n')
+    process.stdout.write(
+      'spec-env review serve: token rotated.\n' +
+        '  EVERY LINK ALREADY HANDED OUT IS NOW DEAD — re-render and send the new one.\n' +
+        (running
+          ? `  the running server (pid ${running}) still answers on the old token; ` +
+            '--stop it, then render again.\n'
+          : ''),
+    )
+    return
+  }
+
   if (flags.status) {
     if (!running) {
       process.stdout.write('spec-env review serve: not running.\n')
@@ -2804,8 +3472,16 @@ async function specEnvReviewServe(dir, config, flags) {
     // ordinary answer and needs no comment; `unknown` is a server from before
     // this was recorded, which is healthy and must not be accused of anything.
     const verdict = staleServer(settings.engine, engineVersionFor(proc.script))
+    // The port AND how it was chosen, so "why is this on 7742?" is answered by
+    // the tool. A server started before `portSource` was recorded has no answer
+    // — the line then carries the port alone rather than a guess, because an
+    // absence is not evidence of any particular source.
+    const reason = servePortReason(settings.portSource)
     process.stdout.write(
       `spec-env review serve: running (pid ${running})\n` +
+        (settings.port
+          ? `  port:  ${settings.port}${reason ? ` (${reason})` : ''}\n`
+          : '') +
         (settings.port ? `  local: ${serveUrl('127.0.0.1', settings)}\n` : '') +
         (settings.engine ? `  engine: ${settings.engine}\n` : '') +
         (verdict === 'stale'
@@ -2839,9 +3515,19 @@ async function specEnvReviewServe(dir, config, flags) {
   })
 
   if (started.error === 'busy') {
+    // NAME `servePort`, not only `--port`. `--port` moves this run aside and
+    // leaves every link already handed out pointing at the busy port — which is
+    // the bug this refusal used to send people straight into. Pinning
+    // `review.servePort` is the durable fix: it is what the next link is built
+    // from, so the move happens once and the links follow it.
     process.stdout.write(
       `spec-env review serve: port ${started.port} is already in use — ` +
-        'pass --port, or --stop if this is an older server.\n',
+        (started.portSource === 'derived'
+          ? 'two repos derived the same port. '
+          : '') +
+        'pin a free one in specs/.core/env.config.json ("review": { "servePort": <n> }) ' +
+        'so the links follow, or --stop if this is an older server.\n' +
+        '  --port <n> moves this run only, and leaves existing links on the busy port.\n',
     )
     return
   }
@@ -2888,8 +3574,13 @@ async function specEnvReviewServe(dir, config, flags) {
  */
 function reviewServedUrls(up, addrs, folder) {
   const page = (host) => `${serveUrl(host, up)}${encodeURIComponent(folder)}`
+  // ALWAYS AVAILABLE WHEN SERVED. A server bound to 0.0.0.0 answers on loopback
+  // too, so `local` is a real tier in both binds — it is not an alternative to
+  // the network URL, it is the same page from the machine holding it.
+  const loopbackUrl = page('127.0.0.1')
   if (up.loopback) {
     return {
+      loopbackUrl,
       url: page('127.0.0.1'),
       // No runners-up: every other address on this machine is one the server
       // is not listening on.
@@ -2902,8 +3593,14 @@ function reviewServedUrls(up, addrs, folder) {
   // and can be wrong, so the alternates are offered rather than thrown away. No
   // address at all means nothing to offer, and the `file://` fallback is the
   // honest answer.
-  if (!addrs.length) return null
-  return { url: page(addrs[0]), alternates: addrs.slice(1).map(page), loopback: false, widen: null }
+  if (!addrs.length) return { loopbackUrl, url: null, alternates: [], loopback: false, widen: null }
+  return {
+    loopbackUrl,
+    url: page(addrs[0]),
+    alternates: addrs.slice(1).map(page),
+    loopback: false,
+    widen: null,
+  }
 }
 
 /**
@@ -3057,7 +3754,7 @@ const DEPS_RE = /(^|\/)(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.l
 // feature. The branch that's checked out IS the lock (assertPrimaryOnMain); the
 // receipt is advisory metadata. `status` is read-only; `take` performs the switch
 // (release/abort land in a later phase).
-async function specEnvLive(dir, config, positional) {
+async function specEnvLive(dir, config, positional, flags) {
   // Both verbs exist to route around the work living somewhere other than the
   // checkout you are in — a proxy to a second stack, or a temporary branch swap.
   // Checkout mode closes that gap permanently, so there is nothing to route.
@@ -3076,7 +3773,7 @@ async function specEnvLive(dir, config, positional) {
       // report cannot describe. It prints ABOVE the report, not instead of it:
       // you asked a question and should still get the answer.
       if (note) process.stdout.write(note)
-      specEnvLiveStatus(dir, config, specArg)
+      specEnvLiveStatus(dir, config, specArg, flags)
       break
     case 'take':
       await specEnvLiveTake(dir, config, specArg)
@@ -3380,8 +4077,9 @@ async function specEnvLiveAbort(dir, config) {
   )
 }
 
-function specEnvLiveStatus(dir, config, specArg) {
+function specEnvLiveStatus(dir, config, specArg, flags) {
   const { onBase, branch, baseBranch } = assertPrimaryOnMain(config, gitReader(dir))
+  const json = Boolean(flags && flags.json)
 
   // Per-spec query (`live status <spec>`): a clear yes/no verdict /spec-start and
   // skill branches on to decide whether to skip worktree provisioning and work in
@@ -3389,6 +4087,26 @@ function specEnvLiveStatus(dir, config, specArg) {
   if (specArg) {
     const spec = resolveSpecWithWorktree(dir, config, specArg)
     const live = !onBase && branch === spec.branch
+    // `--json` answers with the SAME function the review render uses, so a page
+    // and this command can never disagree about whether a spec is live. The
+    // text form above is left exactly as it was: `/spec-start` reads its
+    // `live:      yes|no` line, and a flag must not move a seam.
+    if (json) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            spec: spec.folder,
+            branch: spec.branch,
+            primary: branch || null,
+            base: baseBranch,
+            live: liveStateFor(spec, liveContext(dir, config, spec, { onBase, primaryBranch: branch })),
+          },
+          null,
+          2,
+        ) + '\n',
+      )
+      return
+    }
     process.stdout.write(
       `spec-env live status: ${spec.folder}\n` +
         `  spec:      ${spec.folder}  (branch ${spec.branch})\n` +
@@ -3419,6 +4137,26 @@ function specEnvLiveStatus(dir, config, specArg) {
       ? `${receipt.spec}  (branch ${branch || '(detached)'})`
       : `unknown  (branch ${branch || '(detached)'} — no receipt; switched by hand?)`
 
+  if (json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          primary: branch || null,
+          base: baseBranch,
+          onBase,
+          // The three-state answer the text's `in-flight:` line carries, kept
+          // as three states here too: a branch switched by hand leaves no
+          // receipt, so the spec is `null` while the checkout is plainly busy.
+          inFlight: onBase ? null : receipt && receipt.spec ? String(receipt.spec) : null,
+          receipt: receipt || null,
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return
+  }
+
   process.stdout.write(
     'spec-env live:\n' +
       `  primary:   ${branch || '(detached)'}  (${state})\n` +
@@ -3427,6 +4165,39 @@ function specEnvLiveStatus(dir, config, specArg) {
   )
 }
 
+/**
+ * The `ctx` `liveStateFor` wants, probed from this repo.
+ *
+ * ONE BUILDER, so every caller passes the same shaped answer — the review
+ * render and `live status --json` both come through here, which is what makes
+ * "the page and the command agree" a property of the code rather than a habit.
+ *
+ * `onBase`/`primaryBranch` are the caller's, because it has usually already
+ * asked `assertPrimaryOnMain` and asking twice can straddle a branch switch.
+ *
+ * An unreadable receipt is caught and dropped: it costs the holder's NAME and
+ * never the state, which the branch answers (`liveStateFor`).
+ */
+function liveContext(dir, config, spec, { onBase, primaryBranch }) {
+  let receipt = null
+  try {
+    receipt = readReceipt(dir, config)
+  } catch {
+    receipt = null
+  }
+  const front = (config.dev || []).map((d) => d.frontPort).filter((p) => typeof p === 'number')[0]
+  return {
+    isolated: true,
+    onBase,
+    primaryBranch,
+    receipt,
+    worktreeExists: Boolean(spec && spec.worktreePath && fs.existsSync(spec.worktreePath)),
+    // Null where the project configured no canonical port — there is no URL to
+    // name, and inventing one would send the reader to a closed port.
+    url: front ? `http://${(config.proxy && config.proxy.host) || 'localhost'}:${front}` : null,
+  }
+}
+
 async function specEnv(rest) {
   const [sub, ...args] = rest
   let dir = process.cwd()
@@ -3444,6 +4215,7 @@ async function specEnv(rest) {
     outcome: null,
     claim: null,
     drop: null,
+    buttons: null,
     json: false,
   }
   for (let i = 0; i < args.length; i++) {
@@ -3454,36 +4226,49 @@ async function specEnv(rest) {
     else if (args[i] === '--older-than') flags.olderThanDays = Number(args[++i])
     else if (args[i] === '--branch') flags.branch = true
     else if (args[i] === '--stop') flags.stop = true
+    else if (args[i] === '--rotate-token') flags.rotateToken = true
+    else if (args[i] === '--off') flags.off = true
     else if (args[i] === '--status') flags.status = true
     else if (args[i] === '--port') flags.port = args[++i]
     else if (args[i] === '--host') flags.host = args[++i]
     else if (args[i] === '--publish-copy') flags.publishCopy = true
+    else if (args[i] === '--buttons') flags.buttons = args[++i]
     else if (args[i] === '--out') flags.out = args[++i]
     else if (args[i] === '--review') flags.review = args[++i]
     else if (args[i] === '--notes') flags.notes = args[++i]
+    else if (args[i] === '--verdict') flags.verdict = args[++i]
+    // `--set` keeps an EMPTY STRING rather than coercing it away: empty is the
+    // bare `/spec-remote-review`, and it means toggle. `??` so a missing value
+    // at the end of argv is still the empty form rather than `undefined`, which
+    // would read as the flag never having been passed.
+    else if (args[i] === '--set') flags.set = args[++i] ?? ''
     else if (args[i] === '--resolve') flags.resolve = args[++i]
     else if (args[i] === '--outcome') flags.outcome = args[++i]
     else if (args[i] === '--claim') flags.claim = args[++i]
     else if (args[i] === '--claim-since') flags.claimSince = args[++i]
+    else if (args[i] === '--since') flags.since = args[++i]
+    else if (args[i] === '--timeout') flags.timeout = args[++i]
     else if (args[i] === '--drop') flags.drop = args[++i]
     else if (args[i] === '--json') flags.json = true
     else if (args[i] === '--check') flags.check = true
     else if (args[i] === '--for-command') flags.forCommand = args[++i]
     else if (args[i] === '--phase') flags.phase = args[++i]
     else if (args[i] === '--record-primary') flags.recordPrimary = true
+    else if (args[i] === '--docs') flags.docs = true
     else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
     else positional.push(args[i])
   }
   dir = path.resolve(dir)
-  // Where the caller actually is, kept before the re-anchor below. Only `stage`
-  // wants it: every other subcommand asks about the repo, while that one asks
-  // about the tree in front of you, and the two differ inside a worktree.
+  // Where the caller actually is, kept before the re-anchor below. `stage` and
+  // `review --docs` want it: every other subcommand asks about the repo, while
+  // those two ask about the tree in front of you, and the two differ inside a
+  // worktree.
   const invokedFrom = dir
   // Anchor on the primary checkout so every subcommand resolves {repo}, worktree
   // paths, and the registry identically whether run from main or a worktree.
   dir = resolvePrimaryCheckout(dir, gitReader(dir))
 
-  const { config, present } = loadEnvConfig(dir)
+  const { config, present, unknown } = loadEnvConfig(dir)
   if (!present) {
     process.stdout.write(
       'spec-env: isolation not enabled (no specs/.core/env.config.json).\n' +
@@ -3492,6 +4277,24 @@ async function specEnv(rest) {
     return
   }
 
+  // A key the loader does not read is dropped — it always was, and still is.
+  // What changed is that it is no longer dropped in SILENCE: a mis-typed
+  // `review.required` leaves the gate on and a mis-typed
+  // `teardown.deleteRemoteBranch` reverts to prompt, and the only signal either
+  // gave was that nothing happened.
+  //
+  // Every spec-env subcommand passes through here, which is why it sits at this
+  // one point rather than in a reporting verb someone might never run. It is
+  // ADVISORY: it writes lines and changes no exit status, because a forward-compat
+  // key and a typo are indistinguishable from here and only one of them is a
+  // mistake (.claude/rules/negative-checks.md rule 4).
+  //
+  // STDERR, deliberately: `--json` subcommands write their payload to stdout, and
+  // an advisory line on stdout would make it unparseable.
+  for (const key of unknown || []) {
+    process.stderr.write(`spec-env: ${ENV_CONFIG_LABEL} — unknown key "${key}" is ignored.\n`)
+  }
+
   switch (sub) {
     case 'up':
       specEnvUp(dir, config, positional[0])
@@ -3538,10 +4341,22 @@ async function specEnv(rest) {
         specEnvReviewArm(dir, config, positional[1], flags)
         break
       }
+      if (positional[0] === 'waiting') {
+        specEnvReviewWaiting(dir, config, flags)
+        break
+      }
+      if (positional[0] === 'wait') {
+        await specEnvReviewWait(dir, config, positional[1], flags)
+        break
+      }
       if (positional[0] === 'gate') {
         specEnvReviewGate(dir, config, positional[1], flags, invokedFrom)
         break
       }
+      if (positional[0] === 'allow') {
+        specEnvReviewAllow(dir, config, positional[1], flags)
+        break
+      }
       if (positional[0] === 'skip') {
         // The one positional is the REASON, not a spec: the two are
         // indistinguishable as free text, and the spec is the one thing this
@@ -3549,20 +4364,26 @@ async function specEnv(rest) {
         specEnvReviewSkip(dir, config, positional[1], flags)
         break
       }
-      await specEnvReview(dir, config, positional[0], flags)
+      await specEnvReview(dir, config, positional[0], flags, invokedFrom)
       break
     case 'live':
-      await specEnvLive(dir, config, positional)
+      await specEnvLive(dir, config, positional, flags)
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--json] [--record-primary] [--assert-primary-clean]\n' +
+        `Usage: skitterspec spec-env <${SPEC_ENV_VERBS.join('|')}> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--verdict <word>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--buttons <set>] [--json] [--record-primary] [--assert-primary-clean]\n` +
         '  review serve [--port <n>] [--host <addr>] [--stop] [--status]  serve every diff locally\n' +
+        '  review serve --rotate-token    mint a new URL token; every handed-out link dies\n' +
+        '  review allow <network|remote> [--off]  permit a review tier (writes env.config.json)\n' +
           '  review arm [spec] [--phase <n>]        a phase ended — its diff now owes a verdict\n' +
           '  review gate [spec] [--check] [--json]  is one owed? --check exits non-zero if so\n' +
           '       [--for-command <cmdline>]         ...but only when that command is a git commit\n' +
           '  review skip "<reason>"                 move on without one, on the record\n' +
+          '  review wait [spec] --since <iso>       block until a verdict arrives ([--timeout <s>])\n' +
+          '  review waiting [--json]                every pass waiting, across every spec\n' +
           '  review [spec] --claim-since <iso>      claim the one pass that arrived since <iso>\n' +
+          '  review [spec] --verdict <word>         send just a verdict, with nothing marked\n' +
+          '  review [spec] --buttons midrun         the page offers Continue, not a commit\n' +
           '  [spec] is optional everywhere: omit it and the worktree you are standing\n' +
           '  in is used, else the sole provisioned spec (several -> it lists them).\n' +
           '  A bare `live` takes that spec when the workbench is free, and prints the\n' +
@@ -3677,11 +4498,14 @@ async function run(argv) {
 }
 
 module.exports = {
+  SPEC_ENV_VERBS,
   run,
   parse,
   HELP,
   unknownCommand,
   rankLanAddresses,
+  offerableLanAddresses,
+  reviewTierStack,
   serveProcFor,
   serverScriptOk,
   daemonScript,