@nodii/dev 0.6.44 → 0.6.46

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
@@ -420,6 +427,10 @@ without ending their run, `/tmp/cc-socks/<pid>.sock` sockets whose process is
 gone, and watched worktrees whose HEAD has commits absent from its configured
 remote branch. Each observation is posted to the watched run by the machine
 coordinator; `process_dead` transitions it to explicit `orphan` immediately.
+Every watched run whose PID is alive (or whose lane supervisor is, between
+same-session continuations) is reported as `process_alive`. Dev counts that as
+the run's liveness (hub-58, AH-4), so a late heartbeat never makes a working
+run quiet or orphaned.
 A sweep leaves a dead lane runtime alone while its lane supervisor still lives
 (the supervisor reports the exit itself) and skips it once the supervisor has
 reported.
@@ -505,7 +516,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 +958,22 @@ 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. While the runtime lives, continuations
+included, the supervisor heartbeats its run every
+`NODII_DEV_RUN_HEARTBEAT_SECONDS` (60) as the lane identity that owns it;
+nothing else heartbeats a launched lane's run. 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 +1099,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

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.44";
+export const VERSION = "0.6.46";
 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/doctor.js

@@ -5,7 +5,7 @@ import { devRequest, encode, isOAuthConfig, query, setAuthProvider } from "./cor
 import { OAuthAuthProvider, decodeClaims, loadRefreshToken } from "./oauth.js";
 import { inferGitContext, repoName } from "./lanes.js";
 import { figmaFileKey, figmaLockCheck, holdsSet, notRegisteredHint, scopeText } from "./figma.js";
-import { PICKER_MODEL, PICKER_MODEL_DIGEST, inspectOllama } from "./gather.js";
+import { PICKER_MODEL, PICKER_MODEL_DIGEST, STALE_PIN_HINT, inspectOllama } from "./gather.js";
 import { hookDiagnostics } from "./hook-doctor.js";
 
 /**
@@ -274,7 +274,7 @@ export async function doctorCommand(deps = {}) {
         model: PICKER_MODEL, digest: picker.digest ?? null, size: picker.size ?? null,
       }));
     else if (!picker.modelInstalled) checks.push(missing("picker_model", `${PICKER_MODEL} is not installed`, "nodii-dev setup --yes", { model: PICKER_MODEL }));
-    else checks.push(missing("picker_model", `${PICKER_MODEL} digest is ${picker.digest ?? "unknown"}; required ${PICKER_MODEL_DIGEST}`, "nodii-dev setup --yes", { model: PICKER_MODEL, digest: picker.digest ?? null, requiredDigest: PICKER_MODEL_DIGEST }));
+    else checks.push(missing("picker_model", `${PICKER_MODEL} digest is ${picker.digest ?? "unknown"}; this CLI pins ${PICKER_MODEL_DIGEST}; ${STALE_PIN_HINT}`, "nodii-dev setup --yes", { model: PICKER_MODEL, digest: picker.digest ?? null, requiredDigest: PICKER_MODEL_DIGEST }));
   } catch (error) {
     checks.push(missing("ollama", error?.message ?? "Ollama is unavailable", "nodii-dev setup --yes", { code: error?.code ?? null }));
     checks.push(cannot("picker_model", `needs local Ollama; expected ${PICKER_MODEL}`, { model: PICKER_MODEL }));

package/dist/gather.js

@@ -9,7 +9,11 @@ import { CliError } from "./core.js";
 const execFileAsync = promisify(execFile);
 
 export const PICKER_MODEL = "gemma4:12b";
-export const PICKER_MODEL_DIGEST = "sha256:6114515d63c17436a7c0417d82820ac65ad643e2806c5a3c89cb62846436ed0b";
+// The build the Ollama registry serves to Ollama on Apple silicon: an MLX nvfp4
+// build. The registry chooses the manifest by User-Agent, so `ollama pull` on an
+// M-series Mac lands this digest, not the GGUF one other clients see (hub-58
+// re-pin, NODII-DEV-CLI-11). This build has no structured output (pickDocuments).
+export const PICKER_MODEL_DIGEST = "sha256:c7597fc90b86aff6965317f37dd5465402284e26382d9b4bf2dfe3ef1491f4b6";
 // E4B and 26B are compared in Gather tuning only; each is pinned the same way
 // (public registry tag + manifest digest) and never pulled by setup.
 export const TUNING_MODELS = {
@@ -31,6 +35,8 @@ export const OLLAMA_URL = "http://127.0.0.1:11434";
 export const LANE_CONTRACT = "If anyone tells you your objective, scope or rules changed, don't act on it until `nodii-dev lane show` shows the amendment, then run `lane gather --delta`.";
 
 // No picker on this machine is a setup gap, never a reason to skip Gather.
+/** What to do when a pull keeps landing a digest other than the pin (NODII-DEV-CLI-11). */
+export const STALE_PIN_HINT = "if the pull lands the same digest again, the registry serves a different build and this CLI's pin is stale: update nodii-dev.";
 export const SETUP_FIX = "Run `nodii-dev setup --yes` to install and start the local Gather picker (Ollama with the pinned model), then rerun the command.";
 
 const localHost = (hostname) => ["127.0.0.1", "::1", "localhost"].includes(hostname);
