@nodii/dev 0.6.39 → 0.6.41

package/README.md

@@ -417,6 +417,9 @@ 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.
+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.
 Run launchers and wrappers persist one owner-only record per process under
 `~/.config/nodii-dev/watchdog/runs/`; the plist itself contains only absolute
 command/config paths, its schedule, and log paths, while OAuth credentials
@@ -916,6 +919,22 @@ The launched process uses the already-provisioned lowercase identity (for
 example `~/.config/nodii-dev/agents/lane-ah-12.json`), never the coordinator's
 Dev identity.
 
+A launched or resumed runtime runs under a detached lane supervisor (an
+internal `nodii-dev __lane-supervisor` process), which sees its exit code and
+reports it to Dev as the lane's identity (NODII-DEV-CLI-1). It first reads the
+lane's status. A lane whose done check is recorded (its `dev_check` step done,
+or the lane `on_dev`, `non_issue` or `stopped`) has finished. On it, exit 0 with a clean worktree ends the run
+`done`, exit 0 with uncommitted or untracked files ends it `handed_off` and names
+them, and any other exit ends it `failed`. None of these counts as a death. A
+process that stops before the done check is recorded is unfinished, whatever
+its exit code (a lane that exits 0 after Gather included). It is reported as a
+`process-exit` with its code, fingerprint (`lane-unfinished-exit-0`,
+`lane-exit-N` or `lane-signal-S`) and redacted log tail. Dev orphans that run,
+so `lane resume` relaunches it with `recoveryOf`. A lane status Dev can't serve
+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`.
+
 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)
@@ -938,7 +957,13 @@ messages. Every CLI call from a launched worktree checks the current watched
 run's acknowledgement version. A pending change is printed and blocks the
 call until `lane gather --delta` serves the current rules and acknowledges the
 newest displayed version. `NODII_DEV_RUN_ID` makes this check per subagent run,
-so one child cannot acknowledge for its siblings.
+so one child cannot acknowledge for its siblings. Help and version
+(`--help`, `-h`, `help`, `--version`) skip the check, so a blocked lane can
+still read how to unblock itself. With the agent picker, `lane gather --delta`
+first prints a Trigger shortlist and acknowledges nothing; its `--json` names
+the open amendment and carries the record command as `data.next.command`
+(`--picker agent --shortlist ID --documents CODE[,CODE] --delta`). Running that
+records the pick and acknowledges the amendment (AGENT-HARNESS-14).
 
 Gather also persists the lane's bounded Freeze: the objective and done check,
 strict repository/Figma boundaries, the current pinned clauses, and the lane's

package/dist/cli.js

@@ -95,6 +95,7 @@ import {
   showWaitingResults,
   superviseRun,
 } from "./runs.js";
+import { superviseLane } from "./lane-supervisor.js";
 import { awsCli, superviseRemoteRun } from "./remote.js";
 
 const HELP = `nodii-dev ${VERSION}
@@ -199,7 +200,9 @@ Usage: nodii-dev <command> [options] [--json]
   lane gather [<key>] --picker agent [--shortlist ID --documents CODE[,CODE]]
                                         # the lane agent picks instead of local Gemma: alone it prints the
                                         # recorded trigger shortlist; with --shortlist/--documents it records
-                                        # the pick (picker: agent) and the Clause map
+                                        # the pick (picker: agent) and the Clause map; --json carries that
+                                        # record command as data.next.command, and with --delta it also
+                                        # acknowledges a pending amendment (help stays readable meanwhile)
   lane gather show [<key>] [--gather ID]  # the lane's Clause map (the Freeze references it, not its clauses)
   run [--kind build|test_run|subagent|deploy] [--name TEXT] [--artifact PATH] -- <command> [args...]
                                         # watched command: registers with NODII_DEV_RUN_ID,
@@ -496,12 +499,17 @@ export async function figmaFileAdd(value, flags, { request = devRequest } = {})
   }
 }
 
