@skitterbyte/skitterspec 21.0.0 → 22.1.0

package/src/cli.js

@@ -9,16 +9,53 @@ 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',
+  'nospec',
+  'main',
+])
 const {
   readRegistry,
   writeRegistry,
   allocateSlot,
   freeSlot,
   portOffset,
+  recordSpecless,
+  forgetSpecless,
+  isSpecless,
 } = require('./env/registry.js')
 const {
   resolveSpec,
+  resolveSpecless,
   resolveBaseBranch,
   liveWorktreePaths,
   collectSpecFolders,
@@ -39,6 +76,8 @@ const {
   summarizeReceipt,
   migrationsHit,
   planTake,
+  liveStateFor,
+  liveStateLine,
   planRelease,
   planAbort,
 } = require('./env/live.js')
@@ -46,6 +85,8 @@ const { ensureWorktreeDirTrusted } = require('./env/trust.js')
 const {
   rawGitReader,
   collectReview,
+  reviewTierStack,
+  reviewTierLine,
   renderReviewPage,
   renderReviewBlock,
   reviewOutPath,
@@ -61,6 +102,7 @@ const {
   reviewNotesPath,
   readNotes,
   writeNotes,
+  VERDICTS,
   validateNotesBlob,
   judgeVerdict,
   appendDecision,
@@ -69,6 +111,9 @@ const {
   writePending,
   claimPending,
   passesSince,
+  waitForPass,
+  WAIT_HEARTBEAT_MS,
+  waitingPasses,
   describePending,
   pendingAge,
   reviewPendingPath,
@@ -81,21 +126,45 @@ const {
   reviewGatePath,
   readGate,
   writeGate,
+  writeRenderRecord,
   armGate,
   disarmGate,
   gateState,
+  markGateOffered,
 } = require('./env/review.js')
-const { planUp, planCheckoutUp } = require('./env/provision.js')
-const { classifyDirtyTree } = require('./env/classify.js')
+const {
+  CHECKS_VERSION,
+  BUNDLED_ADAPTERS,
+  runReviewers,
+  diffHashOf,
+  readChecks,
+  writeChecks,
+  cacheHit,
+  asCached,
+} = require('./env/reviewers.js')
+const { planUp, planCheckoutUp, worktreeCd, resolveStack } = require('./env/provision.js')
+const { classifyDirtyTree, dirtyPaths, specDocsIn } = require('./env/classify.js')
 const { isGitCommit } = require('./env/commitcmd.js')
 const { planDown, planDownCheckout } = require('./env/teardown.js')
+const {
+  checkMainWrite,
+  recordAllow,
+  clearAllow,
+  mainGuardStatus,
+} = require('./env/mainguard.js')
 const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
 const { planIntegrate, planIntegrateCheckout } = require('./env/integrate.js')
 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')
 
@@ -137,6 +206,13 @@ Usage:
                               specs/.core/env.config.json). Subcommands:
                                 up <spec>         print the plan to provision a worktree +
                                                   Docker stack (prints commands; creates nothing)
+                                                  --docs: a tree to write documents in — no
+                                                  setup commands, no Docker
+                                nospec <name>     record a branch with no spec document
+                                                  (/no-spec work) and print its plan
+                                main <check|allow|status>
+                                                  the main guard — is a write about to land
+                                                  on the base branch? (/allow-main lifts it)
                                 down <spec>       tear down (guards; --keep-volumes, --force)
                                 prune             reap orphaned test-DB volumes (--older-than <days>)
                                 dev up <spec>     start host dev servers on the spec's ports
@@ -144,11 +220,17 @@ 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)
+                                                   --resolve <json> records what was done;
+                                                   --run-reviewers runs review.reviewers)
+                                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:
@@ -271,31 +353,95 @@ 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)
-    .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
+  const provisioned = allSpecs(dir, config, worktreePaths, speclessMap(dir, config))
+    .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath), specless: s.specless }))
     // The primary checkout is itself in `git worktree list`; a spec is
     // provisioned only when it has its OWN worktree, separate from it.
     .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
   }
 
   const registry = readRegistry(dir, config)
   process.stdout.write('Provisioned specs:\n')
