@nodii/dev 0.6.28 → 0.6.30

package/dist/setup.js

@@ -3,6 +3,7 @@ import { dirname, join, resolve } from "node:path";
 import { CliError, checkLogin } from "./core.js";
 import { codexHooksFromClaude } from "./harness.js";
 import { regroundingHooksSnippet, safetySettingsSnippet } from "./safety.js";
+import { PICKER_MODEL, setupOllama } from "./gather.js";
 
 export const SKILL_PATH = ".claude/skills/nodii-build-workflow/SKILL.md";
 const START = "<!-- nodii-dev build workflow:start -->";
@@ -17,8 +18,8 @@ description: Drive every Nodii build lane through nodii-dev from start to verifi
 
 Use \`nodii-dev\` as the control plane. It talks only to Dev, through the platform edge, signed in with \`nodii-dev login\` as the platform tenant's OAuth app. The canonical policy is the build-workflow rulebook in Dev (\`nodii-dev rulebook list\`), §§1–8 (operator rulings A-020/A-021). Never change lane state in Dev by another route.
 
-1. Start: \`nodii-dev lane start KEY --title "..." --kind dev_fix|new_build|docs_change|uat_fix|prod_fix --side backend|frontend|both [--issue ISSUE]\`.
-2. Ask \`nodii-dev next KEY\`; start, complete, or block the reported API step with \`nodii-dev lane step\`.
+1. The machine coordinator runs \`nodii-dev coordinator start --machine NAME\`, then \`nodii-dev lane launch KEY\` with the issue (whose title is the objective), done check, build kind/side, repeated repository/branch pairs, runtime profile/model and subagent quota. A launched agent begins with \`nodii-dev lane gather\` from its worktree.
+2. Re-run \`nodii-dev lane gather\` for the current steps and rules; start, complete, or block the reported API step with \`nodii-dev lane step\`. After an authoritative \`lane amend\`, every run is blocked until its own \`lane gather --delta\` acknowledgement.
 3. Record durable evidence with \`nodii-dev lane evidence KEY --pr|--commit|--figma|--deploy|--dev-check REF\` and heartbeat long-running work with \`nodii-dev lane heartbeat KEY --note "..."\` (notes are at most 500 characters).
 4. Record the review gate with \`nodii-dev lane review KEY\`. After merge, run \`nodii-dev lane land KEY\`. Done still means deployed and checked live on dev as the right user: \`nodii-dev lane verify KEY --dev-check REF\`.
 5. Use \`nodii-dev lane prioritize|deprioritize KEY --reason "..."\` when priority changes; the reason is required. The lane stays on Built until a staff login runs \`nodii-dev built ack KEY\`. Never treat acknowledgement as testing.
@@ -118,21 +119,37 @@ export async function setupPlan(root = process.cwd()) {
   return changes;
 }
 
-export async function setupCommand(flags, { root = process.cwd(), authCheck = checkLogin } = {}) {
+export async function setupCommand(flags, { root = process.cwd(), authCheck = checkLogin, pickerSetup = setupOllama } = {}) {
+  if (flags.yes && flags.check) throw new CliError("USAGE", "setup accepts either --yes or --check, not both.", 2);
   const changes = await setupPlan(root);
   let authenticated = true;
   try { await authCheck(); } catch { authenticated = false; }
+  let pickerReady = true;
+  let pickerStatus;
+  try { pickerStatus = await pickerSetup({ check: !flags.yes }); }
+  catch (error) {
+    pickerReady = false;
+    pickerStatus = { code: error?.code ?? "PICKER_UNAVAILABLE", message: error?.message ?? String(error) };
+  }
   if (flags.check) {
-    if (changes.length) throw new CliError("SETUP_DRIFT", `Workflow harness drift: ${changes.map((x) => x.relative).join(", ")}`, 1);
-    return { payload: { ok: true, changed: [], authenticated }, human: authenticated ? "Workflow harness is current." : "Workflow harness is current. Not logged in; run `nodii-dev login`." };
+    const drift = [
+      ...(changes.length ? [`Workflow harness drift: ${changes.map((x) => x.relative).join(", ")}`] : []),
+      ...(!pickerReady ? [`Gather picker: ${pickerStatus.message}`] : []),
+    ];
+    if (drift.length) throw new CliError("SETUP_DRIFT", drift.join("; "), 1);
+    return { payload: { ok: true, changed: [], authenticated, picker: pickerStatus }, human: authenticated ? "Workflow harness and Gather picker are current." : "Workflow harness and Gather picker are current. Not logged in; run `nodii-dev login`." };
   }
   if (!flags.yes) {
-    const preview = changes.length ? changes.map((x) => `${x.before === null ? "+ create" : "~ update"} ${x.relative}`).join("\n") : "No changes.";
-    return { payload: { dryRun: true, changed: changes.map((x) => x.relative), authenticated }, human: `${preview}\n${authenticated ? "Authentication: ready." : "Authentication: not logged in; run `nodii-dev login`."}\nRun \`nodii-dev setup --yes\` to apply.` };
+    const preview = [
+      ...(changes.length ? changes.map((x) => `${x.before === null ? "+ create" : "~ update"} ${x.relative}`) : ["No workflow changes."]),
+      pickerReady ? `Gather picker: ${PICKER_MODEL} is ready.` : `+ install Ollama and pull ${PICKER_MODEL}`,
+    ].join("\n");
+    return { payload: { dryRun: true, changed: [...changes.map((x) => x.relative), ...(!pickerReady ? [`ollama:${PICKER_MODEL}`] : [])], authenticated, picker: pickerStatus }, human: `${preview}\n${authenticated ? "Authentication: ready." : "Authentication: not logged in; run `nodii-dev login`."}\nRun \`nodii-dev setup --yes\` to apply.` };
   }
+  if (!pickerReady) throw new CliError(pickerStatus.code, pickerStatus.message, 1);
   for (const change of changes) {
     await mkdir(dirname(change.path), { recursive: true });
     await writeFile(change.path, change.content);
   }
-  return { payload: { applied: true, changed: changes.map((x) => x.relative), authenticated }, human: `${changes.length ? `Applied: ${changes.map((x) => x.relative).join(", ")}` : "Workflow harness already current."}\n${authenticated ? "Authentication: ready." : "Not logged in; run `nodii-dev login`."}` };
+  return { payload: { applied: true, changed: [...changes.map((x) => x.relative), ...(pickerStatus.changed ?? []).map((x) => `ollama:${x}`)], authenticated, picker: pickerStatus }, human: `${changes.length ? `Applied: ${changes.map((x) => x.relative).join(", ")}` : "Workflow harness already current."}\nGather picker: ${PICKER_MODEL} ready on Ollama ${pickerStatus.version}.\n${authenticated ? "Authentication: ready." : "Not logged in; run `nodii-dev login`."}` };
 }

package/dist/starting.js

@@ -0,0 +1,435 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdir, readFile, rmdir, writeFile } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { CliError, configPath, devRequest, encode, query, readConfig, requireFlag } from "./core.js";
+import { GATHER_TIMEOUT_MS } from "./gather.js";
+import { laneCommand, nextCommand } from "./lanes.js";
+
+const execFile = promisify(execFileCallback);
+const via = { via: "nodii-dev" };
+const values = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
+
+const withSignal = (promise, signal) => {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason ?? new Error("aborted"));
+  return new Promise((resolvePromise, rejectPromise) => {
+    const abort = () => rejectPromise(signal.reason ?? new Error("aborted"));
+    signal.addEventListener("abort", abort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => { signal.removeEventListener("abort", abort); resolvePromise(value); },
+      (error) => { signal.removeEventListener("abort", abort); rejectPromise(error); },
+    );
+  });
+};
+
+function pairs(value, flag) {
+  const out = new Map();
+  for (const raw of values(value)) {
+    const at = String(raw).indexOf("=");
+    if (at < 1 || at === String(raw).length - 1)
+      throw new CliError("USAGE", `--${flag} must be NAME=VALUE and may be repeated.`, 2);
+    const key = String(raw).slice(0, at).trim();
+    const item = String(raw).slice(at + 1).trim();
+    if (out.has(key)) throw new CliError("USAGE", `--${flag} repeats ${key}.`, 2);
+    out.set(key, item);
+  }
+  return out;
+}
+
+function groupedPairs(value, flag) {
+  const out = new Map();
+  for (const raw of values(value)) {
+    const at = String(raw).indexOf("=");
+    if (at < 1 || at === String(raw).length - 1)
+      throw new CliError("USAGE", `--${flag} must be NAME=VALUE and may be repeated.`, 2);
+    const key = String(raw).slice(0, at).trim();
+    const item = String(raw).slice(at + 1).trim();
+    out.set(key, [...(out.get(key) ?? []), item]);
+  }
+  return out;
+}
+
+export function launchRepositories(key, flags) {
+  const sources = pairs(flags.repo, "repo");
+  const branches = pairs(flags.branch, "branch");
+  const bases = pairs(flags.base, "base");
+  const worktrees = pairs(flags.worktree, "worktree");
+  const owned = groupedPairs(flags["owned-path"], "owned-path");
+  if (!sources.size) throw new CliError("USAGE", "lane launch needs at least one --repo NAME=/absolute/source.", 2);
+  for (const collection of [branches, bases, worktrees, owned])
+    for (const name of collection.keys())
+      if (!sources.has(name)) throw new CliError("USAGE", `Repository options name unknown repo ${name}.`, 2);
+  return [...sources].map(([name, source]) => {
+    if (!isAbsolute(source)) throw new CliError("USAGE", `--repo ${name} needs an absolute source path.`, 2);
+    const branch = branches.get(name);
+    if (!branch) throw new CliError("USAGE", `Missing --branch ${name}=BRANCH.`, 2);
+    const worktree = worktrees.get(name) ?? join(source, ".claude", "worktrees", key);
+    if (!isAbsolute(worktree)) throw new CliError("USAGE", `--worktree ${name} needs an absolute path.`, 2);
+    return {
+      repo: name,
+      source: resolve(source),
+      branch,
+      worktree: resolve(worktree),
+      baseRef: bases.get(name) ?? "origin/main",
+      ownedPaths: owned.get(name) ?? [],
+    };
+  });
+}
+
+export function figmaScopes(value) {
+  return values(value).map((raw) => {
+    const scope = String(raw).trim();
+    const at = scope.indexOf("=");
+    const fileKey = (at < 0 ? scope : scope.slice(0, at)).trim();
+    const componentSets = at < 0 ? [] : scope.slice(at + 1).split(",").map((item) => item.trim()).filter(Boolean);
+    if (!fileKey || (at >= 0 && componentSets.length === 0))
+      throw new CliError("USAGE", "--figma must be FILE_KEY or FILE_KEY=COMPONENT_SET[,COMPONENT_SET] and may be repeated.", 2);
+    return {
+      fileKey,
+      componentSets,
+    };
+  });
+}
+
+const stateFile = (machine) => join(dirname(configPath()), `coordinator-${encodeURIComponent(machine)}.json`);
+export function laneConfigPath(key, current = configPath()) {
+  const configDir = dirname(current);
+  const agentsDir = basename(configDir) === "agents" ? configDir : join(configDir, "agents");
+  const lane = String(key).toLowerCase().replaceAll(/[^a-z0-9_-]/g, "-");
+  return join(agentsDir, `lane-${lane}.json`);
+}
+async function saveJson(file, value) {
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+async function loadJson(file) {
+  try { return JSON.parse(await readFile(file, "utf8")); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function coordinatorRuntimePid(run = execFile) {
+  let pid = process.ppid;
+  for (let depth = 0; depth < 8 && Number.isInteger(pid) && pid > 1; depth += 1) {
+    const { stdout } = await run("ps", ["-p", String(pid), "-o", "ppid=", "-o", "comm="], { encoding: "utf8" });
+    const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(stdout);
+    if (!match) break;
+    if (/(?:^|\/)(?:codex|claude)(?:$|[-_.])/i.test(match[2])) return pid;
+    pid = Number(match[1]);
+  }
+  throw new CliError("COORDINATOR_PROCESS_NOT_FOUND", "Could not identify the parent Claude or Codex coordinator process.", 1);
+}
+
+async function watchCoordinator(runId) {
+  const { recordWatchedRun } = await import("./watchdog.js");
+  return recordWatchedRun({
+    runId,
+    pid: await coordinatorRuntimePid(),
+    configPath: configPath(),
+    worktree: process.cwd(),
+  });
+}
+
+export async function coordinatorCommand(action, flags, { request = devRequest, config = readConfig, save = saveJson, watch = watchCoordinator } = {}) {
+  if (action !== "start") throw new CliError("USAGE", `Unknown coordinator action: ${action}`, 2);
+  const machine = requireFlag(flags, "machine");
+  const payload = await request("POST", "/api/v1/coordinator-runs/start", {
+    machine,
+    expectedHeartbeatSeconds: flags["heartbeat-seconds"] ? Number(flags["heartbeat-seconds"]) : 60,
+    ...via,
+  });
+  const c = await config();
+  try {
+    await watch(payload.data.run.id);
+  } catch (error) {
+    try {
+      await request("POST", `/api/v1/runs/${encode(payload.data.run.id)}/process-exit`, {
+        reason: "coordinator watcher registration failed",
+        deathFingerprint: "coordinator-watch-registration",
+        logTail: String(error.message).slice(0, 50_000),
+      });
+    } catch {}
+    throw new CliError("COORDINATOR_WATCH_FAILED", `Coordinator run ${payload.data.run.id} was registered, but its session could not be watched: ${error.message}`, 1);
+  }
+  await save(stateFile(machine), {
+    machine,
+    machineId: payload.data.machine.id,
+    runId: payload.data.run.id,
+    agentId: c.agentId,
+    startedAt: payload.data.run.startedAt,
+  });
+  return {
+    payload,
+    human: (p) => [
+      `Coordinator ${p.data.run.id} is watching ${p.data.machine.name}.`,
+      `running lanes: ${p.data.runningLanes.length}`,
+      `orphans: ${p.data.orphanedRuns.length}`,
+      `unclaimed results: ${p.data.unclaimedResults.length}`,
+      ...(p.data.takeoverOfRunId ? [`takeover recorded from ${p.data.takeoverOfRunId}`] : []),
+    ].join("\n"),
+  };
+}
+
+async function createWorktrees(repositories, run = execFile) {
+  for (const repository of repositories) {
+    try {
+      const { stdout } = await run("git", ["-C", repository.worktree, "branch", "--show-current"], { encoding: "utf8" });
+      if (stdout.trim() !== repository.branch)
+        throw new CliError("WORKTREE_CONFLICT", `${repository.worktree} exists on ${stdout.trim() || "a detached HEAD"}, not ${repository.branch}.`, 1);
+      continue;
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+    }
+    await run("git", ["-C", repository.source, "fetch", "origin"]);
+    let branchExists = false;
+    try {
+      await run("git", ["-C", repository.source, "show-ref", "--verify", `refs/heads/${repository.branch}`]);
+      branchExists = true;
+    } catch {}
+    await run("git", ["-C", repository.source, "worktree", "add", repository.worktree, ...(branchExists ? [repository.branch] : ["-b", repository.branch, repository.baseRef])]);
+  }
+}
+
+async function writeLaneMarkers(repositories, marker, run = execFile, save = saveJson) {
+  for (const repository of repositories) {
+    const { stdout } = await run("git", ["-C", repository.worktree, "rev-parse", "--git-dir"], { encoding: "utf8" });
+    const gitDir = isAbsolute(stdout.trim()) ? stdout.trim() : resolve(repository.worktree, stdout.trim());
+    await save(join(gitDir, "nodii-lane.json"), marker);
+  }
+}
+
+async function primaryHead(repositories, run = execFile) {
+  const { stdout } = await run("git", ["-C", repositories[0].worktree, "rev-parse", "HEAD"], { encoding: "utf8" });
+  return stdout.trim();
+}
+
+async function defaultLaunchRuntime(options) {
+  const module = await import("./runtime-launcher.js");
+  return module.launchRuntime(options);
+}
+
+export async function verifyFigmaSeat({ env = process.env, fetchImpl = fetch, rateLimit = figmaRateLimit } = {}) {
+  const token = env.FIGMA_PAT || env.FIGMA_TOKEN;
+  if (!token) throw new CliError("FIGMA_TOKEN_REQUIRED", "--figma preflight needs FIGMA_PAT for the assigned Figma account.", 2);
+  let response;
+  try {
+    response = await rateLimit(() => fetchImpl("https://api.figma.com/v1/me", {
+      headers: { "X-Figma-Token": token },
+      signal: AbortSignal.timeout(10_000),
+    }));
+  } catch (error) {
+    throw new CliError("FIGMA_SEAT_UNAVAILABLE", `Figma seat preflight could not complete: ${error.message}`, 1);
+  }
+  if (!response.ok) throw new CliError("FIGMA_SEAT_UNAVAILABLE", `Figma seat preflight returned HTTP ${response.status}.`, 1);
+  const account = await response.json();
+  if (!account?.id) throw new CliError("FIGMA_SEAT_UNAVAILABLE", "Figma did not identify the assigned account.", 1);
+  return true;
+}
+
+/** Serialize the machine's shared Figma token and keep call starts 10s apart. */
+export async function figmaRateLimit(task, {
+  root = basename(dirname(configPath())) === "agents" ? dirname(dirname(configPath())) : dirname(configPath()),
+  sleep = delay,
+  now = Date.now,
+  fs = { mkdir, readFile, rmdir, writeFile },
+} = {}) {
+  const lock = join(root, "figma-rest.lock");
+  const stamp = join(root, "figma-rest-last-call");
+  await fs.mkdir(root, { recursive: true, mode: 0o700 });
+  const deadline = now() + 30_000;
+  for (;;) {
+    try {
+      await fs.mkdir(lock, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      if (now() >= deadline) throw new CliError("FIGMA_RATE_LOCKED", "Another Figma REST call has held the machine lock for 30 seconds.", 1);
+      await sleep(100);
+    }
+  }
+  try {
+    let previous = 0;
+    try { previous = Number(await fs.readFile(stamp, "utf8")) || 0; }
+    catch (error) { if (error?.code !== "ENOENT") throw error; }
+    const wait = Math.max(0, 10_000 - (now() - previous));
+    if (wait) await sleep(wait);
+    await fs.writeFile(stamp, `${now()}\n`, { mode: 0o600 });
+    return await task();
+  } finally {
+    await fs.rmdir(lock);
+  }
+}
+
+export async function launchLaneCommand(key, flags, {
+  request = devRequest,
+  config = readConfig,
+  state = loadJson,
+  worktrees = createWorktrees,
+  markers = writeLaneMarkers,
+  head = primaryHead,
+  launcher = defaultLaunchRuntime,
+  figmaSeat = verifyFigmaSeat,
+  laneConfig = loadJson,
+  identityPath = laneConfigPath,
+} = {}) {
+  if (!key) throw new CliError("USAGE", "lane launch needs <key>.", 2);
+  const machine = requireFlag(flags, "machine");
+  const coordinator = flags["coordinator-run"]
+    ? { runId: flags["coordinator-run"], machineId: requireFlag(flags, "machine-id") }
+    : await state(stateFile(machine));
+  if (!coordinator) throw new CliError("COORDINATOR_NOT_STARTED", `Run nodii-dev coordinator start --machine ${machine} first.`, 1);
+  const repositories = launchRepositories(key, flags);
+  const runtime = requireFlag(flags, "runtime");
+  if (!["claude", "codex"].includes(runtime)) throw new CliError("USAGE", "--runtime must be claude or codex.", 2);
+  const issueRefs = values(requireFlag(flags, "issue")).flatMap((item) => String(item).split(",")).filter(Boolean);
+  const issueIds = await Promise.all(issueRefs.map(async (ref) => (await request("GET", `/api/v1/issues/${encode(ref)}`)).data.id));
+  const c = await config();
+  if (coordinator.agentId && coordinator.agentId !== c.agentId)
+    throw new CliError("COORDINATOR_IDENTITY_MISMATCH", `The saved ${machine} coordinator run belongs to another Dev agent.`, 1);
+  const devConfigPath = identityPath(key);
+  const identity = await laneConfig(devConfigPath);
+  if (!identity?.agentId)
+    throw new CliError("LANE_IDENTITY_REQUIRED", `Lane ${key} needs its provisioned Dev identity at ${devConfigPath}.`, 1);
+  const scopes = figmaScopes(flags.figma);
+  const figmaSeatVerified = scopes.length ? await figmaSeat() : false;
+  const profile = requireFlag(flags, "profile");
+  if (!isAbsolute(profile)) throw new CliError("USAGE", "--profile must be an absolute runtime profile path.", 2);
+  const body = {
+    key,
+    doneCheck: requireFlag(flags, "done-check"),
+    kind: requireFlag(flags, "kind"),
+    side: requireFlag(flags, "side"),
+    issueIds,
+    agentId: identity.agentId,
+    machineId: coordinator.machineId,
+    coordinatorRunId: coordinator.runId,
+    repositories: repositories.map(({ source: _source, ...repository }) => repository),
+    runtime,
+    profile,
+    devConfigPath,
+    model: requireFlag(flags, "model"),
+    subagentQuota: Number(requireFlag(flags, "subagents")),
+    ...(flags.notes ? { notes: flags.notes } : {}),
+    ...(flags["narrowing-note"] ? { narrowingNote: flags["narrowing-note"] } : {}),
+    ...(flags["narrowing-remainder"] ? { narrowingRemainder: flags["narrowing-remainder"] } : {}),
+    figmaScopes: scopes,
+    preflight: { ...(figmaSeatVerified ? { figmaSeatVerified: true } : {}) },
+    expectedHeartbeatSeconds: flags["heartbeat-seconds"] ? Number(flags["heartbeat-seconds"]) : 60,
+    ...via,
+  };
+  if (!Number.isInteger(body.subagentQuota) || body.subagentQuota < 0 || body.subagentQuota > 100)
+    throw new CliError("USAGE", "--subagents must be an integer from 0 to 100.", 2);
+  await request("POST", "/api/v1/lanes/launch", { phase: "preflight", ...body });
+  await worktrees(repositories);
+  const lastPushedCommit = await head(repositories);
+  let payload;
+  try {
+    payload = await request("POST", "/api/v1/lanes/launch", { phase: "register", ...body, lastPushedCommit });
+  } catch (error) {
+    throw new CliError(error?.code ?? "LANE_REGISTER_FAILED", `${error?.message ?? error}. Worktrees were created and were not removed; reconcile them before retrying.`, 1);
+  }
+  await markers(repositories, { laneKey: key, laneId: payload.data.lane.id, runId: payload.data.run.id });
+  try {
+    await launcher({
+      laneKey: key,
+      devConfigPath,
+      runtime,
+      model: body.model,
+      profileHome: body.profile,
+      cwd: repositories[0].worktree,
+      addDirs: repositories.slice(1).map(({ worktree }) => worktree),
+      prompt: payload.data.brief,
+      runId: payload.data.run.id,
+    });
+  } catch (error) {
+    try {
+      await request("POST", `/api/v1/lanes/${encode(payload.data.lane.id)}/resume/${encode(payload.data.run.id)}/launch-failed`, {
+        reason: error.message,
+        ...via,
+      });
+    } catch (reportError) {
+      throw new CliError("LANE_LAUNCH_FAILED", `Lane ${key} is registered but its runtime did not start (${error.message}), and Dev could not record the launch failure (${reportError.message}).`, 1);
+    }
+    throw new CliError("LANE_LAUNCH_FAILED", `Lane ${key} is registered but its runtime did not start: ${error.message}. Dev recorded it for lane resume.`, 1);
+  }
+  return { payload, human: `Launched ${key}: ${payload.data.brief}` };
+}
+
+export async function amendLaneCommand(key, flags, { request = devRequest } = {}) {
+  if (!key) throw new CliError("USAGE", "lane amend needs <key>.", 2);
+  const change = Object.fromEntries([["objective", flags.objective], ["scope", flags.scope], ["rules", flags.rules]].filter(([, value]) => value));
+  if (!Object.keys(change).length) throw new CliError("USAGE", "lane amend needs --objective, --scope, or --rules.", 2);
+  const payload = await request("POST", `/api/v1/lanes/${encode(key)}/amendments`, { change, reason: requireFlag(flags, "reason"), ...via });
+  return { payload, human: `Recorded amendment ${payload.data.version} for ${key}.` };
+}
+
+export async function currentMarker(run = execFile, load = loadJson, env = process.env) {
+  let stdout;
+  try {
+    ({ stdout } = await run("git", ["rev-parse", "--git-dir"], { encoding: "utf8" }));
+  } catch {
+    return null;
+  }
+  const gitDir = isAbsolute(stdout.trim()) ? stdout.trim() : resolve(process.cwd(), stdout.trim());
+  const marker = await load(join(gitDir, "nodii-lane.json"));
+  if (!marker) return null;
+  const runId = env.NODII_DEV_RUN_ID ?? marker.runId;
+  if (typeof marker.laneKey !== "string" || !marker.laneKey.trim() || typeof runId !== "string" || !runId.trim())
+    throw new CliError("LANE_MARKER_INVALID", "This worktree's Nodii lane marker is invalid; repair the launch record before running CLI commands.", 1);
+  return { ...marker, runId };
+}
+
+export async function amendmentGuard(argv, { request = devRequest, marker = currentMarker } = {}) {
+  const lane = await marker();
+  if (!lane) return null;
+  const [command, action] = argv.filter((token) => !token.startsWith("--"));
+  if ((command === "lane" && action === "gather" && argv.includes("--delta")) || (command === "lane" && action === "amend")) return lane;
+  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 runGather = (key, flags, { request, signal }) => laneCommand("gather", [key], flags, { request, gatherSignal: signal });
+
+export async function gatherLaneCommand(key, flags, { request = devRequest, marker = currentMarker, gather = runGather, acknowledge = nextCommand, gatherTimeoutMs = GATHER_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const deadline = setTimeout(() => controller.abort(), gatherTimeoutMs);
+  const signal = controller.signal;
+  const timedRequest = (method, path, body, options = {}) => withSignal(request(method, path, body, { ...options, signal }), signal);
+  try {
+    const lane = await withSignal(marker(), signal);
+    key ??= lane?.laneKey;
+    if (!key) throw new CliError("USAGE", "lane gather needs <key> outside a launched lane worktree.", 2);
+    if (!flags.delta) return await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    if (lane && lane.laneKey !== key) throw new CliError("LANE_RUN_REQUIRED", "Delta gather for another lane cannot run inside this lane's registered worktree.", 1);
+    if (!lane) return await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    const pending = await timedRequest("GET", `/api/v1/lanes/${encode(key)}/amendments${query({ runId: lane.runId })}`);
+    if (!pending.data.length) {
+      const gathered = await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+      return { ...gathered, human: `${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nNo pending amendments.` };
+    }
+    const version = Math.max(...pending.data.map((item) => item.version));
+    const gathered = await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    const acknowledgement = await withSignal(acknowledge(key, {
+      ...flags,
+      deltaContext: { runId: lane.runId, amendmentVersion: version },
+    }, { request: timedRequest }), signal);
+    const acknowledgedVersion = acknowledgement.payload?.rules?.amendmentAcknowledgement?.version;
+    if (acknowledgedVersion !== version)
+      throw new CliError("LANE_AMENDMENT_ACK_FAILED", `Delta gather did not acknowledge amendment version ${version}; the lane remains blocked.`, 1);
+    return {
+      payload: { ...gathered.payload, rules: acknowledgement.payload?.rules, amendments: pending.data, acknowledgedVersion },
+      human: `${pending.data.map((item) => `v${item.version} ${item.reason}: ${JSON.stringify(item.change)}`).join("\n")}\n${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nAcknowledged amendment version ${version}.`,
+    };
+  } 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 {
+    clearTimeout(deadline);
+  }
+}

package/dist/upload.js

@@ -8,6 +8,7 @@ import { join, relative, resolve } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { CliError, devRequest, devTextRequest, encode, query } from "./core.js";
 import { CHANGE_CLASSES, validateDocument } from "./docs.js";
+import { rulesFindText } from "./gather.js";
 
 /** Exit code when Dev is waiting on the operator to acknowledge parked items. */
 export const EXIT_PARKED = 4;
@@ -307,6 +308,15 @@ const pad = (v, n) => String(v).padStart(n);
  * core, the delivery report, and the operator's core token cap.
  */
 export async function rulesCommand(action, args, flags, { request = devRequest } = {}) {
+  if (action === "find") {
+    const question = args.join(" ").trim();
+    if (!question) throw new CliError("USAGE", 'rules find needs a question, for example: nodii-dev rules find "may this route use offset paging?"', 2);
+    if (question.length > 20_000) throw new CliError("USAGE", "rules find questions are at most 20,000 characters", 2);
+    const limit = flags.limit === undefined ? 10 : Number(flags.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new CliError("USAGE", "rules find --limit needs a whole number from 1 to 100", 2);
+    const payload = await request("GET", `/api/v1/rules/find${query({ question, limit })}`);
+    return { payload, human: rulesFindText };
+  }
   if (action === "core") {
     // Dev refuses a core over the cap with CORE_OVER_CAP; that error is the output.
     const payload = await request("GET", "/api/v1/rules/core");
@@ -337,5 +347,5 @@ export async function rulesCommand(action, args, flags, { request = devRequest }
     const payload = await request("PUT", "/api/v1/rules/core/cap", { cap });
     return { payload, human: (p) => `Core cap: ${p.data.previous} -> ${p.data.cap} tokens.` };
   }
-  throw new CliError("USAGE", "rules core | rules report [--section rulebook|services|all] [--lane KEY] | rules cap TOKENS", 2);
+  throw new CliError("USAGE", 'rules find "QUESTION" [--limit N] | rules core | rules report [--section rulebook|services|all] [--lane KEY] | rules cap TOKENS', 2);
 }