@nodii/dev 0.6.43 → 0.6.45

package/README.md

@@ -324,7 +324,8 @@ nodii-dev hook claude-figma-post      # reads Claude Code hook JSON on stdin
 nodii-dev hook safety-pre             # silent safety decision; blocks with exit 2
 nodii-dev hook safety-post            # silently records resources created by successful commands
 nodii-dev hook nudge-pre              # guideline nudges before a tool call; never blocks
-nodii-dev hook nudge-stop             # guideline nudges when a lane session stops; asks once
+nodii-dev hook nudge-stop             # holds a lane session's stop until its done check is recorded;
+                                      # guideline nudges when a lane session stops; asks once
 nodii-dev figma checked CS-n --unused-properties --stale-placeholders --dialog-body
 nodii-dev hook print-settings         # prints managed-settings JSON; writes nothing
 ```
@@ -356,10 +357,16 @@ nodii-dev lane start KEY --title TEXT --kind dev_fix|new_build|docs_change|uat_f
 nodii-dev lane step KEY --side backend|frontend --start|--done|--block STEP [--reason TEXT]
                     # --reason is kept as a lane note; on a step already blocked,
                     # --block --reason records the new reason (Dev issue 125 moves it onto the step)
+nodii-dev lane step KEY --side backend|frontend --done STEP --review REVIEW.json
+                    # build_test, adopt_test and local_test record their review (as lane review)
+                    # first; a refused review leaves the step open
+nodii-dev lane review KEY --not-required --decision DEC-nnnn|--question ID|--quote TEXT --at ISO-TIME
+                    # a NOT-REQUIRED record for the current diff, citing the ruling it relies on
 nodii-dev lane evidence KEY --pr|--commit|--figma|--deploy|--dev-check REF
 nodii-dev lane done-check KEY --evidence TEXT|URL
                     # the lane's done check is met (NODII-DEV-CLI-4); a launched
-                    # run that exits after it ends finished, not orphaned
+                    # run that exits after it ends finished, not orphaned; on a
+                    # lane already on_dev (land → verify first) it is a no-op
 nodii-dev lane subagent-quota KEY N
 nodii-dev lane heartbeat KEY [--note TEXT]
 nodii-dev lane resume KEY
@@ -505,7 +512,15 @@ covers `dialog-content`). Edits are judged against the file they produce, so
 an Edit or `apply_patch` that only changes an attribute is read in full.
 
 The Stop nudge asks the session to continue once (`decision: block`, skipped
-when `stop_hook_active`); Codex passes it through its managed dispatcher. A
+when `stop_hook_active`); Codex passes it through its managed dispatcher.
+Before that, in a lane session (a `lane-*.json` identity), the same hook holds
+the stop while the lane's done check is not recorded and the lane is not
+BLOCKED (NODII-DEV-CLI-8), even after an earlier block: it reads the lane from
+Dev and answers `Lane KEY: done check not recorded. Continue the Task: STEP.`
+Recording the done check (`lane done-check`), a blocked step (`lane step
+--block`) or a heartbeat note that starts with "blocked" lets the stop
+through, and so does a lane Dev can't serve. One session is held at most
+`NODII_DEV_STOP_BLOCK_LIMIT` times in a row (default 5), as a cost backstop. A
 nudge hook skips the amendment guard and the waiting-results banner, since
 either would corrupt its JSON; it cannot run a Delta gather.
 
@@ -939,6 +954,19 @@ counts as unfinished. Every report carries `exit_code`, `worktree` and
 `lane_status` evidence. `process.pid` still holds the runtime's own PID, and the
 supervisor appends its report line to `process.log`.
 
+Before it reports an unfinished exit, the supervisor continues the same session
+(NODII-DEV-CLI-9) when the lane is not BLOCKED and the run log names the
+session (Claude's `session_id`, Codex's `thread_id`). It runs `claude ...
+--resume SESSION`, or `codex exec resume ... SESSION -`, with the same model
+and permission mode, and sends `Lane KEY: done check not recorded. Continue the
+Task: STEP.` on stdin. It does this up to `NODII_DEV_LANE_CONTINUATIONS` times
+(default 3; 0 turns it off). Each continuation is a run heartbeat, and
+`process.pid` and the watchdog record follow the new PID. A killed runtime
+(a signal) is never continued. After the last continuation, the exit is
+reported as above and its reason counts the continuations. A supervisor runs
+the CLI version that started it, so a fix to this rule reaches a lane only
+when it is launched or resumed on that version.
+
 A lane's Figma scope is held by published key only (MW8-20): `--figma
 FILE_KEY` for a whole file, or `--figma FILE_KEY=COMPONENT_SET_KEY[,KEY]` for
 its component sets. A node id is refused. `--route /app/...` (repeatable)
@@ -1064,6 +1092,22 @@ commit in `base`, exact reviewed commit in `head`,
 `rules`), `severity`, `summary`, `detail`, `disposition`, optional `path` and
 `line`, and a required `clauseId` for rules findings. `lane reviews` reads the
 append-only history, including whether each cited clause was a missed trigger.
+Dev stores a review while the lane is `building` (the build step's review,
+MW1-68) as well as `built` or `review`. `lane step KEY --done STEP --review
+REVIEW.json` records the same file the same way, then marks the step done;
+`nodii-dev next` prints `--review REVIEW.json` on the `build_test`,
+`adopt_test` and `local_test` done command.
+
+Dev completes those three steps only when the lane's latest review record is
+CLEAN or NOT-REQUIRED (hub-58, 30 Oct); otherwise `lane step --done` gets
+`REVIEW_NOT_RECORDED` or `REVIEW_NOT_CLEAN`. `lane review KEY --not-required`
+stores a NOT-REQUIRED record for the current base and head, citing one ruling
+Dev checks: `--decision` (a locked decision, `DEC-nnnn` or a pre-dev id),
+`--question` (an answered Dev question id), or `--quote TEXT --at ISO-TIME`
+(found verbatim in a Dev inbox answer within ten minutes of that time). Free
+text is not a citation; Dev refuses an unknown one with
+`REVIEW_RULING_NOT_FOUND` or `REVIEW_RULING_SUPERSEDED`. It writes the same
+local push receipt as a review.
 
 Heartbeat notes are optional and limited by Dev to 500 characters.
 Prioritize and deprioritize require a 1–500 character reason, which the CLI

package/dist/cli.js

@@ -216,6 +216,8 @@ Usage: nodii-dev <command> [options] [--json]
   lane start <key> --title TEXT --kind KIND --side SIDE [--repo REPO] [--issue ISSUE]
   lane step <key> --side SIDE --start|--done|--block <step> [--reason TEXT]
                                         # --block --reason on a blocked step records its new reason
+  lane step <key> --side SIDE --done <step> --review REVIEW.json
+                                        # records the review (as lane review) first, then marks the step done
   lane step <key> --side SIDE --not-applicable gather --reason-code pre_harness_lane [--note TEXT]
                                         # coordinator only: Gather never applied (pre-Gather lane); never "done"
   lane evidence <key> --pr|--commit|--figma|--deploy|--dev-check REF
@@ -223,6 +225,8 @@ Usage: nodii-dev <command> [options] [--json]
   lane subagent-quota <key> <n>          # coordinator assigns 0-100 subagent slots
   lane heartbeat|resume|land|verify|prioritize|deprioritize|stop <key>
   lane review <key> --file REVIEW.json  # base/head, outcome and clause-cited findings
+  lane review <key> --not-required --decision DEC-nnnn|--question ID|--quote TEXT --at ISO-TIME
+                                        # no review needed for this diff: cites the ruling Dev validates (hub-58)
   lane reviews <key>                    # stored review history for the lane
   lane freeze add <key> --section SECTION --file ITEM.json --reason TEXT
   lane freeze drop <key> --section SECTION --item ID --reason TEXT
@@ -1050,9 +1054,10 @@ export async function main(argv = process.argv.slice(2)) {
         await recordHookFire(payload).catch(() => {});
         const result = await safetyPreHook(payload);
         const nudges = result.nudges ?? [];
-        if (nudges.length && hookRuntime(payload) === "codex")
+        // Both runtimes show the model a PreToolUse nudge only as additionalContext;
+        // Claude keeps plain stdout of an exit-0 hook out of the model's context.
+        if (nudges.length)
           console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: nudges.join("\n") } }));
-        else for (const nudge of nudges) console.log(nudge);
         return;
       } catch (error) {
         // Only an evaluated safety rule may deny. Discovery, parsing, git,

package/dist/core.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 
-export const VERSION = "0.6.43";
+export const VERSION = "0.6.45";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -222,7 +222,7 @@ export async function checkLogin() {
 export const encode = (value) => encodeURIComponent(value);
 // Switches never take the next token as their value, so
 // `docs upload --wait rulebook/` keeps rulebook/ as a path.
-const SWITCHES = new Set(["json", "wait", "pending", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync", "force", "system", "delta", "probe", "no-probe"]);
+const SWITCHES = new Set(["json", "wait", "pending", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync", "force", "system", "delta", "probe", "no-probe", "not-required"]);
 export function parseArgs(argv) {
   const flags = {};
   const args = [];

package/dist/lane-supervisor.js

@@ -1,10 +1,10 @@
 import { execFile as execFileCallback, spawn as nodeSpawn } from "node:child_process";
-import { open } from "node:fs/promises";
-import { join } from "node:path";
+import { open, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { CliError, devRequest, encode } from "./core.js";
 import { redactRunText } from "./runs.js";
-import { saveWatchedRun, watchdogRunDir } from "./watchdog.js";
+import { processStartedAt, saveWatchedRun, watchdogRunDir } from "./watchdog.js";
 
 /**
  * NODII-DEV-CLI-1: a launched or resumed lane's runtime is the child of this
@@ -18,6 +18,14 @@ import { saveWatchedRun, watchdogRunDir } from "./watchdog.js";
  * watchdog could only see a vanished PID and counted every exit as
  * process_dead.
  *
+ * NODII-DEV-CLI-9: an exit before the done check, with the lane not
+ * BLOCKED, first continues the SAME session (`claude --resume`, `codex exec
+ * resume`) with "Lane <key>: done check not recorded. Continue the Task:
+ * <step>.", up to NODII_DEV_LANE_CONTINUATIONS times (3). Each continuation
+ * is a run heartbeat. Only then is the exit reported, so a lane that stops
+ * early keeps its context instead of becoming an orphan that `lane resume`
+ * restarts fresh.
+ *
  * Launcher protocol (IPC): launch -> spawned {pid} -> start {prompt} ->
  * started; or abort, when the launcher could not record the runtime's PID.
  */
@@ -76,15 +84,37 @@ async function send(request, path, body, attempts = 3) {
 }
 
 /**
- * The lane's Dev status and whether its done check is recorded: a recorded
- * done check, a dev_check step done, or a terminal lane. Unreadable reads as
- * unfinished.
+ * Whether a lane's done check is recorded: `lane done-check` (NODII-DEV-CLI-4),
+ * a dev_check step done, or a terminal lane.
+ */
+export const doneCheckRecorded = (lane) =>
+  Boolean(lane?.doneCheckRecorded)
+  || (lane?.steps ?? []).some((step) => step.stepKey === "dev_check" && step.state === "done")
+  || FINISHED_LANE.has(lane?.status);
+
+/** A lane is BLOCKED by a blocked step (`lane step --block`) or a latest heartbeat note that says so. */
+export function laneBlocked(lane) {
+  if ((lane?.steps ?? []).some((step) => step.state === "blocked")) return true;
+  const heartbeat = (lane?.events ?? []).filter((event) => event.type === "heartbeat").at(-1);
+  return /^\s*blocked\b/i.test(String(heartbeat?.metadata?.note ?? ""));
+}
+
+/** The step a lane that stopped early goes back to (hub-58, NODII-DEV-CLI-8/9). */
+export function continueTaskMessage(laneKey, lane) {
+  const next = (lane?.next ?? []).map((step) => `${step.side}/${step.step}`);
+  const current = [lane?.currentBackendStep && `backend/${lane.currentBackendStep}`, lane?.currentFrontendStep && `frontend/${lane.currentFrontendStep}`].filter(Boolean);
+  const step = (next.length ? next : current).join(" and ") || "the lane's objective";
+  return `Lane ${laneKey}: done check not recorded. Continue the Task: ${step}.`;
+}
+
+/**
+ * The lane's Dev status and whether its done check is recorded. Unreadable
+ * reads as unfinished.
  */
 async function laneProgress(request, laneKey) {
   try {
     const lane = (await request("GET", `/api/v1/lanes/${encode(laneKey)}`)).data;
-    const devChecked = (lane?.steps ?? []).some((step) => step.stepKey === "dev_check" && step.state === "done");
-    return { status: lane?.status ?? null, finished: Boolean(lane?.doneCheckRecorded) || devChecked || FINISHED_LANE.has(lane?.status) };
+    return { status: lane?.status ?? null, finished: doneCheckRecorded(lane) };
   } catch {
     return { status: null, finished: false };
   }
@@ -97,7 +127,7 @@ async function laneProgress(request, laneKey) {
  * every exit, exit 0 included, is a process exit: Dev orphans the run and
  * routes it for recovery (`lane resume`).
  */
-export async function reportLaneExit({ runId, laneKey, exitCode, signal, worktrees, logPath }, {
+export async function reportLaneExit({ runId, laneKey, exitCode, signal, worktrees, logPath, continuations = 0 }, {
   request = devRequest,
   inspect = worktreeState,
   tail = readTail,
@@ -128,7 +158,7 @@ export async function reportLaneExit({ runId, laneKey, exitCode, signal, worktre
     outcome = "process_exit";
     const logTail = redactRunText(await tail(logPath).catch(() => "")).trim();
     body = {
-      reason: `The lane process ${exited} before lane ${laneKey}'s done check was recorded (lane ${status ?? "status unknown"}), so the run is unfinished; its worktree is ${worktree.state}.`,
+      reason: `The lane process ${exited} before lane ${laneKey}'s done check was recorded (lane ${status ?? "status unknown"}), so the run is unfinished; its worktree is ${worktree.state}.${continuations ? ` It was continued in the same session ${continuations} time${continuations === 1 ? "" : "s"} first (NODII-DEV-CLI-9).` : ""}`,
       deathFingerprint: signal ? `lane-signal-${signal}` : clean ? "lane-unfinished-exit-0" : `lane-exit-${exitCode ?? -1}`,
       exitCode: Number.isInteger(exitCode) && exitCode >= 0 && exitCode <= 255 ? exitCode : -1,
       ...(logTail ? { logTail: logTail.slice(-50_000) } : {}),