-  for (const { folder, wt } of provisioned) {
+  for (const { folder, wt, specless } of provisioned) {
     const slot = registry.slots[folder]
     let ports = ''
     if (slot !== undefined) {
       const off = portOffset(slot, config)
       ports = `  slot ${slot}  ports ${off}-${off + config.docker.portsPerSpec - 1}`
     }
-    process.stdout.write(`  ${folder}${ports}\n    ${path.relative(dir, wt) || wt}\n`)
-  }
+    // SAID, not left to be noticed. A `/no-spec` branch appears in this list
+    // because it has a worktree like everything else, and a reader who goes
+    // looking for `specs/**/<name>/` must not conclude the repo is broken when
+    // there is nothing there — it is not missing, there never was one.
+    const tag = specless ? '  (no spec)' : ''
+    process.stdout.write(`  ${folder}${tag}${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
@@ -303,49 +449,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.
@@ -541,8 +644,220 @@ function specEnvUpCheckout(dir, config, spec) {
   process.stdout.write(out.join('\n') + '\n')
 }
 
-function specEnvUp(dir, config, specArg) {
+/**
+ * `spec-env main <check|allow|status>` — the main guard.
+ *
+ * `check` is what the hook calls, so it follows `review gate --check`'s
+ * contract exactly: **exit 1 and print the reason** when the write should be
+ * refused, exit 0 and say nothing otherwise. Every cannot-tell is an exit 0.
+ *
+ * `allow` and `status` are for a person. `allow` is reached only through
+ * `/allow-main`, which is user-only — a guard the model can lift is decoration.
+ */
+function specEnvMain(dir, config, positional, flags = {}, present = true, invokedFrom = dir) {
+  const action = positional[0] || 'status'
+  const sessionId = flags.session || process.env.CLAUDE_CODE_SESSION_ID || null
+  const git = gitReader(dir)
+
+  if (action === 'check') {
+    // `invokedFrom`, NOT `dir`. Every subcommand is re-anchored on the primary
+    // checkout before it runs, so asking `dir` whether it is the primary
+    // checkout always answers yes — and the guard would fire on a write inside
+    // somebody's worktree, which is the one place it must never fire.
+    const from = invokedFrom || dir
+    const verdict = checkMainWrite(from, config, gitReader(from), { sessionId, present })
+    if (!verdict.refuse) return
+    process.stdout.write(`spec-env main: ${verdict.reason}\n`)
+    process.exitCode = 1
+    return
+  }
+
+  if (action === 'allow') {
+    // The primary checkout owns the allow file, so an `/allow-main` typed from a
+    // worktree still lands where the guard reads it.
+    const root = dir
+
+    if (flags.off || positional[1] === 'off') {
+      const had = clearAllow(root, config)
+      process.stdout.write(
+        had
+          ? 'spec-env main: allow cleared — the base branch is guarded again.\n'
+          : 'spec-env main: nothing to clear — the base branch was already guarded.\n',
+      )
+      return
+    }
+
+    const reason = positional.slice(1).join(' ').trim() || null
+    const value = recordAllow(root, config, {
+      sessionId,
+      reason,
+      at: new Date().toISOString(),
+    })
+    const scope =
+      value.scope === 'session'
+        ? 'this session only — it lapses when the session ends'
+        : 'this repo until cleared — no session id available, so `/allow-main off` is what ends it'
+    process.stdout.write(
+      `spec-env main: writes to the base branch are allowed (${scope}).\n` +
+        (reason ? `  reason: ${reason}\n` : '  reason: none given\n'),
+    )
+    return
+  }
+
+  if (action === 'status') {
+    const st = mainGuardStatus(dir, config, { sessionId, present })
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(st, null, 2) + '\n')
+      return
+    }
+    if (st.state === 'unconfigured') {
+      process.stdout.write('spec-env main: isolation is not configured — the guard is inactive.\n')
+      return
+    }
+    if (st.state === 'off') {
+      process.stdout.write(
+        'spec-env main: off for this project (guards.mainIsLandingZone is false).\n',
+      )
+      return
+    }
+    if (st.state === 'allowed') {
+      process.stdout.write(
+        `spec-env main: allowed (${st.scope})\n  reason: ${st.reason || 'none given'}\n` +
+          '  /allow-main off ends it\n',
+      )
+      return
+    }
+    process.stdout.write(
+      'spec-env main: guarded — the base branch is a landing zone.\n' +
+        (st.otherSession
+          ? '  an allow exists for a different session, so it does not apply here\n'
+          : ''),
+    )
+    return
+  }
+
+  process.stdout.write(
+    `spec-env main: unknown action "${action}" — one of check, allow, status.\n`,
+  )
+}
+
+/**
+ * `spec-env nospec <name>` — record a SPECLESS branch and print its plan.
+ *
+ * `/no-spec` is the lane for work that genuinely has no spec: bumping four
+ * projects to a new version, a lockfile refresh, a rename. It exists because a
+ * guard that refuses writes on the base branch is a wall unless there is
+ * somewhere cheap to go, and because work done on the base branch renders no
+ * page and therefore gets no review at all.
+ *
+ * IT RECORDS FIRST, THEN PLANS, and the order is the correctness condition. The
+ * record is what makes the name resolvable (`resolve.js`'s specless fallback),
+ * so every later verb — `review`, `integrate`, `down`, `status`, a bare
+ * `resolve` — can find a branch with no document behind it. Plan first and a
+ * caller that runs the printed commands owns a worktree the engine cannot name.
+ *
+ * NO `--docs` HERE, deliberately, and it is the opposite call from `/spec`.
+ * Documents mode skips the `setup` commands because writing markdown needs no
+ * dependencies; `/no-spec` work is *code*, so it needs them. The two lanes want
+ * opposite halves of the same provision.
+ *
+ * It is a planner like `up`: it creates no worktree. The registry write is its
+ * only side effect, which is why it is safe to re-run.
+ */
+function specEnvNospec(dir, config, name, flags = {}) {
+  if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    process.stdout.write(
+      'spec-env nospec: needs a kebab-case name — it becomes the branch and the ' +
+        'worktree folder.\n  e.g. skitterspec spec-env nospec bump-deps\n',
+    )
+    return
+  }
+
+  // A name that is already a spec is refused rather than shadowed. Two things
+  // answering to one name is how `down` comes to tear the wrong tree down.
+  let clash = null
+  try {
+    clash = resolveSpec(name, dir, config, {
+      searchDirs: [...liveWorktreePaths(gitReader(dir))],
+    })
+  } catch {
+    // Not found is the expected case, and the only one that proceeds.
+  }
+  if (clash && !clash.specless) {
+    process.stdout.write(
+      `spec-env nospec: ${name} is already a spec (${clash.bucket}) — ` +
+        `use /spec-start ${name} instead.\n`,
+    )
+    return
+  }
+
+  const before = readRegistry(dir, config)
+  const already = isSpecless(before, name)
+  const spec = resolveSpecless(name, dir, config, before.specless[name])
+  writeRegistry(dir, config, recordSpecless(before, name, { branch: spec.branch }))
+
+  const worktreeRootAbs = path.dirname(spec.worktreePath)
+  const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs)
+  const attached = fs.existsSync(spec.worktreePath)
+
+  const guard = worktreeCd(spec.worktreePath)
+  const setupCommands = (config.setup || []).map((cmd) => `${guard}; ${cmd}`)
+
+  const out = [
+    `spec-env nospec: ${name} ` +
+      (attached ? '(plan — worktree exists; will attach)' : '(plan — nothing created yet)'),
+    '',
+    `  worktree:  ${spec.worktreePath}`,
+    `  branch:    ${spec.branch}`,
+    '  stack:     worktree-only (no docker, no port block)',
+    `  recorded:  ${already ? 'already in' : 'added to'} ${config.registry} as a specless branch`,
+  ]
+  if (trust.reason === 'malformed') {
+    out.push(
+      '  trusted:   ! .claude/settings.local.json is not valid JSON — left it;' +
+        `\n             add ${worktreeRootAbs} to permissions.additionalDirectories yourself`,
+    )
+  } else {
+    out.push(
+      `  trusted:   ${worktreeRootAbs}  ` +
+        `(${trust.changed ? 'added to' : 'already in'} .claude/settings.local.json)`,
+    )
+  }
+  out.push('')
+  out.push('  to provision, run:')
+  out.push(
+    attached
+      ? `    git worktree add ${spec.worktreePath} ${spec.branch}`
+      : `    git worktree add ${spec.worktreePath} -b ${spec.branch}`,
+  )
+  if (setupCommands.length) {
+    out.push('')
+    out.push('  then, in the worktree, run:')
+    for (const cmd of setupCommands) out.push(`    ${cmd}`)
+  }
+  if (flags.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          name,
+          branch: spec.branch,
+          worktreePath: spec.worktreePath,
+          specless: true,
+          attached,
+          recorded: !already,
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return
+  }
+  process.stdout.write(out.join('\n') + '\n')
+}
+
+function specEnvUp(dir, config, specArg, flags = {}) {
   const spec = resolveSpecWithWorktree(dir, config, specArg)
+  const docs = flags.docs === true
 
   // Checkout mode: the branch is built in the primary checkout, so none of the
   // worktree machinery below applies — no slot, no trust entry and no bootstrap.
@@ -592,21 +907,38 @@ function specEnvUp(dir, config, specArg) {
   const worktreeRootAbs = path.dirname(spec.worktreePath)
   const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs)
 
-  const wantsDocker = spec.stack === 'docker' && config.docker.enabled
+  // Documents mode brings no stack up, so a Docker spec provisioned this way is
+  // a worktree-only run. Asked through `resolveStack`, which `planUp` also
+  // calls, so the slot allocated here and the commands planned there cannot
+  // disagree about whether there is a stack — they did, for a header-less spec.
+  const wantsDocker = resolveStack(spec, config, {
+    docs,
+    composeFilePresent: composeFilePresent(dir, config),
+  }).wantsDocker
 
   // Slot allocation is Docker-only: a worktree-only spec never touches the
   // registry (no slot, no port block). Its re-run signal is the worktree already
   // existing on disk (attach the branch, don't `-b`); a Docker spec's is its slot.
+  //
+  // THE WORKTREE ON DISK COUNTS IN BOTH PATHS, and documents mode is what makes
+  // that necessary rather than merely tidy. A Docker spec provisioned with
+  // `--docs` allocates no slot, so a later `up` without the flag would read the
+  // registry, find nothing, and plan `git worktree add -b <branch>` over a
+  // worktree and a branch that both already exist — a plan that cannot run. The
+  // stronger signal is the honest one either way: a tree on disk is a re-run,
+  // whatever the registry remembers.
   let slot = null
   let attached
+  const worktreeOnDisk = fs.existsSync(spec.worktreePath)
   if (wantsDocker) {
     const before = readRegistry(dir, config)
-    attached = Object.prototype.hasOwnProperty.call(before.slots, spec.folder)
+    attached =
+      Object.prototype.hasOwnProperty.call(before.slots, spec.folder) || worktreeOnDisk
     const alloc = allocateSlot(before, spec.folder)
     slot = alloc.slot
     writeRegistry(dir, config, alloc.registry) // the engine's only write (Docker path)
   } else {
-    attached = fs.existsSync(spec.worktreePath)
+    attached = worktreeOnDisk
   }
 
   // The tree gate: the same facts the checkout planner gets, all of them read
@@ -618,7 +950,8 @@ function specEnvUp(dir, config, specArg) {
     specFoundOn: upOnFork.foundOn,
     forkRef: spec.baseRef || currentBranch(upGit) || 'HEAD',
     specUntracked: upSpecUntracked,
-  })
+    composeFilePresent: composeFilePresent(dir, config),
+  }, { docs })
 
   if (plan.blocked) {
     process.stdout.write(`spec-env up: blocked — ${plan.reason}.\n`)
@@ -650,6 +983,11 @@ function specEnvUp(dir, config, specArg) {
   // the operator's only evidence of which mode actually resolved — print it
   // whenever it was set explicitly, right or wrong.
   out.push('  mode:      worktree (each spec gets its own checkout)')
+  // Said positively and only when asked for, so the absent setup step below
+  // reads as a choice rather than as a project with nothing configured.
+  if (plan.docs) {
+    out.push('  docs:      documents only — no setup commands, no docker')
+  }
   if (trust.reason === 'malformed') {
     out.push(
       '  trusted:   ! .claude/settings.local.json is not valid JSON — left it;' +
@@ -684,6 +1022,21 @@ function specEnvUp(dir, config, specArg) {
   process.stdout.write(out.join('\n') + '\n')
 }
 
+/**
+ * The recorded specless branches (`/no-spec` work), or an empty map.
+ *
+ * Wrapped because every caller wants the same cannot-tell behaviour: a
+ * malformed or unreadable registry must not stop a resolution that the folder
+ * search can answer on its own (`.claude/rules/negative-checks.md` rule 4).
+ */
+function speclessMap(dir, config) {
+  try {
+    return readRegistry(dir, config).specless || {}
+  } catch {
+    return {}
+  }
+}
+
 // A read-only git reader over `cwd`: returns trimmed stdout, or null on failure.
 function gitReader(cwd) {
   return (argv) => {
@@ -862,7 +1215,11 @@ function specEnvDown(dir, config, specArg, flags) {
 
   const base = resolveBaseBranch(config, gitReader(dir))
   const worktreeState = worktreeGitState(spec.worktreePath, base)
-  const plan = planDown(spec, config, flags, { worktreeState, timestamp: compactTimestamp() })
+  const plan = planDown(spec, config, flags, {
+    worktreeState,
+    timestamp: compactTimestamp(),
+    composeFilePresent: composeFilePresent(dir, config),
+  })
 
   if (plan.blocked) {
     process.stdout.write(
@@ -874,12 +1231,25 @@ function specEnvDown(dir, config, specArg, flags) {
 
   // Free the slot (the engine's only write on down) — only if one was held; a
   // worktree-only teardown never touches the registry.
-  if (hasSlot) {
-    writeRegistry(dir, config, freeSlot(registry, spec.folder))
+  //
+  // A SPECLESS BRANCH IS FORGOTTEN HERE TOO, and it has to be: the record is the
+  // only thing that made the name resolvable, so leaving it behind would keep a
+  // torn-down `/no-spec` branch answering to `review`, `integrate` and a bare
+  // `resolve` with a worktree path that is no longer on disk. `forgetSpecless`
+  // is idempotent, so this costs a write and nothing else.
+  const wasSpecless = isSpecless(registry, spec.folder)
+  if (hasSlot || wasSpecless) {
+    let next = registry
+    if (hasSlot) next = freeSlot(next, spec.folder)
+    if (wasSpecless) next = forgetSpecless(next, spec.folder)
+    writeRegistry(dir, config, next)
   }
 
   const out = []
-  out.push(`spec-env down: ${spec.folder}${hasSlot ? ' (slot freed)' : ''}`)
+  out.push(
+    `spec-env down: ${spec.folder}` +
+      (hasSlot ? ' (slot freed)' : wasSpecless ? ' (specless record forgotten)' : ''),
+  )
   out.push('')
   out.push(`  worktree:  ${spec.worktreePath}`)
   out.push(`  volumes:   ${plan.volumesDropped ? 'dropped' : 'kept'}`)
@@ -1001,7 +1371,7 @@ function volumeCreatedAt(names) {
  */
 function provisionedSpecChoice(dir, config, cwd = process.cwd()) {
   const worktreePaths = liveWorktreePaths(gitReader(dir))
-  const provisioned = allSpecs(dir, config, worktreePaths)
+  const provisioned = allSpecs(dir, config, worktreePaths, speclessMap(dir, config))
     .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
     // The primary checkout is itself in `git worktree list`; a spec is
     // provisioned only when it has its OWN worktree, separate from it.
@@ -1081,7 +1451,18 @@ function resolveSpecWithWorktree(dir, config, specArg) {
   // another's. A worktree left behind by a declined teardown can still answer
   // with a stale bucket — that is a leftover to prune, not a lookup to distrust.
   const preferDirs = worktreeGuess === dir ? [] : [worktreeGuess]
-  return resolveSpec(specArg, dir, config, { searchDirs, preferDirs })
+  // A SPECLESS BRANCH RESOLVES TOO, on the registry's word and nothing else.
+  // `/no-spec` work has a worktree and a branch and no document under
+  // `specs/**`, so every verb below — down, integrate, review, resolve, status —
+  // would refuse it as "spec not found". Passing the recorded map here is what
+  // makes one name resolvable without making every typo resolvable: `resolveSpec`
+  // consults it only after the folder search has come up empty, and only for a
+  // name the engine itself wrote down.
+  return resolveSpec(specArg, dir, config, {
+    searchDirs,
+    preferDirs,
+    specless: speclessMap(dir, config),
+  })
 }
 
 // Every spec folder name found under specs/* across the given checkout roots.
@@ -1139,7 +1520,7 @@ function specEnvPrune(dir, config, flags) {
   }
 
   const worktrees = liveWorktreePaths(gitReader(dir))
-  const specs = allSpecs(dir, config, worktrees)
+  const specs = allSpecs(dir, config, worktrees, speclessMap(dir, config))
   const liveSlugs = liveSlugsForSpecs(specs, worktrees)
 
   const olderThanDays =
@@ -1517,7 +1898,9 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
   if (flags.recordPrimary) return recordPrimary(dir, config, r)
   if (flags.assertPrimaryClean) return assertPrimaryClean(dir, config, r)
   process.stdout.write(
-    `spec:       ${r.folder} (${r.bucket})\n` +
+    // A specless branch has no bucket because it has no document — say that
+    // rather than printing `(null)`, which reads as a lookup that failed.
+    `spec:       ${r.folder} (${r.specless ? 'no spec' : r.bucket})\n` +
       `type/slug:  ${r.type} / ${r.slug}\n` +
       `branch:     ${r.branch}\n` +
       `worktree:   ${r.worktreePath}\n` +
@@ -1617,6 +2000,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.
  *
@@ -1635,6 +2066,11 @@ 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'
@@ -1662,6 +2098,135 @@ 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.
+ */
+/**
+ * How often the wait says it is alive, in ms. `0` disables it.
+ *
+ * Three states, not two (`.claude/rules/negative-checks.md` rule 4): a value
+ * that is not a number is a cannot-tell, and it takes the DEFAULT rather than
+ * disabling — being wrong that way costs a line of stderr nobody reads, where
+ * the opposite silently removes the thing keeping the wait alive.
+ */
+function resolveHeartbeatMs(flags) {
+  if (flags.heartbeat === undefined || flags.heartbeat === null) return WAIT_HEARTBEAT_MS
+  const seconds = Number(flags.heartbeat)
+  if (!Number.isFinite(seconds) || seconds < 0) return WAIT_HEARTBEAT_MS
+  return seconds * 1000
+}
+
+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`,
+    )
+  }
+
+  // THE HEARTBEAT GOES TO STDERR, and that is the whole reason it is safe.
+  // Stdout is the result a backgrounded caller parses and, under a monitor,
+  // every stdout line becomes a notification — so a proof-of-life line there
+  // would either corrupt the answer or wake somebody every five minutes.
+  // Stderr reaches the output file and raises neither.
+  //
+  // SUPPRESSED UNDER `--json`, which has one machine-readable payload and must
+  // not grow a second stream beside it.
+  const heartbeatMs = resolveHeartbeatMs(flags)
+  const onHeartbeat =
+    flags.json || heartbeatMs === 0
+      ? null
+      : ({ elapsedMs }) => {
+          process.stderr.write(
+            `spec-env review wait: ${spec.folder} — still waiting (${Math.round(elapsedMs / 60000)}m), ` +
+              `window since ${flags.since}\n`,
+          )
+        }
+
+  const result = await waitForPass(() => readPending(out, spec.folder), flags.since, {
+    timeoutMs,
+    onHeartbeat,
+    heartbeatMs: heartbeatMs || WAIT_HEARTBEAT_MS,
+  })
+
+  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)
@@ -1748,6 +2313,24 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
     }
   }
 
+  // RECORDED BEFORE THE ANSWER IS WRITTEN, so the offer this call hands back is
+  // also the one it spends. Explicit rather than automatic: a plain read of the
+  // gate must stay a read, because `/spec-next` makes one on every run.
+  //
+  // Best-effort, like the render record. A sidecar that could not be written
+  // costs a second offer, which is the harmless direction — where refusing to
+  // answer would block a commit over a bookkeeping failure.
+  if (flags.offered && judged.state === 'armed' && target.spec) {
+    const marked = markGateOffered(judged.gate, { at: new Date().toISOString() })
+    if (marked.marked) {
+      try {
+        writeGate(target.out, marked.gate)
+      } catch {
+        /* the gate is the guard; this is only its memory of having asked */
+      }
+    }
+  }
+
   if (flags.json) {
     process.stdout.write(
       JSON.stringify(
@@ -1758,6 +2341,9 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
           armedAt: judged.gate ? judged.gate.armedAt : null,
           phase: judged.gate ? judged.gate.phase : null,
           required: config.review.required,
+          // Absent stays absent: only an `armed` gate has a way out to declare,
+          // and every cannot-tell state carries none.
+          ...(judged.offer ? { offer: judged.offer } : {}),
           log: judged.gate && Array.isArray(judged.gate.log) ? judged.gate.log : [],
         },
         null,
@@ -1787,6 +2373,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()
@@ -1831,7 +2545,7 @@ 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
@@ -1850,21 +2564,178 @@ async function specEnvReview(dir, config, specArg, flags) {
   // of the wrong spec looks exactly like a review of the right one.
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
+  // THE SIDECAR PATHS, RESOLVED BEFORE THE WORKTREE CHECK — and that ordering
+  // is the whole of this feature. `.spec-env/reviews/` lives in the PRIMARY
+  // CHECKOUT, keyed by the spec's folder name; not one byte of it comes from
+  // the worktree. `--out` moves the page and its sidecars together.
+  const out = reviewOutPath(dir, spec.folder, flags.out)
+
+  // The other half of a confirmation: a pass the operator says is not theirs.
+  // Left in the store it is reported on every render until they stop reading the
+  // line — which is how the real one gets waved away too.
+  //
+  // AHEAD OF THE WORKTREE CHECK, because a pass that needs disowning has almost
+  // always outlived its spec. `review waiting` finds the stranded ones and tells
+  // the reader to `--drop` them; refusing that on a missing worktree made the
+  // hint impossible to follow for every pass it could find, and ten real passes
+  // sat behind it. Disowning reads and writes this one file, so the tree it was
+  // being refused for was never involved.
+  //
+  // IT DOES NOT RETURN when it succeeds. A spec that still HAS a worktree falls
+  // through to the render exactly as before, so the page is rewritten without
+  // the pass on it; the gate below is what turns a successful drop into an
+  // ending, and only when there is no page left to write.
+  //
+  // WHAT WOULD FOOL THIS: a spec whose FOLDER was deleted rather than completed.
+  // `resolveSpecWithWorktree` above needs a document to resolve a name, so such
+  // a pass stays unreachable by name however this gate is ordered — only
+  // `spec-env review waiting`, which scans the store directly, can see it.
+  // Relaxing the worktree check does not cover that case and was never meant to:
+  // the two absences are different, and only one of them is what the ten
+  // stranded passes were behind.
+  let dropped = null
+  if (flags.drop) {
+    const heldRead = readPending(out, spec.folder)
+    if (heldRead.corrupt) {
+      process.stdout.write(
+        `spec-env review: ${reviewPendingPath(out)} is not readable JSON — ` +
+          'move it aside rather than losing the passes it holds.\n',
+      )
+      return
+    }
+    // Same match and the SAME SILENCE as a claim. A drop that listed the codes
+    // it could not find would hand a guesser exactly what the claim withholds.
+    const result = claimPending(heldRead.pending, String(flags.drop).trim())
+    if (!result.pass) {
+      process.stdout.write(
+        `spec-env review: no pending pass with that code` +
+          `${result.count ? ` (${result.count} waiting)` : ''}\n`,
+      )
+      return
+    }
+    writePending(out, result.pending)
+    // Nothing is merged, and the notes sidecar is not touched.
+    dropped = { code: result.pass.code, remaining: result.count }
+  }
+
+  // `--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)) {
+    // A DROP THAT ALREADY HAPPENED IS AN ENDING, not a refusal. The work this
+    // invocation asked for is done and written; there is simply no page left to
+    // rewrite, which is a fact about the spec rather than a failure of the run.
+    if (dropped) {
+      // THE SAME SPELLING the render uses for the same event. A drop reported
+      // one way here and another way there is two events as far as anyone
+      // grepping their scrollback is concerned.
+      process.stdout.write(
+        `spec-env review: ${spec.folder}\n` +
+          `  dropped: ${dropped.code} — merged nothing` +
+          `${dropped.remaining ? ` (${dropped.remaining} still waiting)` : ''}\n` +
+          '  no worktree, so nothing was rendered.\n',
+      )
+      return
+    }
+
+    // THE REFUSAL NAMES THE EXIT THAT WORKS. It used to say "run /spec-start to
+    // provision it", which for a completed spec is advice to resurrect it in
+    // order to throw a pass away — and that was the only advice a reader holding
+    // a stranded pass ever got.
+    //
+    // A STRANDED PASS STAYS UNCLAIMABLE, deliberately. Once the branch has
+    // merged and the worktree is gone a `commit` verdict has nowhere to land, so
+    // honouring one would report work that did not happen. Disowning is the only
+    // honest ending, so it is the only one offered.
+    // WHICH MESSAGE depends on a POSITIVE SIGNAL — a pass actually sitting in
+    // the store. That is not decoration: the two readers are in opposite
+    // situations, and one sentence cannot serve both.
+    //
+    // No pass waiting is overwhelmingly the commonest case — a spec in
+    // `backlog/` that nobody has started — and there `/spec-start` is exactly
+    // the right advice, so that message is left byte-for-byte as it was.
+    //
+    // A pass waiting means the spec has almost certainly finished, and telling
+    // that reader to provision a worktree is telling them to resurrect a
+    // completed spec in order to throw a pass away. A corrupt store reads as
+    // zero, so it takes the untouched message rather than inventing a count.
+    const held = readPending(out, spec.folder)
+    const count = held.corrupt ? 0 : (held.pending.passes || []).length
+    if (!count) {
+      process.stdout.write(
+        `spec-env review: ${spec.folder} has no worktree at ${spec.worktreePath} — ` +
+          'run /spec-start to provision it, or --docs to review the spec itself.\n',
+      )
+      return
+    }
     process.stdout.write(
-      `spec-env review: ${spec.folder} has no worktree at ${spec.worktreePath} — ` +
-        'run /spec-start to provision it.\n',
+      `spec-env review: ${spec.folder} has no worktree at ${spec.worktreePath}.\n` +
+        `  ${count} waiting — disown ${count === 1 ? 'it' : 'one'} with --drop <code>, ` +
+        'or `spec-env review waiting` to list them.\n' +
+        // WHY CLAIMING IS NOT OFFERED, said rather than left to be discovered.
+        // A stranded pass is unclaimable by design: with no worktree a `commit`
+        // verdict has nowhere to land, so honouring one would report work that
+        // did not happen. Disowning is the only honest ending, so it is the
+        // only one named.
+        '  It cannot be claimed: with no worktree, a verdict has nowhere to land.\n' +
+        "  --docs reviews the spec's own documents.\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,
+    }),
+  )
 
