@nodii/dev 0.6.28 → 0.6.30

package/dist/lanes.js

@@ -2,10 +2,14 @@ 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";
+import { GATHER_TIMEOUT_MS, gatherText, pickDocuments } from "./gather.js";
+import { storeGatherFreeze } from "./freeze.js";
 
 const execFileAsync = promisify(execFile);
 const via = { via: "nodii-dev" };
+const GATHER_ACTIVE = new Set(["queued", "building"]);
 // heartbeatLane's note limit.
 const BLOCK_NOTE_MAX = 500;
 
@@ -106,14 +110,45 @@ 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 } = {}) {
+async function currentGatherLane(request, config, gitContext) {
+  const c = await config();
+  const context = await gitContext();
+  const lanes = [];
+  let cursor;
+  do {
+    const page = await request("GET", `/api/v1/lanes${query({ agent: c.agentId, cursor, limit: 200 })}`);
+    lanes.push(...(page.data ?? []));
+    cursor = page.nextCursor ?? undefined;
+  } while (cursor);
+  const active = lanes.filter((lane) => GATHER_ACTIVE.has(lane.status));
+  const repositories = (lane) => lane.repositories?.length
+    ? lane.repositories
+    : lane.freeze?.boundaries?.repos?.length
+      ? lane.freeze.boundaries.repos
+      : [{ repo: lane.repos?.[0], branch: lane.branch, worktree: lane.worktree }];
+  const exact = active.filter((lane) => repositories(lane).some((repository) => repository.worktree === context.worktree));
+  const branch = active.filter((lane) => repositories(lane).some((repository) =>
+    repository.branch === context.branch && repoName(repository.repo ?? "") === context.repo));
+  const matches = exact.length ? exact : branch;
+  if (matches.length !== 1)
+    throw new CliError("CURRENT_LANE_AMBIGUOUS", matches.length
+      ? `This worktree matches ${matches.length} active lanes (${matches.map((lane) => lane.key).join(", ")}); pass one key explicitly.`
+      : "No active lane matches this agent and worktree; pass the lane key explicitly.", 2);
+  return matches[0].key;
+}
+
+export async function laneCommand(action, args, flags, { request = devRequest, config = readConfig, gitContext = inferGitContext, commitsOf = branchCommits, read = (path) => readFile(path, "utf8"), reviewContext = reviewCommitContext, reviewReceipt = recordReviewReceipt, picker = pickDocuments, changedPaths = laneChangedPaths, gatherTimeoutMs = GATHER_TIMEOUT_MS, gatherSignal, storeFreeze = storeGatherFreeze, 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 })}`);
@@ -137,12 +172,138 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     const payload = await request("POST", `/api/v1/lanes/${encode(key)}/start`, via);
     return { payload, human: (p) => `Started ${laneLine(p.data)}` };
   }
-  const ref = need(args[0], `lane ${action} needs <key>`);
+  const ref = need(args[0] ?? (action === "gather" ? await currentGatherLane(request, config, gitContext) : undefined), `lane ${action} needs <key>`);
   const id = ref;
   if (action === "show") {
     const payload = await request("GET", `/api/v1/lanes/${encode(id)}`);
     return { payload, human: (p) => detailText(p.data) };
   }
+  if (action === "gather") {
+    const controller = gatherSignal ? null : new AbortController();
+    const deadline = controller ? setTimeout(() => controller.abort(), gatherTimeoutMs) : null;
+    const signal = gatherSignal ?? controller.signal;
+    try {
+      const lane = (await request("GET", `/api/v1/lanes/${encode(id)}`, undefined, { signal })).data;
+      if (flags.objective !== undefined && (typeof flags.objective !== "string" || !flags.objective.trim()))
+        throw new CliError("USAGE", "lane gather --objective needs non-empty text", 2);
+      if (flags["done-check"] !== undefined && (typeof flags["done-check"] !== "string" || !flags["done-check"].trim()))
+        throw new CliError("USAGE", "lane gather --done-check needs non-empty text", 2);
+      const durableObjective = [lane.objective, lane.freeze?.objective?.ask].find((x) => typeof x === "string" && x.trim());
+      const explicitObjective = typeof flags.objective === "string" ? flags.objective.trim() : undefined;
+      if (explicitObjective && durableObjective && explicitObjective !== durableObjective.trim())
+        throw new CliError("GATHER_OBJECTIVE_CONFLICT", `${ref} already has a different objective. Use lane amend; Gather cannot rewrite the durable contract.`, 1);
+      const issueObjective = typeof lane.issue?.bodyMd === "string" && lane.issue.bodyMd.trim() ? lane.issue.bodyMd : undefined;
+      const objective = durableObjective ?? explicitObjective ?? issueObjective;
+      if (!objective) throw new CliError("GATHER_OBJECTIVE_MISSING", `${ref} has no recorded objective. Amend the lane or pass --objective; the CLI does not invent one.`, 1);
+      if (objective.length > 20_000) throw new CliError("USAGE", "The recorded Gather objective exceeds Dev's 20,000-character limit.", 2);
+      const durableDoneCheck = [lane.doneCheck, lane.freeze?.objective?.doneCheck].find((x) => typeof x === "string" && x.trim());
+      const explicitDoneCheck = typeof flags["done-check"] === "string" ? flags["done-check"].trim() : undefined;
+      if (explicitDoneCheck && durableDoneCheck && explicitDoneCheck !== durableDoneCheck.trim())
+        throw new CliError("GATHER_DONE_CHECK_CONFLICT", `${ref} already has a different done check. Use lane amend; Gather cannot rewrite the durable contract.`, 1);
+      const doneCheck = durableDoneCheck ?? explicitDoneCheck;
+      if (!doneCheck) throw new CliError("GATHER_DONE_CHECK_MISSING", `${ref} has no recorded done check. Pass --done-check before Gather records anything.`, 1);
+      if (doneCheck.length > 10_000) throw new CliError("USAGE", "The Gather done check exceeds Dev's 10,000-character limit.", 2);
+      const legacyRepository = {
+        repo: lane.repos?.[0],
+        branch: lane.branch,
+        worktree: lane.worktree,
+        ownedPaths: lane.ownedPaths ?? [],
+      };
+      const sourceRepositories = lane.repositories?.length
+        ? lane.repositories
+        : lane.freeze?.boundaries?.repos?.length
+          ? lane.freeze.boundaries.repos
+          : [legacyRepository];
+      const repositories = sourceRepositories.map((repository) => Object.fromEntries(
+        ["repo", "branch", "worktree", "ownedPaths"]
+          .map((key) => [key, repository[key]])
+          .filter(([, value]) => value !== undefined),
+      ));
+      if (!repositories.length || repositories.some((repository) => !repository.repo || !repository.branch || !repository.worktree))
+        throw new CliError("GATHER_BOUNDARIES_MISSING", `${ref} has an incomplete repository boundary. Repair its repo, branch, and worktree before Gather records anything.`, 1);
+      const limit = flags.limit === undefined ? undefined : Number(flags.limit);
+      if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 500))
+        throw new CliError("USAGE", "lane gather --limit needs a whole number from 1 to 500", 2);
+      const sectionLimit = flags["section-limit-per-document"] === undefined ? undefined : Number(flags["section-limit-per-document"]);
+      if (sectionLimit !== undefined && (!Number.isInteger(sectionLimit) || sectionLimit < 1 || sectionLimit > 20))
+        throw new CliError("USAGE", "lane gather --section-limit-per-document needs a whole number from 1 to 20", 2);
+      const recordedPaths = [
+        ...(lane.repositories ?? []).flatMap((repository) => repository.ownedPaths ?? []),
+        ...(lane.freeze?.boundaries?.repos ?? []).flatMap((repository) => repository.ownedPaths ?? []),
+        ...(lane.ownedPaths ?? []),
+      ];
+      const driftPaths = await changedPaths(lane, { signal });
+      if (driftPaths === null)
+        throw new CliError("GATHER_PATHS_UNAVAILABLE", "Gather could not read every recorded worktree. Repair the lane boundary or make its repositories available before continuing.", 1);
+      const paths = flags.paths ? list(flags.paths) : [...new Set([...recordedPaths, ...driftPaths])];
+      if (paths.length > 5000) throw new CliError("GATHER_SCOPE_TOO_LARGE", `Gather found ${paths.length} paths; Dev accepts at most 5,000. Narrow the lane's recorded scope before continuing.`, 1);
+      const repoRefs = [
+        ...(lane.repositories ?? []).map((repository) => repository.repo),
+        ...(lane.freeze?.boundaries?.repos ?? []).map((repository) => repository.repo),
+        ...(Array.isArray(lane.repos) ? lane.repos.map((repo) => typeof repo === "string" ? repo : repo.repo) : []),
+      ];
+      const repos = [...new Set(repoRefs.filter(Boolean).map(repoName))];
+      const components = flags.components ? list(flags.components) : [
+        ...(lane.freeze?.boundaries?.figma ?? []).flatMap((file) => file.componentSetKeys ?? []),
+        ...(lane.launch?.figmaScopes ?? []).flatMap((file) => file.componentSets ?? []),
+        ...(lane.components ?? []),
+      ];
+      const shortlistBody = {
+        objective,
+        paths,
+        repos,
+        components,
+        ...(limit !== undefined ? { limit } : {}),
+      };
+      const shortlist = await request("POST", "/api/v1/rules/shortlist", shortlistBody, { signal });
+      const triggers = shortlist.data?.triggers ?? [];
+      const picked = await picker({
+        objective,
+        files: paths,
+        triggers: triggers.map((trigger) => ({
+          code: trigger.code,
+          trigger: trigger.sentence,
+          ...(trigger.forcedBy ? { forcedBy: trigger.forcedBy } : {}),
+        })),
+      }, { signal });
+      const payload = await request("POST", `/api/v1/lanes/${encode(id)}/gather`, {
+        objective,
+        documentCodes: picked.documents,
+        paths,
+        components,
+        mode: flags.delta ? "delta" : "full",
+        ...(sectionLimit !== undefined ? { sectionLimitPerDocument: sectionLimit } : {}),
+      }, { signal });
+      const figma = lane.freeze?.boundaries?.figma ?? (lane.launch?.figmaScopes ?? []).map((file) => ({
+        fileKey: file.fileKey,
+        ...(file.componentSets?.length ? { componentSetKeys: file.componentSets } : {}),
+      }));
+      const issue = lane.issue ? { key: lane.issue.key, title: lane.issue.title } : null;
+      const laneNotes = [
+        lane.launch?.notes,
+        lane.launch?.narrowingNote && `Narrowing: ${lane.launch.narrowingNote}`,
+        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, {
+        gather: payload.data,
+        boundaries: { repos: repositories, ...(figma.length ? { figma } : {}) },
+        issue,
+        laneNotes,
+        doneCheck,
+      }, { request: freezeRequest });
+      const reasons = Object.fromEntries(triggers.map((trigger) => [
+        trigger.code,
+        Array.isArray(trigger.forcedBy) && trigger.forcedBy.length ? `forced by ${trigger.forcedBy.join(", ")}` : trigger.sentence,
+      ]));
+      return { payload, human: (p) => gatherText(p, objective, reasons) };
+    } catch (error) {
+      if (signal.aborted) throw new CliError("GATHER_TIMEOUT", `Gather exceeded its ${Math.round(gatherTimeoutMs / 1000)}-second deadline; nothing was retried.`, 1);
+      throw error;
+    } finally {
+      if (deadline) clearTimeout(deadline);
+    }
+  }
   if (action === "step") {
     const selected = ["start", "done", "block"].filter((x) => flags[x]);
     if (selected.length !== 1) throw new CliError("USAGE", "lane step needs exactly one of --start, --done, or --block.", 2);
@@ -194,6 +355,40 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     );
     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);