+// Help and version only print text, so they stay readable while an amendment
+// blocks the lane: a blocked lane needs them to unblock itself (AGENT-HARNESS-14).
+const readsHelp = (argv) => argv[0] === "help" || argv.some((token) => ["--help", "-h"].includes(token)) || (argv.length === 1 && ["--version", "-v"].includes(argv[0]));
+
 export async function main(argv = process.argv.slice(2)) {
-  // Amendment acknowledgement is a lane-wide backstop, including otherwise
-  // local commands such as help and version.
+  // A lane's own exit reporter runs after its runtime ends (NODII-DEV-CLI-1).
+  if (argv[0] === "__lane-supervisor") return superviseLane();
+  // Amendment acknowledgement is a lane-wide backstop for every other command.
   // A nudge hook is fail-open and writes only its own JSON: it cannot run a
   // Delta gather, and a waiting-results banner would corrupt its output.
-  if (argv[0] !== "__run-supervisor" && !(argv[0] === "hook" && argv[1]?.startsWith("nudge-"))) {
+  if (argv[0] !== "__run-supervisor" && !readsHelp(argv) && !(argv[0] === "hook" && argv[1]?.startsWith("nudge-"))) {
     await amendmentGuard(argv);
     await showWaitingResults({ acknowledge: argv[0] !== "hook" });
   }

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.39";
+export const VERSION = "0.6.41";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");

package/dist/freeze.js

@@ -21,6 +21,7 @@ export function shouldReground(argv) {
         "-h",
         "help",
         "hook",
+        "__lane-supervisor",
         "login",
         "logout",
       ].includes(command),
@@ -109,6 +110,7 @@ export const GATHER_LOOKUP_IDS = ["figma-guidelines"];
 /** Build the stored contract; Delta Gather keeps lane-authored sections. */
 export function freezeFromGather({
   gather,
+  ask,
   boundaries,
   issue,
   laneNotes,
@@ -131,7 +133,8 @@ export function freezeFromGather({
     );
   return {
     objective: {
-      ask: gather.objective,
+      // Dev's Lane contract names the ask; without one, Gather's objective.
+      ask: ask ?? gather.objective,
       issue: issue === undefined ? (current?.objective?.issue ?? null) : issue,
       laneNotes:
         laneNotes === undefined

package/dist/lane-supervisor.js

@@ -0,0 +1,222 @@
+import { execFile as execFileCallback, spawn as nodeSpawn } from "node:child_process";
+import { open } from "node:fs/promises";
+import { 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";
+
+/**
+ * NODII-DEV-CLI-1: a launched or resumed lane's runtime is the child of this
+ * supervisor, so its exit code is known. The supervisor reports it to Dev
+ * with the worktree's clean/dirty state and the lane's status. A lane whose
+ * done check is recorded (its dev_check step done, or the lane on_dev,
+ * non_issue or stopped) has finished: its run
+ * ends, never as a death. A process that stops before that is unfinished,
+ * whatever its exit code: it is reported as a process exit, which Dev orphans
+ * so `lane resume` relaunches it (hub-58 scope add). Before this, the
+ * watchdog could only see a vanished PID and counted every exit as
+ * process_dead.
+ *
+ * Launcher protocol (IPC): launch -> spawned {pid} -> start {prompt} ->
+ * started; or abort, when the launcher could not record the runtime's PID.
+ */
+
+const execFile = promisify(execFileCallback);
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const LOG_TAIL_BYTES = 8 * 1024;
+// Dev's terminal lane statuses: verified on dev (lane verify), or closed.
+const FINISHED_LANE = new Set(["on_dev", "non_issue", "stopped"]);
+
+/** Each worktree's uncommitted and untracked paths; null when git cannot read it. */
+export async function worktreeState(worktrees, { execute = execFile } = {}) {
+  const dirty = [];
+  const unreadable = [];
+  for (const worktree of worktrees) {
+    try {
+      const { stdout } = await execute("git", ["-C", worktree, "status", "--porcelain"], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 });
+      for (const line of stdout.split("\n").filter(Boolean)) dirty.push(`${worktree}: ${line.trim()}`);
+    } catch {
+      unreadable.push(worktree);
+    }
+  }
+  return { state: unreadable.length ? "unknown" : dirty.length ? "dirty" : "clean", dirty, unreadable };
+}
+
+async function readTail(path, bytes = LOG_TAIL_BYTES) {
+  if (!path) return "";
+  const handle = await open(path, "r");
+  try {
+    const { size } = await handle.stat();
+    const length = Math.min(size, bytes);
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, size - length);
+    return buffer.toString("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+const describeWorktree = ({ state, dirty, unreadable }) => [
+  ...dirty.slice(0, 50),
+  ...(dirty.length > 50 ? [`... ${dirty.length - 50} more`] : []),
+  ...unreadable.map((worktree) => `${worktree}: git status failed`),
+].join("\n") || state;
+
+async function send(request, path, body, attempts = 3) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await request("POST", path, body);
+    } catch (error) {
+      // Dev's answer is final; only a transport failure is retried.
+      if (error instanceof CliError || attempt >= attempts) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 500 * attempt));
+    }
+  }
+}
+
+/**
+ * The lane's Dev status and whether its done check is recorded: a dev_check
+ * step done, or a terminal lane. 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: devChecked || FINISHED_LANE.has(lane?.status) };
+  } catch {
+    return { status: null, finished: false };
+  }
+}
+
+/**
+ * Report one lane process exit. On a finished lane, exit 0 with a clean
+ * worktree ends the run done, exit 0 with uncommitted work hands it off
+ * naming that work, and any other exit ends it failed. On an unfinished lane
+ * 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 }, {
+  request = devRequest,
+  inspect = worktreeState,
+  tail = readTail,
+  markTerminal = markWatchedTerminal,
+} = {}) {
+  const worktree = await inspect(worktrees);
+  const { status, finished } = await laneProgress(request, laneKey);
+  const clean = exitCode === 0 && !signal;
+  const exitRef = signal ? `signal ${signal}` : String(exitCode ?? -1);
+  const exited = signal ? `was ended by ${signal}` : `exited with code ${exitCode ?? -1}`;
+  const evidence = [
+    { kind: "exit_code", ref: exitRef },
+    { kind: "worktree", ref: worktree.state, note: describeWorktree(worktree) },
+    { kind: "lane_status", ref: status ?? "unknown" },
+  ];
+  let outcome;
+  let body;
+  if (finished && clean) {
+    outcome = worktree.state === "clean" ? "done" : "handed_off";
+    body = outcome === "done"
+      ? { status: "done", evidence }
+      : { status: "handed_off", handoff: `The lane process exited 0 and left its worktree ${worktree.state}:\n${describeWorktree(worktree)}`, evidence };
+  } else if (finished) {
+    // A finished lane has nothing to resume, so a failed exit is not a death.
+    outcome = "failed";
+    body = { status: "failed", reason: `The lane process ${exited} after lane ${laneKey} reached ${status}.`, evidence };
+  } else {
+    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}.`,
+      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) } : {}),
+    };
+  }
+  try {
+    await send(request, `/api/v1/runs/${encode(runId)}/${outcome === "process_exit" ? "process-exit" : "end"}`, body);
+  } catch (error) {
+    // The agent may have ended its own run already; that is not a failure.
+    if (error?.code !== "RUN_ALREADY_TERMINAL") throw error;
+    outcome = "already_terminal";
+  }
+  await markTerminal(runId).catch(() => {});
+  return { outcome, exitCode: exitCode ?? null, signal: signal ?? null, worktree: worktree.state, laneStatus: status };
+}
+
+/** The sweep skips a run whose exit was reported (it would otherwise report process_dead). */
+export async function markWatchedTerminal(runId, { home } = {}) {
+  const registryPath = join(watchdogRunDir(home), `${runId}.json`);
+  const handle = await open(registryPath, "r");
+  let record;
+  try { record = JSON.parse(await handle.readFile("utf8")); }
+  finally { await handle.close(); }
+  if (record.terminalSeenAt || record.orphanReportedAt) return;
+  await saveWatchedRun({ ...record, terminalSeenAt: new Date().toISOString(), registryPath });
+}
+
+/** 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),
+} = {}) {
+  if (typeof channel.send !== "function")
+    throw new CliError("USAGE", "__lane-supervisor is started by lane launch and lane resume only.", 2);
+  const launch = await new Promise((resolve) => channel.once("message", resolve));
+  if (launch?.type !== "launch") return exit(2);
+  const { invocation, runId, laneKey, worktrees, logPath } = launch;
+  // The launcher may already be gone; a reply it cannot read is dropped.
+  const tell = (message) => {
+    try { if (channel.connected !== false) channel.send(message); } catch {}
+  };
+  let child;
+  try {
+    child = spawn(invocation.command, invocation.args, { cwd: invocation.cwd, env: invocation.env, shell: false, stdio: ["pipe", "inherit", "inherit"] });
+  } catch (error) {
+    tell({ type: "error", message: error.message });
+    return exit(1);
+  }
+  let state = "spawning";
+  const closed = new Promise((resolve) => child.once("close", (exitCode, signal) => resolve({ exitCode, signal })));
+  child.once("error", (error) => {
+    if (state !== "spawning") return;
+    state = "failed";
+    tell({ type: "error", message: error.message });
+  });
+  child.once("spawn", () => {
+    if (state !== "spawning") return;
+    state = "waiting";
+    tell({ type: "spawned", pid: child.pid });
+  });
+  channel.on("message", (message) => {
+    if (message?.type === "start" && state === "waiting") {
+      state = "running";
+      child.stdin.end(message.prompt);
+      tell({ type: "started" });
+    } else if (message?.type === "abort" && state !== "running") {
+      state = "aborted";
+      child.kill("SIGTERM");
+    }
+  });
+  // A launcher that went away before start never handed over a prompt.
+  channel.once("disconnect", () => {
+    if (state === "waiting" || state === "spawning") {
+      state = "aborted";
+      child.kill("SIGTERM");
+    }
+  });
+  // 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);
+  try {
+    const result = await report({ runId, laneKey, exitCode, signal, worktrees, logPath });
+    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) {
+    process.stderr.write(`nodii-dev: could not report the lane process exit to Dev (${error?.code ?? error?.message ?? error}); the watchdog reports it as process_dead.\n`);
+    return exit(1);
+  }
+}

package/dist/lanes.js

@@ -98,7 +98,31 @@ const agentFollowUp = (ref, shortlistId, flags) => [
     .filter((flag) => typeof flags[flag] === "string")
     .map((flag) => `--${flag} ${shellQuote(flags[flag])}`),
 ].join(" ");
+// The record step, in --json too: an agent reads the payload, not the text
+// (AGENT-HARNESS-14). With --delta it also acknowledges a pending amendment.
+const agentNext = (ref, shortlistId, triggers, flags) => ({
+  command: agentFollowUp(ref, shortlistId, flags),
+  fill: "--documents: the codes of every document that applies, from triggers; forced ones are added for you.",
+  forced: triggers.filter((trigger) => trigger.forcedBy?.length).map((trigger) => trigger.code),
+  acknowledgesAmendment: Boolean(flags.delta),
+});
+// Dev's Lane contract (hub-58): objective, issue body, the coordinator's lane
+// notes, done check and boundaries, printed before anything else.
+const contractLines = (data) => (data.laneContract ? ["Lane contract", data.laneContract, ""] : []);
+async function laneContract(id, request, options) {
+  try {
+    return (await request("GET", `/api/v1/lanes/${encode(id)}/contract`, undefined, options)).data?.text ?? null;
+  } catch (error) {
+    // A Dev from before the Lane contract route: say so, never hide it.
+    if (error?.code === "HTTP_404" || error?.code === "NOT_FOUND") return "(this Dev does not serve the Lane contract yet; read the lane with `nodii-dev lane show`)";
+    throw error;
+  }
+}
+// Gather never ends on a bare "finished" (hub-58): the next step is the task.
+const nextStepText = (ref, doneCheck) =>
+  `Gather is finished. Next: Task. Work the objective until ${doneCheck} is met, then run \`nodii-dev lane land ${ref}\` (or the lane's finish command). Don't stop before that.`;
 const agentShortlistText = (ref, data, flags) => [
+  ...contractLines(data),
   `Trigger shortlist ${data.shortlistId} · ${JSON.stringify(data.objective)}`,
   "You are Gather's picker (picker: agent). Nothing is recorded yet.",
   ...data.triggers.map((trigger) => `  ${trigger.code}\t${trigger.title ?? ""}: ${trigger.sentence ?? ""}${trigger.forcedBy?.length ? `  [forced by ${trigger.forcedBy.join(", ")}]` : ""}`),
@@ -387,8 +411,10 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
         : await request("POST", "/api/v1/rules/shortlist", shortlistBody, { signal });
       const shortlistId = shortlist.data?.shortlistId;
       const triggers = shortlist.data?.triggers ?? [];
-      if (byAgent && !byAgent.shortlist)
-        return { payload: { data: { recorded: false, picker: "agent", shortlistId, objective, triggers } }, human: (p) => agentShortlistText(ref, p.data, flags) };
+      if (byAgent && !byAgent.shortlist) {
+        const contract = await laneContract(id, request, { signal });
+        return { payload: { data: { recorded: false, picker: "agent", shortlistId, objective, triggers, laneContract: contract, next: agentNext(ref, shortlistId, triggers, flags) } }, human: (p) => agentShortlistText(ref, p.data, flags) };
+      }
       // Only the local model pick takes the per-lane pick lock; an agent pick
       // records a choice already made (AGENT-HARNESS-19 + GATHER-NA).
       const pickInput = {
@@ -409,7 +435,8 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
           // No picker on this Mac: the agent picks from the same shortlist (hub-58).
           const fallback = agentFallbackReason(error);
           if (!fallback) throw error;
-          return { payload: { data: { recorded: false, picker: "agent", fallback, shortlistId, objective, triggers } }, human: (p) => `picker: agent (${p.data.fallback})\n${agentShortlistText(ref, p.data, flags)}` };
+          const contract = await laneContract(id, request, { signal });
+          return { payload: { data: { recorded: false, picker: "agent", fallback, shortlistId, objective, triggers, laneContract: contract, next: agentNext(ref, shortlistId, triggers, flags) } }, human: (p) => `picker: agent (${p.data.fallback})\n${agentShortlistText(ref, p.data, flags)}` };
         }
       }
       const payload = await request("POST", `/api/v1/lanes/${encode(id)}/gather`, {
@@ -421,6 +448,7 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
         ...(sectionLimit !== undefined ? { sectionLimitPerDocument: sectionLimit } : {}),
         shortlistId,
         picker: byAgent ? "agent" : picked.model ?? PICKER_MODEL,
+        doneCheck,
       }, { signal });
       const figma = figmaScope.map((file) => ({
         fileKey: file.fileKey,
@@ -434,7 +462,19 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
         lane.launch?.narrowingRemainder && `Narrowing remainder: ${lane.launch.narrowingRemainder}`,
       ].filter(Boolean);
       const freezeRequest = (method, path, body, options = {}) => request(method, path, body, { ...options, signal });
-      await storeFreeze(id, {
+      // Dev's Lane contract is what Gather printed; the Freeze stores it word for word.
+      const contract = payload.data?.contract;
+      const contractRepos = contract?.boundaries?.repos;
+      const fromContract = Boolean(contractRepos?.length && contractRepos.every((repository) => repository.repo && repository.branch && repository.worktree));
+      await storeFreeze(id, fromContract ? {
+        gather: payload.data,
+        ask: contract.objective.ask,
+        boundaries: contract.boundaries,
+        issue: contract.objective.issue,
+        laneNotes: contract.objective.laneNotes,
+        doneCheck: contract.objective.doneCheck ?? doneCheck,
+        lookups: lookup ? [lookup] : [],
+      } : {
         gather: payload.data,
         boundaries: { repos: repositories, ...(declaredFigma ? { figma } : {}) },
         issue,
@@ -453,7 +493,8 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
       // The pick's model and latency ride along in --json (morning check records them).
       const result = { ...payload, picker: { model: picked.model ?? null, latency: picked.latency ?? null, ...(picked.timing ? { timing: picked.timing, stats: picked.stats } : {}) } };
       const timingLine = picked.timing ? `\n${pickTimingLine(picked.timing, picked.stats)}` : "";
-      return { payload: result, human: (p) => `${gatherText(p, objective, reasons)}${scopeNotice}${timingLine}` };
+      const doneText = contract?.objective?.doneCheck ?? doneCheck;
+      return { payload: result, human: (p) => `${gatherText(p, objective, reasons)}${scopeNotice}${timingLine}\n\n${nextStepText(ref, doneText)}` };
     } catch (error) {
       if (signal.aborted) throw new CliError("GATHER_TIMEOUT", `Gather's Dev requests exceeded their ${Math.round(deadline.ms / 1000)}-second deadline (the local pick runs on its own budget); nothing was retried.`, 1);
       throw error;

package/dist/runtime-launcher.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import * as fsPromises from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { configPath } from "./core.js";
 import { recordWatchedRun } from "./watchdog.js";
 
@@ -141,12 +142,23 @@ export function recoveryStateRoot(path = configPath()) {
   return join(nodiiDir, "runs");
 }
 
-async function launchDetached({ invocation, prompt, runId, laneKey, devConfigPath }, {
+// The supervisor is this package's own entrypoint (src/ in a checkout, dist/ when packed).
+const SUPERVISOR_ENTRY = fileURLToPath(new URL("nodii-dev.js", import.meta.url));
+
+/**
+ * Spawn the runtime under a detached lane supervisor (NODII-DEV-CLI-1): the
+ * supervisor is the runtime's parent, so it sees the exit code and reports it
+ * to Dev. The recorded PID stays the runtime's own; the prompt is sent only
+ * after that PID is saved and watched.
+ */
+async function launchDetached({ invocation, prompt, runId, laneKey, devConfigPath, addDirs = [] }, {
   spawnImpl,
   fs,
   stateRoot,
   watch,
   terminate,
+  execPath = process.execPath,
+  supervisorEntry = SUPERVISOR_ENTRY,
 }) {
   absolutePath(stateRoot, "stateRoot");
   const runDir = join(stateRoot, runId);
@@ -162,63 +174,83 @@ async function launchDetached({ invocation, prompt, runId, laneKey, devConfigPat
     throw error;
   }
 
-  let child;
+  let supervisor;
   try {
-    child = spawnImpl(invocation.command, invocation.args, {
+    supervisor = spawnImpl(execPath, [supervisorEntry, "__lane-supervisor"], {
       cwd: invocation.cwd,
       env: invocation.env,
       shell: false,
       detached: true,
-      stdio: ["pipe", log.fd, log.fd],
+      stdio: ["ignore", log.fd, log.fd, "ipc"],
     });
   } catch (error) {
     await closeQuietly(log);
     throw error;
   }
 
-  return new Promise((resolveLaunch, rejectLaunch) => {
-    let settled = false;
-    child.once("error", (error) => {
-      if (settled) return;
-      settled = true;
-      closeQuietly(log).finally(() => rejectLaunch(error));
-    });
-    child.once("spawn", () => {
-      if (settled) return;
-      settled = true;
-      (async () => {
-        if (!Number.isInteger(child.pid) || child.pid <= 0)
-          throw new Error("runtime process spawned without a PID");
-        await fs.writeFile(pidPath, `${child.pid}\n`, { mode: 0o600, flag: "w" });
-        try {
-          await watch({ runId, pid: child.pid, configPath: devConfigPath, worktree: invocation.cwd });
-        } catch (error) {
-          // This exact child has already been recorded in its private PID file.
-          // Do not leave an untracked runtime alive when registry persistence fails.
-          await terminate(child);
-          throw error;
-        }
-        if (!child.stdin || typeof child.stdin.end !== "function")
-          throw new Error("runtime process has no stdin pipe");
-        child.stdin.end(prompt);
-        await closeQuietly(log);
-        child.unref();
-        resolveLaunch({
-          runId,
-          laneKey,
-          pid: child.pid,
-          logPath,
-          pidPath,
-          command: invocation.command,
-          args: invocation.args,
-          cwd: invocation.cwd,
-        });
-      })().catch(async (error) => {
-        await closeQuietly(log);
-        rejectLaunch(error);
+  // One reply from the supervisor, or its early end as an error.
+  const reply = (type) => new Promise((resolveReply, rejectReply) => {
+    const onMessage = (message) => {
+      if (message?.type === "error") return settle(() => rejectReply(new Error(message.message)));
+      if (message?.type === type) settle(() => resolveReply(message));
+    };
+    const onExit = (code, signal) => settle(() => rejectReply(new Error(`lane supervisor exited before ${type} (${signal ?? code})`)));
+    const onError = (error) => settle(() => rejectReply(error));
+    const settle = (done) => {
+      supervisor.off("message", onMessage);
+      supervisor.off("exit", onExit);
+      supervisor.off("error", onError);
+      done();
+    };
+    supervisor.on("message", onMessage);
+    supervisor.once("exit", onExit);
+    supervisor.once("error", onError);
+  });
+
+  try {
+    await new Promise((resolveSpawn, rejectSpawn) => {
+      supervisor.once("error", rejectSpawn);
+      supervisor.once("spawn", () => {
+        supervisor.off("error", rejectSpawn);
+        resolveSpawn();
       });
     });
-  });
+    const spawned = reply("spawned");
+    supervisor.send({ type: "launch", invocation, runId, laneKey, worktrees: [invocation.cwd, ...addDirs], logPath });
+    const { pid } = await spawned;
+    if (!Number.isInteger(pid) || pid <= 0)
+      throw new Error("runtime process spawned without a PID");
+    await fs.writeFile(pidPath, `${pid}\n`, { mode: 0o600, flag: "w" });
+    try {
+      await watch({ runId, pid, supervisorPid: supervisor.pid, configPath: devConfigPath, worktree: invocation.cwd });
+    } catch (error) {
+      // This exact runtime has already been recorded in its private PID file.
+      // Do not leave an untracked runtime alive when registry persistence fails.
+      try { supervisor.send({ type: "abort" }); } catch {}
+      await terminate(supervisor);
+      throw error;
+    }
+    const started = reply("started");
+    supervisor.send({ type: "start", prompt });
+    await started;
+    supervisor.disconnect();
+    await closeQuietly(log);
+    supervisor.unref();
+    return {
+      runId,
+      laneKey,
+      pid,
+      supervisorPid: supervisor.pid,
+      logPath,
+      pidPath,
+      command: invocation.command,
+      args: invocation.args,
+      cwd: invocation.cwd,
+    };
+  } catch (error) {
+    await closeQuietly(log);
+    throw error;
+  }
 }
 
 const terminateChild = async (child) => {
@@ -234,6 +266,7 @@ export async function launchRuntime(options, {
   env = process.env,
   watch = recordWatchedRun,
   terminate = terminateChild,
+  supervisorEntry,
 } = {}) {
   const launch = validateLaunch(options);
   const invocation = buildInvocation(launch, { env, home });
@@ -243,6 +276,7 @@ export async function launchRuntime(options, {
     stateRoot: stateRoot ?? recoveryStateRoot(launch.devConfigPath),
     watch,
     terminate,
+    ...(supervisorEntry ? { supervisorEntry } : {}),
   });
 }
 
@@ -260,17 +294,19 @@ export async function launchRecovery(payload, {
   env = process.env,
   watch = recordWatchedRun,
   terminate = terminateChild,
+  supervisorEntry,
 } = {}) {
   const data = dataFrom(payload);
-  const { runId, laneKey } = validateData(data);
+  const { runId, laneKey, addDirs } = validateData(data);
   const devConfigPath = absolutePath(data?.launch?.devConfigPath, "launch.devConfigPath");
   const prompt = buildRecoveryPrompt(data);
   const invocation = buildRecoveryInvocation(data, { env, home });
-  return launchDetached({ invocation, prompt, runId, laneKey, devConfigPath }, {
+  return launchDetached({ invocation, prompt, runId, laneKey, devConfigPath, addDirs }, {
     spawnImpl,
     fs,
     stateRoot: stateRoot ?? recoveryStateRoot(devConfigPath),
     watch,
     terminate,
+    ...(supervisorEntry ? { supervisorEntry } : {}),
   });
 }

package/dist/starting.js

@@ -538,7 +538,8 @@ export async function amendmentGuard(argv, { request = devRequest, marker = curr
   const pending = await request("GET", `/api/v1/lanes/${encode(lane.laneKey)}/amendments${query({ runId: lane.runId })}`);
   if (!pending.data.length) return lane;
   const detail = pending.data.map((item) => `v${item.version} ${item.reason}: ${JSON.stringify(item.change)}`).join("\n");
-  throw new CliError("LANE_AMENDMENT_ACK_REQUIRED", `Lane ${lane.laneKey} changed:\n${detail}\nDelta gather required: run nodii-dev lane gather ${lane.laneKey} --delta.`, 1, { amendments: pending.data });
+  const next = `nodii-dev lane gather ${lane.laneKey} --delta`;
+  throw new CliError("LANE_AMENDMENT_ACK_REQUIRED", `Lane ${lane.laneKey} changed:\n${detail}\nDelta gather required: run ${next}. If it prints a Trigger shortlist (picker: agent), run the record command it prints (data.next.command in --json): that records your pick and acknowledges the amendment. Help stays readable: nodii-dev --help.`, 1, { amendments: pending.data, next });
 }
 
 // Gather's human output is a renderer of its payload; Delta gather prints the
@@ -569,8 +570,15 @@ export async function gatherLaneCommand(key, flags, { request = devRequest, mark
     }
     const version = Math.max(...pending.data.map((item) => item.version));
     const gathered = await withSignal(gather(key, flags, { request: timedRequest, deadline }), signal);
-    // An agent picker's shortlist step records nothing, so it acknowledges nothing.
-    if (gathered.payload?.data?.recorded === false) return gathered;
+    // An agent picker's shortlist step records nothing, so it acknowledges
+    // nothing: it names the amendment still open and the command that closes it.
+    if (gathered.payload?.data?.recorded === false) {
+      const open = `Amendment version ${version} is not acknowledged yet: run the record command above.`;
+      return {
+        payload: { ...gathered.payload, amendments: pending.data, acknowledgedVersion: null },
+        human: (p) => `${typeof gathered.human === "function" ? gathered.human(p) : gathered.human}\n${open}`,
+      };
+    }
     const acknowledgement = await withSignal(acknowledge(key, {
       ...flags,
       deltaContext: { runId: lane.runId, amendmentVersion: version },

package/dist/watchdog.js

@@ -17,6 +17,8 @@ function validateRecord(record) {
   if (!record || typeof record !== "object") throw new CliError("WATCHDOG_RECORD_INVALID", "A watched run record must be an object.", 2);
   if (!RUN_ID.test(record.runId ?? "")) throw new CliError("WATCHDOG_RECORD_INVALID", "A watched run record needs its Dev run UUID.", 2);
   if (!Number.isSafeInteger(record.pid) || record.pid < 1) throw new CliError("WATCHDOG_RECORD_INVALID", "A watched run record needs a positive process id.", 2);
+  if (record.supervisorPid !== undefined && (!Number.isSafeInteger(record.supervisorPid) || record.supervisorPid < 1))
+    throw new CliError("WATCHDOG_RECORD_INVALID", "A watched run supervisor id must be a positive process id.", 2);
   if (record.configPath !== undefined && (typeof record.configPath !== "string" || !isAbsolute(record.configPath)))
     throw new CliError("WATCHDOG_RECORD_INVALID", "A watched run config path must be absolute.", 2);
   if (record.worktree !== undefined && (typeof record.worktree !== "string" || !isAbsolute(record.worktree)))
@@ -38,6 +40,7 @@ async function atomicWrite(path, contents, mode = 0o600) {
 export async function recordWatchedRun(input, { home = homedir(), now = () => new Date(), processStart = processStartedAt } = {}) {
   const record = validateRecord({ ...input, version: 1, recordedAt: now().toISOString() });
   if (!record.processStartedAt) record.processStartedAt = await processStart(record.pid).catch(() => null);
+  if (record.supervisorPid && !record.supervisorStartedAt) record.supervisorStartedAt = await processStart(record.supervisorPid).catch(() => null);
   const dir = watchdogRunDir(home);
   await mkdir(dir, { recursive: true, mode: 0o700 });
   await chmod(dir, 0o700);
@@ -140,6 +143,8 @@ export async function collectWatchdogFacts(records, {
 } = {}) {
   const deadRuns = [];
   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 } : {}) });
   }

package/package.json

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