-  let mode = 'working'
+  const readFrom = docs ? docs.tree : live.state === 'on' ? dir : spec.worktreePath
+  const git = rawGitReader(readFrom)
+  const trimmed = gitReader(readFrom)
+
+  let mode = docs ? 'docs' : 'working'
   let ref = 'HEAD'
   let base = null
 
@@ -1898,9 +2769,6 @@ async function specEnvReview(dir, config, specArg, flags) {
     mode = 'branch'
   }
 
-  // The sidecar is keyed to the page's path, so resolve that first — `--out`
-  // moves both together.
-  const out = reviewOutPath(dir, spec.folder, flags.out)
   const stored = readNotes(out, spec.folder)
   let notes = stored.notes
   let merged = null
@@ -1947,6 +2815,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
@@ -1995,37 +2896,27 @@ async function specEnvReview(dir, config, specArg, flags) {
       accepted: parsed.accepted.length,
       unaccepted: parsed.unaccepted.length,
       comments: parsed.comments.length,
+      // THE INSTRUCTION THE PASS CARRIED, and the one field here that is not a
+      // count. An action blob concludes nothing — it asks for something to be
+      // done and hands the page straight back — so a claim that reported only
+      // the counts was indistinguishable from a pass carrying no decision at
+      // all, and `/spec-diff` §2b could never fire. That is what a pressed
+      // `live-on` looked like: "0 accepts, 0 withdrawn, 0 comments".
+      //
+      // `null` rather than absent, deliberately. Every other optional key on
+      // this payload is spread away so an existing consumer sees nothing new,
+      // but `claimed` is itself conditional — anything reading it was written
+      // after this shipped, and a present `null` is what separates "carried no
+      // action" from "an engine too old to say".
+      //
+      // It is NOT a verdict and must never reach `sentVerdict`: `ACTIONS` is
+      // disjoint from `VERDICTS` by construction, and the gate reads the
+      // verdict. This is a field beside it, not a widening of it.
+      action: parsed.action || null,
     }
     merged = { accepted: claimed.accepted, unaccepted: claimed.unaccepted, comments: claimed.comments }
   }
 