@@ -264,17 +459,26 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
 /**
  * The files a lane touches, for path-tagged rules (M05-32): its branch and
  * working-tree changes against origin/main, plus untracked files, read from
- * its recorded worktree. Null when that worktree cannot be read here; Dev then
- * serves every path-tagged clause rather than miss one.
+ * its recorded worktree. Null when any worktree cannot be read here; Gather
+ * refuses that unknown scope rather than silently omit path-triggered rules.
  */
-export async function laneChangedPaths(lane) {
+export async function laneChangedPaths(lane, { signal, exec = execFileAsync } = {}) {
   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);
-  } catch {
+    const repositories = lane.repositories?.length
+      ? lane.repositories
+      : lane.freeze?.boundaries?.repos?.length
+        ? lane.freeze.boundaries.repos
+        : [{ repo: lane.repos?.[0], worktree: lane.worktree, baseRef: "origin/main" }];
+    const changed = await Promise.all(repositories.map(async (repository) => {
+      const run = async (...args) => (await exec("git", ["-C", repository.worktree, ...args], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024, signal })).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())];
+  } catch (error) {
+    if (signal?.aborted) throw error;
     return null;
   }
 }
@@ -295,11 +499,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/nodii-dev.js

@@ -1,14 +1,24 @@
 #!/usr/bin/env node
 import { fail, main } from "./cli.js";
