@nodii/dev 0.6.46 → 0.6.48

package/README.md

@@ -141,10 +141,10 @@ nodii-dev rules find "QUESTION" [--limit N]
 nodii-dev rules show CLAUSE_ID
 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 start --cases all|ID,ID --corpus-ref REF [--pickers P,Q] [--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 gather tune finalize RUN_ID [--supersedes RUN_ID --reason TEXT]
 nodii-dev gather timings [--model M] [--last N]
 
 nodii-dev open-questions list|show|answer
@@ -954,7 +954,11 @@ its exit code (a lane that exits 0 after Gather included). It is reported as a
 `process-exit` with its code, fingerprint (`lane-unfinished-exit-0`,
 `lane-exit-N` or `lane-signal-S`) and redacted log tail. Dev orphans that run,
 so `lane resume` relaunches it with `recoveryOf`. A lane status Dev can't serve
-counts as unfinished. Every report carries `exit_code`, `worktree` and
+counts as unfinished. A lane that recorded BLOCKED (a blocked step, or a
+latest heartbeat note that starts with "blocked") and then exits ends its run
+`blocked` with that reason: never an orphan, never a death that counts toward
+the same-death stop (hub-58). A Dev without that status gets the process exit,
+which it also ends blocked from the lane's record. Every report carries `exit_code`, `worktree` and
 `lane_status` evidence. `process.pid` still holds the runtime's own PID, and the
 supervisor appends its report line to `process.log`.
 

package/dist/cli.js

@@ -167,13 +167,16 @@ Usage: nodii-dev <command> [options] [--json]
   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 start --cases all|ID,ID --corpus-ref REF [--pickers P,Q] [--trigger manual] [--settings JSON]
+                                        # --pickers: the subset this run scores (default all five)
   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
+                                        # runs each automatic picker the run scores 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
+  gather tune finalize <run-id> [--supersedes <run-id> --reason TEXT]
+                                        # Dev scores the run's own picker x 5-repeat matrix; --supersedes
+                                        # retires an earlier run in favour of this one (its trials are kept)
   gather picker-latency [--picker gemma-12b|gemma-e4b|gemma-26b]
                                         # cold (model unloaded first) and warm pick latency, for the tuning record
   gather timings [--model M] [--last N]  # this Mac's lane Gather picks: warm-up and first-pick p50/p95
@@ -214,6 +217,8 @@ Usage: nodii-dev <command> [options] [--json]
                                         # N min (default 10, then cancelled); --artifact is a path there
 
   lane start <key> --title TEXT --kind KIND --side SIDE [--repo REPO] [--issue ISSUE]
+  lane start <ISSUE> --key KEY --title TEXT --kind KIND --side SIDE
+                                        # --key names the lane; the positional is then its 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 --done <step> --review REVIEW.json

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

package/dist/lane-supervisor.js

@@ -93,10 +93,15 @@ export const doneCheckRecorded = (lane) =>
   || FINISHED_LANE.has(lane?.status);
 
 /** A lane is BLOCKED by a blocked step (`lane step --block`) or a latest heartbeat note that says so. */
-export function laneBlocked(lane) {
-  if ((lane?.steps ?? []).some((step) => step.state === "blocked")) return true;
+export const laneBlocked = (lane) => Boolean(laneBlockedReason(lane));
+
+/** Why a lane is BLOCKED, or null (the same rule Dev applies to a run's exit). */
+export function laneBlockedReason(lane) {
+  const step = (lane?.steps ?? []).find((candidate) => candidate.state === "blocked");
+  if (step) return `Lane step ${step.side}/${step.stepKey} is blocked.`;
   const heartbeat = (lane?.events ?? []).filter((event) => event.type === "heartbeat").at(-1);
-  return /^\s*blocked\b/i.test(String(heartbeat?.metadata?.note ?? ""));
+  const note = String(heartbeat?.metadata?.note ?? "");
+  return /^\s*blocked\b/i.test(note) ? `Lane heartbeat: ${note.slice(0, 500)}` : null;
 }
 
 /** The step a lane that stopped early goes back to (hub-58, NODII-DEV-CLI-8/9). */
@@ -114,9 +119,9 @@ export function continueTaskMessage(laneKey, lane) {
 async function laneProgress(request, laneKey) {
   try {
     const lane = (await request("GET", `/api/v1/lanes/${encode(laneKey)}`)).data;
-    return { status: lane?.status ?? null, finished: doneCheckRecorded(lane) };
+    return { status: lane?.status ?? null, finished: doneCheckRecorded(lane), blocked: laneBlockedReason(lane) };
   } catch {
-    return { status: null, finished: false };
+    return { status: null, finished: false, blocked: null };
   }
 }
 
@@ -134,7 +139,7 @@ export async function reportLaneExit({ runId, laneKey, exitCode, signal, worktre
   markTerminal = markWatchedTerminal,
 } = {}) {
   const worktree = await inspect(worktrees);
-  const { status, finished } = await laneProgress(request, laneKey);
+  const { status, finished, blocked } = await laneProgress(request, laneKey);
   const clean = exitCode === 0 && !signal;
   const exitRef = signal ? `signal ${signal}` : String(exitCode ?? -1);
   const exited = signal ? `was ended by ${signal}` : `exited with code ${exitCode ?? -1}`;
@@ -154,6 +159,11 @@ export async function reportLaneExit({ runId, laneKey, exitCode, signal, worktre
     // A finished lane has nothing to resume, so a failed exit is not a death.
     outcome = "failed";
     body = { status: "failed", reason: `The lane process ${exited} after lane ${laneKey} reached ${status}.`, evidence };
+  } else if (blocked) {
+    // hub-58 (30 Oct): a lane that recorded BLOCKED stopped on purpose. Its
+    // run ends blocked: never an orphan, never a death to resume.
+    outcome = "blocked";
+    body = { status: "blocked", reason: `${blocked} The lane process ${exited} while BLOCKED.`, evidence };
   } else {
     outcome = "process_exit";
     const logTail = redactRunText(await tail(logPath).catch(() => "")).trim();
@@ -168,8 +178,17 @@ export async function reportLaneExit({ runId, laneKey, exitCode, signal, worktre
     await send(request, `/api/v1/runs/${encode(runId)}/${outcome === "process_exit" ? "process-exit" : "end"}`, body);
   } catch (error) {
     // The agent may have ended its own run already; that is not a failure.
-    if (error?.code !== "RUN_ALREADY_TERMINAL") throw error;
-    outcome = "already_terminal";
+    if (error?.code === "RUN_ALREADY_TERMINAL") outcome = "already_terminal";
+    // A Dev without the blocked status refuses it: report the exit, which a
+    // current Dev also ends blocked from the lane's own record.
+    else if (outcome === "blocked" && error instanceof CliError) {
+      outcome = "process_exit";
+      await send(request, `/api/v1/runs/${encode(runId)}/process-exit`, {
+        reason: body.reason,
+        deathFingerprint: signal ? `lane-signal-${signal}` : clean ? "lane-unfinished-exit-0" : `lane-exit-${exitCode ?? -1}`,
+        exitCode: Number.isInteger(exitCode) && exitCode >= 0 && exitCode <= 255 ? exitCode : -1,
+      });
+    } else throw error;
   }
   await markTerminal(runId).catch(() => {});
   return { outcome, exitCode: exitCode ?? null, signal: signal ?? null, worktree: worktree.state, laneStatus: status };

package/dist/lanes.js

@@ -294,13 +294,19 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     return { payload, human: (p) => p.data.map(laneLine).join("\n") || "No lanes." };
   }
   if (action === "start") {
-    const key = need(args[0], "lane start needs <key>");
+    // `--key` names the lane; the positional is then the issue (NODII-DEV-CLI-13).
+    if (flags.key !== undefined && (typeof flags.key !== "string" || !flags.key.trim()))
+      throw new CliError("USAGE", "lane start --key needs one lane key", 2);
+    if (flags.key !== undefined && args[0] !== undefined && flags.issue !== undefined)
+      throw new CliError("USAGE", `lane start got both <${args[0]}> and --key ${flags.key} --issue ${flags.issue}; pass the lane key once (as <key> or --key) and the issue once.`, 2);
+    const key = need(flags.key?.trim() ?? args[0], "lane start needs <key>");
+    const issue = flags.key !== undefined ? flags.issue ?? args[0] : flags.issue;
     const c = await config();
     const context = await gitContext();
     const agent = (await request("GET", `/api/v1/agents/${encode(c.agentId)}`)).data;
     if (!agent.machineId) throw new CliError("MACHINE_REQUIRED", "The current agent is not assigned to a machine.", 1);
     let issueIds = [];
-    if (flags.issue) issueIds = [String(flags.issue)].flatMap((x) => x.split(",")).map(String);
+    if (issue) issueIds = [String(issue)].flatMap((x) => x.split(",")).map(String);
     issueIds = await Promise.all(issueIds.map(async (ref) => (await request("GET", `/api/v1/issues/${encode(ref)}`)).data.id));
     await request("POST", "/api/v1/lanes", {
       key, title: requireFlag(flags, "title"), kind: requireFlag(flags, "kind"), side: requireFlag(flags, "side"),

package/dist/tune.js

@@ -1,12 +1,13 @@
 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.
+// Dev's tuning matrix (AH-11): every case, each of the run's pickers, five
+// repeats. A run names its pickers at start (all five by default; hub-58 lets an
+// agent-picker run leave the Gemma columns out). Finalize refuses anything short
+// of the run's own 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;
@@ -31,6 +32,15 @@ function pickerFlag(value) {
   return value;
 }
 
+function pickersFlag(value) {
+  const pickers = list(value).map((picker) => {
+    if (!TUNING_PICKERS.includes(picker)) throw new CliError("USAGE", `--pickers must name pickers from ${TUNING_PICKERS.join(", ")}`, 2);
+    return picker;
+  });
+  if (!pickers.length || new Set(pickers).size !== pickers.length) throw new CliError("USAGE", "--pickers needs a comma list of distinct pickers", 2);
+  return pickers;
+}
+
 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);
@@ -223,7 +233,8 @@ async function runCases(request, id) {
   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 pickers = Array.isArray(run.pickers) && run.pickers.length ? run.pickers : TUNING_PICKERS;
+  return { run, cases, pickers };
 }
 
 const putTrial = (request, runId, trial, iteration) => request("PUT", `/api/v1/gather/tuning/runs/${encode(runId)}/trials`, {
@@ -249,9 +260,12 @@ function execText(payload) {
 }
 
 function summaryText(run) {
-  const lines = [`Tuning run ${run.id}: ${run.state}${run.summary ? ` · ${run.summary.trials} trials` : ""}`];
+  const coverage = run.summary?.coverage?.note ?? run.settings?.coverage?.note;
+  const lines = [`Tuning run ${run.id}: ${run.state}${run.summary ? ` · ${run.summary.trials} trials` : ""}${coverage ? ` · ${coverage}` : ""}`];
+  if (run.state === "superseded") lines.push(`  superseded by ${run.supersededByRunId}: ${run.supersededReason}`);
   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` : ""}`);
+  if (run.superseded) lines.push(`Superseded ${run.superseded.id}: ${run.superseded.supersededReason}`);
   return lines.join("\n");
 }
 
@@ -302,8 +316,16 @@ export async function tuneCommand(action, args, flags, { request = devRequest, p
       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}` };
+    const body = { trigger, caseIds, corpusRef: flags["corpus-ref"].trim(), settings };
+    if (flags.pickers !== undefined) body.pickers = pickersFlag(flags.pickers);
+    const payload = await request("POST", "/api/v1/gather/tuning/runs", body);
+    return { payload, human: (p) => {
+      const lines = [`Started tuning run ${p.data.id}: ${p.data.caseCount} case${p.data.caseCount === 1 ? "" : "s"} × ${p.data.pickers.length} picker${p.data.pickers.length === 1 ? "" : "s"} (${p.data.pickers.join(", ")}) × ${p.data.repeats} repeats.`];
+      if (p.data.settings?.coverage?.note) lines.push(`Coverage: ${p.data.settings.coverage.note}.`);
+      if (p.data.pickers.some((picker) => picker !== "lane-agent")) lines.push(`Run the automatic pickers: nodii-dev gather tune exec ${p.data.id}`);
+      if (p.data.pickers.includes("lane-agent")) lines.push(`Record each lane-agent pick: nodii-dev gather tune replay <case-id>, then gather tune trial ${p.data.id} --picker lane-agent`);
+      return lines.join("\n");
+    } };
   }
   if (action === "trial") {
     const runId = uuid(args[0], "<run-id>");
@@ -311,8 +333,9 @@ export async function tuneCommand(action, args, flags, { request = devRequest, p
     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);
+    const { cases, pickers } = await runCases(request, runId);
     if (!cases.includes(caseId)) throw new CliError("TUNING_CASE_OUTSIDE_RUN", `case ${caseId} is not in run ${runId}`, 1);
+    if (!pickers.includes(picker)) throw new CliError("TUNING_TRIAL_OUTSIDE_MATRIX", `run ${runId} scores ${pickers.join(", ")}, not ${picker}`, 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) });
@@ -321,9 +344,13 @@ export async function tuneCommand(action, args, flags, { request = devRequest, p
   }
   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 requested = flags.pickers === undefined ? null : pickersFlag(flags.pickers);
+    if (requested?.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, pickers: runPickers } = await runCases(request, runId);
+    const outside = (requested ?? []).filter((picker) => !runPickers.includes(picker));
+    if (outside.length) throw new CliError("TUNING_TRIAL_OUTSIDE_MATRIX", `run ${runId} scores ${runPickers.join(", ")}, not ${outside.join(", ")}`, 1);
+    // By default, every automatic picker the run scores.
+    const pickers = requested ?? runPickers.filter((picker) => picker !== "lane-agent");
     const shared = corpus ?? tuningCorpus(request);
     const replays = new Map();
     const replayOf = async (caseId) => {
@@ -354,8 +381,15 @@ export async function tuneCommand(action, args, flags, { request = devRequest, p
   }
   if (action === "finalize") {
     const runId = uuid(args[0], "<run-id>");
-    const payload = await request("POST", `/api/v1/gather/tuning/runs/${encode(runId)}/finalize`, {});
+    const body = {};
+    if (flags.supersedes !== undefined || flags.reason !== undefined) {
+      const supersedes = uuid(flags.supersedes, "--supersedes <run-id>");
+      if (typeof flags.reason !== "string" || !flags.reason.trim()) throw new CliError("USAGE", "--supersedes needs --reason TEXT: why the earlier run is retired", 2);
+      if (supersedes === runId) throw new CliError("USAGE", "a run cannot supersede itself", 2);
+      body.supersedes = { runId: supersedes, reason: flags.reason.trim() };
+    }
+    const payload = await request("POST", `/api/v1/gather/tuning/runs/${encode(runId)}/finalize`, body);
     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);
+  throw new CliError("USAGE", "gather tune cases|replay <case-id>|start --cases all|ID,ID --corpus-ref REF [--pickers P,Q]|trial <run-id> --case ID --picker P --iteration N [--documents A,B]|exec <run-id> [--pickers P,Q]|finalize <run-id> [--supersedes <run-id> --reason TEXT]|runs", 2);
 }

package/package.json

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