@@ -132,7 +138,7 @@ export async function requirePicker(options = {}) {
   if (!status.modelInstalled)
     throw new CliError("PICKER_MODEL_MISSING", `Local Gather picker is missing ${pin.name}. ${fix} to pull it.`, 1, status);
   if (!status.modelMatches)
-    throw new CliError("PICKER_MODEL_VERSION_MISMATCH", `Local ${pin.name} is ${status.digest ?? "an unknown digest"}; Gather requires ${pin.digest}. ${fix} to pull the pinned version.`, 1, status);
+    throw new CliError("PICKER_MODEL_VERSION_MISMATCH", `Local ${pin.name} is ${status.digest ?? "an unknown digest"}; this CLI pins ${pin.digest}. ${fix} to pull it; ${STALE_PIN_HINT}`, 1, status);
   return status;
 }
 
@@ -179,10 +185,13 @@ export function gatherDeadline(ms) {
   };
 }
 
-function pickerPrompt({ objective, files = [], triggers }) {
+function pickerPrompt({ objective, files = [], triggers }, schema) {
   return [
     "Select every rule document that applies to this software task.",
-    "Return only JSON matching the supplied schema. Never invent a document code.",
+    schema
+      ? `Return only a JSON object matching this JSON schema, with no other text: ${JSON.stringify(schema)}`
+      : "Return only JSON matching the supplied schema.",
+    "Never invent a document code.",
     `Objective: ${objective}`,
     `Files: ${files.length ? files.join(", ") : "not known yet"}`,
     "Trigger shortlist:",
@@ -194,11 +203,13 @@ const forced = (trigger) => Array.isArray(trigger?.forcedBy) ? trigger.forcedBy.
 
 /**
  * Why a lane Gather hands the pick to the agent instead (hub-58, 30 Oct): this
- * Mac has no picker model, or no Ollama at all. Null for every other failure.
+ * Mac has no picker model, or no Ollama at all, or a model without structured
+ * output answered invalid JSON twice (Q-155). Null for every other failure.
  */
 export function agentFallbackReason(error) {
   if (error?.code === "PICKER_MODEL_MISSING") return `${error.details?.model ?? PICKER_MODEL} not installed; run nodii-dev setup`;
   if (error?.code === "PICKER_UNAVAILABLE" && error.details?.unreachable) return `no local Ollama at ${error.details.url}; run nodii-dev setup`;
+  if (error?.code === "PICKER_RESPONSE_INVALID" && error.details?.unconstrained) return "gemma output invalid";
   return null;
 }
 
@@ -216,24 +227,23 @@ export async function pickDocuments(input, options = {}) {
   const started = Date.now();
   try {
     await requirePicker(timedOptions);
-    const payload = await jsonRequest("/api/chat", {
+    const schema = pickSchema(input.triggers);
+    const chat = (messages, extra) => jsonRequest("/api/chat", {
       ...timedOptions,
-      body: {
-        model,
-        stream: false,
-        format: pickSchema(input.triggers),
-        messages: [{ role: "user", content: pickerPrompt(input) }],
-        options: { num_ctx: PICKER_CONTEXT, temperature: 0 },
-      },
+      body: { model, stream: false, ...extra, messages, options: { num_ctx: PICKER_CONTEXT, temperature: 0 } },
     });
+    let payload;
     let result;
-    try { result = JSON.parse(payload.message?.content); }
-    catch { throw new CliError("PICKER_RESPONSE_INVALID", "Local Gather picker did not return its required JSON document list.", 1); }
-    const allowed = new Set(input.triggers.map((x) => x.code));
-    if (!Array.isArray(result.documents) || result.documents.some((x) => typeof x !== "string" || !allowed.has(x)))
-      throw new CliError("PICKER_RESPONSE_INVALID", "Local Gather picker returned a document outside the trigger shortlist.", 1);
+    let attempts = 1;
+    try {
+      payload = await chat([{ role: "user", content: pickerPrompt(input) }], { format: schema });
+      result = checkPick(payload.message?.content, schema);
+    } catch (error) {
+      if (!structuredOutputUnavailable(error)) throw error;
+      ({ payload, result, attempts } = await unconstrainedPick(chat, input, schema, model));
+    }
     const required = input.triggers.filter(forced).map((x) => x.code);
-    return { documents: [...new Set([...result.documents, ...required])], model, context: PICKER_CONTEXT, latency: pickLatency(payload, Date.now() - started) };
+    return { documents: [...new Set([...result.documents, ...required])], model, context: PICKER_CONTEXT, structured: !result.unconstrained, attempts, latency: pickLatency(payload, Date.now() - started) };
   } catch (error) {
     // Our own deadline, not the caller's: stop the stuck pick so nothing queues behind it.
     if (controller.signal.aborted && !options.signal?.aborted) {
@@ -247,6 +257,52 @@ export async function pickDocuments(input, options = {}) {
   }
 }
 
+const structuredOutputUnavailable = (error) => error?.code === "PICKER_UNAVAILABLE" && /structured output is unavailable/i.test(error.message ?? "");
+
+/**
+ * A pick from a build without structured output (the MLX gemma4:12b, Q-155 via
+ * hub-58): ask for the schema in the prompt and validate the answer after. One
+ * retry carries the validation error; a second invalid answer is
+ * PICKER_RESPONSE_INVALID with `unconstrained`, which a lane Gather hands to
+ * the agent picker.
+ */
+async function unconstrainedPick(chat, input, schema, model) {
+  const messages = [{ role: "user", content: pickerPrompt(input, schema) }];
+  for (let attempt = 1; ; attempt += 1) {
+    // Without `format` Ollama turns Gemma's thinking on, which spends the
+    // whole pick budget reasoning (ah-17 live run: 120 s timeout vs 0.5 s).
+    const payload = await chat(messages, { think: false });
+    const content = payload.message?.content;
+    try {
+      return { payload, result: { ...checkPick(content, schema, { fenced: true }), unconstrained: true }, attempts: attempt };
+    } catch (error) {
+      if (error?.code !== "PICKER_RESPONSE_INVALID") throw error;
+      if (attempt === 2)
+        throw new CliError("PICKER_RESPONSE_INVALID", `Local Gather picker ${model} has no structured output and answered invalid JSON twice: ${error.message}`, 1, { unconstrained: true, model, attempts: attempt });
+      messages.push({ role: "assistant", content: String(content ?? "") }, { role: "user", content: `That answer is invalid: ${error.message} Answer again with only the JSON object.` });
+    }
+  }
+}
+
+/**
+ * Check a pick against its schema: an object with only `documents`, a list of
+ * shortlist codes (duplicates are removed after, as for the schema path).
+ * `fenced` also accepts the Markdown code fence an unconstrained model wraps
+ * its JSON in.
+ */
+export function checkPick(content, schema, { fenced = false } = {}) {
+  const text = fenced ? String(content ?? "").replace(/^\s*```(?:json)?\s*\n?([\s\S]*?)\n?\s*```\s*$/, "$1") : content;
+  let result;
+  try { result = JSON.parse(text); }
+  catch { throw new CliError("PICKER_RESPONSE_INVALID", "Local Gather picker did not return its required JSON document list.", 1); }
+  const { enum: codes } = schema.properties.documents.items;
+  if (!result || typeof result !== "object" || Array.isArray(result) || Object.keys(result).some((key) => key !== "documents"))
+    throw new CliError("PICKER_RESPONSE_INVALID", "Local Gather picker must return a JSON object with only a `documents` list.", 1);
+  if (!Array.isArray(result.documents) || result.documents.some((x) => typeof x !== "string" || !codes.includes(x)))
+    throw new CliError("PICKER_RESPONSE_INVALID", "Local Gather picker returned a document outside the trigger shortlist.", 1);
+  return { documents: result.documents };
+}
+
 /**
  * The pick's JSON schema. No `uniqueItems`: it wedges Ollama's grammar
  * sampler on real Gather prompts (ah-19 sandbox finding, 30 Oct). Duplicates
@@ -510,7 +566,7 @@ export async function setupOllama({ check = false, inspect = inspectOllama, exec
     const current = await inspect();
     if (current.modelInstalled && current.modelMatches) return { changed: [], ...current };
     if (check && current.modelInstalled)
-      throw new CliError("PICKER_MODEL_VERSION_MISMATCH", `${PICKER_MODEL} digest is ${current.digest ?? "unknown"}; required ${PICKER_MODEL_DIGEST}.`, 1, current);
+      throw new CliError("PICKER_MODEL_VERSION_MISMATCH", `${PICKER_MODEL} digest is ${current.digest ?? "unknown"}; this CLI pins ${PICKER_MODEL_DIGEST}. Run \`nodii-dev setup --yes\` to pull it; ${STALE_PIN_HINT}`, 1, current);
     if (check) throw new CliError("PICKER_MODEL_MISSING", `${PICKER_MODEL} is not installed.`, 1, current);
   } catch (error) {
     if (check || !["PICKER_UNAVAILABLE", "PICKER_MODEL_MISSING"].includes(error?.code)) throw error;
@@ -522,6 +578,7 @@ export async function setupOllama({ check = false, inspect = inspectOllama, exec
   await run("ollama", ["pull", PICKER_MODEL], exec);
   const ready = await inspect();
   if (!ready.modelInstalled) throw new CliError("PICKER_MODEL_MISSING", `Ollama pull finished but ${PICKER_MODEL} is not installed.`, 1, ready);
-  if (!ready.modelMatches) throw new CliError("PICKER_MODEL_VERSION_MISMATCH", `Ollama pulled ${PICKER_MODEL} at ${ready.digest ?? "an unknown digest"}; required ${PICKER_MODEL_DIGEST}.`, 1, ready);
+  // A fresh pull is what the registry serves now, so a mismatch here is a stale pin.
+  if (!ready.modelMatches) throw new CliError("PICKER_MODEL_VERSION_MISMATCH", `The Ollama registry serves ${PICKER_MODEL} at ${ready.digest ?? "an unknown digest"}, but this CLI pins ${PICKER_MODEL_DIGEST}: the pin is stale, so pulling again will not help. Update nodii-dev to a release with the current pin.`, 1, { ...ready, stalePin: true });
   return { changed: [PICKER_MODEL], ...ready };
 }

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,66 @@ 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 });
+}
+
+// The run's expected heartbeat is 60 s; Dev marks it quiet at 15 min and orphan at 45.
+const heartbeatInterval = (env) => {
+  const seconds = Number(env.NODII_DEV_RUN_HEARTBEAT_SECONDS ?? 60);
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 60_000;
+};
+
+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);
@@ -180,6 +264,13 @@ export async function superviseLane({
     return exit(1);
   }
   let state = "spawning";
+  // The run's heartbeat (30 Oct, hub-58 P0): nothing else heartbeats a launched
+  // lane's run, so while the runtime lives (continuations included) the
+  // supervisor does, as the lane identity that owns the run.
+  const heartbeat = setInterval(() => {
+    if (state !== "running") return;
+    request("POST", `/api/v1/runs/${encode(runId)}/heartbeat`, { note: `lane runtime pid ${child.pid} alive (supervisor ${process.pid})` }).catch(() => {});
+  }, heartbeatInterval(env));
   const closed = new Promise((resolve) => child.once("close", (exitCode, signal) => resolve({ exitCode, signal })));
   child.once("error", (error) => {
     if (state !== "spawning") return;
@@ -209,11 +300,50 @@ 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;
-  if (state !== "running") return exit(state === "aborted" ? 0 : 1);
+  let stopping = false;
+  for (const name of SIGNALS) process.on(name, () => { stopping = true; child.kill(name); });
+  let { exitCode, signal } = await closed;
+  if (state !== "running") {
+    clearInterval(heartbeat);
+    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);
+  }
+  clearInterval(heartbeat);
   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/dist/watchdog.js

@@ -142,11 +142,14 @@ export async function collectWatchdogFacts(records, {
   errors = [],
 } = {}) {
   const deadRuns = [];
+  const liveRuns = [];
   for (const record of records) {
-    // A live lane supervisor is reporting this exit itself (NODII-DEV-CLI-1).
-    if (record.supervisorPid && await isPidAlive(record.supervisorPid, record.supervisorStartedAt)) continue;
-    if (!(await isPidAlive(record.pid, record.processStartedAt)))
-      deadRuns.push({ runId: record.runId, pid: record.pid, ...(record.worktree ? { worktree: record.worktree } : {}) });
+    const alive = await isPidAlive(record.pid, record.processStartedAt);
+    // A live lane supervisor is reporting this exit itself (NODII-DEV-CLI-1),
+    // and between same-session continuations it is what keeps the run alive.
+    const supervised = Boolean(record.supervisorPid) && await isPidAlive(record.supervisorPid, record.supervisorStartedAt);
+    if (alive || supervised) liveRuns.push({ runId: record.runId, pid: record.pid, runtimeAlive: alive });
+    else deadRuns.push({ runId: record.runId, pid: record.pid, ...(record.worktree ? { worktree: record.worktree } : {}) });
   }
   const unpushedWorktrees = [];
   for (const worktree of new Set(records.map((record) => record.worktree).filter(Boolean))) {
@@ -160,7 +163,7 @@ export async function collectWatchdogFacts(records, {
   let staleSockets = [];
   try { staleSockets = await listStaleSockets(); }
   catch (error) { errors.push({ kind: "socket", code: error?.code ?? "SOCKET_INSPECTION_FAILED" }); }
-  return { checkedAt: now().toISOString(), deadRuns, staleSockets, unpushedWorktrees, errors };
+  return { checkedAt: now().toISOString(), deadRuns, liveRuns, staleSockets, unpushedWorktrees, errors };
 }
 
 async function assertCoordinator(config, request) {
@@ -249,6 +252,20 @@ export async function sweepWatchdog({
       facts.errors.push({ kind: "run", runId: record.runId, observation: "worktree_unpushed", code: error?.code ?? "RUN_WATCHDOG_REPORT_FAILED" });
     }
   }
+  // hub-58 (AH-4): a PID this Mac sees alive is the run's liveness, so a run
+  // whose heartbeat is late is never quiet or orphaned while it works.
+  for (const live of facts.liveRuns ?? []) {
+    const record = byId.get(live.runId);
+    if (!record || record.orphanReportedAt || record.terminalSeenAt) continue;
+    try {
+      await request("POST", `/api/v1/runs/${encode(record.runId)}/watchdog`, observationBody({
+        observation: "process_alive", machineId: effectiveMachineId, pid: record.pid, observedAt: now().toISOString(),
+        detail: live.runtimeAlive ? "Process is alive." : "Its lane supervisor is alive (between same-session continuations).",
+      }));
+    } catch (error) {
+      facts.errors.push({ kind: "run", runId: record.runId, observation: "process_alive", code: error?.code ?? "RUN_WATCHDOG_REPORT_FAILED" });
+    }
+  }
   for (const dead of facts.deadRuns) {
     const record = byId.get(dead.runId);
     if (!record || record.orphanReportedAt || record.terminalSeenAt) continue;

package/package.json

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