@nodii/dev 0.6.32 → 0.6.34

package/README.md

@@ -807,6 +807,23 @@ The launched process uses the already-provisioned lowercase identity (for
 example `~/.config/nodii-dev/agents/lane-ah-12.json`), never the coordinator's
 Dev identity.
 
+A lane's Figma scope is held by published key only (MW8-20): `--figma
+FILE_KEY` for a whole file, or `--figma FILE_KEY=COMPONENT_SET_KEY[,KEY]` for
+its component sets. A node id is refused. `--route /app/...` (repeatable)
+derives the scope from the DS catalog (`https://design.nodii.co/registry.json`,
+or `NODII_DEV_DS_REGISTRY_URL`): the route's Surfaces (page, dialogs, tabs),
+each one's published `componentSetKey`, and its file. A route with no Surface
+is `FIGMA_ROUTE_UNMAPPED` (a DS catalog fix), and a Surface whose key is not
+published yet is `FIGMA_KEY_UNPUBLISHED`. The scope becomes the Freeze's Figma
+boundaries. Gather sends the DS components those Surfaces are built from, so
+their guidelines and U-docs apply, and pins one `figma-guidelines` lookup.
+An explicit set key must be a published Surface in that file
+(`FIGMA_KEY_UNKNOWN`). `figma lock`, `figma scope add|set` and the Figma
+pre-write hook refuse a file, page, section or set outside the scope with
+`FIGMA_OUTSIDE_LANE_SCOPE` (the hook exits 2). A lane that declared no Figma
+scope is not bounded; a Freeze with `figma: []` means "no Figma" and refuses
+every Figma lock and write.
+
 Objective, scope and rule changes are durable `lane amend` records, never chat
 messages. Every CLI call from a launched worktree checks the current watched
 run's acknowledgement version. A pending change is printed and blocks the

package/dist/cli.js

@@ -20,7 +20,7 @@ import {
   refuseFromLane,
   revokeOAuth,
 } from "./oauth.js";
-import { heartbeatCurrentLane, postHook, postHookFailure, preHook, sessionStartContext, settingsSnippet, workflowSuggestion } from "./hooks.js";
+import { FIGMA_HOOK_DENIALS, heartbeatCurrentLane, postHook, postHookFailure, preHook, sessionStartContext, settingsSnippet, workflowSuggestion } from "./hooks.js";
 import { setupCommand } from "./setup.js";
 import { harnessCommand } from "./harness.js";
 import { hookRuntime, recordHookFire, safetyContext, safetyPostHook, safetyPreHook } from "./safety.js";
@@ -53,6 +53,7 @@ import {
 } from "./figma.js";
 export { figmaLock, submitMode } from "./figma.js";
 import { tuneCommand } from "./tune.js";
+import { TUNING_MODELS, measurePickerLatency } from "./gather.js";
 import { docsCommand, rulebookCommand, rulesCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import { designCheck, designCheckText, designRoles, designRolesText } from "./design.js";
@@ -165,19 +166,27 @@ Usage: nodii-dev <command> [options] [--json]
   gather tune trial <run-id> --case ID --picker P --iteration N [--documents A,B]
                                         # one trial; lane-agent passes its own --documents pick
   gather tune finalize <run-id>         # Dev scores the full 5-picker x 5-repeat matrix
+  gather picker-latency [--picker gemma-12b|gemma-e4b|gemma-26b]
+                                        # cold (model unloaded first) and warm pick latency, for the tuning record
 
   coordinator start --machine NAME       # register this machine's one watched coordinator; refuses a live second
   lane launch <key> --done-check TEXT --kind KIND --side SIDE
               --issue KEY --repo NAME=/SOURCE --branch NAME=BRANCH [--repo ... --branch ...]
               --machine NAME --runtime claude|codex --profile PATH --model MODEL --subagents N
               [--base NAME=REF] [--worktree NAME=PATH] [--owned-path NAME=PATH]
-              [--figma FILE[=COMPONENT_SET[,SET]]] [--notes TEXT]
+              [--route /app/... ...] [--figma FILE_KEY[=COMPONENT_SET_KEY[,KEY]]] [--notes TEXT]
               [--narrowing-note TEXT --narrowing-remainder DESTINATION]
                                         # authoritative preflight, one worktree per repo, watched launch
                                         # uses the provisioned agents/lane-<key>.json Dev identity
+                                        # Figma scope by published key: --route derives it from the
+                                        # DS catalog (route -> Surfaces -> componentSetKey -> file)
   lane amend <key> --objective|--scope|--rules TEXT --reason TEXT
   lane gather [<key>] [--delta] [--objective TEXT] [--done-check TEXT] [--components a,b] [--paths a,b]
                                         # infers a launched worktree; explicit contract inputs support manual lane start
+  lane gather [<key>] --picker agent [--shortlist ID --documents CODE[,CODE]]
+                                        # the lane agent picks instead of local Gemma: alone it prints the
+                                        # recorded trigger shortlist; with --shortlist/--documents it records
+                                        # the pick (picker: agent) and the Clause map
   run [--kind build|test_run|subagent|deploy] [--name TEXT] -- <command> [args...]
                                         # watched command: registers with NODII_DEV_RUN_ID,
                                         # heartbeats, and records exit code + redacted log tail
@@ -185,6 +194,8 @@ Usage: nodii-dev <command> [options] [--json]
   lane start <key> --title TEXT --kind KIND --side SIDE [--repo REPO] [--issue ISSUE]
   lane step <key> --side SIDE --start|--done|--block <step> [--reason TEXT]
                                         # --block --reason on a blocked step records its new reason
+  lane step <key> --side SIDE --not-applicable gather --reason-code pre_harness_lane [--note TEXT]
+                                        # coordinator only: Gather never applied (pre-Gather lane); never "done"
   lane evidence <key> --pr|--commit|--figma|--deploy|--dev-check REF
   lane subagent-quota <key> <n>          # coordinator assigns 0-100 subagent slots
   lane heartbeat|resume|land|verify|prioritize|deprioritize|stop <key>
@@ -578,6 +589,14 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "docs") return emitCommand(await docsCommand(action, rest, f));
   if (command === "rulebook" && ["list", "show", "diff"].includes(action)) return emitCommand(await rulebookCommand(action, rest, f));
   if (command === "rules") return emitCommand(await rulesCommand(action, rest, f));
+  if (command === "gather" && action === "picker-latency") {
+    const name = f.picker ?? "gemma-12b";
+    const model = Object.hasOwn(TUNING_MODELS, name) ? TUNING_MODELS[name] : null;
+    if (!model) throw new CliError("USAGE", `gather picker-latency [--picker ${Object.keys(TUNING_MODELS).join("|")}]`, 2);
+    const result = await measurePickerLatency({ model });
+    const line = (label, x) => `${label} ${x.wallMs} ms (Ollama total ${x.totalMs ?? "?"} ms, model load ${x.loadMs ?? "?"} ms)`;
+    return emit(result, json, (r) => `${r.model}\n${line("cold", r.cold)}\n${line("warm", r.warm)}`);
+  }
   if (command === "gather" && action === "tune") {
     const result = await tuneCommand(rest[0], rest.slice(1), f);
     emit(result.payload, json, result.human);
@@ -609,6 +628,8 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "lane" && action === "amend") return emitCommand(await amendLaneCommand(rest[0], f));
   if (command === "lane" && action === "gather") {
     const result = await gatherLaneCommand(rest[0], f);
+    // An agent picker's shortlist step records nothing yet.
+    if (result.payload?.data?.recorded === false) return emitCommand(result);
     // What a gather covered is the lane's gathered set for the nudge hooks.
     const asked = (value) => (typeof value === "string" ? value.split(",").map((item) => item.trim()).filter(Boolean) : []);
     await (async () => recordGathered(process.cwd(), { guidelines: asked(f.components), deltaGathered: f.delta ? (f.paths ? asked(f.paths) : await changedPaths(process.cwd())) : [] }))().catch(() => {});
@@ -910,7 +931,7 @@ export async function main(argv = process.argv.slice(2)) {
       } catch (error) {
         // A known policy denial still blocks. Hook/runtime failures fail open
         // and stay silent so a broken environment cannot stop the session.
-        if (!["FIGMA_FILE_KEY_MISSING", "FIGMA_LOCK_DENIED"].includes(error?.code)) return;
+        if (!FIGMA_HOOK_DENIALS.includes(error?.code)) return;
         if (payload && hookRuntime(payload) === "codex") {
           console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: `Blocked Figma write: ${error?.message ?? String(error)}` } }));
           return;

package/dist/core.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 
-export const VERSION = "0.6.32";
+export const VERSION = "0.6.34";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");

package/dist/figma-scope.js

