@nodii/dev 0.6.27 → 0.6.29

package/dist/doctor.js

@@ -19,7 +19,7 @@ export const LANE_PERMISSIONS = [
   { key: "devops.issues.read", for: "issues list|show" },
   { key: "devops.issues.write", for: "issues create|update|claim|release|transition" },
   { key: "devops.lanes.read", for: "lane show|list, next" },
-  { key: "devops.lanes.write", for: "lane start|step|evidence|heartbeat|review|land|verify" },
+  { key: "devops.lanes.write", for: "lane launch|amend|start|step|evidence|heartbeat|review|land|verify" },
   { key: "devops.agents.read", for: "whoami, reading this agent" },
   { key: "devops.agents.write", for: "agent register|heartbeat" },
   { key: "devops.machines.manage", for: "machine show (this agent's machine and coordinator)" },

package/dist/hooks.js

@@ -1,7 +1,7 @@
 import { CliError, devRequest, readConfig } from "./core.js";
 import { FOUNDATIONS_ID, figmaLockCheck, outOfScopeText } from "./figma.js";
 import { execFile } from "node:child_process";
-import { realpath } from "node:fs/promises";
+import { readFile, realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { promisify } from "node:util";
 import { safetySettingsSnippet } from "./safety.js";
@@ -209,6 +209,15 @@ export async function heartbeatCurrentLane(request = devRequest) {
   try { branch = (await execFileAsync("git", ["branch", "--show-current"], { encoding: "utf8" })).stdout.trim(); }
   catch { return { heartbeated: false, reason: "not a git worktree" }; }
   if (!branch) return { heartbeated: false, reason: "detached HEAD" };
+  try {
+    const markerPath = (await execFileAsync("git", ["rev-parse", "--path-format=absolute", "--git-path", "nodii-lane.json"], { encoding: "utf8" })).stdout.trim();
+    const marker = JSON.parse(await readFile(markerPath, "utf8"));
+    const lane = (await request("GET", `/api/v1/lanes/${encodeURIComponent(marker.laneKey)}`)).data;
+    if (lane.repositories?.some((repository) => repository.branch === branch)) {
+      await request("POST", `/api/v1/lanes/${encodeURIComponent(lane.id)}/heartbeat`, { via: "nodii-dev" });
+      return { heartbeated: true, key: lane.key };
+    }
+  } catch {}
   const lanes = (await request("GET", "/api/v1/lanes?limit=200")).data ?? [];
   const lane = lanes.find((x) => x.branch === branch && !["on_dev", "stopped"].includes(x.status));
   if (!lane) return { heartbeated: false, reason: "no lane for current branch" };
@@ -226,6 +235,23 @@ export async function sessionStartContext(payload, { request = devRequest, confi
     const rootText = (await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" })).stdout.trim();
     const root = await realpath(rootText).catch(() => resolve(rootText));
     const current = await config(false);
+    try {
+      const markerPath = (await execFileAsync("git", ["rev-parse", "--path-format=absolute", "--git-path", "nodii-lane.json"], { cwd, encoding: "utf8" })).stdout.trim();
+      const marker = JSON.parse(await readFile(markerPath, "utf8"));
+      const marked = (await request("GET", `/api/v1/lanes/${encodeURIComponent(marker.laneKey)}`)).data;
+      const repository = marked.repositories?.find((item) => item.branch === branch && resolve(item.worktree) === root);
+      if (marked.agentId === current.agentId && repository && !["on_dev", "stopped"].includes(marked.status)) lane = marked;
+    } catch {}
+    if (lane) {
+      const freeze = lane.freeze ?? {};
+      return [
+        `Freeze re-grounding for ${lane.key}:`,
+        `title: ${lane.title ?? "(untitled)"}`,
+        `status: ${lane.status}`,
+        `boundaries: ${JSON.stringify(freeze.boundaries ?? {})}`,
+        `rules: ${JSON.stringify(freeze.rules ?? freeze.ruleRefs ?? [])}`,
+      ].join("\n");
+    }
     const lanes = (await request("GET", "/api/v1/lanes?limit=200")).data ?? [];
     for (const item of lanes) {
       if (item.agentId !== current.agentId || item.branch !== branch || ["on_dev", "stopped"].includes(item.status)) continue;

package/dist/lanes.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { CliError, encode, devRequest, query, readConfig, requireFlag } from "./core.js";
+import { launchRecovery } from "./runtime-launcher.js";
 import { recordReviewReceipt, reviewCommitContext } from "./safety.js";
 
 const execFileAsync = promisify(execFile);
@@ -106,14 +107,18 @@ const MAX_COMMITS = 200;
 /** The lane's branch commits not on origin/main (as last fetched), from its recorded worktree. */
 export async function branchCommits(lane) {
   try {
-    const out = (await execFileAsync("git", ["-C", lane.worktree, "rev-list", `origin/main..${lane.branch}`], { encoding: "utf8" })).stdout.trim();
-    return out ? out.split("\n") : [];
+    const repositories = lane.repositories?.length ? lane.repositories : [{ worktree: lane.worktree, branch: lane.branch, baseRef: "origin/main" }];
+    const commits = await Promise.all(repositories.map(async (repository) => {
+      const out = (await execFileAsync("git", ["-C", repository.worktree, "rev-list", `${repository.baseRef ?? "origin/main"}..${repository.branch}`], { encoding: "utf8" })).stdout.trim();
+      return out ? out.split("\n") : [];
+    }));
+    return [...new Set(commits.flat())];
   } catch {
-    throw new CliError("GIT_REQUIRED", `Cannot read the commits of ${lane.branch} in ${lane.worktree}. Pass --commits SHA[,SHA], or --branch dropped:REASON.`, 2);
+    throw new CliError("GIT_REQUIRED", `Cannot read every repository branch for this lane. Pass --commits SHA[,SHA], or --branch dropped:REASON.`, 2);
   }
 }
 
-export async function laneCommand(action, args, flags, { request = devRequest, config = readConfig, gitContext = inferGitContext, commitsOf = branchCommits, read = (path) => readFile(path, "utf8"), reviewContext = reviewCommitContext, reviewReceipt = recordReviewReceipt } = {}) {
+export async function laneCommand(action, args, flags, { request = devRequest, config = readConfig, gitContext = inferGitContext, commitsOf = branchCommits, read = (path) => readFile(path, "utf8"), reviewContext = reviewCommitContext, reviewReceipt = recordReviewReceipt, launch = launchRecovery } = {}) {
   if (action === "list") {
     const c = flags.mine ? await config() : null;
     const payload = await request("GET", `/api/v1/lanes${query({ kind: flags.kind, status: flags.status, machine: flags.machine, agent: flags.mine ? c.agentId : flags.agent, "waiting-on": flags["waiting-on"], stuck: flags.stuck, cursor: flags.cursor, limit: flags.limit })}`);
@@ -182,6 +187,52 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
   if (action === "heartbeat") {
     return { payload: await request("POST", `/api/v1/lanes/${encode(id)}/heartbeat`, { ...(flags.note !== undefined ? { note: flags.note } : {}), ...via }), human: `${ref}: heartbeat recorded.` };
   }
+  if (action === "subagent-quota") {
+    const raw = need(args[1], "lane subagent-quota needs <key> <n>");
+    const quota = Number(raw);
+    if (!Number.isInteger(quota) || quota < 0 || quota > 100)
+      throw new CliError("USAGE", "Subagent quota must be an integer from 0 to 100.", 2);
+    const payload = await request(
+      "PUT",
+      `/api/v1/lanes/${encode(id)}/subagent-quota`,
+      { quota, ...via },
+    );
+    return { payload, human: `${ref}: subagent quota set to ${quota}.` };
+  }
+  if (action === "resume") {
+    const payload = await request(
+      "POST",
+      `/api/v1/lanes/${encode(id)}/resume`,
+      via,
+    );
+    let launched;
+    try {
+      launched = await launch(payload);
+    } catch (error) {
+      const reason = `local recovery launch failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2_000);
+      const runId = payload?.data?.run?.id;
+      if (runId) {
+        await request(
+          "POST",
+          `/api/v1/lanes/${encode(id)}/resume/${encode(runId)}/launch-failed`,
+          { reason, ...via },
+        ).catch(() => {});
+      }
+      throw new CliError("RECOVERY_LAUNCH_FAILED", reason, 1);
+    }
+    return {
+      payload,
+      human: (response) => {
+        const runId = response.data.run.id;
+        const next = response.data.lane.next?.[0];
+        const checkpoint = response.data.recovery.lastPushedCommit;
+        const continuation = next
+          ? `${next.side}/${next.step}`
+          : "the lane's next unfinished step";
+        return `${ref}: resumed fresh run ${runId} as PID ${launched.pid}; continuing ${continuation} from ${checkpoint}.`;
+      },
+    };
+  }
   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);
@@ -257,11 +308,15 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
  */
 export async function laneChangedPaths(lane) {
   try {
-    const run = async (...args) => (await execFileAsync("git", ["-C", lane.worktree, ...args], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 })).stdout;
-    const base = (await run("merge-base", "origin/main", "HEAD")).trim();
-    const changed = (await run("diff", "--name-only", base)).split("\n");
-    const untracked = (await run("ls-files", "--others", "--exclude-standard")).split("\n");
-    return [...new Set([...changed, ...untracked].map((x) => x.trim()).filter(Boolean))].slice(0, 5000);
+    const repositories = lane.repositories?.length ? lane.repositories : [{ repo: lane.repos?.[0], worktree: lane.worktree, baseRef: "origin/main" }];
+    const changed = await Promise.all(repositories.map(async (repository) => {
+      const run = async (...args) => (await execFileAsync("git", ["-C", repository.worktree, ...args], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 })).stdout;
+      const base = (await run("merge-base", repository.baseRef ?? "origin/main", "HEAD")).trim();
+      const tracked = (await run("diff", "--name-only", base)).split("\n");
+      const untracked = (await run("ls-files", "--others", "--exclude-standard")).split("\n");
+      return [...tracked, ...untracked].map((path) => path.trim()).filter(Boolean);
+    }));
+    return [...new Set(changed.flat())].slice(0, 5000);
   } catch {
     return null;
   }
@@ -283,11 +338,14 @@ export async function nextCommand(ref, flags, { request = devRequest, changedPat
   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}` }));
   // M05-32: the clauses Dev serves for this step. A failure here never hides the next step.
   let rules = null;
-  if (data.length) {
+  if (data.length || flags.deltaContext) {
     const paths = flags.paths ? list(flags.paths) : await changedPaths(lane);
-    const body = { ...(paths ? { paths } : {}), ...(flags.components ? { components: list(flags.components) } : {}), ...(flags.role ? { role: String(flags.role) } : {}) };
+    const body = { ...(paths ? { paths } : {}), ...(flags.components ? { components: list(flags.components) } : {}), ...(flags.role ? { role: String(flags.role) } : {}), ...(flags.deltaContext && typeof flags.deltaContext === "object" ? { delta: flags.deltaContext } : {}) };
     try { rules = (await request("POST", `/api/v1/lanes/${encode(lane.key)}/rules`, body)).data; }
-    catch (error) { rules = { error: error.code ?? error.message }; }
+    catch (error) {
+      if (flags.deltaContext) throw error;
+      rules = { error: error.code ?? error.message };
+    }
   }
   const human = data.length
     ? [...data.map((x) => `${x.side}: ${x.label}\n  ${x.command}`), ...rulesLines(rules, lane.key)].join("\n")

package/dist/runs.js

@@ -0,0 +1,341 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { basename } from "node:path";
+import { CliError, devRequest, encode } from "./core.js";
+
+export const RUN_ID_ENV = "NODII_DEV_RUN_ID";
+const DEFAULT_HEARTBEAT_MS = 60_000;
+const DEFAULT_TAIL_BYTES = 8 * 1024;
+const RUN_KINDS = new Set(["build", "test_run", "subagent", "deploy"]);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+export function redactRunText(value) {
+  return String(value)
+    .replace(/-----BEGIN [^-\r\n]*PRIVATE KEY-----[\s\S]*?-----END [^-\r\n]*PRIVATE KEY-----/gi, "[REDACTED PRIVATE KEY]")
+    .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]")
+    .replace(/\b(?:github_pat_|gh[pousr]_|sk-)[A-Za-z0-9_-]{12,}\b/g, "[REDACTED]")
+    .replace(
+      /\b((?=[A-Za-z0-9_-]*(?:token|secret|password|passwd|pwd|api[_-]?key|access[_-]?key))[A-Za-z][A-Za-z0-9_-]*\s*[:=]\s*)[^\s,;]+/gi,
+      "$1[REDACTED]",
+    )
+    .replace(/([a-z][a-z0-9+.-]*:\/\/[^\s:/]+:)[^@\s]+@/gi, "$1[REDACTED]@");
+}
+
+function appendTail(current, chunk, maxBytes) {
+  const next = Buffer.concat([current, Buffer.from(chunk)]);
+  return next.length <= maxBytes ? next : next.subarray(next.length - maxBytes);
+}
+
+function writeSafe(write, value) {
+  try {
+    write(value);
+    return true;
+  } catch (error) {
+    if (error?.code !== "EPIPE") throw error;
+    return false;
+  }
+}
+
+function currentRunId(runId = process.env[RUN_ID_ENV]) {
+  if (runId === undefined || runId === "") return null;
+  if (!UUID.test(runId))
+    throw new CliError(
+      "RUN_CONTEXT_INVALID",
+      `${RUN_ID_ENV} must be the UUID of this lane, subagent, or coordinator run.`,
+      2,
+    );
+  return runId;
+}
+
+function evidenceText(evidence) {
+  return (evidence ?? [])
+    .map((item) => {
+      const head = `  ${redactRunText(item.kind)}: ${redactRunText(item.ref)}`;
+      if (!item.note) return head;
+      return `${head}\n${redactRunText(item.note)
+        .split("\n")
+        .map((line) => `    ${line}`)
+        .join("\n")}`;
+    })
+    .join("\n");
+}
+
+function resultText(result) {
+  const lines = [
+    `Result ${redactRunText(result.id)} · ${redactRunText(result.outcome)} · run ${redactRunText(result.sourceRunId)}`,
+  ];
+  if (result.failureReason)
+    lines.push(`  reason: ${redactRunText(result.failureReason)}`);
+  if (result.handoff) lines.push(`  handoff: ${redactRunText(result.handoff)}`);
+  const evidence = evidenceText(result.evidence);
+  if (evidence) lines.push(evidence);
+  return lines.join("\n");
+}
+
+export async function showWaitingResults({
+  runId = process.env[RUN_ID_ENV],
+  request = devRequest,
+  write = (value) => process.stderr.write(value),
+  acknowledge = true,
+} = {}) {
+  const waiterRunId = currentRunId(runId);
+  if (!waiterRunId) return [];
+  const payload = await request(
+    "GET",
+    `/api/v1/runs/${encode(waiterRunId)}/results`,
+  );
+  const results = payload.data ?? [];
+  if (!results.length) return [];
+
+  const rendered = writeSafe(
+    write,
+    `${results.map(resultText).join("\n\n")}\n`,
+  );
+  if (!rendered || !acknowledge) return results;
+  for (const result of results) {
+    try {
+      await request(
+        "POST",
+        `/api/v1/results/${encode(result.id)}/acknowledge`,
+        { waiterRunId },
+      );
+    } catch (error) {
+      writeSafe(
+        write,
+        `Result ${redactRunText(result.id)} remains waiting: acknowledgement failed (${redactRunText(error?.code ?? error?.message ?? "error")}).\n`,
+      );
+    }
+  }
+  return results;
+}
+
+function commandLabel(command) {
+  return basename(command[0] ?? "command").slice(0, 240) || "command";
+}
+
+function runKind(value) {
+  const kind = value ?? "build";
+  if (!RUN_KINDS.has(kind))
+    throw new CliError(
+      "USAGE",
+      `run --kind must be one of ${[...RUN_KINDS].join(", ")}.`,
+      2,
+    );
+  return kind;
+}
+
+function runEvidence(command, exitCode, signal, tail) {
+  const evidence = [
+    { kind: "command", ref: commandLabel(command) },
+    { kind: "exit_code", ref: String(exitCode ?? -1) },
+    {
+      kind: "log_tail",
+      ref: "combined stdout/stderr",
+      note: redactRunText(tail.toString("utf8")) || "(no output)",
+    },
+  ];
+  if (signal) evidence.push({ kind: "signal", ref: signal });
+  return evidence;
+}
+
+async function endRun(request, runId, body, attempts = 3) {
+  let error;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await request("POST", `/api/v1/runs/${encode(runId)}/end`, body);
+    } catch (caught) {
+      error = caught;
+      if (attempt + 1 < attempts)
+        await new Promise((resolve) => setTimeout(resolve, 250 * (attempt + 1)));
+    }
+  }
+  throw error;
+}
+
+export async function superviseRun({
+  command,
+  waiterRunId = process.env[RUN_ID_ENV],
+  kind,
+  name,
+  expectedHeartbeatSeconds = 60,
+  heartbeatIntervalMs = DEFAULT_HEARTBEAT_MS,
+  tailBytes = DEFAULT_TAIL_BYTES,
+  request = devRequest,
+  spawn = nodeSpawn,
+  stdoutWrite = (value) => process.stdout.write(value),
+  stderrWrite = (value) => process.stderr.write(value),
+} = {}) {
+  const waiter = currentRunId(waiterRunId);
+  if (!waiter)
+    throw new CliError(
+      "RUN_CONTEXT_REQUIRED",
+      `nodii-dev run needs ${RUN_ID_ENV}, supplied by the harness launcher for the current waiter run.`,
+      2,
+    );
+  if (!Array.isArray(command) || !command.length || !command[0])
+    throw new CliError("USAGE", "run needs a command after `--`.", 2);
+  const selectedKind = runKind(kind);
+  const label = redactRunText(String(name ?? commandLabel(command)))
+    .trim()
+    .slice(0, 300);
+  if (!label) throw new CliError("USAGE", "run --name cannot be empty.", 2);
+  const registered = await request("POST", "/api/v1/runs", {
+    kind: selectedKind,
+    name: label,
+    externalRef: `pid:${process.pid}`,
+    waiterRunId: waiter,
+    expectedHeartbeatSeconds,
+    metadata: { executable: redactRunText(commandLabel(command)) },
+  });
+  const runId = registered.data?.id;
+  if (!runId) throw new CliError("RUN_REGISTER_INVALID", "Dev registered a run without an id.", 1);
+
+  let tail = Buffer.alloc(0);
+  let spawnError = null;
+  let heartbeatInFlight = false;
+  let child;
+  let timer;
+  const forwardSignals = new Map();
+  for (const signal of SIGNALS) {
+    const forward = () => {
+      if (child?.pid && child.exitCode === null && child.signalCode === null)
+        child.kill(signal);
+    };
+    forwardSignals.set(signal, forward);
+    process.on(signal, forward);
+  }
+
+  try {
+    try {
+      child = spawn(command[0], command.slice(1), {
+        shell: false,
+        stdio: ["inherit", "pipe", "pipe"],
+      });
+    } catch (error) {
+      const evidence = runEvidence(command, 1, null, tail);
+      await endRun(request, runId, {
+        status: "failed",
+        reason: `Command could not start: ${redactRunText(error?.code ?? error?.message ?? "error")}`,
+        evidence,
+      });
+      return {
+        runId,
+        exitCode: 1,
+        signal: null,
+        tail: "",
+      };
+    }
+    child.stdout?.on("data", (chunk) => {
+      tail = appendTail(tail, chunk, tailBytes);
+      writeSafe(stdoutWrite, chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      tail = appendTail(tail, chunk, tailBytes);
+      writeSafe(stderrWrite, chunk);
+    });
+
+    const heartbeat = async () => {
+      if (heartbeatInFlight) return;
+      heartbeatInFlight = true;
+      try {
+        await request("POST", `/api/v1/runs/${encode(runId)}/heartbeat`, {
+          note: `command pid ${child.pid ?? "starting"}`,
+        });
+      } catch (error) {
+        writeSafe(
+          stderrWrite,
+          `nodii-dev run heartbeat failed (${redactRunText(error?.code ?? error?.message ?? "error")}); retrying.\n`,
+        );
+      } finally {
+        heartbeatInFlight = false;
+      }
+    };
+    timer = setInterval(heartbeat, heartbeatIntervalMs);
+    const outcome = await new Promise((resolve) => {
+      child.once("error", (error) => {
+        spawnError = error;
+      });
+      child.once("close", (exitCode, signal) => resolve({ exitCode, signal }));
+    });
+    clearInterval(timer);
+    timer = undefined;
+    while (heartbeatInFlight)
+      await new Promise((resolve) => setTimeout(resolve, 5));
+
+    const evidence = runEvidence(
+      command,
+      outcome.exitCode,
+      outcome.signal,
+      tail,
+    );
+    const succeeded = outcome.exitCode === 0 && !outcome.signal && !spawnError;
+    const reason = spawnError
+      ? `Command could not start: ${redactRunText(spawnError.code ?? spawnError.message)}`
+      : outcome.signal
+        ? `Command ended by signal ${outcome.signal}`
+        : `Command exited with code ${outcome.exitCode ?? -1}`;
+    await endRun(
+      request,
+      runId,
+      succeeded
+        ? { status: "done", evidence }
+        : { status: "failed", reason, evidence },
+    );
+    return {
+      runId,
+      exitCode: succeeded ? 0 : (outcome.exitCode ?? 1),
+      signal: outcome.signal,
+      tail: redactRunText(tail.toString("utf8")),
+    };
+  } finally {
+    if (timer) clearInterval(timer);
+    for (const [signal, forward] of forwardSignals)
+      process.off(signal, forward);
+  }
+}
+
+export async function launchRunSupervisor(
+  command,
+  {
+    entrypoint = process.argv[1],
+    spawn = nodeSpawn,
+    env = process.env,
+    kind,
+    name,
+  } = {},
+) {
+  if (!entrypoint)
+    throw new CliError("RUN_SUPERVISOR_UNAVAILABLE", "Cannot locate the nodii-dev entrypoint.", 1);
+  const args = [entrypoint, "__run-supervisor"];
+  if (kind) args.push("--kind", kind);
+  if (name) args.push("--name", name);
+  args.push("--", ...command);
+  const supervisor = spawn(process.execPath, args, {
+    detached: true,
+    shell: false,
+    stdio: "inherit",
+    env,
+  });
+  const forwardSignals = new Map();
+  for (const signal of SIGNALS) {
+    const forward = () => {
+      if (
+        supervisor.pid &&
+        supervisor.exitCode === null &&
+        supervisor.signalCode === null
+      )
+        supervisor.kill(signal);
+    };
+    forwardSignals.set(signal, forward);
+    process.on(signal, forward);
+  }
+  try {
+    return await new Promise((resolve, reject) => {
+      supervisor.once("error", reject);
+      supervisor.once("close", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+  } finally {
+    for (const [signal, forward] of forwardSignals)
+      process.off(signal, forward);
+  }
+}