@nodii/dev 0.6.33 → 0.6.35

package/dist/lanes.js

@@ -4,8 +4,9 @@ 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, PICKER_MODEL, gatherText, pickDocuments } from "./gather.js";
+import { GATHER_TIMEOUT_MS, PICKER_MODEL, gatherText, pickDocuments, withPickLock } from "./gather.js";
 import { storeGatherFreeze } from "./freeze.js";
+import { SWAP_BOUNDARIES, componentsForScope, guidelineLookup, laneFigmaScope, loadDsCatalog } from "./figma-scope.js";
 
 const execFileAsync = promisify(execFile);
 const via = { via: "nodii-dev" };
@@ -206,7 +207,7 @@ async function currentGatherLane(request, config, gitContext) {
   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 } = {}) {
+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, catalog = loadDsCatalog, pickLock = withPickLock } = {}) {
   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 })}`);
@@ -230,6 +231,16 @@ 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)}` };
   }
+  // The Freeze references the Clause map rather than holding it (hub-58).
+  if (action === "gather" && args[0] === "show") {
+    // A Gather flag here means a Gather was meant: never show silently instead.
+    const gatherFlags = ["picker", "shortlist", "documents", "delta", "objective", "done-check", "paths", "components", "limit", "section-limit-per-document"].filter((flag) => flags[flag] !== undefined);
+    if (gatherFlags.length)
+      throw new CliError("USAGE", `lane gather show takes only [<key>] [--gather ID]; --${gatherFlags.join(", --")} belong to lane gather.`, 2);
+    const key = need(args[1] ?? await currentGatherLane(request, config, gitContext), "lane gather show needs <key>");
+    const payload = await request("GET", `/api/v1/lanes/${encode(key)}/gather${query({ gatherId: flags.gather })}`);
+    return { payload, human: (p) => `Gather ${p.data.gatherId}\n${gatherText(p, p.data.objective ?? "")}` };
+  }
   const ref = need(args[0] ?? (action === "gather" ? await currentGatherLane(request, config, gitContext) : undefined), `lane ${action} needs <key>`);
   const id = ref;
   if (action === "show") {
@@ -302,11 +313,29 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
         ...(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 ?? []),
+      // The Figma scope (published keys) pulls in the DS components its
+      // Surfaces are built from, so their guidelines and U-docs apply.
+      // null = no declared Figma scope (kept undeclared); [] = declared "no Figma".
+      // A first Gather on a launch scope stored before keys were enforced
+      // stores "no Figma" (fails closed) so the lane can swap boundaries.
+      let declaredFigma;
+      let invalidScope = null;
+      try {
+        declaredFigma = laneFigmaScope(lane);
+      } catch (error) {
+        if (error?.code !== "FIGMA_SCOPE_INVALID" || lane.freeze) throw error;
+        declaredFigma = [];
+        invalidScope = error.reason ?? error.message;
+      }
+      const figmaScope = declaredFigma ?? [];
+      const scoped = figmaScope.some((file) => file.componentSets.length)
+        ? componentsForScope(await catalog({ signal }), figmaScope)
+        : { surfaces: [], components: [], unknownKeys: [] };
+      const components = flags.components ? list(flags.components) : [...new Set([
+        ...scoped.components,
+        ...scoped.surfaces,
         ...(lane.components ?? []),
-      ];
+      ])];
       const shortlistBody = {
         objective,
         paths,
@@ -322,7 +351,9 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
       const triggers = shortlist.data?.triggers ?? [];
       if (byAgent && !byAgent.shortlist)
         return { payload: { data: { recorded: false, picker: "agent", shortlistId, objective, triggers } }, human: (p) => agentShortlistText(ref, p.data, flags) };
-      const picked = byAgent ? { documents: byAgent.documents } : await picker({
+      // Only the local model pick takes the per-lane pick lock; an agent pick
+      // records a choice already made (AGENT-HARNESS-19 + GATHER-NA).
+      const picked = byAgent ? { documents: byAgent.documents } : await pickLock(lane.id ?? id, () => picker({
         objective,
         files: paths,
         triggers: triggers.map((trigger) => ({
@@ -330,7 +361,7 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
           trigger: trigger.sentence,
           ...(trigger.forcedBy ? { forcedBy: trigger.forcedBy } : {}),
         })),
-      }, { signal });
+      }, { signal }));
       const payload = await request("POST", `/api/v1/lanes/${encode(id)}/gather`, {
         objective,
         documentCodes: picked.documents,
@@ -341,10 +372,11 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
         shortlistId,
         picker: byAgent ? "agent" : picked.model ?? PICKER_MODEL,
       }, { signal });
-      const figma = lane.freeze?.boundaries?.figma ?? (lane.launch?.figmaScopes ?? []).map((file) => ({
+      const figma = figmaScope.map((file) => ({
         fileKey: file.fileKey,
-        ...(file.componentSets?.length ? { componentSetKeys: file.componentSets } : {}),
+        ...(file.componentSets.length ? { componentSetKeys: file.componentSets } : {}),
       }));
+      const lookup = guidelineLookup(scoped.components);
       const issue = lane.issue ? { key: lane.issue.key, title: lane.issue.title } : null;
       const laneNotes = [
         lane.launch?.notes,
@@ -354,16 +386,23 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
       const freezeRequest = (method, path, body, options = {}) => request(method, path, body, { ...options, signal });
       await storeFreeze(id, {
         gather: payload.data,
-        boundaries: { repos: repositories, ...(figma.length ? { figma } : {}) },
+        boundaries: { repos: repositories, ...(declaredFigma ? { figma } : {}) },
         issue,
         laneNotes,
         doneCheck,
+        lookups: lookup ? [lookup] : [],
       }, { 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) };
+      const scopeNotice = [
+        ...(scoped.unknownKeys.length ? [`Notice: no DS catalog Surface has component-set key ${scoped.unknownKeys.join(", ")}; no component guidelines were pulled for ${scoped.unknownKeys.length === 1 ? "it" : "them"}.`] : []),
+        ...(invalidScope ? [`Notice: the launch Figma scope is not published keys (${invalidScope.replace(/\.$/, "")}), so the Freeze was stored with no Figma scope and every Figma lock and write is refused. Set the published keys with ${SWAP_BOUNDARIES(id)}.`] : []),
+      ].map((line) => `\n${line}`).join("");
+      // The pick's model and latency ride along in --json (morning check records them).
+      const result = { ...payload, picker: { model: picked.model ?? null, latency: picked.latency ?? null } };
+      return { payload: result, human: (p) => `${gatherText(p, objective, reasons)}${scopeNotice}` };
     } 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;

package/dist/nodii-dev.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { fail, main } from "./cli.js";
 import { regroundCurrentLane, shouldReground } from "./freeze.js";
+import { isHookDenial } from "./hooks.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.
@@ -16,8 +17,7 @@ async function run() {
 }
 
 run().catch((error) => {
-  const denial = String(error?.code ?? "").startsWith("SAFETY_") ||
-    ["FIGMA_FILE_KEY_MISSING", "FIGMA_LOCK_DENIED", "WRITE_OUT_OF_SCOPE"].includes(error?.code);
+  const denial = isHookDenial(error?.code);
   if (argv[0] === "hook" && !denial) {
     process.exitCode = 0;
     return;

package/dist/runtime-launcher.js

@@ -108,7 +108,8 @@ 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])];
+    // Claude Code refuses --print with stream-json unless --verbose is set.
+    : ["--print", "--output-format", "stream-json", "--verbose", "--model", model, ...addDirs.flatMap((path) => ["--add-dir", path])];
   return {
     command: runtime,
     args,

package/dist/starting.js

@@ -4,6 +4,7 @@ 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 { assertKnownSets, checkComponentSetKey, checkFileKey, loadDsCatalog, mergeScopes, scopesFromRoutes } from "./figma-scope.js";
 import { GATHER_TIMEOUT_MS } from "./gather.js";
 import { laneCommand, nextCommand } from "./lanes.js";
 
@@ -79,18 +80,30 @@ export function launchRepositories(key, flags) {
 }
 
 export function figmaScopes(value) {
-  return values(value).map((raw) => {
+  return mergeScopes(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);
+      throw new CliError("USAGE", "--figma must be FILE_KEY or FILE_KEY=COMPONENT_SET_KEY[,COMPONENT_SET_KEY] (published keys) and may be repeated.", 2);
     return {
-      fileKey,
-      componentSets,
+      fileKey: checkFileKey(fileKey),
+      componentSets: componentSets.map(checkComponentSetKey),
     };
-  });
+  }));
+}
+
+/** --figma as given, plus what each --route derives from the DS catalog. */
+export async function launchFigmaScopes(flags, { catalog = loadDsCatalog } = {}) {
+  const explicit = figmaScopes(flags.figma);
+  const routes = values(flags.route).map((route) => String(route).trim());
+  if (routes.some((route) => !route.startsWith("/")))
+    throw new CliError("USAGE", "--route must be a frontend route such as /app/dev/building and may be repeated.", 2);
+  if (!routes.length && !explicit.some((scope) => scope.componentSets.length)) return explicit;
+  const surfaces = await catalog();
+  assertKnownSets(surfaces, explicit);
+  return routes.length ? mergeScopes(explicit, scopesFromRoutes(surfaces, routes)) : explicit;
 }
 
 const stateFile = (machine) => join(dirname(configPath()), `coordinator-${encodeURIComponent(machine)}.json`);
@@ -273,6 +286,7 @@ export async function launchLaneCommand(key, flags, {
   head = primaryHead,
   launcher = defaultLaunchRuntime,
   figmaSeat = verifyFigmaSeat,
+  catalog = loadDsCatalog,
   laneConfig = loadJson,
   identityPath = laneConfigPath,
 } = {}) {
@@ -294,7 +308,7 @@ export async function launchLaneCommand(key, flags, {
   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 scopes = await launchFigmaScopes(flags, { catalog });
   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);
@@ -356,7 +370,11 @@ export async function launchLaneCommand(key, flags, {
     }
     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}` };
+  const figmaLines = body.figmaScopes.map((scope) => `Figma scope: ${scope.fileKey} ${scope.componentSets.length ? `component sets ${scope.componentSets.join(", ")}` : "(whole file)"}`);
+  return {
+    payload: { ...payload, figmaScopes: body.figmaScopes },
+    human: [`Launched ${key}: ${payload.data.brief}`, ...(figmaLines.length ? figmaLines : ["Figma scope: none declared"])].join("\n"),
+  };
 }
 
 export async function amendLaneCommand(key, flags, { request = devRequest } = {}) {
@@ -394,6 +412,9 @@ 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 });
 }
 
+// Gather's human output is a renderer of its payload; Delta gather prints the
+// Clause map too, never only "Gather complete.".
+
 const runGather = (key, flags, { request, signal }) => laneCommand("gather", [key], flags, { request, gatherSignal: signal });
 
 // Gather's human text is its Clause map (a function of the payload).

package/dist/tune.js

@@ -345,7 +345,7 @@ export async function tuneCommand(action, args, flags, { request = devRequest, p
       } catch (error) {
         // A Gemma picker this Mac cannot run is reported, not filled in; any
         // other failure is a real error and stops the run.
-        if (!(error instanceof CliError) || !["PICKER_UNAVAILABLE", "PICKER_MODEL_MISSING", "PICKER_MODEL_VERSION_MISMATCH", "OLLAMA_URL_INVALID"].includes(error.code)) throw error;
+        if (!(error instanceof CliError) || !["PICKER_UNAVAILABLE", "PICKER_TIMEOUT", "PICKER_MODEL_MISSING", "PICKER_MODEL_VERSION_MISMATCH", "OLLAMA_URL_INVALID"].includes(error.code)) throw error;
         Object.assign(result, { status: "unavailable", code: error.code, reason: error.message });
       }
     }

package/dist/upload.js

@@ -317,6 +317,15 @@ export async function rulesCommand(action, args, flags, { request = devRequest }
     const payload = await request("GET", `/api/v1/rules/find${query({ question, limit })}`);
     return { payload, human: rulesFindText };
   }
+  if (action === "show") {
+    const id = args[0]?.trim();
+    if (!id) throw new CliError("USAGE", "rules show needs a clause id, for example: nodii-dev rules show S04-7", 2);
+    const payload = await request("GET", `/api/v1/rules/clauses/${encode(id)}`);
+    return {
+      payload,
+      human: (p) => p.data.map((c) => `${c.clauseId}${c.counterInstinct ? " ⚑" : ""} · ${c.documentCode}@${c.documentVersion} › ${c.section}\n${c.text}`).join("\n\n"),
+    };
+  }
   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");
@@ -347,5 +356,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 find "QUESTION" [--limit N] | rules core | rules report [--section rulebook|services|all] [--lane KEY] | rules cap TOKENS', 2);
+  throw new CliError("USAGE", 'rules find "QUESTION" [--limit N] | rules show CLAUSE_ID | 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.33",
+  "version": "0.6.35",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {