@nodii/dev 0.6.30 → 0.6.32

package/README.md

@@ -137,6 +137,12 @@ nodii-dev lane freeze swap KEY --section SECTION [--item ID] --file VALUE.json -
 nodii-dev lane freeze show KEY
 nodii-dev lane freeze history KEY
 nodii-dev rules find "QUESTION" [--limit N]
+nodii-dev gather tune cases|runs
+nodii-dev gather tune replay CASE_ID
+nodii-dev gather tune start --cases all|ID,ID --corpus-ref REF [--trigger T] [--settings JSON]
+nodii-dev gather tune exec RUN_ID [--pickers shortlist-only,gemma-e4b,gemma-12b,gemma-26b]
+nodii-dev gather tune trial RUN_ID --case ID --picker P --iteration N [--documents A,B]
+nodii-dev gather tune finalize RUN_ID
 
 nodii-dev open-questions list|show|answer
 nodii-dev feature-docs list|show|claim|release|status
@@ -313,6 +319,9 @@ nodii-dev hook claude-figma-pre       # reads Claude Code hook JSON on stdin
 nodii-dev hook claude-figma-post      # reads Claude Code hook JSON on stdin
 nodii-dev hook safety-pre             # silent safety decision; blocks with exit 2
 nodii-dev hook safety-post            # silently records resources created by successful commands
+nodii-dev hook nudge-pre              # guideline nudges before a tool call; never blocks
+nodii-dev hook nudge-stop             # guideline nudges when a lane session stops; asks once
+nodii-dev figma checked CS-n --unused-properties --stale-placeholders --dialog-body
 nodii-dev hook print-settings         # prints managed-settings JSON; writes nothing
 
 nodii-dev lane start KEY --title TEXT --kind dev_fix|new_build|docs_change|uat_fix|prod_fix
@@ -429,6 +438,38 @@ deploy. A coordinator's exceptional `--no-verify` also requires
 `NODII_DEV_NO_VERIFY_REASON`; the CLI records the reason in private Git
 metadata. Lanes and subagents can never use `--no-verify`.
 
+### Guideline nudges (AGENT-HARNESS-21)
+
+`harness install` and `harness update` add two more `nodii-dev` hooks for
+Claude Code and Codex. A nudge reminds a lane of a rule at the moment it is
+about to be broken and **says nothing when the rule is met**. Nudges never
+block a tool call, fail open on any error or unknown payload, and stay silent
+in any session that is not a Dev lane. Each cites the clause it protects.
+
+| Moment | Nudge | Silent when |
+|---|---|---|
+| Edit or write | A DS component or product page is used or edited and its guideline is not in the lane's gathered set (U07-19, DEC-0010) | the guideline is in the gathered set, or was read with `design guideline show` |
+| Edit or write | `className` or `style` on a DS component (U07-19) | the tag is not a DS import, or has neither prop |
+| Edit or write | A new migration: journal `when` = max + 1, then a Delta gather. A `_journal.json` write whose `when` values do not rise | the migration is covered by a Delta gather, or already exists |
+| Edit or write | Code renders a person: `PiiText` without `self`, a raw `.email`/`.phone`/`.displayName`, or the page masks a value itself (R5, U05-25) | `PiiText` carries `self`, or no person is rendered |
+| Figma read | A code lane reads by node id (`get_design_context`, `get_metadata`, `get_screenshot`, ...) instead of the published key (MW8-20) | a Figma lane, or no node id |
+| `figma submit CS-n` | The unused-property, stale `Blocked on DS` placeholder and Dialog-without-body hand checks (F-34, CS-2453) | all three are recorded with `figma checked CS-n --unused-properties --stale-placeholders --dialog-body` |
+| AskUserQuestion | The question is also an item in `docs/figma-ux-drive/qa-with-abhi/open.md` (R7) | open.md already holds the question |
+| Stop | The lane is not `on_dev` but "done" was claimed (MW3); an "I couldn't" with no filed issue; Unconfirmed Freeze items still open; uncommitted work | none of those; a Stop that was already nudged once may stop |
+
+The lane's gathered set is the private Git file `nodii-lane-knowledge.json`:
+`lane gather --components a,b` adds the components it covered to `guidelines`,
+`lane gather --delta` adds the paths it saw (`--paths`, else every path this
+worktree changes against origin/main) to `deltaGathered`, and `design guideline
+show` adds to `guidelinesRead`. A part's guideline is its root's (`dialog`
+covers `dialog-content`). Edits are judged against the file they produce, so
+an Edit or `apply_patch` that only changes an attribute is read in full.
+
+The Stop nudge asks the session to continue once (`decision: block`, skipped
+when `stop_hook_active`); Codex passes it through its managed dispatcher. A
+nudge hook skips the amendment guard and the waiting-results banner, since
+either would corrupt its JSON; it cannot run a Delta gather.
+
 ### DS conformance: `design roles` and `design check` (DEC-0034)
 
 Every UI role names exactly one DS component (MW6-14). Resolve your brief's

package/dist/cli.js

