@nodii/dev 0.6.29 → 0.6.30

package/dist/lanes.js

@@ -4,9 +4,12 @@ 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;
 
@@ -118,7 +121,34 @@ export async function branchCommits(lane) {
   }
 }
 
-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 } = {}) {
+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 })}`);
@@ -142,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);
@@ -303,21 +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 repositories = lane.repositories?.length ? lane.repositories : [{ repo: lane.repos?.[0], worktree: lane.worktree, baseRef: "origin/main" }];
+    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 execFileAsync("git", ["-C", repository.worktree, ...args], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 })).stdout;
+      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())].slice(0, 5000);
-  } catch {
+    return [...new Set(changed.flat())];
+  } catch (error) {
+    if (signal?.aborted) throw error;
     return null;
   }
 }

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/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 -->";
@@ -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

@@ -4,12 +4,26 @@ 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 { nextCommand } from "./lanes.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)) {
@@ -380,27 +394,42 @@ export async function amendmentGuard(argv, { request = devRequest, marker = curr
   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 });
 }
 
-export async function gatherLaneCommand(key, flags, { request = devRequest, marker = currentMarker, gather = nextCommand } = {}) {
-  const lane = await marker();
-  key ??= lane?.laneKey;
-  if (!key) throw new CliError("USAGE", "lane gather needs <key> outside a launched lane worktree.", 2);
-  if (!flags.delta) return gather(key, flags, { request });
-  if (!lane || lane.laneKey !== key) throw new CliError("LANE_RUN_REQUIRED", "Delta gather must run inside this lane's registered worktree.", 1);
-  const pending = await request("GET", `/api/v1/lanes/${encode(key)}/amendments${query({ runId: lane.runId })}`);
-  if (!pending.data.length) {
-    const gathered = await gather(key, flags, { request });
-    return { ...gathered, human: `${typeof gathered.human === "string" ? gathered.human : "Gather complete."}\nNo pending amendments.` };
+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);
   }
-  const version = Math.max(...pending.data.map((item) => item.version));
-  const gathered = await gather(key, {
-    ...flags,
-    deltaContext: { runId: lane.runId, amendmentVersion: version },
-  }, { request });
-  const acknowledgedVersion = gathered.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, 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}.`,
-  };
 }

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);
 }

package/package.json

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