@@ -156,12 +186,60 @@ export async function markWatchedTerminal(runId, { home } = {}) {
   await saveWatchedRun({ ...record, terminalSeenAt: new Date().toISOString(), registryPath });
 }
 
+const SESSION_ID = { claude: /"session_id":"([0-9a-f-]{36})"/g, codex: /"thread_id":"([0-9a-f-]{36})"/g };
+const LOG_SCAN_BYTES = 256 * 1024;
+
+/** The runtime's session id, from the stream-json / --json lines it wrote to the run log. */
+export async function sessionIdFromLog(logPath, runtime) {
+  const pattern = SESSION_ID[runtime];
+  if (!pattern || !logPath) return null;
+  const handle = await open(logPath, "r");
+  try {
+    const { size } = await handle.stat();
+    // Codex names its thread once, at the start; Claude repeats its session id, so the end has the latest.
+    const ranges = [[0, Math.min(size, LOG_SCAN_BYTES)], [Math.max(0, size - LOG_SCAN_BYTES), Math.min(size, LOG_SCAN_BYTES)]];
+    let found = null;
+    for (const [position, length] of ranges) {
+      const buffer = Buffer.alloc(length);
+      await handle.read(buffer, 0, length, position);
+      for (const match of buffer.toString("utf8").matchAll(pattern)) found = match[1];
+    }
+    return found;
+  } finally {
+    await handle.close();
+  }
+}
+
+/** The same session, resumed headless with the same model and permission mode. */
+export function continuationInvocation(invocation, sessionId) {
+  if (invocation.command === "claude") return { ...invocation, args: [...invocation.args, "--resume", sessionId] };
+  const model = invocation.args[invocation.args.indexOf("--model") + 1];
+  return { ...invocation, args: ["exec", "resume", "--json", "--dangerously-bypass-approvals-and-sandbox", "--model", model, sessionId, "-"] };
+}
+
+/** The watched run follows the continued runtime's PID (the live supervisor still covers it). */
+export async function rewatchRun(runId, pid, { home } = {}) {
+  const registryPath = join(watchdogRunDir(home), `${runId}.json`);
+  const record = JSON.parse(await readFile(registryPath, "utf8"));
+  if (record.terminalSeenAt || record.orphanReportedAt) return;
+  await saveWatchedRun({ ...record, pid, processStartedAt: await processStartedAt(pid).catch(() => null), registryPath });
+}
+
+const continuationLimit = (env) => {
+  const value = Number(env.NODII_DEV_LANE_CONTINUATIONS ?? 3);
+  return Number.isInteger(value) && value >= 0 ? value : 3;
+};
+
 /** The supervisor process: spawn the runtime, hand its PID back, report its exit. */