+import { regroundCurrentLane, shouldReground } from "./freeze.js";
 
 // Hooks run in the agent's environment, which may be incomplete or may not be
 // a git worktree. An unavailable hook must never turn into a refused tool call.
 // Intentional policy denials are handled inside the hook command before they
 // reach this boundary.
-main().catch((error) => {
+const argv = process.argv.slice(2);
+
+async function run() {
+  // AGENT-HARNESS-19: this is the executable boundary, so every ordinary CLI
+  // invocation re-grounds without adding hidden requests to library callers.
+  if (shouldReground(argv)) await regroundCurrentLane();
+  await main(argv);
+}
+
+run().catch((error) => {
   const denial = String(error?.code ?? "").startsWith("SAFETY_") ||
     ["FIGMA_FILE_KEY_MISSING", "FIGMA_LOCK_DENIED", "WRITE_OUT_OF_SCOPE"].includes(error?.code);
-  if (process.argv[2] === "hook" && !denial) {
+  if (argv[0] === "hook" && !denial) {
     process.exitCode = 0;
     return;
   }

package/dist/runtime-launcher.js

@@ -0,0 +1,270 @@
+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 { configPath } from "./core.js";
+import { recordWatchedRun } from "./watchdog.js";
+
+const RUNTIMES = new Set(["codex", "claude"]);
+
+const requiredText = (value, name) => {
+  if (typeof value !== "string" || !value.trim())
+    throw new TypeError(`${name} must be a non-empty string`);
+  return value;
+};
+
+const absolutePath = (value, name) => {
+  requiredText(value, name);
+  if (!isAbsolute(value) || resolve(value) !== value)
+    throw new TypeError(`${name} must be an absolute, normalized path`);
+  return value;
+};
+
+const printable = (value) => {
+  if (value === undefined || value === null || value === "") return "(none)";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value, null, 2);
+};
+
+const dataFrom = (payload) => {
+  if (!payload || typeof payload !== "object" || !payload.data || typeof payload.data !== "object")
+    throw new TypeError("recovery payload must contain data");
+  return payload.data;
+};
+
+function validateData(data) {
+  const runId = requiredText(data?.run?.id, "run.id");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId))
+    throw new TypeError("run.id is not a safe state-directory name");
+  const laneKey = requiredText(data?.lane?.key, "lane.key");
+  const runtime = requiredText(data?.launch?.runtime, "launch.runtime");
+  if (!RUNTIMES.has(runtime))
+    throw new TypeError("launch.runtime must be codex or claude");
+  const model = requiredText(data?.launch?.model, "launch.model");
+  const cwd = absolutePath(data?.launch?.cwd, "launch.cwd");
+  const addDirs = data?.launch?.addDirs ?? [];
+  if (!Array.isArray(addDirs)) throw new TypeError("launch.addDirs must be an array");
+  for (const [index, path] of addDirs.entries())
+    absolutePath(path, `launch.addDirs[${index}]`);
+  return { runId, laneKey, runtime, model, cwd, addDirs };
+}
+
+function validateLaunch(options) {
+  const runId = requiredText(options?.runId, "runId");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId))
+    throw new TypeError("runId is not a safe state-directory name");
+  const laneKey = requiredText(options?.laneKey, "laneKey");
+  const runtime = requiredText(options?.runtime, "runtime");
+  if (!RUNTIMES.has(runtime)) throw new TypeError("runtime must be codex or claude");
+  const model = requiredText(options?.model, "model");
+  const cwd = absolutePath(options?.cwd, "cwd");
+  const devConfigPath = absolutePath(options?.devConfigPath, "devConfigPath");
+  const addDirs = options?.addDirs ?? [];
+  if (!Array.isArray(addDirs)) throw new TypeError("addDirs must be an array");
+  for (const [index, path] of addDirs.entries()) absolutePath(path, `addDirs[${index}]`);
+  const prompt = requiredText(options?.prompt, "prompt");
+  return { runId, laneKey, runtime, model, cwd, devConfigPath, addDirs, prompt, profileHome: options.profileHome };
+}
+
+function profileVariable(runtime, profileHome, home) {
+  if (profileHome === undefined || profileHome === null) return {};
+  absolutePath(profileHome, "launch.profileHome");
+  absolutePath(home, "home");
+  const child = relative(home, profileHome);
+  const expected = runtime === "codex" ? /^\.codex(?:[-_.][A-Za-z0-9._-]+)?$/ : /^\.claude(?:[-_.][A-Za-z0-9._-]+)?$/;
+  if (!child || child.startsWith("..") || isAbsolute(child) || child.includes("/") || !expected.test(basename(profileHome)))
+    throw new TypeError(`launch.profileHome must be a safe ${runtime} profile directory directly under home`);
+  return runtime === "codex"
+    ? { CODEX_HOME: profileHome }
+    : { CLAUDE_CONFIG_DIR: profileHome };
+}
+
+/** Build the complete recovery message passed to the fresh runtime over stdin. */
+export function buildRecoveryPrompt(data) {
+  const { runId, laneKey } = validateData(data);
+  return [
+    `You are lane ${laneKey}, relaunched as fresh run ${runId} after an orphaned process.`,
+    "Continue from the recorded next step. Do not redo finished lane steps.",
+    "",
+    `Next step:\n${printable(data.lane.next)}`,
+    "",
+    `Last pushed commit:\n${printable(data.recovery?.lastPushedCommit)}`,
+    "",
+    `Freeze:\n${printable(data.recovery?.freeze)}`,
+    "",
+    `Dead run log tail:\n${printable(data.recovery?.logTail)}`,
+    "",
+  ].join("\n");
+}
+
+/** Build an allowlisted, fresh headless runtime invocation. No prompt is put in argv. */
+export function buildRecoveryInvocation(data, { env = process.env, home = homedir() } = {}) {
+  const { runId, laneKey, runtime, model, cwd, addDirs } = validateData(data);
+  const devConfigPath = absolutePath(data?.launch?.devConfigPath, "launch.devConfigPath");
+  return buildInvocation({ runId, laneKey, runtime, model, cwd, addDirs, profileHome: data.launch.profileHome, devConfigPath }, { env, home });
+}
+
+function buildInvocation(options, { env = process.env, home = homedir() } = {}) {
+  const { runId, laneKey, runtime, model, cwd, addDirs, profileHome, devConfigPath } = options;
+  const args = runtime === "codex"
+    ? ["exec", "--json", "--cd", cwd, "--model", model, ...addDirs.flatMap((path) => ["--add-dir", path]), "-"]
+    : ["--print", "--output-format", "stream-json", "--model", model, ...addDirs.flatMap((path) => ["--add-dir", path])];
+  return {
+    command: runtime,
+    args,
+    cwd,
+    env: {
+      ...env,
+      NODII_DEV_RUN_ID: runId,
+      NODII_DEV_LANE_KEY: laneKey,
+      NODII_DEV_CONFIG_PATH: devConfigPath,
+      ...profileVariable(runtime, profileHome, home),
+    },
+  };
+}
+
+const closeQuietly = async (handle) => {
+  try {
+    await handle?.close?.();
+  } catch {}
+};
+
+export function recoveryStateRoot(path = configPath()) {
+  const configDir = dirname(path);
+  const nodiiDir = basename(configDir) === "agents" ? dirname(configDir) : configDir;
+  return join(nodiiDir, "runs");
+}
+
+async function launchDetached({ invocation, prompt, runId, laneKey, devConfigPath }, {
+  spawnImpl,
+  fs,
+  stateRoot,
+  watch,
+  terminate,
+}) {
+  absolutePath(stateRoot, "stateRoot");
+  const runDir = join(stateRoot, runId);
+  const logPath = join(runDir, "process.log");
+  const pidPath = join(runDir, "process.pid");
+
+  await fs.mkdir(runDir, { recursive: true, mode: 0o700 });
+  const log = await fs.open(logPath, "a", 0o600);
+  try {
+    await fs.chmod(logPath, 0o600);
+  } catch (error) {
+    await closeQuietly(log);
+    throw error;
+  }
+
+  let child;
+  try {
+    child = spawnImpl(invocation.command, invocation.args, {
+      cwd: invocation.cwd,
+      env: invocation.env,
+      shell: false,
+      detached: true,
+      stdio: ["pipe", log.fd, log.fd],
+    });
+  } 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);
+      });
+    });
+  });
+}
+
+const terminateChild = async (child) => {
+  if (typeof child.kill === "function") child.kill("SIGTERM");
+};
+
+/** Launch a newly registered lane with its lane-scoped Dev identity. */
+export async function launchRuntime(options, {
+  spawnImpl = spawn,
+  fs = fsPromises,
+  stateRoot,
+  home = homedir(),
+  env = process.env,
+  watch = recordWatchedRun,
+  terminate = terminateChild,
+} = {}) {
+  const launch = validateLaunch(options);
+  const invocation = buildInvocation(launch, { env, home });
+  return launchDetached({ invocation, prompt: launch.prompt, ...launch }, {
+    spawnImpl,
+    fs,
+    stateRoot: stateRoot ?? recoveryStateRoot(launch.devConfigPath),
+    watch,
+    terminate,
+  });
+}
+
+/**
+ * Launch a fresh recovery process after Dev has reserved its run.
+ *
+ * Files live outside the repository under stateRoot/<run-id>. The log is
+ * opened append-only and both files are private to the current user.
+ */
+export async function launchRecovery(payload, {
+  spawnImpl = spawn,
+  fs = fsPromises,
+  stateRoot,
+  home = homedir(),
+  env = process.env,
+  watch = recordWatchedRun,
+  terminate = terminateChild,
+} = {}) {
+  const data = dataFrom(payload);
+  const { runId, laneKey } = 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 }, {
+    spawnImpl,
+    fs,
+    stateRoot: stateRoot ?? recoveryStateRoot(devConfigPath),
+    watch,
+    terminate,
+  });
+}