-  // The other half of a confirmation: a pass the operator says is not theirs.
-  // Left in the store it is reported on every render until they stop reading the
-  // line — which is how the real one gets waved away too.
-  let dropped = null
-  if (flags.drop) {
-    const heldRead = readPending(out, spec.folder)
-    if (heldRead.corrupt) {
-      process.stdout.write(
-        `spec-env review: ${reviewPendingPath(out)} is not readable JSON — ` +
-          'move it aside rather than losing the passes it holds.\n',
-      )
-      return
-    }
-    // Same match and the SAME SILENCE as a claim. A drop that listed the codes
-    // it could not find would hand a guesser exactly what the claim withholds.
-    const result = claimPending(heldRead.pending, String(flags.drop).trim())
-    if (!result.pass) {
-      process.stdout.write(
-        `spec-env review: no pending pass with that code` +
-          `${result.count ? ` (${result.count} waiting)` : ''}\n`,
-      )
-      return
-    }
-    writePending(out, result.pending)
-    // Nothing is merged, and the notes sidecar is not touched.
-    dropped = { code: result.pass.code, remaining: result.count }
-  }
 
   if (flags.notes) {
     // Refuse rather than write over notes we could not read: an unreadable
@@ -2109,7 +3000,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 = {
@@ -2185,7 +3085,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, buttons })
+  // 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
@@ -2201,8 +3117,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
@@ -2219,6 +3141,7 @@ async function specEnvReview(dir, config, specArg, flags) {
         notes,
         gate,
         buttons,
+        ...surfaceArgs,
         fellBack: true,
       })
       if (wider.totals.files > 0) {
@@ -2238,8 +3161,79 @@ async function specEnvReview(dir, config, specArg, flags) {
     data.review = JSON.parse(raw)
   }
 
+  // THE MACHINE HALF. It composes with the written review rather than replacing
+  // it: a page can carry a person's read and a tool's findings at once, and
+  // which is which is on every check as its `source`.
+  //
+  // `--docs` deliberately never runs them. A spec document is prose, not the
+  // code these tools read, and spending a rate-limited review on one is waste.
+  let reviewerOutcomes = null
+  if (flags.runReviewers && !docs && (config.review.reviewers || []).length) {
+    const scope = mode === 'branch' ? 'branch' : 'working'
+    const diffHash = diffHashOf(data.files)
+    const { cache, corrupt } = readChecks(out, spec.folder)
+    let checks
+    let outcomes
+    if (!corrupt && cacheHit(cache, spec.folder, diffHash)) {
+      // KEYED ON THE DIFF, NOT A CLOCK. Re-rendering unchanged work must not
+      // spend another review against an hourly limit — and any change at all
+      // must re-run, because findings about code that has moved on are worse
+      // than no findings.
+      checks = cache.checks
+      outcomes = asCached(cache.outcomes)
+    } else {
+      const ran = await runReviewers(config, {
+        worktree: spec.worktreePath,
+        base: base || reviewBase(),
+        scope,
+        spec: spec.folder,
+        adapters: BUNDLED_ADAPTERS,
+      })
+      checks = ran.checks
+      outcomes = ran.outcomes
+      // Best-effort. A cache that could not be written costs a re-run next
+      // time, which is the harmless direction — it must never fail the render.
+      try {
+        writeChecks(out, {
+          version: CHECKS_VERSION,
+          spec: spec.folder,
+          diffHash,
+          at: now,
+          checks,
+          outcomes,
+        })
+      } catch {
+        /* a cache is an optimisation, never a record */
+      }
+    }
+    reviewerOutcomes = outcomes
+    // The written review's checks lead — a person's read is what the reader
+    // came for — and the machine's follow, grouped by the reviewer that
+    // produced them because `runReviewers` runs in sequence.
+    data.review = {
+      ...(data.review || {}),
+      checks: [...((data.review && data.review.checks) || []), ...checks],
+      reviewers: outcomes,
+    }
+  }
+
   writeReviewPage(out, renderReviewPage(data, { reviewHtml: renderReviewBlock(data.review) }))
 
+  // RECORD WHAT THIS RENDER DECLARED, for the served copy to read back. The
+  // daemon re-renders per request and is not the caller, so without this it can
+  // only see what the work IS — enough for `authoring`, `nospec` and
+  // `committing`, and blind to `midrun` and `refresh`, which say whether the run
+  // had finished. `buttonsForView` takes only those two from here.
+  //
+  // Best-effort, like the reviewer cache: a record that could not be written
+  // costs a served page its narrowing, which is the harmless direction, and it
+  // must never fail a render.
+  try {
+    writeRenderRecord(out, { spec: spec.folder, buttons, at: now })
+  } catch {
+    /* the page is the artefact; this is a note for the daemon */
+  }
+
   // The publish-ready copy, ONLY when asked. An ordinary render must not pay for
   // a second copy of the whole diff on disk for a path most renders never take.
   let publishCopy = null
@@ -2269,8 +3263,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
@@ -2284,7 +3311,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 }
       }
