@skitterbyte/skitterspec 22.0.0 → 22.1.0

package/src/cli.js

@@ -40,6 +40,8 @@ const SPEC_ENV_VERBS = Object.freeze([
   'stage',
   'status',
   'resolve',
+  'nospec',
+  'main',
 ])
 const {
   readRegistry,
@@ -47,9 +49,13 @@ const {
   allocateSlot,
   freeSlot,
   portOffset,
+  recordSpecless,
+  forgetSpecless,
+  isSpecless,
 } = require('./env/registry.js')
 const {
   resolveSpec,
+  resolveSpecless,
   resolveBaseBranch,
   liveWorktreePaths,
   collectSpecFolders,
@@ -106,6 +112,7 @@ const {
   claimPending,
   passesSince,
   waitForPass,
+  WAIT_HEARTBEAT_MS,
   waitingPasses,
   describePending,
   pendingAge,
@@ -119,14 +126,32 @@ const {
   reviewGatePath,
   readGate,
   writeGate,
+  writeRenderRecord,
   armGate,
   disarmGate,
   gateState,
+  markGateOffered,
 } = require('./env/review.js')
-const { planUp, planCheckoutUp } = require('./env/provision.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')
@@ -181,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
@@ -194,7 +226,8 @@ Usage:
                                 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
@@ -377,8 +410,8 @@ function specEnvReviewWaiting(dir, config, flags) {
 
 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))
@@ -394,14 +427,19 @@ function specEnvStatus(dir, config) {
 
   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))
 }
@@ -606,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.
@@ -657,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
@@ -683,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`)
@@ -715,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;' +
@@ -749,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) => {
@@ -927,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(
@@ -939,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'}`)
@@ -1066,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.
@@ -1146,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.
@@ -1204,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 =
@@ -1582,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` +
@@ -1796,6 +2114,21 @@ function gateTarget(dir, config, specArg) {
  * `--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 {
@@ -1836,7 +2169,30 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
     )
   }
 
-  const result = await waitForPass(() => readPending(out, spec.folder), flags.since, { timeoutMs })
+  // 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`)
@@ -1957,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(
@@ -1967,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,
@@ -2187,6 +2564,60 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
   // 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.
@@ -2220,9 +2651,63 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
     }
   })()
   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, or --docs to review the spec itself.\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
   }
@@ -2284,9 +2769,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
     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
@@ -2414,37 +2896,27 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
       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
@@ -2689,8 +3161,79 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
     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
@@ -2823,6 +3366,10 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
           // 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,
@@ -2882,7 +3429,13 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
         : '') +
       (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
@@ -3735,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 {
@@ -3776,7 +4349,7 @@ async function specEnvLive(dir, config, positional, flags) {
       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)
@@ -3865,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).
@@ -3913,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
   }
 
@@ -4210,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,
@@ -4235,6 +4838,7 @@ 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
@@ -4246,15 +4850,18 @@ async function specEnv(rest) {
     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])
   }
@@ -4268,7 +4875,7 @@ async function specEnv(rest) {
   // paths, and the registry identically whether run from main or a worktree.
   dir = resolvePrimaryCheckout(dir, gitReader(dir))
 
-  const { config, present, unknown } = 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' +
@@ -4295,9 +4902,43 @@ async function specEnv(rest) {
     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)
@@ -4371,7 +5012,7 @@ async function specEnv(rest) {
       break
     default:
       process.stdout.write(
-        `Usage: skitterspec spec-env <${SPEC_ENV_VERBS.join('|')}> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--verdict <word>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--buttons <set>] [--json] [--record-primary] [--assert-primary-clean]\n` +
+        `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' +
@@ -4379,6 +5020,8 @@ async function specEnv(rest) {
           '  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' +