@@ -0,0 +1,205 @@
+// A lane's Figma scope (AGENT-HARNESS-19, operator 30 Oct): Figma files and
+// component sets by PUBLISHED key (MW8-20), never by node id. Launch derives it
+// from the DS catalog (route → Surfaces → componentSetKey → file); Gather turns
+// it into the DS components whose guidelines apply; the hooks refuse Figma
+// locks and writes outside it.
+import { CliError, devRequest } from "./core.js";
+import { currentLane } from "./freeze.js";
+
+/** The DS catalog as the design site publishes it (`build:public-assets`). */
+export const DS_REGISTRY_URL = "https://design.nodii.co/registry.json";
+export const DS_REGISTRY_TIMEOUT_MS = 20_000;
+export const FIGMA_FILE_KEY = /^[A-Za-z0-9]{10,64}$/;
+export const COMPONENT_SET_KEY = /^[0-9a-f]{40}$/;
+const NODE_ID = /^I?\d+[:-]\d+/;
+
+const notAKey = (value, what) =>
+  new CliError(
+    "FIGMA_SCOPE_INVALID",
+    NODE_ID.test(value)
+      ? `${value} is a node id; a lane's Figma scope names ${what} by published key, never by node id (MW8-20).`
+      : `${value} is not ${what === "a file" ? "a Figma file key" : "a published component-set key (40 hex characters)"}.`,
+    2,
+  );
+
+export function checkFileKey(value) {
+  const key = String(value ?? "").trim();
+  if (!FIGMA_FILE_KEY.test(key)) throw notAKey(key, "a file");
+  return key;
+}
+
+export function checkComponentSetKey(value) {
+  const key = String(value ?? "").trim();
+  if (!COMPONENT_SET_KEY.test(key)) throw notAKey(key, "a component set");
+  return key;
+}
+
+/** Union per file; an empty set list means the whole file and wins. */
+export function mergeScopes(...lists) {
+  const files = new Map();
+  for (const scope of lists.flat()) {
+    const current = files.get(scope.fileKey);
+    if (!current) files.set(scope.fileKey, { fileKey: scope.fileKey, componentSets: [...scope.componentSets] });
+    else if (!current.componentSets.length || !scope.componentSets.length) current.componentSets = [];
+    else current.componentSets = [...new Set([...current.componentSets, ...scope.componentSets])];
+  }
+  return [...files.values()];
+}
+
+const componentName = (dependency) => /\/r\/components\/([a-z0-9-]+)\.json$/.exec(String(dependency))?.[1] ?? null;
+
+/** The product-page Surfaces in the DS registry, with what scope checks need. */
+export function surfacesFrom(registry) {
+  const items = Array.isArray(registry?.items) ? registry.items : null;
+  if (!items) throw new CliError("DS_CATALOG_INVALID", "The DS registry has no items list.", 1);
+  return items
+    .filter((item) => item?.meta?.productPage && item?.meta?.figma)
+    .map((item) => {
+      const figma = item.meta.figma;
+      return {
+        name: item.name,
+        route: item.meta.productPage.frontendRoute ?? null,
+        surfaceType: item.meta.productPage.kind ?? null,
+        fileKey: figma.fileKey,
+        componentSetKey: figma.componentSetKey ?? null,
+        pendingKey: figma.pendingKey ?? null,
+        nodeIds: [figma.nodeId ?? item.figmaNodeId, ...Object.values(figma.states ?? {})].filter(Boolean),
+        components: [...new Set((item.registryDependencies ?? []).map(componentName).filter(Boolean))],
+      };
+    });
+}
+
+let cached;
+/** Fetch the DS catalog once per process. */
+export async function loadDsCatalog({ fetchImpl = fetch, url = process.env.NODII_DEV_DS_REGISTRY_URL ?? DS_REGISTRY_URL, timeoutMs = DS_REGISTRY_TIMEOUT_MS, signal } = {}) {
+  if (cached?.url === url) return cached.surfaces;
+  let response;
+  try {
+    // A caller's signal (Gather's deadline) bounds the read; otherwise our own.
+    response = await fetchImpl(url, { headers: { accept: "application/json" }, signal: signal ?? AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    throw new CliError("DS_CATALOG_UNAVAILABLE", `Could not read the DS catalog at ${url}: ${error.message}`, 1);
+  }
+  if (!response.ok) throw new CliError("DS_CATALOG_UNAVAILABLE", `The DS catalog at ${url} returned HTTP ${response.status}.`, 1);
+  let registry;
+  try { registry = await response.json(); }
+  catch { throw new CliError("DS_CATALOG_INVALID", `The DS catalog at ${url} is not JSON.`, 1); }
+  const surfaces = surfacesFrom(registry);
+  cached = { url, surfaces };
+  return surfaces;
+}
+export const clearDsCatalogCache = () => { cached = undefined; };
+
+/** route → Surfaces → published componentSetKey → file (rules-AB E5). */
+const routeKey = (route) => (route.length > 1 ? route.replace(/\/+$/, "") : route);
+
+export function scopesFromRoutes(surfaces, routes) {
+  const scopes = [];
+  for (const route of routes) {
+    const matched = surfaces.filter((surface) => surface.route && routeKey(surface.route) === routeKey(route));
+    if (!matched.length) {
+      const near = surfaces.filter((surface) => surface.route?.startsWith(`${routeKey(route)}/`)).map((surface) => surface.route);
+      throw new CliError("FIGMA_ROUTE_UNMAPPED", `No DS catalog Surface has frontendRoute ${route}.${near.length ? ` Under it: ${[...new Set(near)].slice(0, 5).join(", ")} (single-quote routes with $params).` : ""} A missing mapping is a DS catalog fix in a DS lane, never a launch workaround.`, 1);
+    }
+    for (const surface of matched) {
+      if (!COMPONENT_SET_KEY.test(surface.componentSetKey ?? "")) {
+        const pending = surface.pendingKey ? ` (pending ${surface.pendingKey.changeSetId}, ${surface.pendingKey.followUpIssue})` : "";
+        throw new CliError("FIGMA_KEY_UNPUBLISHED", `${surface.name} (${route}) has no published componentSetKey yet${pending}. Publish the set first, or scope the lane to its file with --figma ${surface.fileKey}.`, 1);
+      }
+      scopes.push({ fileKey: checkFileKey(surface.fileKey), componentSets: [surface.componentSetKey] });
+    }
+  }
+  return mergeScopes(scopes);
+}
+
+/** An explicit set key must be a published Surface in that file, or no lock could ever be checked. */
+export function assertKnownSets(surfaces, scopes) {
+  for (const scope of scopes)
+    for (const key of scope.componentSets) {
+      const surface = surfaces.find((item) => item.componentSetKey === key);
+      if (!surface)
+        throw new CliError("FIGMA_KEY_UNKNOWN", `${key} is not a published component-set key in the DS catalog. Scope the lane to the whole file (--figma ${scope.fileKey}) or derive it with --route.`, 1);
+      if (surface.fileKey !== scope.fileKey)
+        throw new CliError("FIGMA_KEY_UNKNOWN", `${key} (${surface.name}) is in file ${surface.fileKey}, not ${scope.fileKey}.`, 1);
+    }
+  return scopes;
+}
+
+/**
+ * The lane's Figma boundaries: its Freeze's `figma` once stored, else its
+ * launch scope. null = the lane declared no Figma scope, so nothing is bounded
+ * (lanes from before scopes existed); [] = declared "no Figma", so every Figma
+ * lock and write is refused.
+ */
+export function laneFigmaScope(lane) {
+  const stored = lane?.freeze?.boundaries?.figma;
+  if (Array.isArray(stored))
+    return stored.map((file) => ({ fileKey: file.fileKey, componentSets: file.componentSetKeys ?? [] }));
+  const launch = lane?.launch?.figmaScopes;
+  if (!Array.isArray(launch) || !launch.length) return null;
+  try {
+    return launch.map((file) => ({ fileKey: checkFileKey(file.fileKey), componentSets: (file.componentSets ?? []).map(checkComponentSetKey) }));
+  } catch (error) {
+    const fix = lane?.freeze
+      ? `Set the published keys with ${SWAP_BOUNDARIES(lane.key)}.`
+      : `Run \`nodii-dev lane gather\` (it stores the Freeze with no Figma scope), then set the published keys with ${SWAP_BOUNDARIES(lane.key)}.`;
+    throw Object.assign(new CliError("FIGMA_SCOPE_INVALID", `Lane ${lane.key ?? ""} was launched with a Figma scope that is not published keys: ${error.message.replace(/\.$/, "")}. ${fix}`, 1), { reason: error.message });
+  }
+}
+
+/** The DS components (guideline keys) and Surfaces a scope covers. */
+export function componentsForScope(surfaces, scope) {
+  const keys = new Set(scope.flatMap((file) => file.componentSets));
+  const files = new Set(scope.filter((file) => !file.componentSets.length).map((file) => file.fileKey));
+  const covered = surfaces.filter((surface) => keys.has(surface.componentSetKey));
+  const known = new Set(covered.map((surface) => surface.componentSetKey));
+  return {
+    surfaces: covered.map((surface) => surface.name),
+    components: [...new Set(covered.flatMap((surface) => surface.components))].sort(),
+    unknownKeys: [...keys].filter((key) => !known.has(key)),
+    wholeFiles: [...files],
+  };
+}
+
+/** The Freeze lookup that sends the agent to each in-scope component's guideline. */
+export function guidelineLookup(components) {
+  if (!components.length) return null;
+  return {
+    id: "figma-guidelines",
+    instruction: `Before editing a DS component in this lane's Figma scope, run \`nodii-dev design guideline show <key>\` for it: ${components.join(", ")}.`,
+  };
+}
+
+export const SWAP_BOUNDARIES = (key = "<key>") => `\`nodii-dev lane freeze swap ${key} --section boundaries --file BOUNDARIES.json --reason TEXT\` (the whole section: repos plus figma: [{fileKey, componentSetKeys}]; start from \`nodii-dev lane freeze show ${key}\`)`;
+
+const outside = (message, details) => new CliError("FIGMA_OUTSIDE_LANE_SCOPE", `${message} Change the scope only with ${SWAP_BOUNDARIES()}, or ask the coordinator to amend the lane.`, 2, details);
+
+/**
+ * Refuse a Figma lock (lockScopes = the scopes asked for; [] = whole file) or a
+ * write (lockScopes = null) outside the lane's scope. `scope` null = the lane
+ * declared none, so nothing is bounded here.
+ */
+export async function assertWithinLaneScope(scope, fileKey, lockScopes, { catalog = loadDsCatalog } = {}) {
+  if (scope === null) return { checked: false };
+  const file = scope.find((item) => item.fileKey === fileKey);
+  if (!file)
+    throw outside(`${fileKey} is outside this lane's Figma scope (${scope.length ? scope.map((item) => item.fileKey).join(", ") : "no Figma files"}).`, { fileKey, scope });
+  if (lockScopes === null || !file.componentSets.length) return { checked: true, fileKey };
+  const wide = lockScopes.length ? lockScopes.filter((item) => item.kind !== "component") : [{ kind: "file" }];
+  if (wide.length)
+    throw outside(`This lane may lock only its component sets in ${fileKey}, not ${wide.map((item) => item.kind).join(", ")}.`, { fileKey, scope: file });
+  const allowed = new Set((await catalog()).filter((surface) => file.componentSets.includes(surface.componentSetKey)).flatMap((surface) => surface.nodeIds));
+  const stray = lockScopes.filter((item) => !allowed.has(item.nodeId));
+  if (stray.length)
+    throw outside(`${stray.map((item) => item.nodeId).join(", ")} in ${fileKey} is not one of this lane's component sets (${file.componentSets.join(", ")}).`, { fileKey, scope: file, nodeIds: stray.map((item) => item.nodeId) });
+  return { checked: true, fileKey };
+}
+
+/** The Figma scope of the lane this worktree belongs to; null outside a lane or when it declares none. */
+export async function currentLaneFigmaScope({ cwd = process.cwd() } = {}, deps = {}) {
+  let lane = await currentLane({ cwd }, deps);
+  if (!lane) return null;
+  // A lane found through the list carries no launch record; read its detail.
+  if (!("launch" in lane)) lane = (await (deps.request ?? devRequest)("GET", `/api/v1/lanes/${encodeURIComponent(lane.key)}`)).data ?? lane;
+  return laneFigmaScope(lane);
+}

package/dist/figma.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { setTimeout as delay } from "node:timers/promises";
 import { CliError, devAsyncRequest, devRequest, encode } from "./core.js";
+import { assertWithinLaneScope, currentLaneFigmaScope } from "./figma-scope.js";
 
 /** A Figma file key, or the key inside a figma.com file link (a branch link's branch key). */
 export function figmaFileKey(value) {
@@ -405,8 +406,10 @@ export const holdsSet = (check) => Boolean(check?.changeSetId) && (check.allowed
 
 const isWholeFile = (scopes) => !scopes?.length || scopes.some((s) => s.kind === "file");
 
-export async function figmaLock(value, title, { scopes = [], request = devRequest } = {}) {
+export async function figmaLock(value, title, { scopes = [], request = devRequest, laneScope = currentLaneFigmaScope } = {}) {
   const key = figmaFileKey(value);
+  // The lane's Freeze bounds which files and component sets it may lock.
+  await assertWithinLaneScope(await laneScope({}, { request }), key, scopes);
   const result = await fileCall(key, request)("POST", `/api/v1/design/files/${encode(key)}/lock`, {
     changeSetTitle: title,
     ...(scopes.length ? { scopes } : {}),
@@ -431,8 +434,17 @@ export const figmaLockText = (cs) =>
       : `Holds ${cs.scopes.length} scope(s) in ${cs.fileKey}: ${cs.scopes.map(scopeText).join(", ")}`,
   ].join("\n");
 
-export async function figmaScopeAdd(id, scopes, { request = devRequest } = {}) {
+/** A widened or replaced claim is held to the lane's Figma scope like a new lock. */
+async function assertChangeSetInLaneScope(id, scopes, request, laneScope) {
+  const scope = await laneScope({}, { request });
+  if (scope === null) return;
+  const changeSet = (await request("GET", `/api/v1/design/change-sets/${encode(id)}`)).data;
+  await assertWithinLaneScope(scope, changeSet?.fileKey, scopes);
+}
+
+export async function figmaScopeAdd(id, scopes, { request = devRequest, laneScope = currentLaneFigmaScope } = {}) {
   if (!id || !scopes.length) throw new CliError("USAGE", `figma scope add CHANGE_SET ${SCOPE_USAGE} [--scope ...]`, 2);
+  await assertChangeSetInLaneScope(id, scopes, request, laneScope);
   return changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/scopes`, { scopes });
 }
 
@@ -442,8 +454,9 @@ export async function figmaScopeAdd(id, scopes, { request = devRequest } = {}) {
  * sit inside what the set holds: the whole file holds everything, a page its
  * components and creates.
  */
-export async function figmaScopeSet(id, scopes, { request = devRequest } = {}) {
+export async function figmaScopeSet(id, scopes, { request = devRequest, laneScope = currentLaneFigmaScope } = {}) {
   if (!id || !scopes.length) throw new CliError("USAGE", `figma scope set CHANGE_SET ${SCOPE_USAGE} [--scope ...]`, 2);
+  await assertChangeSetInLaneScope(id, scopes, request, laneScope);
   try {
     return await request("PUT", `/api/v1/design/change-sets/${encode(id)}/scopes`, { scopes });
   } catch (error) {

package/dist/freeze.js

@@ -82,6 +82,8 @@ export function pinnedClausesFromGather(clauses) {
   });
 }
 
+export const GATHER_LOOKUP_IDS = ["figma-guidelines"];
+
 /** Build the six-section stored contract; Delta Gather keeps lane-authored sections. */
 export function freezeFromGather({
   gather,
@@ -89,6 +91,7 @@ export function freezeFromGather({
   issue,
   laneNotes,
   doneCheck,
+  lookups = [],
   current = null,
 }) {
   const effectiveDoneCheck = doneCheck ?? current?.objective?.doneCheck;
@@ -116,7 +119,13 @@ export function freezeFromGather({
     },
     boundaries,
     pinnedClauses: pinnedClausesFromGather(gather.clauses),
-    lookups: current?.lookups ?? [],
+    // Gather owns the lookups it derives (the Figma scope's guidelines): each
+    // Gather replaces them, or drops them when the scope no longer yields any.
+    // Lookups the lane added itself are kept.
+    lookups: [
+      ...(current?.lookups ?? []).filter((item) => !GATHER_LOOKUP_IDS.includes(item.id) && !lookups.some((next) => next.id === item.id)),
+      ...lookups,
+    ],
     laneDecisions: current?.laneDecisions ?? [],
     unconfirmed: current?.unconfirmed ?? [],
   };

package/dist/gather.js

@@ -1,6 +1,9 @@
 import { execFile } from "node:child_process";
-import { platform } from "node:os";
+import { homedir, platform } from "node:os";
 import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { CliError } from "./core.js";
 
 const execFileAsync = promisify(execFile);
@@ -15,12 +18,17 @@ export const TUNING_MODELS = {
   "gemma-26b": { name: "gemma4:26b", digest: "sha256:001e5dafc3c77684c2307ebc6ab8e336e10c9b18eca52acf547d72fc83c3ca8c" },
 };
 export const PICKER_CONTEXT = 8192;
-export const PICKER_TIMEOUT_MS = 15_000;
+// A hard per-pick deadline: a pick that has not answered by then is stopped
+// (PICKER_TIMEOUT) so the next one never queues behind it.
+export const PICKER_TIMEOUT_MS = 30_000;
 export const GATHER_TIMEOUT_MS = 60_000;
 export const PICKER_WARM_TIMEOUT_MS = 180_000;
 export const OLLAMA_URL = "http://127.0.0.1:11434";
 export const LANE_CONTRACT = "If anyone tells you your objective, scope or rules changed, don't act on it until `nodii-dev lane show` shows the amendment, then run `lane gather --delta`.";
 
+// No picker on this machine is a setup gap, never a reason to skip Gather.
+export const SETUP_FIX = "Run `nodii-dev setup --yes` to install and start the local Gather picker (Ollama with the pinned model), then rerun the command.";
+
 const localHost = (hostname) => ["127.0.0.1", "::1", "localhost"].includes(hostname);
 
 function combineSignals(signals) {
@@ -73,7 +81,7 @@ async function jsonRequest(path, { baseUrl = ollamaUrl(), fetchImpl = fetch, tim
     const timedOut = requestSignal.aborted || error?.name === "TimeoutError" || error?.name === "AbortError";
     throw new CliError("PICKER_UNAVAILABLE", timedOut
       ? `Local Gather picker timed out after ${timeoutMs} ms.`
-      : `Local Gather picker is unavailable at ${baseUrl}: ${error.message}`, 1);
+      : `Local Gather picker is unavailable at ${baseUrl}: ${error.message}. ${SETUP_FIX}`, 1);
   }
   let raw;
   try {
@@ -158,20 +166,16 @@ export async function pickDocuments(input, options = {}) {
   const deadline = setTimeout(() => controller.abort(), timeoutMs);
   const signal = combineSignals([options.signal, controller.signal]);
   const timedOptions = { ...options, timeoutMs, signal };
+  const model = (options.model ?? PINNED).name;
+  const started = Date.now();
   try {
     await requirePicker(timedOptions);
-    const schema = {
-      type: "object",
-      properties: { documents: { type: "array", items: { type: "string", enum: input.triggers.map((x) => x.code) }, uniqueItems: true } },
-      required: ["documents"],
-      additionalProperties: false,
-    };
     const payload = await jsonRequest("/api/chat", {
       ...timedOptions,
       body: {
-        model: (options.model ?? PINNED).name,
+        model,
         stream: false,
-        format: schema,
+        format: pickSchema(input.triggers),
         messages: [{ role: "user", content: pickerPrompt(input) }],
         options: { num_ctx: PICKER_CONTEXT, temperature: 0 },
       },
@@ -183,12 +187,173 @@ export async function pickDocuments(input, options = {}) {
     if (!Array.isArray(result.documents) || result.documents.some((x) => typeof x !== "string" || !allowed.has(x)))
       throw new CliError("PICKER_RESPONSE_INVALID", "Local Gather picker returned a document outside the trigger shortlist.", 1);
     const required = input.triggers.filter(forced).map((x) => x.code);
-    return { documents: [...new Set([...result.documents, ...required])], model: (options.model ?? PINNED).name, context: PICKER_CONTEXT };
+    return { documents: [...new Set([...result.documents, ...required])], model, context: PICKER_CONTEXT, latency: pickLatency(payload, Date.now() - started) };
+  } catch (error) {
+    // Our own deadline, not the caller's: stop the stuck pick so nothing queues behind it.
+    if (controller.signal.aborted && !options.signal?.aborted) {
+      // Not awaited: the refusal is immediate; the unload finishes before exit.
+      unloadPicker(model, options).catch(() => {});
+      throw new CliError("PICKER_TIMEOUT", `Local Gather picker ${model} did not answer within ${Math.round(timeoutMs / 1000)} s; the pick was stopped and the model unloaded. Rerun the command.`, 1);
+    }
+    throw error;
   } finally {
     clearTimeout(deadline);
   }
 }
 
+/**
+ * The pick's JSON schema. No `uniqueItems`: it wedges Ollama's grammar
+ * sampler on real Gather prompts (ah-19 sandbox finding, 30 Oct). Duplicates
+ * are removed after the pick; `maxItems` still bounds the list.
+ */
+export function pickSchema(triggers) {
+  const codes = triggers.map((x) => x.code);
+  return {
+    type: "object",
+    properties: { documents: { type: "array", items: { type: "string", enum: codes }, maxItems: new Set(codes).size } },
+    required: ["documents"],
+    additionalProperties: false,
+  };
+}
+
+const ms = (ns) => (typeof ns === "number" ? Math.round(ns / 1e6) : null);
+/** Wall time, plus Ollama's own total and model-load times for the pick. */
+export const pickLatency = (payload, wallMs) => ({ wallMs, totalMs: ms(payload?.total_duration), loadMs: ms(payload?.load_duration) });
+
+/** Unload the model (Ollama keep_alive 0), which also ends a run stuck on it. */
+export async function unloadPicker(model, options = {}) {
+  await jsonRequest("/api/generate", { ...options, signal: undefined, timeoutMs: 5_000, body: { model, keep_alive: 0, stream: false } });
+}
+
+/** Per-user lock directory, under the user's own runtime or cache dir (not shared /tmp). */
+export const pickLockDir = (env = process.env) => env.XDG_RUNTIME_DIR ? join(env.XDG_RUNTIME_DIR, "nodii-dev", "picks") : join(homedir(), ".cache", "nodii-dev", "picks");
+
+async function privateDir(dir) {
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const st = await lstat(dir);
+  if (!st.isDirectory() || (process.getuid && st.uid !== process.getuid()) || (process.platform !== "win32" && (st.mode & 0o077)))
+    throw new CliError("PICKER_LOCK_UNSAFE", `The Gather pick lock directory ${dir} is not a private directory owned by you; remove it and rerun.`, 1);
+}
+
+const NO_HARD_LINKS = new Set(["EPERM", "ENOTSUP", "EXDEV", "ENOSYS", "EOPNOTSUPP"]);
+/** Create the lock whole (hard link of a written token file); exclusive create where links are unsupported. */
+async function createLock(temp, lock, token) {
+  try { await link(temp, lock); }
+  catch (error) {
+    if (!NO_HARD_LINKS.has(error?.code)) throw error;
+    await writeFile(lock, token, { flag: "wx", mode: 0o600 });
+  }
+}
+
+const GUARD_STALE_MS = 5_000;
+/**
+ * Remove a stale lock, one takeover at a time (a guard file serializes them),
+ * judged from a single open handle and unlinked only if the path still holds
+ * that same file. Returns the live holder's pid when the lock is not stale.
+ */
+async function removeIfStale(lock, token, { alive, now, staleMs }) {
+  const guard = `${lock}.takeover`;
+  try { await writeFile(guard, token, { flag: "wx", mode: 0o600 }); }
+  catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    const st = await stat(guard).catch(() => null);
+    if (st && now() - st.mtimeMs > GUARD_STALE_MS) await rm(guard, { force: true });
+    return { retry: true };
+  }
+  try {
+    let handle;
+    try { handle = await open(lock, "r"); }
+    catch (error) { if (error?.code === "ENOENT") return { retry: true }; throw error; }
+    try {
+      const st = await handle.stat();
+      const holder = Number((await handle.readFile("utf8")).split(".")[0]);
+      const fresh = now() - st.mtimeMs < staleMs;
+      if (fresh && (!(Number.isInteger(holder) && holder > 0) || alive(holder))) return { holder: holder || null };
+      const current = await stat(lock).catch(() => null);
+      if (current && current.ino === st.ino && current.dev === st.dev) await rm(lock, { force: true });
+      return { retry: true };
+    } finally {
+      await handle.close();
+    }
+  } finally {
+    if ((await readFile(guard, "utf8").catch(() => null)) === token) await rm(guard, { force: true });
+  }
+}
+
+/**
+ * One in-flight pick per lane, across processes. The lock is created whole,
+ * released only by its owner, and taken over only when stale: its holder is
+ * dead, or it is older than twice the pick deadline (a pick never runs that
+ * long). Takeovers are serialized, so the lock path is never emptied under a
+ * live pick.
+ */
+export async function withPickLock(lane, task, { dir = pickLockDir(), pid = process.pid, alive = processAlive, now = Date.now, staleMs = 2 * PICKER_TIMEOUT_MS, attempts = 40, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  await privateDir(dir);
+  const name = encodeURIComponent(lane);
+  const lock = join(dir, `${name}.lock`);
+  const token = `${pid}.${randomUUID()}`;
+  const temp = join(dir, `.${name}.${token}`);
+  await writeFile(temp, token, { mode: 0o600 });
+  let acquired = false;
+  try {
+    for (let attempt = 0; attempt < attempts && !acquired; attempt += 1) {
+      try {
+        await createLock(temp, lock, token);
+        acquired = true;
+        break;
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+      }
+      const verdict = await removeIfStale(lock, token, { alive, now, staleMs });
+      if (!verdict.retry)
+        throw new CliError("PICKER_BUSY", `A Gather pick for lane ${lane} is already running (pid ${verdict.holder ?? "unknown"}); it ends within ${Math.round(PICKER_TIMEOUT_MS / 1000)} s. Rerun after it finishes (lock: ${lock}).`, 1, { pid: verdict.holder, lock });
+      await sleep(5 + Math.random() * 20);
+    }
+  } finally {
+    await rm(temp, { force: true });
+  }
+  if (!acquired) throw new CliError("PICKER_BUSY", `Could not take the Gather pick lock for lane ${lane} (lock: ${lock}).`, 1, { lock });
+  try {
+    return await task();
+  } finally {
+    if ((await readFile(lock, "utf8").catch(() => null)) === token) await rm(lock, { force: true });
+  }
+}
+
+const processAlive = (pid) => {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code === "EPERM"; }
+};
+
+const LATENCY_PROBE = {
+  objective: "Add a contacts list endpoint with cursor paging.",
+  triggers: [
+    { code: "S10", trigger: "Applies when a change adds or edits an HTTP request handler." },
+    { code: "PII", trigger: "Applies when a change stores, shows or sends a person's name, email or phone." },
+    { code: "U05", trigger: "Applies when a page shows a person." },
+  ],
+};
+
+/** Cold (model unloaded, confirmed gone) and warm pick latency for one pinned picker. */
+export async function measurePickerLatency(options = {}, { pick = pickDocuments, unload = unloadPicker, loaded = modelLoaded, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const model = (options.model ?? PINNED).name;
+  await requirePicker(options);
+  await unload(model, options);
+  for (let i = 0; i < 50 && (await loaded(model, options)); i += 1) await sleep(200);
+  if (await loaded(model, options)) throw new CliError("PICKER_UNAVAILABLE", `${model} did not unload, so a cold pick cannot be measured.`, 1);
+  // A cold load can take tens of seconds; it gets the warm-up deadline, not the pick's.
+  const cold = await pick(LATENCY_PROBE, { ...options, timeoutMs: PICKER_WARM_TIMEOUT_MS });
+  // A different objective, so the warm pick is not a cached-prompt replay.
+  const warm = await pick({ ...LATENCY_PROBE, objective: "Show each contact's owner on the contacts page." }, options);
+  return { model, cold: cold.latency, warm: warm.latency };
+}
+
+/** Whether Ollama currently holds the model in memory (/api/ps). */
+export async function modelLoaded(model, options = {}) {
+  const ps = await jsonRequest("/api/ps", { ...options, signal: undefined });
+  return (ps.models ?? []).some((x) => x?.name === model || x?.model === model);
+}
+
 const tags = (clause) => {
   const repos = clause.repos ?? [];
   const steps = clause.steps ?? [];

package/dist/hooks.js

@@ -1,5 +1,6 @@
 import { CliError, devRequest, readConfig } from "./core.js";
 import { FOUNDATIONS_ID, figmaLockCheck, outOfScopeText } from "./figma.js";
+import { assertWithinLaneScope, currentLaneFigmaScope } from "./figma-scope.js";
 import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
@@ -107,7 +108,11 @@ export function extractNodeIds(value, out = new Set(), { text = false } = {}) {
   return [...out];
 }
 
-export async function preHook(payload, request = devRequest) {
+/** Policy refusals a Figma hook must surface (exit 2); anything else fails open. */
+export const FIGMA_HOOK_DENIALS = ["FIGMA_FILE_KEY_MISSING", "FIGMA_LOCK_DENIED", "FIGMA_OUTSIDE_LANE_SCOPE", "FIGMA_SCOPE_INVALID", "WRITE_OUT_OF_SCOPE"];
+export const isHookDenial = (code) => String(code ?? "").startsWith("SAFETY_") || FIGMA_HOOK_DENIALS.includes(code);
+
+export async function preHook(payload, request = devRequest, laneScope = currentLaneFigmaScope) {
   const name = payload.tool_name ?? "";
   if (!isFigmaTool(name) || isReadTool(name))
     return { allowed: true, ignored: true };
@@ -118,6 +123,16 @@ export async function preHook(payload, request = devRequest) {
       "Blocked Figma write: no fileKey/file_key/Figma URL was found.",
       2,
     );
+  // A write outside the lane's Freeze Figma scope is refused before the lock check.
+  let scope;
+  try {
+    scope = await laneScope({ cwd: payload.cwd ?? process.cwd() }, { request });
+  } catch (error) {
+    // A lane whose stored scope is invalid is refused, never left unbounded.
+    if (error?.code === "FIGMA_SCOPE_INVALID") throw error;
+    throw new CliError("FIGMA_CHECK_FAILED", `Blocked Figma write: ${error.message}`, 2);
+  }
+  await assertWithinLaneScope(scope, fileKey, null);
   const config = (await import("./core.js")).readConfig;
   const { agentId } = await config();
   let response;

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, 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" };
@@ -46,7 +47,65 @@ export async function inferGitContext() {
 }
 
 const laneLine = (x) => `${x.key}\t${x.status}\t${x.kind}/${x.side}\t${x.title}${x.stuck ? "\tSTUCK" : ""}`;
-const detailText = (x) => [laneLine(x), ...(x.steps ?? []).map((s) => `  ${s.side}\t${s.state}\t${s.stepKey}\t${s.label}`)].join("\n");
+// GATHER-NA: a step the coordinator ruled not applicable is never shown as done.
+const stepState = (s) => s.state === "not_applicable" ? `not applicable: ${s.notApplicableReason ?? "(no reason recorded)"}` : s.state;
+const detailText = (x) => [laneLine(x), ...(x.steps ?? []).map((s) => `  ${s.side}\t${stepState(s)}\t${s.stepKey}\t${s.label}`)].join("\n");
+
+/**
+ * GATHER-NA: `--picker agent` makes the lane agent Gather's picker. Without
+ * --shortlist it only shortlists and prints the triggers to pick from; with
+ * --shortlist ID --documents A,B it records that pick against the recorded
+ * shortlist: Dev reuses its objective, paths and components, refuses a pick
+ * it did not offer, and adds its forced triggers. Gather never records a
+ * pick with no shortlist behind it.
+ */
+function agentPickerFlags(flags) {
+  if (flags.picker === undefined) {
+    if (flags.shortlist !== undefined || flags.documents !== undefined)
+      throw new CliError("USAGE", "--shortlist and --documents go with --picker agent.", 2);
+    return null;
+  }
+  if (flags.picker !== "agent")
+    throw new CliError("USAGE", `--picker accepts only agent; without it the local ${PICKER_MODEL} picks.`, 2);
+  const shortlist = typeof flags.shortlist === "string" ? flags.shortlist.trim() : undefined;
+  const documents = typeof flags.documents === "string" ? list(flags.documents) : undefined;
+  if ((flags.shortlist !== undefined && !shortlist) || (flags.documents !== undefined && !documents?.length))
+    throw new CliError("USAGE", "--shortlist needs an id and --documents needs one or more codes.", 2);
+  if (Boolean(shortlist) !== Boolean(documents))
+    throw new CliError("USAGE", "Record an agent pick with both --shortlist ID and --documents CODE[,CODE]; run --picker agent alone first to see the shortlist.", 2);
+  return { shortlist, documents };
+}
+
+// hub-58: the reason is a fixed code (Dev stores its canonical text); a note may add context.
+export const NOT_APPLICABLE_REASON_CODES = ["pre_harness_lane"];
+function notApplicableRuling(flags) {
+  const code = flags["reason-code"];
+  if (!NOT_APPLICABLE_REASON_CODES.includes(code))
+    throw new CliError("USAGE", `--not-applicable needs --reason-code ${NOT_APPLICABLE_REASON_CODES.join("|")}.`, 2);
+  if (flags.note !== undefined && (typeof flags.note !== "string" || !flags.note.trim()))
+    throw new CliError("USAGE", "--note needs non-empty text.", 2);
+  return { reasonCode: code, ...(flags.note !== undefined ? { note: flags.note.trim() } : {}) };
+}
+
+const shellQuote = (value) => `'${String(value).replace(/'/g, "'\\''")}'`;
+// The follow-up repeats the flags that shaped this Gather, so it records the same one.
+const agentFollowUp = (ref, shortlistId, flags) => [
+  `nodii-dev lane gather ${ref} --picker agent --shortlist ${shortlistId} --documents CODE[,CODE]`,
+  ...(flags.delta ? ["--delta"] : []),
+  // --paths/--components are not resent to Dev (it reuses the shortlist's),
+  // but the local gathered set for the nudge hooks reads them.
+  ...["objective", "done-check", "section-limit-per-document", "paths", "components"]
+    .filter((flag) => typeof flags[flag] === "string")
+    .map((flag) => `--${flag} ${shellQuote(flags[flag])}`),
+].join(" ");
+const agentShortlistText = (ref, data, flags) => [
+  `Trigger shortlist ${data.shortlistId} · ${JSON.stringify(data.objective)}`,
+  "You are Gather's picker (picker: agent). Nothing is recorded yet.",
+  ...data.triggers.map((trigger) => `  ${trigger.code}\t${trigger.title ?? ""}: ${trigger.sentence ?? ""}${trigger.forcedBy?.length ? `  [forced by ${trigger.forcedBy.join(", ")}]` : ""}`),
+  "",
+  "Pick every document that applies (forced ones are added for you), then record the pick:",
+  `  ${agentFollowUp(ref, data.shortlistId, flags)}`,
+].join("\n");
 
 function evidence(flags) {
   const selected = ["pr", "commit", "figma", "deploy", "dev-check"].filter((x) => flags[x] !== undefined);
@@ -148,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 })}`);
@@ -183,6 +242,7 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     const deadline = controller ? setTimeout(() => controller.abort(), gatherTimeoutMs) : null;
     const signal = gatherSignal ?? controller.signal;
     try {
+      const byAgent = agentPickerFlags(flags);
       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);
@@ -243,11 +303,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,
@@ -255,9 +333,17 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
         components,
         ...(limit !== undefined ? { limit } : {}),
       };
-      const shortlist = await request("POST", "/api/v1/rules/shortlist", shortlistBody, { signal });
+      // An agent pick records against the shortlist it was made from.
+      const shortlist = byAgent?.shortlist
+        ? { data: { shortlistId: byAgent.shortlist, triggers: [] } }
+        : await request("POST", "/api/v1/rules/shortlist", shortlistBody, { signal });
+      const shortlistId = shortlist.data?.shortlistId;
       const triggers = shortlist.data?.triggers ?? [];
-      const picked = await picker({
+      if (byAgent && !byAgent.shortlist)
+        return { payload: { data: { recorded: false, picker: "agent", shortlistId, objective, triggers } }, human: (p) => agentShortlistText(ref, p.data, flags) };
+      // 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) => ({
@@ -265,19 +351,22 @@ 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,
-        paths,
-        components,
+        // An agent pick answers the shortlist's own paths and components.
+        ...(byAgent ? {} : { paths, components }),
         mode: flags.delta ? "delta" : "full",
         ...(sectionLimit !== undefined ? { sectionLimitPerDocument: sectionLimit } : {}),
+        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,
@@ -287,16 +376,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;
@@ -305,15 +401,24 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     }
   }
   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);
+    const selected = ["start", "done", "block", "not-applicable"].filter((x) => flags[x]);
+    if (selected.length !== 1) throw new CliError("USAGE", "lane step needs exactly one of --start, --done, --block, or --not-applicable.", 2);
     const side = requireFlag(flags, "side");
-    const stepRef = need(flags[selected[0]] === true ? args[1] : flags[selected[0]], "lane step needs <key> --side <side> --start|--done|--block <step>");
+    const stepRef = need(flags[selected[0]] === true ? args[1] : flags[selected[0]], "lane step needs <key> --side <side> --start|--done|--block|--not-applicable <step>");
     const reason = typeof flags.reason === "string" ? flags.reason.trim() : "";
     if (flags.reason !== undefined && (selected[0] !== "block" || !reason)) throw new CliError("USAGE", "--reason TEXT goes with --block.", 2);
+    const ruling = selected[0] === "not-applicable" ? notApplicableRuling(flags) : null;
+    if (!ruling && (flags["reason-code"] !== undefined || flags.note !== undefined)) throw new CliError("USAGE", "--reason-code and --note go with --not-applicable.", 2);
     const lane = (await request("GET", `/api/v1/lanes/${encode(id)}`)).data;
     const step = lane.steps.find((x) => x.side === side && (x.id === stepRef || x.stepKey === stepRef));
     if (!step) throw new CliError("STEP_NOT_FOUND", `No ${side} step ${stepRef} on ${ref}.`, 1);
+    // hub-58: Gather is the only step a coordinator may rule not applicable.
+    if (ruling && step.stepKey !== "gather") throw new CliError("USAGE", "--not-applicable covers only the gather step.", 2);
+    // GATHER-NA: coordinator only; Dev refuses a lane identity (COORDINATOR_REQUIRED).
+    if (ruling) {
+      const payload = await request("POST", `/api/v1/lanes/${encode(id)}/steps/${encode(step.id)}/not-applicable`, { ...ruling, ...via });
+      return { payload, human: (p) => `${ref}: ${side}/${step.stepKey} not applicable: ${p.data.notApplicableReason}${ruling.note ? ` (${ruling.note})` : ""}` };
+    }
     // Dev's blockLaneStep stores no reason and refuses a step that is already
     // blocked (INVALID_STEP_STATE), so the reason is a lane heartbeat note
     // until Dev issue 125 lets the step carry it.

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,8 +412,14 @@ 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).
+const gatheredText = (gathered) => typeof gathered.human === "function" ? gathered.human(gathered.payload) : gathered.human ?? "Gather complete.";
+
 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);
@@ -411,10 +435,13 @@ export async function gatherLaneCommand(key, flags, { request = devRequest, mark
     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.` };
+      if (gathered.payload?.data?.recorded === false) return gathered;
+      return { ...gathered, human: `${gatheredText(gathered)}\nNo pending amendments.` };
     }
     const version = Math.max(...pending.data.map((item) => item.version));
     const gathered = await withSignal(gather(key, flags, { request: timedRequest, signal }), signal);
+    // An agent picker's shortlist step records nothing, so it acknowledges nothing.
+    if (gathered.payload?.data?.recorded === false) return gathered;
     const acknowledgement = await withSignal(acknowledge(key, {
       ...flags,
       deltaContext: { runId: lane.runId, amendmentVersion: version },
@@ -424,7 +451,7 @@ export async function gatherLaneCommand(key, flags, { request = devRequest, mark
       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}.`,
+      human: `${pending.data.map((item) => `v${item.version} ${item.reason}: ${JSON.stringify(item.change)}`).join("\n")}\n${gatheredText(gathered)}\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);

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/package.json

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