@@ -2297,15 +3324,38 @@ 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,
@@ -2316,6 +3366,10 @@ async function specEnvReview(dir, config, specArg, flags) {
           // reporting it would make every existing consumer see a new key.
           ...(data.buttons ? { buttons: data.buttons } : {}),
           reviewed: Boolean(data.review),
+          // Absent unless reviewers actually ran, so a consumer that never
+          // configured one sees no new key. An empty ARRAY would be a claim
+          // that they ran and said nothing.
+          ...(reviewerOutcomes ? { reviewers: reviewerOutcomes } : {}),
           totals: data.totals,
           notes: data.notes,
           merged,
@@ -2375,13 +3429,22 @@ async function specEnvReview(dir, config, specArg, flags) {
         : '') +
       (claimed
         ? `  claimed: ${claimed.code} — ${claimed.accepted} accept${claimed.accepted === 1 ? '' : 's'}, ` +
-          `${claimed.unaccepted} withdrawn, ${claimed.comments} comment${claimed.comments === 1 ? '' : 's'}\n`
+          `${claimed.unaccepted} withdrawn, ${claimed.comments} comment${claimed.comments === 1 ? '' : 's'}` +
+          // Last on the line rather than folded into the counts: a reader
+          // scanning for what a press did finds the verb at the end of the one
+          // line the claim prints, and a pass with no action reads exactly as it
+          // did before this existed.
+          (claimed.action ? ` · action: ${claimed.action}` : '') +
+          '\n'
         : '') +
       (dropped ? `  dropped: ${dropped.code} — merged nothing\n` : '') +
       (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` : '') +
@@ -2397,39 +3460,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` : '') +
@@ -2505,6 +3574,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)
@@ -2639,6 +3763,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.
  *
@@ -2679,11 +3824,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,
@@ -2721,13 +3871,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 })
 
@@ -2752,7 +3918,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(
@@ -2764,7 +3931,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',
@@ -2815,6 +3993,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')
@@ -2828,8 +4025,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'
@@ -2863,9 +4068,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
   }
@@ -2912,8 +4127,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.
@@ -2926,8 +4146,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,
+  }
 }
 
 /**
@@ -3062,6 +4288,26 @@ async function specEnvConnect(dir, config, specArg) {
 
 // Dispatch `skitterspec spec-env <sub> [args] [--dir path]`. No-ops with a clear
 // message when the feature isn't enabled (no specs/.core/env.config.json).
+// Is the project's configured compose file actually on disk?
+//
+// Read from the PRIMARY CHECKOUT rather than the worktree, and that is forced
+// rather than chosen: a fresh provision plans before `git worktree add` runs, so
+// the worktree does not exist yet to be looked in. A compose file is committed
+// at the repo root in every layout this supports, so the two answers agree
+// wherever both could be read.
+//
+// Any failure to look is `undefined` — cannot-tell, which callers route to the
+// branch that does not escalate — never `false`.
+function composeFilePresent(dir, config) {
+  const file = config && config.docker && config.docker.composeFile
+  if (!file) return undefined
+  try {
+    return fs.existsSync(path.join(dir, file))
+  } catch {
+    return undefined
+  }
+}
+
 // Run a mutating git command; return { ok, err } (stderr captured, not swallowed).
 function runGit(cwd, args) {
   try {
@@ -3081,7 +4327,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.
@@ -3100,10 +4346,10 @@ 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)
+      await specEnvLiveTake(dir, config, specArg, flags)
       break
     case 'release':
       await specEnvLiveRelease(dir, config, specArg)
@@ -3192,7 +4438,7 @@ function bareLive(dir, config) {
 
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
-async function specEnvLiveTake(dir, config, specArg) {
+async function specEnvLiveTake(dir, config, specArg, flags = {}) {
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Probe the primary checkout's git state (IO stays here; the planner is pure).
@@ -3240,7 +4486,34 @@ async function specEnvLiveTake(dir, config, specArg) {
   })
 
   if (plan.blocked) {
-    process.stdout.write(`spec-env live take: blocked — ${plan.reason}.\n`)
+    // A MACHINE-READABLE REFUSAL, so a caller reads the offer rather than
+    // parsing the sentence. `take` had no `--json` at all, and a skill
+    // scraping `blocked — …` prose for a command to run is exactly the kind of
+    // second implementation that drifts out of step with the first.
+    if (flags.json) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            spec: spec.folder,
+            blocked: true,
+            reason: plan.reason,
+            // Absent stays absent — most refusals have no way out to declare.
+            ...(plan.offer ? { offer: plan.offer } : {}),
+          },
+          null,
+          2,
+        ) + '\n',
+      )
+      return
+    }
+    // THE OFFER IS NAMED IN THE TEXT TOO, not only in `--json`. A reader in a
+    // plain terminal is the one person a picker cannot reach, and they are
+    // entitled to the same way out — so the refusal prints what it would have
+    // offered rather than making a harness the only route to it.
+    process.stdout.write(
+      `spec-env live take: blocked — ${plan.reason}.\n` +
+        (plan.offer ? `  ${plan.offer.label}: ${plan.offer.command}\n` : ''),
+    )
     return
   }
 
@@ -3404,8 +4677,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
@@ -3413,6 +4687,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` +
@@ -3443,6 +4737,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` +
@@ -3451,6 +4765,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()
@@ -3463,10 +4810,13 @@ async function specEnv(rest) {
     branch: false,
     out: null,
     review: null,
+    runReviewers: false,
     notes: null,
     resolve: null,
     outcome: null,
     claim: null,
+    offered: false,
+    heartbeat: null,
     drop: null,
     buttons: null,
     json: false,
@@ -3479,6 +4829,8 @@ 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]
@@ -3486,30 +4838,44 @@ async function specEnv(rest) {
     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] === '--run-reviewers') flags.runReviewers = true
     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] === '--heartbeat') flags.heartbeat = 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] === '--offered') flags.offered = true
     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] === '--session') flags.session = args[++i]
     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, badReviewers } = loadEnvConfig(dir)
   if (!present) {
     process.stdout.write(
       'spec-env: isolation not enabled (no specs/.core/env.config.json).\n' +
@@ -3518,9 +4884,61 @@ 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`)
+  }
+
+  // The same advisory, for the one place the check above structurally cannot
+  // reach: `review.reviewers` is an array, and `collectUnknownKeys` deliberately
+  // does not walk into one. Dropping an entry silently is worse than dropping a
+  // key silently — the page then shows no line for that reviewer at all, which
+  // reads as "not configured" rather than "configured wrong".
+  for (const bad of badReviewers || []) {
+    process.stderr.write(
+      `spec-env: ${ENV_CONFIG_LABEL} — review.reviewers[${bad.index}] ${bad.reason}; it is ignored.\n`,
+    )
+  }
+
+  // A `use` NAMING AN ADAPTER THIS BUILD DOES NOT HAVE, said here rather than
+  // waiting for the run to report it. The config module deliberately does not
+  // know the registry — shape is its business and the adapter list is the
+  // runner's — so the check lives at the one place that can see both.
+  //
+  // It is advisory like the two above: an older engine reading a config written
+  // for a newer one is a forward-compat gap, not a mistake, and the run reports
+  // it again as that reviewer's own outcome either way.
+  for (const r of config.review.reviewers || []) {
+    if (r.use && !Object.prototype.hasOwnProperty.call(BUNDLED_ADAPTERS, r.use)) {
+      process.stderr.write(
+        `spec-env: ${ENV_CONFIG_LABEL} — review.reviewers "${r.use}" is not a bundled adapter ` +
+          `(have: ${Object.keys(BUNDLED_ADAPTERS).join(', ') || 'none'}); it will not run.\n`,
+      )
+    }
+  }
+
   switch (sub) {
     case 'up':
-      specEnvUp(dir, config, positional[0])
+      specEnvUp(dir, config, positional[0], flags)
+      break
+    case 'nospec':
+      specEnvNospec(dir, config, positional[0], flags)
+      break
+    case 'main':
+      specEnvMain(dir, config, positional, flags, present, invokedFrom)
       break
     case 'down':
       specEnvDown(dir, config, positional[0], flags)
@@ -3564,10 +4982,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
@@ -3575,20 +5005,27 @@ 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>] [--buttons <set>] [--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>] [--run-reviewers] [--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 gate [spec] --offered           record that the bypass was offered (spends it)\n' +
+          '  review wait [spec] --heartbeat <secs>  proof-of-life cadence on stderr; 0 disables\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' +
@@ -3704,11 +5141,14 @@ async function run(argv) {
 }
 
 module.exports = {
+  SPEC_ENV_VERBS,
   run,
   parse,
   HELP,
   unknownCommand,
   rankLanAddresses,
+  offerableLanAddresses,
+  reviewTierStack,
   serveProcFor,
   serverScriptOk,
   daemonScript,