@@ -23,7 +23,8 @@ import {
 import { heartbeatCurrentLane, postHook, postHookFailure, preHook, sessionStartContext, settingsSnippet, workflowSuggestion } from "./hooks.js";
 import { setupCommand } from "./setup.js";
 import { harnessCommand } from "./harness.js";
-import { hookRuntime, recordHookFire, safetyPostHook, safetyPreHook } from "./safety.js";
+import { hookRuntime, recordHookFire, safetyContext, safetyPostHook, safetyPreHook } from "./safety.js";
+import { SUBMIT_CHECK_FLAGS, changedPaths, nudgeCandidate, nudgePre, nudgeStop, recordGathered, recordGuidelineRead, recordSubmitChecks } from "./nudges.js";
 import { doctorCommand } from "./doctor.js";
 import { dispatchManagedHook } from "./managed-hooks.js";
 import { freezeCommand } from "./freeze.js";
@@ -51,6 +52,7 @@ import {
   conformanceLines,
 } from "./figma.js";
 export { figmaLock, submitMode } from "./figma.js";
+import { tuneCommand } from "./tune.js";
 import { docsCommand, rulebookCommand, rulesCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import { designCheck, designCheckText, designRoles, designRolesText } from "./design.js";
@@ -126,6 +128,7 @@ Usage: nodii-dev <command> [options] [--json]
   figma published FILE_KEY|CHANGE_SET --figma-version V   # a file key marks every awaiting set published
   figma check|log-write|submit|apply|abandon|release
   figma submit CHANGE_SET --file SUBMIT.json [--sync]
+  figma checked CHANGE_SET --unused-properties --stale-placeholders --dialog-body   # the hand checks the submit nudge asks for
                                         # submit, resubmit and design check --change-set run as a job in Dev
                                         # and poll it (a large set outlasts the edge's timeout); --sync waits
                                         # on one request instead. A 502/504 is checked against the set, never resent
@@ -135,7 +138,7 @@ Usage: nodii-dev <command> [options] [--json]
   figma changeset show CHANGE_SET       # items, variants, round, decision and comment (with the previous round's)
   figma file add FILE_KEY --name TEXT --kind design-system|surfaces|prototype [--module M]
                                         # register a Figma file in Dev so it can be locked
-  hook claude-figma-pre|claude-figma-post|safety-pre|safety-post|session-start|managed-dispatch|print-settings
+  hook claude-figma-pre|claude-figma-post|safety-pre|safety-post|nudge-pre|nudge-stop|session-start|managed-dispatch|print-settings
   setup [--yes|--check]                 # dry-run by default; installs/checks Ollama and pulls the Gather model
   harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--system]
                                         # --system stages managed hooks and only prints operator-reviewed sudo commands
@@ -153,6 +156,15 @@ Usage: nodii-dev <command> [options] [--json]
   rules report [--section S] [--lane KEY]   # delivery totals per document; rules served per lane
   rules find "QUESTION" [--limit N]         # answer an ad-hoc rules question from the indexed sections
   rules cap TOKENS                      # operator: set the core token cap (default 3000)
+  gather tune cases|runs                # Gather tuning (AH-11): frozen cases; runs with per-picker scores
+  gather tune replay <case-id>          # blind replay + trigger shortlist, for the lane-agent picker
+  gather tune start --cases all|ID,ID --corpus-ref REF [--trigger manual] [--settings JSON]
+  gather tune exec <run-id> [--pickers shortlist-only,gemma-e4b,gemma-12b,gemma-26b]
+                                        # runs each automatic picker 5x per case; a Gemma model this Mac
+                                        # lacks is reported unavailable (exit 1), never filled in
+  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
 
   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
@@ -164,7 +176,7 @@ Usage: nodii-dev <command> [options] [--json]
                                         # authoritative preflight, one worktree per repo, watched launch
                                         # uses the provisioned agents/lane-<key>.json Dev identity
   lane amend <key> --objective|--scope|--rules TEXT --reason TEXT
-  lane gather [<key>] [--delta] [--objective TEXT] [--done-check 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
   run [--kind build|test_run|subagent|deploy] [--name TEXT] -- <command> [args...]
                                         # watched command: registers with NODII_DEV_RUN_ID,
@@ -444,7 +456,9 @@ export async function figmaFileAdd(value, flags, { request = devRequest } = {})
 export async function main(argv = process.argv.slice(2)) {
   // Amendment acknowledgement is a lane-wide backstop, including otherwise
   // local commands such as help and version.
-  if (argv[0] !== "__run-supervisor") {
+  // A nudge hook is fail-open and writes only its own JSON: it cannot run a
+  // Delta gather, and a waiting-results banner would corrupt its output.
+  if (argv[0] !== "__run-supervisor" && !(argv[0] === "hook" && argv[1]?.startsWith("nudge-"))) {
     await amendmentGuard(argv);
     await showWaitingResults({ acknowledge: argv[0] !== "hook" });
   }
@@ -564,8 +578,19 @@ 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 === "tune") {
+    const result = await tuneCommand(rest[0], rest.slice(1), f);
+    emit(result.payload, json, result.human);
+    if (result.exitCode) process.exitCode = result.exitCode;
+    return;
+  }
   // Guideline change sets: approving or rejecting one is a person's action in Dev.
-  if (command === "design" && action === "guideline") return emitCommand(await guidelineCommand(rest[0], rest.slice(1), f));
+  if (command === "design" && action === "guideline") {
+    const result = await guidelineCommand(rest[0], rest.slice(1), f);
+    // A guideline read in a lane counts toward the lane's gathered set (nudge hooks).
+    if (rest[0] === "show" && rest[1]) await recordGuidelineRead(process.cwd(), rest[1]).catch(() => {});
+    return emitCommand(result);
+  }
   if (command === "design" && action === "changeset") return emitCommand(await changeSetCommand(rest[0], rest.slice(1), f));
   if (command === "design" && action === "roles") return emit(await designRoles(rest), json, designRolesText);
   if (command === "design" && action === "check") {
@@ -582,7 +607,13 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "coordinator") return emitCommand(await coordinatorCommand(action, f));
   if (command === "lane" && action === "launch") return emitCommand(await launchLaneCommand(rest[0], f));
   if (command === "lane" && action === "amend") return emitCommand(await amendLaneCommand(rest[0], f));
-  if (command === "lane" && action === "gather") return emitCommand(await gatherLaneCommand(rest[0], f));
+  if (command === "lane" && action === "gather") {
+    const result = await gatherLaneCommand(rest[0], f);
+    // 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(() => {});
+    return emitCommand(result);
+  }
   if (command === "lane" && action === "freeze")
     return emitCommand(await freezeCommand(rest[0], rest.slice(1), f));
   if (command === "lane") return emitCommand(await laneCommand(action, rest, f));
@@ -816,6 +847,13 @@ export async function main(argv = process.argv.slice(2)) {
       if (!result.data.allowed) process.exitCode = 3;
       return;
     }
+    if (action === "checked") {
+      const flagged = SUBMIT_CHECK_FLAGS.filter((check) => f[check]);
+      if (!isChangeSetId(rest[0]) || rest.length > 1 || !flagged.length)
+        throw new CliError("USAGE", `figma checked CHANGE_SET ${SUBMIT_CHECK_FLAGS.map((check) => `--${check}`).join(" ")} (at least one)`, 2);
+      await recordSubmitChecks(process.cwd(), rest[0], flagged);
+      return emit({ data: { changeSetId: rest[0], checked: flagged } }, json, `${rest[0]}: recorded ${flagged.join(", ")}.`);
+    }
     if (action === "log-write")
       return emit(await figmaLogWrite(rest[0], requireFlag(f, "tool"), requireFlag(f, "nodes").split(",").filter(Boolean)), json);
     if (["apply", "published", "abandon"].includes(action)) {
@@ -921,6 +959,27 @@ export async function main(argv = process.argv.slice(2)) {
       } catch {}
       return;
     }
+    // Guideline nudges (AGENT-HARNESS-21) never block: any error, a payload
+    // they don't know or a session outside a lane ends in no output.
+    if (action === "nudge-pre") {
+      try {
+        const payload = JSON.parse(await stdinText());
+        await recordHookFire(payload).catch(() => {});
+        if (!(await nudgeCandidate(payload))) return;
+        const nudges = await nudgePre(payload, await safetyContext(payload.cwd ?? process.cwd()));
+        if (nudges.length) console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: nudges.join("\n") } }));
+      } catch {}
+      return;
+    }
+    if (action === "nudge-stop") {
+      try {
+        const payload = JSON.parse(await stdinText());
+        await recordHookFire(payload).catch(() => {});
+        const nudges = await nudgeStop(payload, await safetyContext(payload.cwd ?? process.cwd()));
+        if (nudges.length) console.log(JSON.stringify({ decision: "block", reason: nudges.join("\n") }));
+      } catch {}
+      return;
+    }
     if (action === "lane-heartbeat") {
       const result = await heartbeatCurrentLane();
       return emit(result, json, result.heartbeated ? `Heartbeat recorded for ${result.key}.` : "No current-branch lane; no heartbeat sent.");

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.30";
+export const VERSION = "0.6.32";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");

package/dist/gather.js

@@ -7,9 +7,17 @@ const execFileAsync = promisify(execFile);
 
 export const PICKER_MODEL = "gemma4:12b";
 export const PICKER_MODEL_DIGEST = "sha256:6114515d63c17436a7c0417d82820ac65ad643e2806c5a3c89cb62846436ed0b";
+// E4B and 26B are compared in Gather tuning only; each is pinned the same way
+// (public registry tag + manifest digest) and never pulled by setup.
+export const TUNING_MODELS = {
+  "gemma-e4b": { name: "gemma4:e4b", digest: "sha256:dc35e8d9c6061baa6f0fa870975ab6932e2542b579b13ea0f199fa4bb7300c9c" },
+  "gemma-12b": { name: PICKER_MODEL, digest: PICKER_MODEL_DIGEST },
+  "gemma-26b": { name: "gemma4:26b", digest: "sha256:001e5dafc3c77684c2307ebc6ab8e336e10c9b18eca52acf547d72fc83c3ca8c" },
+};
 export const PICKER_CONTEXT = 8192;
 export const PICKER_TIMEOUT_MS = 15_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`.";
 
@@ -81,20 +89,24 @@ async function jsonRequest(path, { baseUrl = ollamaUrl(), fetchImpl = fetch, tim
   return payload;
 }
 
-const modelMatch = (model) => model?.name === PICKER_MODEL || model?.model === PICKER_MODEL;
+const PINNED = { name: PICKER_MODEL, digest: PICKER_MODEL_DIGEST };
+// Ollama's /api/tags reports the manifest digest as bare hex; the pin carries
+// the registry's `sha256:` form. Compare them without the algorithm prefix.
+const bareDigest = (digest) => typeof digest === "string" ? digest.replace(/^sha256:/, "") : null;
 
 export async function inspectOllama(options = {}) {
+  const pin = options.model ?? PINNED;
   const [version, tags] = await Promise.all([
     jsonRequest("/api/version", options),
     jsonRequest("/api/tags", options),
   ]);
-  const model = (tags.models ?? []).find(modelMatch) ?? null;
+  const model = (tags.models ?? []).find((x) => x?.name === pin.name || x?.model === pin.name) ?? null;
   return {
     available: true,
     version: String(version.version ?? "unknown"),
-    model: PICKER_MODEL,
+    model: pin.name,
     modelInstalled: Boolean(model),
-    modelMatches: model?.digest === PICKER_MODEL_DIGEST,
+    modelMatches: Boolean(model?.digest) && bareDigest(model.digest) === bareDigest(pin.digest),
     digest: model?.digest ?? null,
     size: model?.size ?? null,
     details: model?.details ?? null,
@@ -102,11 +114,24 @@ export async function inspectOllama(options = {}) {
 }
 
 export async function requirePicker(options = {}) {
+  const pin = options.model ?? PINNED;
+  // setup pulls only the 12B Gather default; tuning-only models are pulled by hand.
+  const fix = pin.name === PICKER_MODEL ? "Run `nodii-dev setup --yes`" : `Run \`ollama pull ${pin.name}\``;
   const status = await inspectOllama(options);
   if (!status.modelInstalled)
-    throw new CliError("PICKER_MODEL_MISSING", `Local Gather picker is missing ${PICKER_MODEL}. Run \`nodii-dev setup --yes\` to pull it.`, 1, status);
+    throw new CliError("PICKER_MODEL_MISSING", `Local Gather picker is missing ${pin.name}. ${fix} to pull it.`, 1, status);
   if (!status.modelMatches)
-    throw new CliError("PICKER_MODEL_VERSION_MISMATCH", `Local ${PICKER_MODEL} is ${status.digest ?? "an unknown digest"}; Gather requires ${PICKER_MODEL_DIGEST}. Run \`nodii-dev setup --yes\` to pull and verify the pinned version.`, 1, status);
+    throw new CliError("PICKER_MODEL_VERSION_MISMATCH", `Local ${pin.name} is ${status.digest ?? "an unknown digest"}; Gather requires ${pin.digest}. ${fix} to pull the pinned version.`, 1, status);
+  return status;
+}
+
+/**
+ * Load a pinned model before timed picks, so a cold load (tens of seconds for
+ * the larger tuning models) is not mistaken for a slow or unavailable picker.
+ */
+export async function warmPicker(options = {}) {
+  const status = await requirePicker(options);
+  await jsonRequest("/api/generate", { ...options, timeoutMs: options.timeoutMs ?? PICKER_WARM_TIMEOUT_MS, body: { model: (options.model ?? PINNED).name, prompt: "", stream: false } });
   return status;
 }
 
@@ -144,7 +169,7 @@ export async function pickDocuments(input, options = {}) {
     const payload = await jsonRequest("/api/chat", {
       ...timedOptions,
       body: {
-        model: PICKER_MODEL,
+        model: (options.model ?? PINNED).name,
         stream: false,
         format: schema,
         messages: [{ role: "user", content: pickerPrompt(input) }],
@@ -158,7 +183,7 @@ 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: PICKER_MODEL, context: PICKER_CONTEXT };
+    return { documents: [...new Set([...result.documents, ...required])], model: (options.model ?? PINNED).name, context: PICKER_CONTEXT };
   } finally {
     clearTimeout(deadline);
   }

package/dist/harness.js

@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { CliError, devRequest, query } from "./core.js";
 import { managedHookBundle, nodiiCommandArgs, writeManagedHookBundle } from "./managed-hooks.js";
+import { nudgeSettingsSnippet } from "./nudges.js";
 import { codexSafetyHooksSnippet, regroundingHooksSnippet, safetySettingsSnippet } from "./safety.js";
 
 /** What this CLI wrote, per path: { mode, sha256 }, or for merge-json the hook entries it `added`. */
@@ -198,6 +199,7 @@ export function withSafetyHooks(harness) {
   const parsed = JSON.parse(settings.content);
   let hooks = addHookEntries(parsed.hooks, safetySettingsSnippet().hooks);
   hooks = addHookEntries(hooks, regroundingHooksSnippet().hooks);
+  hooks = addHookEntries(hooks, nudgeSettingsSnippet().hooks);
   assertNodiiHooks(hooks, ".claude/settings.json");
   settings.content = JSON.stringify({ ...parsed, hooks });
   settings.sha256 = sha(settings.content);

package/dist/managed-hooks.js

@@ -135,7 +135,12 @@ export async function dispatchManagedHook(event, payloadText, deps = {}) {
     }
     const structured = messages.map((message) => message.hookSpecificOutput?.additionalContext).filter(Boolean);
     const plain = successful.map((result) => responseOf(result.stdout) ? "" : result.stdout.trim()).filter(Boolean);
-    if (["Stop", "SubagentStop"].includes(event)) return "{}\n";
+    // A Stop nudge asks the session to continue once; any other Stop output is dropped.
+    if (event === "Stop") {
+      const block = messages.find((message) => message.decision === "block" && typeof message.reason === "string");
+      return block ? `${JSON.stringify({ decision: "block", reason: block.reason })}\n` : "{}\n";
+    }
+    if (event === "SubagentStop") return "{}\n";
     return [...structured, ...plain].join("\n") + ([...structured, ...plain].length ? "\n" : "");
   } catch {
     return emptyResponse(event);

package/dist/nudges.js

@@ -0,0 +1,441 @@
+// Guideline nudge hooks (AGENT-HARNESS-21, agent-harness-design.md "Hooks").
+//
+// A nudge reminds a lane of a rule at the moment it is about to break it, and
+// says nothing when the rule is already met. Nothing here blocks a tool call;
+// the one hard stop in a session (Stop) is asked at most once. Every entry
+// point fails open: an error, an unknown payload or no lane yields no nudge.
+// Each nudge names the clause it protects, so an unused one can be retired.
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { isFigmaTool, isReadTool } from "./hooks.js";
+import { patchPaths } from "./safety.js";
+
+const execFileAsync = promisify(execFile);
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit", "apply_patch"]);
+const SHELL_TOOLS = new Set(["Bash", "shell", "exec_command"]);
+export const LANE_KNOWLEDGE = "nodii-lane-knowledge.json";
+export const SUBMIT_CHECKS = "nodii-submit-checks.json";
+export const SUBMIT_CHECK_FLAGS = ["unused-properties", "stale-placeholders", "dialog-body"];
+const OPEN_MD = "docs/figma-ux-drive/qa-with-abhi/open.md";
+const DS_SOURCE = /["'](@cognion-nucleus\/nodii-(?:design-system|blocks)(?:\/[^"']*)?)["']/;
+const MAX_LISTED = 6;
+
+// A file a nudge cannot read is the same as one that is not there.
+async function optional(path) {
+  try { return await readFile(path, "utf8"); }
+  catch { return null; }
+}
+
+async function git(cwd, ...args) {
+  return (await execFileAsync("git", args, { cwd, encoding: "utf8" })).stdout.trim();
+}
+
+const privatePath = (cwd, name) => git(cwd, "rev-parse", "--path-format=absolute", "--git-path", name);
+
+async function readPrivateJson(cwd, name) {
+  try {
+    const text = await optional(await privatePath(cwd, name));
+    return text ? JSON.parse(text) : {};
+  } catch { return {}; }
+}
+
+async function writePrivateJson(cwd, name, update) {
+  const path = await privatePath(cwd, name);
+  const before = await optional(path).then((text) => (text ? JSON.parse(text) : {})).catch(() => ({}));
+  const next = update(before);
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, path);
+  return next;
+}
+
+/**
+ * What the lane has already read. Gather writes `guidelines` (the lane's
+ * gathered set) and `deltaGathered` (paths a Delta gather covered); reading a
+ * guideline with `design guideline show` adds to `guidelinesRead`.
+ */
+export const laneKnowledge = (cwd) => readPrivateJson(cwd, LANE_KNOWLEDGE);
+
+/** What `lane gather` covered: the components asked for, and on a Delta gather the paths it saw. */
+export const recordGathered = (cwd, { guidelines = [], deltaGathered = [] }) =>
+  writePrivateJson(cwd, LANE_KNOWLEDGE, (state) => ({
+    ...state,
+    guidelines: [...new Set([...(state.guidelines ?? []), ...guidelines])],
+    deltaGathered: [...new Set([...(state.deltaGathered ?? []), ...deltaGathered])],
+  }));
+
+/** The paths this worktree changes against origin/main, committed or not. */
+export async function changedPaths(cwd) {
+  const base = await git(cwd, "merge-base", "origin/main", "HEAD");
+  const lines = [await git(cwd, "diff", "--name-only", base), await git(cwd, "ls-files", "--others", "--exclude-standard", "--full-name")];
+  return [...new Set(lines.join("\n").split("\n").map((line) => line.trim()).filter(Boolean))].slice(0, 5000);
+}
+
+export const recordGuidelineRead = (cwd, key) =>
+  writePrivateJson(cwd, LANE_KNOWLEDGE, (state) => ({ ...state, guidelinesRead: [...new Set([...(state.guidelinesRead ?? []), key])] }));
+
+/** The checks attested for one Figma change set before its submit. */
+export const recordSubmitChecks = (cwd, changeSet, checks) =>
+  writePrivateJson(cwd, SUBMIT_CHECKS, (state) => ({ ...state, [changeSet]: { ...state[changeSet], ...Object.fromEntries(checks.map((check) => [check, new Date().toISOString()])) } }));
+
+// ─── reading the edit ──────────────────────────────────────────────────────
+
+const cleanPath = (path) => String(path).split("\\").join("/").replace(/^\.\//, "");
+
+function editedPaths(payload) {
+  const input = payload.tool_input ?? {};
+  if (payload.tool_name === "apply_patch") return patchPaths(input.command ?? input.input);
+  return [input.file_path, input.path, input.notebook_path].filter((x) => typeof x === "string" && x);
+}
+
+const lf = (text) => String(text).replace(/\r\n/g, "\n");
+const replaceOnce = (text, from, to, all = false) => {
+  if (!from || !text.includes(from)) return null;
+  return all ? text.split(from).join(to) : text.replace(from, () => to);
+};
+
+/** One v4A patch section applied to `text`; a hunk that does not apply adds its new lines at the end. */
+function patchedText(text, section) {
+  let result = text;
+  for (const hunk of section.split(/^@@.*$/m)) {
+    const oldLines = [];
+    const newLines = [];
+    const lines = hunk.split("\n");
+    while (lines.length && lines.at(-1) === "") lines.pop();
+    for (const line of lines) {
+      if (line === "") { oldLines.push(""); newLines.push(""); }
+      else if (line.startsWith("+")) newLines.push(line.slice(1));
+      else if (line.startsWith("-")) oldLines.push(line.slice(1));
+      else if (line.startsWith(" ")) { oldLines.push(line.slice(1)); newLines.push(line.slice(1)); }
+    }
+    if (!oldLines.length && !newLines.length) continue;
+    const next = oldLines.length ? replaceOnce(result, oldLines.join("\n"), newLines.join("\n")) : null;
+    result = next ?? `${result}\n${newLines.join("\n")}`;
+  }
+  return result;
+}
+
+/** Each file the call writes, before and after it, as best the payload shows. */
+async function editedFiles(payload, cwd) {
+  const input = payload.tool_input ?? {};
+  const absolute = (path) => (isAbsolute(path) ? path : resolve(cwd, path));
+  if (payload.tool_name === "apply_patch") {
+    const sections = String(input.command ?? input.input ?? "").split(/^\*\*\* (?=(?:Add|Update|Delete) File: )/m).slice(1);
+    return Promise.all(sections.map(async (section) => {
+      const [head, ...body] = section.split("\n");
+      const [, kind, name] = /^(Add|Update|Delete) File: (.+)$/.exec(head) ?? [];
+      const from = absolute(name?.trim() ?? "");
+      const moved = /^\*\*\* Move to: (.+)$/m.exec(body.join("\n"))?.[1]?.trim();
+      const path = moved ? absolute(moved) : from;
+      const disk = await optional(from);
+      const before = kind === "Add" ? "" : lf(disk ?? "");
+      const text = body.join("\n");
+      const after = kind === "Add" ? text.split("\n").filter((line) => line.startsWith("+")).map((line) => line.slice(1)).join("\n") : patchedText(before, lf(text));
+      return { kind, path, existed: (moved ? await optional(path) : disk) !== null, before, after };
+    })).then((files) => files.filter((file) => file.kind !== "Delete"));
+  }
+  const paths = editedPaths(payload).map(absolute).slice(0, 1);
+  return Promise.all(paths.map(async (path) => {
+    const disk = await optional(path);
+    const before = lf(disk ?? "");
+    let after;
+    if (typeof input.content === "string") after = lf(input.content);
+    else if (typeof input.new_source === "string") after = lf(input.new_source);
+    else if (Array.isArray(input.edits)) after = input.edits.reduce((text, edit) => replaceOnce(text, lf(edit?.old_string ?? ""), lf(edit?.new_string ?? ""), edit?.replace_all) ?? `${text}\n${lf(edit?.new_string ?? "")}`, before);
+    else after = replaceOnce(before, lf(input.old_string ?? ""), lf(input.new_string ?? ""), input.replace_all) ?? `${before}\n${lf(input.new_string ?? "")}`;
+    return { path, existed: disk !== null, before, after };
+  }));
+}
+
+const lineCounts = (text) => {
+  const counts = new Map();
+  for (const line of String(text).split("\n")) counts.set(line.trim(), (counts.get(line.trim()) ?? 0) + 1);
+  return counts;
+};
+/** Lines of `after` that `before` does not have. */
+function changedLines(before, after) {
+  const had = lineCounts(before);
+  return String(after).split("\n").filter((line) => {
+    const key = line.trim();
+    if (!key) return false;
+    if (had.get(key) > 0) { had.set(key, had.get(key) - 1); return false; }
+    return true;
+  });
+}
+
+const kebab = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").toLowerCase();
+
+/** Local name → DS export, for PascalCase components imported from the DS or its blocks. */
+export function dsImports(text) {
+  const out = new Map();
+  for (const match of String(text).matchAll(/import\s+(?!type\b)\{([^}]*)\}\s+from\s+(["'][^"']+["'])/g)) {
+    if (!DS_SOURCE.test(match[2])) continue;
+    for (const part of match[1].split(",")) {
+      const spec = part.trim();
+      if (!spec || /^type\s/.test(spec)) continue;
+      const [imported, local = imported] = spec.split(/\s+as\s+/);
+      if (/^[A-Z]/.test(imported) && !/(?:Props|Variants?|Context)$/.test(imported)) out.set(local.trim(), imported.trim());
+    }
+  }
+  return out;
+}
+
+/**
+ * Every `<Tag …>` opening tag: its name, its source (`raw`), and the attribute
+ * text outside `{…}` and quotes. An expression is skipped by brace depth alone,
+ * so an apostrophe or a regex inside one cannot swallow the rest of the file.
+ */
+export function jsxOpenTags(text) {
+  const tags = [];
+  const source = String(text);
+  for (const match of source.matchAll(/<([A-Z][\w.]*)(?=[\s/>])/g)) {
+    let depth = 0;
+    let quote = null;
+    let attrs = "";
+    let end = source.length;
+    for (let at = match.index + match[0].length; at < source.length; at += 1) {
+      const char = source[at];
+      if (quote) { attrs += char === quote ? char : " "; if (char === quote) quote = null; continue; }
+      if (char === "{") { depth += 1; attrs += " "; continue; }
+      if (char === "}") { depth = Math.max(0, depth - 1); continue; }
+      if (depth > 0) continue;
+      if (char === '"' || char === "'") { quote = char; attrs += char; continue; }
+      if (char === ">") { end = at; break; }
+      attrs += char;
+    }
+    tags.push({ tag: match[1], attrs, raw: source.slice(match.index, end + 1) });
+  }
+  return tags;
+}
+
+/** Opening tags in `after` that `before` does not already have verbatim. */
+function changedTags(before, after) {
+  const had = new Map();
+  for (const { raw } of jsxOpenTags(before)) had.set(raw, (had.get(raw) ?? 0) + 1);
+  return jsxOpenTags(after).filter(({ raw }) => {
+    if (had.get(raw) > 0) { had.set(raw, had.get(raw) - 1); return false; }
+    return true;
+  });
+}
+
+const withoutTags = (text) => jsxOpenTags(text).reduce((out, { raw }) => out.replace(raw, " "), String(text));
+const uiFile = (path) => /\.(?:tsx|jsx)$/.test(path) && !/\.(?:test|spec|stories)\.[jt]sx?$/.test(path);
+
+// ─── the nudges ────────────────────────────────────────────────────────────
+
+// A part's guideline is its root's: `dialog` covers `dialog-content`, but `alert` does not cover `alert-dialog`.
+const PARTS = /^(?:content|header|footer|title|description|trigger|item|items|list|group|label|separator|body|row|cell|head|caption|action|cancel|close|overlay|portal|value|indicator|viewport|sub|text|root)$/;
+const covers = (known, key) => known.some((entry) => key === entry || (key.startsWith(`${entry}-`) && key.slice(entry.length + 1).split("-").every((part) => PARTS.test(part))));
+const listed = (items) => items.slice(0, MAX_LISTED).join(", ") + (items.length > MAX_LISTED ? `, +${items.length - MAX_LISTED} more` : "");
+const PAGE_NOISE = /^(?:index|types?|utils?|constants?|use-.*|.*-(?:types?|utils?|constants?|mocks?|fixtures?|helpers?|hooks?))$/;
+
+/** DS component or product page used or edited without its guideline in the lane's gathered set. */
+export function guidelineNudges({ rel, before, after }, knowledge) {
+  const known = [...(knowledge.guidelines ?? []), ...(knowledge.guidelinesRead ?? [])].map(kebab);
+  const keys = new Set();
+  const component = /(?:^|\/)packages\/design-system\/src\/components\/([a-z0-9-]+)\.tsx$/.exec(rel);
+  if (component) keys.add(component[1]);
+  const page = /(?:^|\/)product-pages\/(?:.*\/)?([a-z0-9-]+?)(?:\.figma)?\.(?:tsx|ts)$/.exec(rel);
+  if (page && page[1].includes("-") && !PAGE_NOISE.test(page[1])) keys.add(page[1]);
+  if (uiFile(rel)) {
+    const imports = dsImports(after);
+    for (const { tag } of changedTags(before, after)) {
+      const root = tag.split(".")[0];
+      if (imports.has(root)) keys.add(kebab(imports.get(root)));
+    }
+  }
+  const missing = [...keys].filter((key) => !covers(known, key));
+  if (!missing.length) return [];
+  return [`nodii-dev nudge: no guideline for ${listed(missing)} in this lane's gathered set. Read it before using or editing it: ${missing.slice(0, 3).map((key) => `\`nodii-dev design guideline show ${key}\``).join(", ")} (U07-19, DEC-0010).`];
+}
+
+/** className or style passed to a DS component (U07-19). */
+export function restyleNudges({ rel, before, after }) {
+  if (!uiFile(rel)) return [];
+  const imports = dsImports(after);
+  const hits = new Set();
+  for (const { tag, attrs } of changedTags(before, after)) {
+    if (!imports.has(tag.split(".")[0])) continue;
+    for (const prop of ["className", "style"]) if (new RegExp(`(?:^|\\s)${prop}\\s*=`).test(attrs)) hits.add(`<${tag} ${prop}>`);
+  }
+  if (!hits.size) return [];
+  return [`nodii-dev nudge: ${listed([...hits])}: a consumer MUST NOT pass className or style to a DS component (U07-19). Set only props, variants, slots and children; a missing capability is a DS gap (U07-20), filed as a DS issue.`];
+}
+
+const PERSON_FIELD = /(?<!\$)\{\s*[\w$.?]+\??\.(?:email|phone|mobile|displayName|fullName|firstName|lastName|personName)\s*\}/;
+const MASKING = /\bmask(?:ed)?(?:Name|Email|Phone|Pii|Person)?\s*\(|\b[A-Za-z]\*{3,}/;
+
+/** Code that renders a person: through PiiText, never masking the viewer (R5, U05-25). */
+export function selfPiiNudges({ rel, before, after }) {
+  if (!uiFile(rel)) return [];
+  const notes = [];
+  for (const { tag, raw } of changedTags(before, after))
+    if (tag === "PiiText" && /\bkind\s*=\s*\{?["']?(?:name|email|phone)/.test(raw) && !/\bself\b/.test(raw))
+      notes.push("PiiText shows a person without `self`: if this can be the viewer pass `self={isSelf}`");
+  if (PERSON_FIELD.test(changedLines(withoutTags(before), withoutTags(after)).join("\n"))) notes.push("a person's name, email or phone is rendered without PiiText");
+  if (MASKING.test(changedLines(before, after).join("\n"))) notes.push("the page masks a value itself (a page never masks or reveals; PiiText does)");
+  if (!notes.length) return [];
+  return [`nodii-dev nudge: ${notes.join("; ")}. Ask: is this the viewer? Self is never masked (R5, D967, U05-25); every other person goes through PiiText.`];
+}
+
+/** `when` values of a Drizzle journal, in file order. */
+const journalWhens = (text) => (JSON.parse(text).entries ?? []).map((entry) => entry.when);
+
+/** A new migration, or a journal edit that breaks the `when` rule. */
+export async function migrationNudges({ path, rel, existed, after }, knowledge) {
+  const notes = [];
+  if (/(?:^|\/)(?:migrations|drizzle)\/(?:.*\/)?[^/]+\.sql$/.test(rel) && !existed) {
+    const covered = (knowledge.deltaGathered ?? []).map((item) => cleanPath(item).replace(/\/$/, ""));
+    if (!covered.some((item) => rel === item || rel.startsWith(`${item}/`))) {
+      let newest = "";
+      try { const whens = journalWhens(await optional(resolve(dirname(path), "meta/_journal.json")) ?? "{}"); if (whens.length) newest = ` (the journal's newest is ${Math.max(...whens)}, so the next \`when\` is ${Math.max(...whens) + 1})`; } catch {}
+      notes.push(`${rel} is a new migration. Its journal entry needs when = max(existing when) + 1${newest} with idx and tag strictly increasing (never drizzle-kit's now()); then run \`nodii-dev lane gather --delta\` (scope drift)`);
+    }
+  }
+  if (/(?:^|\/)meta\/_journal\.json$/.test(rel)) {
+    try {
+      const whens = journalWhens(after);
+      const bad = whens.findIndex((when, at) => at > 0 && !(when > whens[at - 1]));
+      if (bad !== -1) notes.push(`${rel}: journal entry ${bad} has when ${whens[bad]}, not above the one before (${whens[bad - 1]}); Drizzle silently skips a migration whose when is not newer`);
+    } catch {}
+  }
+  return notes.map((note) => `nodii-dev nudge: ${note}.`);
+}
+
+const NODE_ID_TOOLS = /(?:get_design_context|get_metadata|get_screenshot|get_variable_defs|get_motion_context)$/;
+
+/** A code lane reading Figma by node id (MW8-20). */
+export function figmaReadNudges(payload, lane) {
+  const name = payload.tool_name ?? "";
+  if (!isFigmaTool(name) || !isReadTool(name) || !NODE_ID_TOOLS.test(name)) return [];
+  if (/figma|design/i.test(`${lane.kind ?? ""} ${lane.side ?? ""}`)) return [];
+  const input = payload.tool_input ?? {};
+  const byUrl = typeof input.url === "string" && /[?&]node-id=/.test(input.url);
+  if (!(typeof input.nodeId === "string" || typeof input.node_id === "string" || byUrl)) return [];
+  return ["nodii-dev nudge: this code lane reads Figma by node id. Find the surface by its published component-set key (`figma:keys:refresh`), never a node id; a node id is not a stable reference across hops (MW8-20, MW8-17)."];
+}
+
+const SUBMIT_COMMAND = /(?:nodii-dev|@nodii\/dev(?:@\S+)?)\s+figma\s+submit\b([^;&|\n]*)/;
+const CHECKED_COMMAND = /(?:nodii-dev|@nodii\/dev(?:@\S+)?)\s+figma\s+checked\s+(CS-[\w-]+)([^;&|\n]*)/g;
+
+/** `nodii-dev figma submit CS-n`: the hand checks Dev's gate cannot see. */
+export async function submitNudges(command, { cwd }) {
+  const text = String(command ?? "");
+  const submit = SUBMIT_COMMAND.exec(text);
+  const changeSet = /\b(CS-[\w-]+)/.exec(submit?.[1] ?? "")?.[1];
+  if (!changeSet) return [];
+  const done = { ...(await readPrivateJson(cwd, SUBMIT_CHECKS))[changeSet] };
+  // The same command line may record them first: `figma checked CS-n … && figma submit CS-n …`.
+  for (const [, id, flags] of text.matchAll(CHECKED_COMMAND)) if (id === changeSet) for (const check of SUBMIT_CHECK_FLAGS) if (flags.includes(`--${check}`)) done[check] = true;
+  const label = { "unused-properties": "every component property is used (F-34)", "stale-placeholders": 'every "Blocked on DS: <part>" placeholder is re-checked against the published library (CS-2453)', "dialog-body": "a Dialog with no body is an AlertDialog" };
+  const missing = SUBMIT_CHECK_FLAGS.filter((check) => !done[check]);
+  if (!missing.length) return [];
+  return [`nodii-dev nudge: before submitting ${changeSet}, check that ${missing.map((check) => label[check]).join("; ")}. Then record it: \`nodii-dev figma checked ${changeSet} ${missing.map((check) => `--${check}`).join(" ")}\` (DEC-0034 hand check).`];
+}
+
+/** AskUserQuestion: the ask also lives as an item in open.md (R7). */
+export async function askNudges(payload, { root }) {
+  if (payload.tool_name !== "AskUserQuestion") return [];
+  const questions = (payload.tool_input?.questions ?? []).map((item) => String(item?.question ?? "")).filter(Boolean);
+  const openMd = (await optional(resolve(root, OPEN_MD)))?.toLowerCase().replace(/\s+/g, " ");
+  const unrecorded = questions.filter((question) => !openMd?.includes(question.toLowerCase().replace(/\s+/g, " ").slice(0, 60)));
+  if (questions.length && !unrecorded.length) return [];
+  return [`nodii-dev nudge: a question for the operator is also an item in ${OPEN_MD} (R7), with its Q section; chat alone is not where an ask lives. Add it, and say "item #n in open.md" here.`];
+}
+
+const SIGNALS = /@cognion-nucleus|PiiText|\bmask\w*\(|\b[A-Za-z]\*{3,}|\.(?:email|phone|mobile|displayName|fullName|firstName|lastName|personName)\b/;
+
+/** Whether any nudge could apply to this call, so most calls never resolve the lane. */
+export async function nudgeCandidate(payload) {
+  const tool = payload.tool_name ?? "";
+  if (isFigmaTool(tool)) return isReadTool(tool) && NODE_ID_TOOLS.test(tool);
+  if (tool === "AskUserQuestion") return true;
+  if (SHELL_TOOLS.has(tool)) return /\bfigma\s+submit\b/.test(String(payload.tool_input?.command ?? ""));
+  if (!EDIT_TOOLS.has(tool)) return false;
+  const cwd = payload.cwd ?? process.cwd();
+  return (await editedFiles(payload, cwd)).some(({ path, before, after }) => {
+    const p = cleanPath(path);
+    if (/\.sql$|_journal\.json$|product-pages\/|design-system\/src\/components\//.test(p)) return true;
+    if (!uiFile(p)) return false;
+    return SIGNALS.test(changedLines(before, after).join("\n")) || (changedTags(before, after).length > 0 && SIGNALS.test(after));
+  });
+}
+
+/** PreToolUse nudges for one tool call. Returns [] outside a lane. */
+export async function nudgePre(payload, context, { knowledge = laneKnowledge } = {}) {
+  const lane = context?.lane;
+  if (!lane) return [];
+  const tool = payload.tool_name ?? "";
+  const root = context.root;
+  const cwd = payload.cwd ?? context.cwd ?? root;
+  if (isFigmaTool(tool)) return figmaReadNudges(payload, lane);
+  if (tool === "AskUserQuestion") return askNudges(payload, { root });
+  if (SHELL_TOOLS.has(tool)) return submitNudges(payload.tool_input?.command, { cwd });
+  if (!EDIT_TOOLS.has(tool)) return [];
+  const known = await knowledge(cwd);
+  const out = [];
+  for (const file of await editedFiles(payload, cwd)) {
+    const edit = { ...file, rel: cleanPath(relative(root, file.path)) };
+    out.push(...guidelineNudges(edit, known), ...restyleNudges(edit), ...selfPiiNudges(edit), ...(await migrationNudges(edit, known)));
+  }
+  return out;
+}
+
+// ─── Stop ──────────────────────────────────────────────────────────────────
+
+// A claim that the work is finished, judged a sentence at a time so "the docs are not done" cannot hide "it is done".
+const DONE_CLAIM = /\b(?:all|everything|work|lane|task|ticket|issue|build|it|this|that|i'm|we're|i am|we are)\s*(?:is|are|'s|'m|'re)?\s*(?:now\s+)?(?:done|complete[d]?|finished)\b|^\W*(?:done|all done|complete)\b/i;
+const SHOUTED_DONE = /\bDONE\b/;
+const NOT_DONE = /\b(?:not|isn't|aren't|wasn't|never|until|nothing is|n't)\s+(?:yet\s+)?(?:done|complete[d]?|finished)\b|\b(?:unfinished|incomplete)\b/i;
+const claimsDone = (text) => String(text).split(/(?<=[.!?\n])\s+/).some((sentence) => (DONE_CLAIM.test(sentence) || SHOUTED_DONE.test(sentence)) && !NOT_DONE.test(sentence));
+const COULDNT = /\b(?:I|we)\s+(?:couldn't|could not|can't|cannot|was unable to|were unable to|wasn't able to|am unable to)\b/i;
+const FILED = /\b[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)*-\d+\b|\bfiled\b|\bissue\s+#?\d+|\bopen\.md\b/;
+
+/** The last assistant message: the Stop payload's own, else the transcript's final one. */
+export async function lastAssistantText(payload) {
+  if (typeof payload.last_assistant_message === "string") return payload.last_assistant_message;
+  if (!payload.transcript_path) return "";
+  try {
+    const lines = String(await optional(payload.transcript_path) ?? "").trim().split("\n");
+    for (const line of lines.reverse()) {
+      const entry = JSON.parse(line);
+      if ((entry.type ?? entry.message?.role) !== "assistant") continue;
+      const content = entry.message?.content;
+      const text = Array.isArray(content) ? content.filter((part) => part?.type === "text").map((part) => part.text).join("\n") : String(content ?? "");
+      if (text.trim()) return text;
+    }
+  } catch {}
+  return "";
+}
+
+const openUnconfirmed = (lane) => [lane.freeze?.unconfirmed, lane.unconfirmed].flat().filter(Boolean).filter((item) =>
+  typeof item === "string" || !(item?.resolvedAt || item?.confirmedAt || ["resolved", "confirmed", "dropped"].includes(item?.status)));
+
+/** Stop nudges. A lane that has just been nudged once is left to stop (stop_hook_active). */
+export async function nudgeStop(payload, context, { lastText = lastAssistantText, status = (root) => git(root, "status", "--porcelain") } = {}) {
+  const lane = context?.lane;
+  if (!lane || payload.stop_hook_active) return [];
+  const notes = [];
+  const text = await lastText(payload);
+  if (claimsDone(text) && lane.status !== "on_dev")
+    notes.push(`${lane.key} reads ${lane.status}, not on_dev: done means merged, deployed and verified live on dev (MW3). Run \`nodii-dev lane show ${lane.key}\`, and say what is left instead of "done"`);
+  if (COULDNT.test(text) && !FILED.test(text))
+    notes.push('you said you couldn\'t do something and cited no filed issue; file it (`nodii-dev issues create`, or a request or drift entry) so it is not lost');
+  const unconfirmed = openUnconfirmed(lane);
+  if (unconfirmed.length)
+    notes.push(`${unconfirmed.length} Unconfirmed item${unconfirmed.length === 1 ? " is" : "s are"} still open in ${lane.key}'s Freeze; confirm or drop each with a reason (\`nodii-dev lane freeze\`)`);
+  const dirty = (await status(context.root).catch(() => "")).split("\n").filter(Boolean);
+  if (dirty.length)
+    notes.push(`${dirty.length} uncommitted path${dirty.length === 1 ? "" : "s"} in ${context.root}: commit in your worktree (push on commit, so a death loses nothing)`);
+  return notes.map((note) => `nodii-dev nudge: ${note}.`);
+}
+
+export const nudgeSettingsSnippet = () => ({
+  hooks: {
+    PreToolUse: [{ matcher: "^(AskUserQuestion|mcp__(?:figma|claude_ai_Figma|figma-dev-mode)__.*|Bash|Edit|Write|MultiEdit|NotebookEdit)$", hooks: [{ type: "command", command: "nodii-dev hook nudge-pre" }] }],
+    Stop: [{ hooks: [{ type: "command", command: "nodii-dev hook nudge-stop" }] }],
+  },
+});

package/dist/tune.js

@@ -0,0 +1,361 @@
+import { CliError, devRequest, encode, query } from "./core.js";
+import { GATHER_TIMEOUT_MS, TUNING_MODELS, gatherText, pickDocuments, warmPicker } from "./gather.js";
+
+// Dev's tuning matrix (AH-11): every case, every picker, five repeats. Finalize
+// refuses anything short of the full matrix, so a picker that cannot run here is
+// reported unavailable and sends nothing — a missing trial is never faked.
+export const TUNING_PICKERS = ["shortlist-only", "lane-agent", "gemma-e4b", "gemma-12b", "gemma-26b"];
+export const TUNING_REPEATS = 5;
+const AUTOMATIC = TUNING_PICKERS.filter((picker) => picker !== "lane-agent");
+const TRIGGERS = ["setup", "trigger_change", "document_change", "missed_trigger", "manual"];
+const SECTION_LIMIT = 3;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const list = (value) => String(value ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+const bps = (value) => `${(value / 100).toFixed(1)}%`;
+// Dev's rule-report token estimate: ceil(chars / 4).
+const estimateTokens = (text) => Math.ceil(text.length / 4);
+// Dev's clause gist: the first sentence, at most 160 characters.
+const clauseGist = (text) => {
+  const sentence = /^(.+?[.!?])(?:\s|$)/.exec(text)?.[1] ?? text;
+  return sentence.length > 160 ? `${sentence.slice(0, 157)}...` : sentence;
+};
+
+function uuid(value, what) {
+  if (typeof value !== "string" || !UUID.test(value)) throw new CliError("USAGE", `gather tune needs ${what} as a UUID`, 2);
+  return value;
+}
+
+function pickerFlag(value) {
+  if (!TUNING_PICKERS.includes(value)) throw new CliError("USAGE", `--picker must be one of ${TUNING_PICKERS.join(", ")}`, 2);
+  return value;
+}
+
+function iterationFlag(value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > TUNING_REPEATS) throw new CliError("USAGE", `--iteration needs a whole number from 1 to ${TUNING_REPEATS}`, 2);
+  return n;
+}
+
+/** Paths a frozen diff touches, from its `diff --git a/X b/Y` headers (both sides of a rename). */
+export function diffPaths(changes = []) {
+  const paths = new Set();
+  for (const change of changes)
+    for (const match of String(change.diff ?? "").matchAll(/^diff --git a\/(\S+) b\/(\S+)$/gm)) {
+      paths.add(match[1]);
+      paths.add(match[2]);
+    }
+  return [...paths].filter((path) => path.length <= 1000).slice(0, 5000);
+}
+
+/** What a picker sees: the case's objective, touched files and repos (no answer key). */
+export function replayInput(replay) {
+  const objective = [replay.objective?.title, replay.objective?.body].filter((x) => typeof x === "string" && x.trim()).join("\n\n").slice(0, 20_000);
+  if (!objective.trim()) throw new CliError("TUNING_CASE_INVALID", `tuning case ${replay.id} has no objective`, 1);
+  return { objective, paths: diffPaths(replay.changes), repos: replay.repos ?? [] };
+}
+
+/**
+ * The read-only corpus a trial assembles its Clause map from: documents with
+ * their current clauses, service feature documents per repo, and Lane bases.
+ * Cached for one command, because the corpus does not change mid-run.
+ */
+export function tuningCorpus(request) {
+  const documents = new Map();
+  const services = new Map();
+  let bases;
+  let all;
+  const document = (code) => {
+    if (!documents.has(code)) documents.set(code, request("GET", `/api/v1/documents/${encode(code)}`).then((x) => x.data));
+    return documents.get(code);
+  };
+  return {
+    document,
+    async serviceDocuments(repo) {
+      if (!services.has(repo))
+        services.set(repo, request("GET", `/api/v1/documents${query({ section: "services", serviceId: repo, limit: 500 })}`).then((x) => {
+          if ((x.total ?? 0) > 500) throw new CliError("TUNING_CORPUS_TOO_LARGE", `${repo} has ${x.total} feature documents; tuning reads at most 500`, 1);
+          return (x.data ?? []).map((d) => d.code);
+        }));
+      return services.get(repo);
+    },
+    async laneBase(buildType, side) {
+      bases ??= request("GET", "/api/v1/rules/lane-bases").then((x) => x.data ?? []);
+      const sides = side === "both" ? ["backend", "frontend"] : [side];
+      return new Set((await bases).filter((base) => base.buildType === buildType && sides.includes(base.side)).flatMap((base) => base.clauseIds));
+    },
+    async allCodes() {
+      // Lane Gather scans every document for Lane base clauses; page through all of them.
+      all ??= (async () => {
+        const codes = [];
+        for (let offset = 0; ; offset += 500) {
+          const page = await request("GET", `/api/v1/documents${query({ limit: 500, offset })}`);
+          codes.push(...(page.data ?? []).map((d) => d.code));
+          if (!page.data?.length || codes.length >= (page.total ?? codes.length)) return codes;
+        }
+      })();
+      return all;
+    },
+  };
+}
+
+/**
+ * One trial, assembled the way Dev's lane Gather assembles a Clause map
+ * (picked documents + the lane repos' feature documents + Lane base, then a
+ * hybrid section search with three sections per document), but read-only:
+ * nothing is recorded against a lane.
+ */
+export async function runTrial(replay, picker, { request = devRequest, corpus = tuningCorpus(request), pick = pickDocuments, documents: agentDocuments, timeoutMs = GATHER_TIMEOUT_MS } = {}) {
+  const { objective, paths, repos } = replayInput(replay);
+  const controller = new AbortController();
+  const deadline = setTimeout(() => controller.abort(), timeoutMs);
+  const { signal } = controller;
+  // Corpus reads are cached across trials, so they are raced against this
+  // trial's deadline rather than aborted.
+  const within = (promise) => new Promise((resolvePromise, rejectPromise) => {
+    const abort = () => rejectPromise(new Error("aborted"));
+    if (signal.aborted) return abort();
+    signal.addEventListener("abort", abort, { once: true });
+    promise.then(resolvePromise, rejectPromise).finally(() => signal.removeEventListener("abort", abort));
+  });
+  try {
+    const shortlist = await request("POST", "/api/v1/rules/shortlist", { objective, paths, repos, components: [] }, { signal });
+    const triggers = shortlist.data?.triggers ?? [];
+    const codes = triggers.map((trigger) => trigger.code);
+    const forced = triggers.filter((trigger) => trigger.forcedBy?.length).map((trigger) => trigger.code);
+    let picked;
+    if (picker === "shortlist-only") picked = codes;
+    else if (picker === "lane-agent") {
+      if (!agentDocuments?.length) throw new CliError("USAGE", "the lane-agent picker needs --documents CODE[,CODE]: the documents the agent picked from the replay's shortlist", 2);
+      const outside = agentDocuments.filter((code) => !codes.includes(code));
+      if (outside.length) throw new CliError("TUNING_PICK_INVALID", `lane-agent picked documents outside the shortlist: ${outside.join(", ")}`, 2);
+      picked = [...new Set([...agentDocuments, ...forced])];
+    } else {
+      if (!triggers.length) throw new CliError("TUNING_SHORTLIST_EMPTY", `the trigger shortlist for case ${replay.id} is empty`, 1);
+      const result = await pick({
+        objective,
+        files: paths,
+        triggers: triggers.map((trigger) => ({ code: trigger.code, trigger: trigger.sentence, ...(trigger.forcedBy ? { forcedBy: trigger.forcedBy } : {}) })),
+      }, { model: TUNING_MODELS[picker], signal });
+      picked = result.documents;
+    }
+    // An empty pick is recorded as the picker's (zero-recall) result rather than
+    // refused as lane Gather does: the matrix needs every trial, and a picker
+    // that picks nothing is exactly what tuning has to see.
+    const service = (await within(Promise.all(repos.map((repo) => corpus.serviceDocuments(repo))))).flat();
+    const baseIds = await within(corpus.laneBase(replay.buildType, replay.side));
+    let documentCodes = [...new Set([...picked, ...service])];
+    if (baseIds.size) {
+      const withBase = await within(corpus.allCodes().then((codes) => Promise.all(codes.filter((code) => !documentCodes.includes(code)).map(async (code) => ({ code, doc: await corpus.document(code) })))));
+      documentCodes = [...documentCodes, ...withBase.filter(({ doc }) => doc.clauses?.some((clause) => baseIds.has(clause.id))).map(({ code }) => code)];
+    }
+    const sections = [];
+    if (documentCodes.length) {
+      const ranked = await request("POST", "/api/v1/rules/search", {
+        query: [objective, ...paths].join("\n").slice(0, 20_000),
+        documentCodes: documentCodes.slice(0, 500),
+        limit: Math.min(500, documentCodes.length * Math.max(20, SECTION_LIMIT)),
+      }, { signal });
+      const seen = new Map();
+      for (const section of ranked.data?.sections ?? []) {
+        const count = seen.get(section.documentCode) ?? 0;
+        if (count >= SECTION_LIMIT) continue;
+        seen.set(section.documentCode, count + 1);
+        sections.push(section);
+      }
+    }
+    const sectionOf = new Map(sections.flatMap((section) => section.clauseIds.map((id) => [`${section.documentCode}\u0000${id}`, section])));
+    const clauses = [];
+    const fetched = await within(Promise.all(documentCodes.map((code) => corpus.document(code))));
+    for (const [at, code] of documentCodes.entries()) {
+      const doc = fetched[at];
+      for (const clause of doc.clauses ?? []) {
+        const section = sectionOf.get(`${code}\u0000${clause.id}`);
+        if (!section && !baseIds.has(clause.id)) continue;
+        // A Lane base clause outside the ranked sections is shown under its own
+        // section heading; Dev's map uses the indexed breadcrumb, which only
+        // shifts the map's size estimate slightly.
+        clauses.push({
+          documentCode: code,
+          documentVersion: doc.currentVersion,
+          sectionId: section?.sectionId ?? `${code}:${clause.section}`,
+          breadcrumb: section?.breadcrumb ?? clause.section,
+          clauseId: clause.id,
+          gist: clauseGist(clause.text),
+          counterInstinct: clause.counterInstinct ?? false,
+          repos,
+          steps: clause.appliesTo?.step ?? ["*"],
+          laneBase: baseIds.has(clause.id),
+        });
+      }
+    }
+    clauses.sort((a, b) => a.documentCode.localeCompare(b.documentCode) || a.breadcrumb.localeCompare(b.breadcrumb) || a.clauseId.localeCompare(b.clauseId));
+    // The same Lane contract and notices Dev puts on a lane's map, so the size is the map a lane gets.
+    const laneContract = [
+      `Lane ${replay.issueKey} · ${replay.buildType}/${replay.side}`,
+      `Objective: ${objective}`,
+      `Repositories: ${repos.join(", ") || "none"}`,
+      `Paths: ${paths.join(", ") || "not supplied"}`,
+      "Gather: full",
+    ].join("\n");
+    const notices = [...(shortlist.data?.notice ? [shortlist.data.notice] : []), 'Not sure something applies? nodii-dev rules find "<question>"'];
+    const map = gatherText({ laneContract, notices, clauses }, objective);
+    return {
+      caseId: replay.id,
+      picker,
+      selectedClauseIds: [...new Set(clauses.map((clause) => clause.clauseId))],
+      selectedDocuments: documentCodes,
+      mapTokens: estimateTokens(map),
+    };
+  } catch (error) {
+    if (signal.aborted && !(error instanceof CliError && error.code === "PICKER_UNAVAILABLE"))
+      throw new CliError("GATHER_TIMEOUT", `the ${picker} trial for case ${replay.id} exceeded its ${Math.round(timeoutMs / 1000)}-second Gather deadline`, 1);
+    throw error;
+  } finally {
+    clearTimeout(deadline);
+  }
+}
+
+async function runCases(request, id) {
+  const runs = (await request("GET", "/api/v1/gather/tuning/runs")).data ?? [];
+  const run = runs.find((x) => x.id === id);
+  if (!run) throw new CliError("TUNING_RUN_NOT_FOUND", `tuning run ${id} was not found`, 1);
+  if (run.state !== "running") throw new CliError("TUNING_RUN_NOT_RUNNING", `tuning run ${id} is ${run.state}; only a running run accepts trials`, 1);
+  const cases = Array.isArray(run.settings?.caseIds) ? run.settings.caseIds : [];
+  if (!cases.length) throw new CliError("TUNING_RUN_INVALID", `tuning run ${id} has no frozen case cohort`, 1);
+  return { run, cases };
+}
+
+const putTrial = (request, runId, trial, iteration) => request("PUT", `/api/v1/gather/tuning/runs/${encode(runId)}/trials`, {
+  caseId: trial.caseId,
+  picker: trial.picker,
+  iteration,
+  selectedClauseIds: trial.selectedClauseIds,
+  selectedDocuments: trial.selectedDocuments,
+  mapTokens: trial.mapTokens,
+});
+
+function execText(payload) {
+  const d = payload.data;
+  const lines = [`Tuning run ${d.runId}: ${d.cases} case${d.cases === 1 ? "" : "s"} × ${TUNING_REPEATS} repeats`];
+  for (const p of d.pickers) {
+    if (p.status === "recorded") lines.push(`  ${p.picker.padEnd(15)}recorded ${p.recorded}/${p.expected}`);
+    else lines.push(`  ${p.picker.padEnd(15)}${p.status.toUpperCase()}${p.recorded ? ` after ${p.recorded}/${p.expected}` : ""}: ${p.reason}`);
+  }
+  lines.push(d.complete
+    ? `All requested pickers recorded. Finalize once every picker is in: nodii-dev gather tune finalize ${d.runId}`
+    : "The matrix is not complete; Dev's finalize refuses a partial run. Nothing was faked for the pickers above.");
+  return lines.join("\n");
+}
+
+function summaryText(run) {
+  const lines = [`Tuning run ${run.id}: ${run.state}${run.summary ? ` · ${run.summary.trials} trials` : ""}`];
+  for (const [picker, s] of Object.entries(run.summary?.perPicker ?? {}))
+    lines.push(`  ${picker.padEnd(15)}recall ${bps(s.recallBps)}  ⚑ recall ${bps(s.flaggedRecallBps)}  noise ${bps(s.noiseBps)}  ~${s.averageMapTokens} tokens  consistency ${bps(s.consistencyBps)}${s.flaggedMissedTrials ? `  ⚑ missed in ${s.flaggedMissedTrials} trials` : ""}`);
+  return lines.join("\n");
+}
+
+/**
+ * `nodii-dev gather tune cases|replay|start|trial|exec|finalize|runs`: the
+ * client for Dev's Gather tuning API (AH-11). Scoring is Dev's; the CLI only
+ * runs the pickers and assembles each trial's Clause map read-only.
+ */
+export async function tuneCommand(action, args, flags, { request = devRequest, pick = pickDocuments, warm = warmPicker, corpus } = {}) {
+  if (action === "cases") {
+    const payload = await request("GET", "/api/v1/gather/tuning/cases");
+    return { payload, human: (p) => (p.data ?? []).length
+      ? p.data.map((c) => `${c.id}\t${c.issueKey}\t${c.state}\t${c.buildType}/${c.side}\t${c.repos.join(",")}\t${c.answerCount} answers${c.disputeCount ? `, ${c.disputeCount} disputed` : ""}\t${c.objectiveTitle}`).join("\n")
+      : "No tuning cases. Harvest them with: nodii-dev api harvestGatherTuningCases" };
+  }
+  if (action === "runs") {
+    const payload = await request("GET", "/api/v1/gather/tuning/runs");
+    return { payload, human: (p) => (p.data ?? []).length ? p.data.map(summaryText).join("\n") : "No tuning runs." };
+  }
+  if (action === "replay") {
+    const id = uuid(args[0], "<case-id>");
+    const replay = (await request("GET", `/api/v1/gather/tuning/cases/${encode(id)}/replay`)).data;
+    const input = replayInput(replay);
+    const shortlist = (await request("POST", "/api/v1/rules/shortlist", { ...input, components: [] })).data;
+    const payload = { data: { case: { id: replay.id, issueKey: replay.issueKey, buildType: replay.buildType, side: replay.side }, ...input, shortlist } };
+    return { payload, human: (p) => [
+      `Case ${p.data.case.issueKey} (${p.data.case.buildType}/${p.data.case.side}) · repos ${p.data.repos.join(", ") || "none"}`,
+      `Objective: ${p.data.objective}`,
+      `Files: ${p.data.paths.length ? p.data.paths.join(", ") : "none"}`,
+      "Trigger shortlist:",
+      ...(p.data.shortlist.triggers ?? []).map((t) => `  ${t.code}: ${t.sentence}${t.forcedBy?.length ? ` [required by ${t.forcedBy.join(", ")}]` : ""}`),
+      `Record the lane-agent pick: nodii-dev gather tune trial <run-id> --case ${p.data.case.id} --picker lane-agent --iteration N --documents CODE,CODE`,
+    ].join("\n") };
+  }
+  if (action === "start") {
+    const trigger = flags.trigger ?? "manual";
+    if (!TRIGGERS.includes(trigger)) throw new CliError("USAGE", `--trigger must be one of ${TRIGGERS.join(", ")}`, 2);
+    if (typeof flags["corpus-ref"] !== "string" || !flags["corpus-ref"].trim()) throw new CliError("USAGE", "gather tune start needs --corpus-ref REF (the rule corpus the run is scored against)", 2);
+    if (typeof flags.cases !== "string") throw new CliError("USAGE", "gather tune start needs --cases all|ID,ID", 2);
+    let caseIds;
+    if (flags.cases === "all") {
+      caseIds = ((await request("GET", "/api/v1/gather/tuning/cases")).data ?? []).filter((c) => c.state === "challenged" && !c.disputeCount && !c.omissionCount).map((c) => c.id);
+      if (!caseIds.length) throw new CliError("TUNING_CASE_NOT_CHALLENGED", "no tuning case has an undisputed, independently challenged answer key yet", 1);
+    } else caseIds = list(flags.cases).map((id) => uuid(id, "every --cases entry"));
+    let settings = {};
+    if (flags.settings !== undefined) {
+      try { settings = JSON.parse(flags.settings); }
+      catch { throw new CliError("USAGE", "--settings must be a JSON object", 2); }
+      if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new CliError("USAGE", "--settings must be a JSON object", 2);
+    }
+    const payload = await request("POST", "/api/v1/gather/tuning/runs", { trigger, caseIds, corpusRef: flags["corpus-ref"].trim(), settings });
+    return { payload, human: (p) => `Started tuning run ${p.data.id}: ${p.data.caseCount} case${p.data.caseCount === 1 ? "" : "s"} × ${p.data.pickers.length} pickers × ${p.data.repeats} repeats.\nRun the automatic pickers: nodii-dev gather tune exec ${p.data.id}` };
+  }
+  if (action === "trial") {
+    const runId = uuid(args[0], "<run-id>");
+    const caseId = uuid(flags.case, "--case");
+    const picker = pickerFlag(flags.picker);
+    const iteration = iterationFlag(flags.iteration);
+    if (picker !== "lane-agent" && flags.documents !== undefined) throw new CliError("USAGE", "--documents is the lane-agent's own pick; other pickers choose for themselves", 2);
+    const { cases } = await runCases(request, runId);
+    if (!cases.includes(caseId)) throw new CliError("TUNING_CASE_OUTSIDE_RUN", `case ${caseId} is not in run ${runId}`, 1);
+    const replay = (await request("GET", `/api/v1/gather/tuning/cases/${encode(caseId)}/replay`)).data;
+    if (TUNING_MODELS[picker]) await warm({ model: TUNING_MODELS[picker] });
+    const trial = await runTrial(replay, picker, { request, pick, corpus: corpus ?? tuningCorpus(request), documents: list(flags.documents) });
+    const payload = await putTrial(request, runId, trial, iteration);
+    return { payload, human: (p) => `Recorded ${picker} #${iteration} for case ${caseId}: recall ${bps(p.data.recallBps)}, ⚑ recall ${bps(p.data.flaggedRecallBps)}, noise ${bps(p.data.noiseBps)}, ~${p.data.mapTokens} tokens.` };
+  }
+  if (action === "exec") {
+    const runId = uuid(args[0], "<run-id>");
+    const pickers = flags.pickers === undefined ? AUTOMATIC : list(flags.pickers).map(pickerFlag);
+    if (pickers.includes("lane-agent")) throw new CliError("USAGE", "the lane-agent picker is the agent itself: record each pick with `gather tune trial --picker lane-agent`", 2);
+    const { cases } = await runCases(request, runId);
+    const shared = corpus ?? tuningCorpus(request);
+    const replays = new Map();
+    const replayOf = async (caseId) => {
+      if (!replays.has(caseId)) replays.set(caseId, (await request("GET", `/api/v1/gather/tuning/cases/${encode(caseId)}/replay`)).data);
+      return replays.get(caseId);
+    };
+    const results = [];
+    for (const picker of pickers) {
+      const result = { picker, status: "recorded", recorded: 0, expected: cases.length * TUNING_REPEATS };
+      results.push(result);
+      try {
+        if (TUNING_MODELS[picker]) await warm({ model: TUNING_MODELS[picker] });
+        for (const caseId of cases)
+          for (let iteration = 1; iteration <= TUNING_REPEATS; iteration++) {
+            const trial = await runTrial(await replayOf(caseId), picker, { request, pick, corpus: shared });
+            await putTrial(request, runId, trial, iteration);
+            result.recorded++;
+          }
+      } 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;
+        Object.assign(result, { status: "unavailable", code: error.code, reason: error.message });
+      }
+    }
+    const complete = results.every((r) => r.status === "recorded");
+    return { payload: { data: { runId, cases: cases.length, complete, pickers: results } }, human: execText, exitCode: complete ? 0 : 1 };
+  }
+  if (action === "finalize") {
+    const runId = uuid(args[0], "<run-id>");
+    const payload = await request("POST", `/api/v1/gather/tuning/runs/${encode(runId)}/finalize`, {});
+    return { payload, human: (p) => summaryText(p.data) };
+  }
+  throw new CliError("USAGE", "gather tune cases|replay <case-id>|start --cases all|ID,ID --corpus-ref REF|trial <run-id> --case ID --picker P --iteration N [--documents A,B]|exec <run-id> [--pickers P,Q]|finalize <run-id>|runs", 2);
+}

package/package.json

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