package/dist/safety.js

@@ -280,6 +280,18 @@ async function harnessGenerated(root) {
 }
 
 function laneOwnership(lane, root) {
+  const repository = lane?.repositories?.find((item) => {
+    const worktree = resolve(item.worktree);
+    return worktree === root;
+  });
+  if (repository) {
+    const paths = repository.ownedPaths.map((item) => {
+      if (!isAbsolute(item)) return cleanPath(item);
+      const rel = cleanPath(relative(root, item));
+      return rel.startsWith("../") ? item : rel;
+    });
+    return { known: true, paths };
+  }
   const direct = lane && Object.hasOwn(lane, "ownedPaths");
   const frozen = lane?.freeze?.boundaries && Object.hasOwn(lane.freeze.boundaries, "ownedPaths");
   const candidates = direct ? lane.ownedPaths : frozen ? lane.freeze.boundaries.ownedPaths : [];
@@ -298,6 +310,13 @@ async function currentLane(cwd, request, config) {
   const branch = await git(cwd, "branch", "--show-current");
   const rootText = await git(cwd, "rev-parse", "--show-toplevel");
   const root = await realpath(rootText).catch(() => resolve(rootText));
+  const markerText = await optional(await gitPrivatePath(cwd, "nodii-lane.json"));
+  if (markerText) {
+    const marker = JSON.parse(markerText);
+    const lane = (await request("GET", `/api/v1/lanes/${encode(marker.laneKey)}`)).data;
+    const repository = lane.repositories?.find((item) => item.branch === branch && resolve(item.worktree) === root);
+    if (lane.agentId === config.agentId && repository && ACTIVE.has(lane.status)) return lane;
+  }
   const lanes = (await request("GET", "/api/v1/lanes?limit=200")).data ?? [];
   for (const lane of lanes) {
     if (lane.agentId !== config.agentId || lane.branch !== branch || !ACTIVE.has(lane.status)) continue;