+
 export async function superviseLane({
   channel = process,
   spawn = nodeSpawn,
   report = reportLaneExit,
   exit = (code) => process.exit(code),
+  request = devRequest,
+  rewatch = rewatchRun,
+  env = process.env,
 } = {}) {
   if (typeof channel.send !== "function")
     throw new CliError("USAGE", "__lane-supervisor is started by lane launch and lane resume only.", 2);
@@ -209,11 +287,46 @@ export async function superviseLane({
     }
   });
   // A signal sent to the supervisor ends the runtime too, and is reported.
-  for (const name of SIGNALS) process.on(name, () => child.kill(name));
-  const { exitCode, signal } = await closed;
+  let stopping = false;
+  for (const name of SIGNALS) process.on(name, () => { stopping = true; child.kill(name); });
+  let { exitCode, signal } = await closed;
   if (state !== "running") return exit(state === "aborted" ? 0 : 1);
+  const limit = continuationLimit(env);
+  let continued = 0;
+  // NODII-DEV-CLI-9: an early stop continues the same session before it is reported.
+  while (!stopping && !signal && continued < limit) {
+    const sessionId = await sessionIdFromLog(logPath, invocation.command).catch(() => null);
+    if (!sessionId) break;
+    let lane;
+    try { lane = (await request("GET", `/api/v1/lanes/${encode(laneKey)}`)).data; } catch { break; }
+    if (doneCheckRecorded(lane) || laneBlocked(lane)) break;
+    const message = continueTaskMessage(laneKey, lane);
+    continued += 1;
+    await request("POST", `/api/v1/runs/${encode(runId)}/heartbeat`, {
+      note: `continuation ${continued}/${limit} of session ${sessionId} after exit ${exitCode}: ${message}`.slice(0, 500),
+    }).catch(() => {});
+    const next = continuationInvocation(invocation, sessionId);
+    try {
+      child = spawn(next.command, next.args, { cwd: next.cwd, env: next.env, shell: false, stdio: ["pipe", "inherit", "inherit"] });
+    } catch {
+      break;
+    }
+    const ended = new Promise((resolve) => {
+      child.once("close", (code, sig) => resolve({ exitCode: code, signal: sig }));
+      child.once("error", () => resolve({ exitCode: -1, signal: null }));
+    });
+    child.once("spawn", () => {
+      writeFile(join(dirname(logPath), "process.pid"), `${child.pid}\n`, { mode: 0o600 }).catch(() => {});
+      rewatch(runId, child.pid).catch(() => {});
+    });
+    // A runtime that exits before reading its prompt must not end the supervisor (EPIPE).
+    child.stdin?.on("error", () => {});
+    child.stdin?.end(`${message}\n`);
+    process.stderr.write(`nodii-dev: ${message} (same-session continuation ${continued}/${limit})\n`);
+    ({ exitCode, signal } = await ended);
+  }
   try {
-    const result = await report({ runId, laneKey, exitCode, signal, worktrees, logPath });
+    const result = await report({ runId, laneKey, exitCode, signal, worktrees, logPath, continuations: continued });
     process.stderr.write(`nodii-dev: lane process exit reported to Dev (${result.outcome}, exit ${signal ?? exitCode}, lane ${result.laneStatus ?? "status unknown"}, worktree ${result.worktree}).\n`);
     return exit(0);
   } catch (error) {

package/dist/lanes.js

@@ -6,6 +6,7 @@ import { launchRecovery } from "./runtime-launcher.js";
 import { recordReviewReceipt, reviewCommitContext } from "./safety.js";
 import { GATHER_TIMEOUT_MS, PICKER_FIRST_PICK_TIMEOUT_MS, PICKER_MODEL, agentFallbackReason, gatherDeadline, gatherText, pickDocuments, pickTimingLine, pickTimingStats, readPickTimings, recordPickTiming, warmPicker, withPickLock } from "./gather.js";
 import { storeGatherFreeze } from "./freeze.js";
+import { doneCheckRecorded } from "./lane-supervisor.js";
 import { SWAP_BOUNDARIES, componentsForScope, guidelineLookup, laneFigmaScope, loadDsCatalog } from "./figma-scope.js";
 
 const execFileAsync = promisify(execFile);
@@ -13,6 +14,8 @@ const via = { via: "nodii-dev" };
 const GATHER_ACTIVE = new Set(["queued", "building"]);
 // heartbeatLane's note limit.
 const BLOCK_NOTE_MAX = 500;
+// MW1-68, MW1-73, MW1-79: steps done only with a CLEAN review, recorded with --review.
+const REVIEW_STEPS = new Set(["build_test", "adopt_test", "local_test"]);
 
 const need = (value, usage) => {
   if (!value) throw new CliError("USAGE", usage, 2);
@@ -157,6 +160,22 @@ export async function reviewBody(flags, read = (path) => readFile(path, "utf8"))
   return { ...body, ...via };
 }
 
+/**
+ * hub-58 (30 Oct): a NOT-REQUIRED record cites exactly one ruling Dev can
+ * check: --decision ID, --question ID, or --quote TEXT with --at ISO-TIME.
+ */
+export function notRequiredCitation(flags) {
+  const given = ["decision", "question", "quote"].filter((x) => flags[x] !== undefined);
+  const usage = "--not-required cites one ruling: --decision DEC-nnnn, --question QUESTION_ID, or --quote TEXT --at ISO-TIME.";
+  if (given.length !== 1 || flags.file !== undefined) throw new CliError("USAGE", usage, 2);
+  const value = requireFlag(flags, given[0]);
+  if (given[0] !== "quote") {
+    if (flags.at !== undefined) throw new CliError("USAGE", usage, 2);
+    return { [given[0]]: value };
+  }
+  return { quote: value, at: requireFlag(flags, "at") };
+}
+
 /**
  * DEC-0011 (MW1-28.1): the body for `lane non-issue`. A re-route needs at
  * least one issue key or an explicit `none`, and the branch work is either
@@ -506,6 +525,31 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
       if (!outerDeadline) deadline.clear();
     }
   }
+  // MW2-45: `lane review` and a step's `--done --review` record through one path.
+  const recordReview = async (reviewFlags = flags) => {
+    // The input is checked before git is read, so a bad call never touches the worktree.
+    const notRequired = reviewFlags["not-required"] ? notRequiredCitation(reviewFlags) : null;
+    const filed = notRequired ? null : await reviewBody(reviewFlags, read);
+    const current = await reviewContext();
+    const body = filed ?? { base: current.base, head: current.commit, iterationCount: 0, exitReason: "NOT_REQUIRED", appliedPatches: [], unresolvedProposals: [], reviewerErrors: [], findings: [], notRequired, ...via };
+    if (body.head !== current.commit || body.base !== current.base)
+      throw new CliError(
+        "REVIEW_FILE_STALE",
+        `The review file covers base ${body.base ?? "(missing)"} and head ${body.head ?? "(missing)"}, but this worktree is base ${current.base} and head ${current.commit}. Review the current diff and write a new receipt.`,
+        2,
+      );
+    const payload = await request("POST", `/api/v1/lanes/${encode(id)}/review`, body);
+    try { await reviewReceipt(); }
+    catch (error) {
+      throw new CliError("REVIEW_RECEIPT_FAILED", `${ref}: Dev recorded the review, but the local push receipt could not be written (${error?.message ?? error}). Re-run nodii-dev lane review ${ref} --file REVIEW.json from its worktree.`, 1);
+    }
+    return payload;
+  };
+  const reviewSummary = (p) => {
+    const findings = p.data.findings ?? [];
+    const missed = findings.filter((finding) => finding.missedTrigger === true).length;
+    return `review recorded for the current commit and origin/main (${p.data.exitReason}; ${findings.length} finding(s), ${missed} missed trigger(s))`;
+  };
   if (action === "step") {
     const selected = ["start", "done", "block", "not-applicable"].filter((x) => flags[x]);
     if (selected.length !== 1) throw new CliError("USAGE", "lane step needs exactly one of --start, --done, --block, or --not-applicable.", 2);
@@ -515,9 +559,12 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     if (flags.reason !== undefined && (selected[0] !== "block" || !reason)) throw new CliError("USAGE", "--reason TEXT goes with --block.", 2);
     const ruling = selected[0] === "not-applicable" ? notApplicableRuling(flags) : null;
     if (!ruling && (flags["reason-code"] !== undefined || flags.note !== undefined)) throw new CliError("USAGE", "--reason-code and --note go with --not-applicable.", 2);
+    if (flags.review !== undefined && (selected[0] !== "done" || typeof flags.review !== "string" || !flags.review)) throw new CliError("USAGE", "--review REVIEW.json goes with --done.", 2);
     const lane = (await request("GET", `/api/v1/lanes/${encode(id)}`)).data;
     const step = lane.steps.find((x) => x.side === side && (x.id === stepRef || x.stepKey === stepRef));
     if (!step) throw new CliError("STEP_NOT_FOUND", `No ${side} step ${stepRef} on ${ref}.`, 1);
+    // A review goes only with a step it can finish; record a late one with lane review.
+    if (flags.review !== undefined && step.state !== "current") throw new CliError("INVALID_STEP_STATE", `${side}/${step.stepKey} on ${ref} is ${step.state}, not current; nothing was recorded. To store the review anyway, run nodii-dev lane review ${ref} --file ${flags.review}.`, 1);
     // Dev finishes gather and starts the next step itself when Gather's Freeze
     // is written (NODII-DEV-CLI-3), so asking for that again is already true.
     const already = { done: "done", start: "current" }[selected[0]];
@@ -541,7 +588,18 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
       await recordReason();
       return { payload: { data: step, reason }, human: `${ref}: ${side}/${step.stepKey} is still blocked; new reason recorded.` };
     }
-    const payload = await request("POST", `/api/v1/lanes/${encode(id)}/steps/${encode(step.id)}/${selected[0]}`, via);
+    // MW1-68: the build step's review is recorded first; a refused review leaves the step open.
+    const review = flags.review === undefined ? null : await recordReview({ file: flags.review });
+    let payload;
+    try {
+      payload = await request("POST", `/api/v1/lanes/${encode(id)}/steps/${encode(step.id)}/${selected[0]}`, via);
+    } catch (error) {
+      if (!review && ["REVIEW_NOT_RECORDED", "REVIEW_NOT_CLEAN"].includes(error?.code))
+        throw new CliError(error.code, `${side}/${step.stepKey} on ${ref} needs a stored review record whose latest entry is CLEAN, or a NOT-REQUIRED record citing a ruling (hub-58). Run lane step ${ref} --side ${side} --done ${step.stepKey} --review REVIEW.json, or lane review ${ref} --not-required --decision DEC-nnnn|--question ID|--quote TEXT --at ISO-TIME first.`, 1);
+      if (!review) throw error;
+      throw new CliError(error?.code ?? "STEP_DONE_FAILED", `${ref}: the review is recorded, but ${side}/${step.stepKey} was not marked done (${error?.message ?? error}). Run the same lane step --done without --review.`, 1);
+    }
+    if (review) return { payload: { ...payload, review: review.data }, human: `${ref}: ${side}/${step.stepKey} done; ${reviewSummary(review)}.` };
     if (reason) {
       try {
         await recordReason();
@@ -562,7 +620,17 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     const value = typeof flags.evidence === "string" ? flags.evidence.trim() : "";
     if (!value) throw new CliError("USAGE", "lane done-check needs --evidence TEXT|URL: what shows the lane's done check is met.", 2);
     const body = { kind: "done_check", ...(/^https?:\/\//i.test(value) && URL.canParse(value) ? { url: value } : { ref: value }), ...via };
-    const payload = await request("POST", `/api/v1/lanes/${encode(id)}/evidence`, body);
+    let payload;
+    try {
+      payload = await request("POST", `/api/v1/lanes/${encode(id)}/evidence`, body);
+    } catch (error) {
+      // A lane already verified on dev (or closed) has finished: its run ends
+      // finished on exit (lane-supervisor.js), so a later done check is a no-op.
+      if (error?.code !== "LANE_TERMINAL") throw error;
+      const lane = (await request("GET", `/api/v1/lanes/${encode(id)}`)).data;
+      if (!doneCheckRecorded(lane)) throw error;
+      return { payload: { data: lane }, human: `${ref} is already ${lane.status}, which counts as its done check; nothing more to record. The lane's run ends finished when its process exits.` };
+    }
     if (!payload?.data?.doneCheckRecorded)
       throw new CliError("DONE_CHECK_NOT_RECORDED", `Dev took the evidence but does not show ${ref}'s done check as recorded; it predates NODII-DEV-CLI-4. The run would still end orphaned.`, 1);
     return { payload, human: `${ref}: done check recorded. The lane's run ends finished when its process exits.` };
@@ -617,29 +685,7 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     };
   }
   if (action === "land") return { payload: await request("POST", `/api/v1/lanes/${encode(id)}/land`, via), human: `${ref}: recorded on main.` };
-  if (action === "review") {
-    const body = await reviewBody(flags, read);
-    const current = await reviewContext();
-    if (body.head !== current.commit || body.base !== current.base)
-      throw new CliError(
-        "REVIEW_FILE_STALE",
-        `The review file covers base ${body.base ?? "(missing)"} and head ${body.head ?? "(missing)"}, but this worktree is base ${current.base} and head ${current.commit}. Review the current diff and write a new receipt.`,
-        2,
-      );
-    const payload = await request("POST", `/api/v1/lanes/${encode(id)}/review`, body);
-    try { await reviewReceipt(); }
-    catch (error) {
-      throw new CliError("REVIEW_RECEIPT_FAILED", `${ref}: Dev recorded the review, but the local push receipt could not be written (${error?.message ?? error}). Re-run nodii-dev lane review ${ref} --file REVIEW.json from its worktree.`, 1);
-    }
-    return {
-      payload,
-      human: (p) => {
-        const findings = p.data.findings ?? [];
-        const missed = findings.filter((finding) => finding.missedTrigger === true).length;
-        return `${ref}: review recorded for the current commit and origin/main (${p.data.exitReason}; ${findings.length} finding(s), ${missed} missed trigger(s)).`;
-      },
-    };
-  }
+  if (action === "review") return { payload: await recordReview(), human: (p) => `${ref}: ${reviewSummary(p)}.` };
   if (action === "reviews") {
     const payload = await request("GET", `/api/v1/lanes/${encode(id)}`);
     return {
@@ -651,7 +697,7 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
               .map((run) => {
                 const missed = run.findings.filter((finding) => finding.missedTrigger === true).length;
                 return [
-                  `${run.createdAt}\t${run.head}\t${run.exitReason}\t${run.findings.length} finding(s)\t${missed} missed trigger(s)`,
+                  `${run.createdAt}\t${run.head}\t${run.exitReason}\t${run.findings.length} finding(s)\t${missed} missed trigger(s)${run.notRequiredKind ? `\tcites ${run.notRequiredKind} ${run.notRequiredKind === "operator_quote" ? `"${run.notRequiredQuote}" (${run.notRequiredAt})` : run.notRequiredRef}` : ""}`,
                   ...run.findings.map(
                     (finding) =>
                       `  ${finding.severity}\t${finding.perspective}\t${finding.clauseId ?? "-"}\t${finding.summary}${finding.missedTrigger ? "\tMISSED_TRIGGER" : ""}`,
@@ -723,7 +769,7 @@ export async function nextCommand(ref, flags, { request = devRequest, changedPat
   const lane = (await request("GET", `/api/v1/lanes/${encode(ref)}`)).data;
   const pending = lane.steps.filter((x) => ["waiting", "current", "blocked"].includes(x.state)).sort((a, b) => a.position - b.position);
   const steps = ["backend", "frontend"].map((side) => pending.find((x) => x.side === side)).filter(Boolean);
-  const data = steps.map((step) => ({ side: step.side, step: step.stepKey, label: step.label, state: step.state, command: `nodii-dev lane step ${lane.key} --side ${step.side} --${step.state === "current" ? "done" : "start"} ${step.stepKey}` }));
+  const data = steps.map((step) => ({ side: step.side, step: step.stepKey, label: step.label, state: step.state, command: `nodii-dev lane step ${lane.key} --side ${step.side} --${step.state === "current" ? "done" : "start"} ${step.stepKey}${step.state === "current" && REVIEW_STEPS.has(step.stepKey) ? " --review REVIEW.json" : ""}` }));
   // M05-32: the clauses Dev serves for this step. A failure here never hides the next step.
   let rules = null;
   if (data.length || flags.deltaContext) {

package/dist/nudges.js

@@ -9,7 +9,9 @@ import { execFile } from "node:child_process";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { promisify } from "node:util";
+import { devRequest, encode } from "./core.js";
 import { isFigmaTool, isReadTool } from "./hooks.js";
+import { continueTaskMessage, doneCheckRecorded, laneBlocked } from "./lane-supervisor.js";
 import { patchPaths } from "./safety.js";
 
 const execFileAsync = promisify(execFile);
@@ -17,6 +19,7 @@ const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit", "apply
 const SHELL_TOOLS = new Set(["Bash", "shell", "exec_command"]);
 export const LANE_KNOWLEDGE = "nodii-lane-knowledge.json";
 export const SUBMIT_CHECKS = "nodii-submit-checks.json";
+export const STOP_GATE = "nodii-stop-gate.json";
 export const SUBMIT_CHECK_FLAGS = ["unused-properties", "stale-placeholders", "dialog-body"];
 const OPEN_MD = "docs/figma-ux-drive/qa-with-abhi/open.md";
 const DS_SOURCE = /["'](@cognion-nucleus\/nodii-(?:design-system|blocks)(?:\/[^"']*)?)["']/;
@@ -414,10 +417,50 @@ export async function lastAssistantText(payload) {
 const openUnconfirmed = (lane) => [lane.freeze?.unconfirmed, lane.unconfirmed].flat().filter(Boolean).filter((item) =>
   typeof item === "string" || !(item?.resolvedAt || item?.confirmedAt || ["resolved", "confirmed", "dropped"].includes(item?.status)));
 
+const stopBlockLimit = (env) => {
+  const value = Number(env.NODII_DEV_STOP_BLOCK_LIMIT ?? 5);
+  return Number.isInteger(value) && value >= 0 ? value : 5;
+};
+
+/**
+ * NODII-DEV-CLI-8 (hub-58, gate for AGENT-HARNESS-13): a lane session may not
+ * stop before its done check is recorded unless the lane is BLOCKED. The
+ * lane is read fresh; an unreadable lane lets the stop through (fail open).
+ * Each session is held at most NODII_DEV_STOP_BLOCK_LIMIT times (5) in a row,
+ * a cost backstop; the launch supervisor then continues it (NODII-DEV-CLI-9).
+ */
+export async function doneCheckStopGate(payload, context, { request = devRequest, env = process.env, state = (update) => writePrivateJson(context.root, STOP_GATE, update) } = {}) {
+  if (context?.role !== "lane" || !context.lane?.key) return null;
+  let lane;
+  try { lane = (await request("GET", `/api/v1/lanes/${encode(context.lane.key)}`)).data; } catch { return null; }
+  const session = String(payload.session_id ?? "");
+  const forget = (before) => { const sessions = { ...before.sessions }; delete sessions[session]; return { sessions }; };
+  if (!lane || doneCheckRecorded(lane) || laneBlocked(lane)) {
+    await state(forget).catch(() => {});
+    return null;
+  }
+  let held = 0;
+  try {
+    await state((before) => {
+      held = (before.sessions?.[session] ?? 0) + 1;
+      return held > stopBlockLimit(env) ? forget(before) : { sessions: { ...before.sessions, [session]: held } };
+    });
+  } catch {
+    // No count to hold against: block once, as the other Stop nudges do.
+    held = payload.stop_hook_active ? Number.POSITIVE_INFINITY : 1;
+  }
+  if (held > stopBlockLimit(env)) return null;
+  return continueTaskMessage(context.lane.key, lane);
+}
+
 /** Stop nudges. A lane that has just been nudged once is left to stop (stop_hook_active). */
-export async function nudgeStop(payload, context, { lastText = lastAssistantText, status = (root) => git(root, "status", "--porcelain") } = {}) {
+export async function nudgeStop(payload, context, { lastText = lastAssistantText, status = (root) => git(root, "status", "--porcelain"), gate = doneCheckStopGate } = {}) {
   const lane = context?.lane;
-  if (!lane || payload.stop_hook_active) return [];
+  if (!lane) return [];
+  // The done-check gate holds the stop even after an earlier block (stop_hook_active).
+  const held = await gate(payload, context).catch(() => null);
+  if (held) return [held];
+  if (payload.stop_hook_active) return [];
   const notes = [];
   const text = await lastText(payload);
   if (claimsDone(text) && lane.status !== "on_dev")

package/dist/safety.js

@@ -95,10 +95,11 @@ function gitInvocations(tokens) {
 
 function commandRef(after, verb) {
   if (!after.length) return null;
-  if (["checkout", "reset"].includes(verb) && after[0] === "--") return null;
   let skip = false;
   for (const item of after) {
     if (skip) { skip = false; continue; }
+    // Everything after `--` is a pathspec (`git reset -q -- file` unstages), never a ref.
+    if (item === "--" && ["checkout", "reset"].includes(verb)) return null;
     if (["-b", "-B", "--orphan", "--pathspec-from-file"].includes(item)) { skip = true; continue; }
     if (item.startsWith("-")) continue;
     return item;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.43",
+  "version": "0.6.45",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {