@nodii/dev 0.6.35 → 0.6.37

package/README.md

@@ -145,6 +145,7 @@ nodii-dev gather tune start --cases all|ID,ID --corpus-ref REF [--trigger T] [--
 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 timings [--model M] [--last N]
 
 nodii-dev open-questions list|show|answer
 nodii-dev feature-docs list|show|claim|release|status
@@ -154,7 +155,8 @@ nodii-dev libraries register-version LIBRARY_ID --version VERSION
 nodii-dev state diff
 nodii-dev heartbeat audit [SERVICE]
 
-nodii-dev run [--kind build|test_run|subagent|deploy] [--name TEXT] -- COMMAND [ARGS...]
+nodii-dev run [--kind build|test_run|subagent|deploy] [--name TEXT] [--artifact PATH] -- COMMAND [ARGS...]
+nodii-dev run --remote-ssm INSTANCE SCRIPT [--artifact PATH] [--quiet-minutes N] [--poll-seconds N] [--region R]
 
 nodii-dev design entries [--kind KIND] [--group GROUP] [--q TEXT]
 nodii-dev design entry KEY
@@ -325,6 +327,29 @@ nodii-dev hook nudge-pre              # guideline nudges before a tool call; nev
 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
+```
+
+`hook safety-pre` (installed by `harness install` for Claude Code and Codex)
+blocks, silently when satisfied (AGENT-HARNESS-15):
+
+- **Everyone, in a lane or not:** pattern kills (`pkill`, `killall`,
+  `kill $(pgrep …)`, `ps … | xargs kill`, `kill -1`). Kill only a PID you
+  started and saved.
+- **In a lane:** `git stash`; checking out or creating another branch;
+  `git add -A`; `git reset` onto another branch; `git worktree remove --force`;
+  a force push (`-f`, `--force`, `--force-with-lease`, `+ref`); a push without
+  a review receipt for HEAD and origin/main; `--no-verify` and its aliases
+  (`LEFTHOOK=0`, `HUSKY=0`, `core.hooksPath`); `nodii-dev login`, `logout`,
+  `agent register`; `nodii/prod` secrets, `NODE_ENV=test`, `skipAuth`;
+  `docker compose down -v` or volume deletes on stacks the run didn't create;
+  deploy/apply without a `GO deploy <sha>` grant; shell writes outside the
+  worktree (redirects, `tee`, `cp`, `mv`, `rm`, `mkdir`, `touch` …; temp space
+  is fine) and mutating `git -C` into another checkout; Edit/Write outside the
+  worktree, outside owned paths or on generated files.
+- **A coordinator** may use `--no-verify` only with `NODII_DEV_NO_VERIFY_REASON`
+  set; the reason is recorded in private Git metadata.
+
+```bash
 
 nodii-dev lane start KEY --title TEXT --kind dev_fix|new_build|docs_change|uat_fix|prod_fix
                      --side backend|frontend|both [--repo REPO] [--issue ISSUE]
@@ -371,7 +396,7 @@ nodii-dev rulebook diff CODE [--from V] [--to V]
 nodii-dev docs check PATH...                   # local M-05 checks only
 nodii-dev docs validate PATH... --class CLASS  # Dev's dry run of the upload
 nodii-dev docs upload PATH... --class ruling|conformance|editorial
-                      [--base CODE=VERSION ...] [--decision DECISION.json] [--pending]
+                      [--base CODE=VERSION ...] [--decision DECISION.json]
                       [--conformance-ref PR|REPO@SHA] [--meaning-unchanged REASON]
                       [--wait [--wait-minutes N]]
 nodii-dev docs ratify --domain KEY [--domain KEY ...] --decision DECISION.json [--wait]
@@ -620,10 +645,9 @@ Dev's error codes, and nothing is sent until there are none. Dev then runs the
 same checks, plus the ones that need its data, in one transaction.
 
 - `--class` is required on every write (M05-8). A `ruling` carries its
-  decision (`--decision`, with `amends`). Agents must add `--pending`: Dev
-  stores the ruling versions under a pending decision without activating
-  them, and a signed-in staff person locks it later. Omitting `--pending`
-  requests the staff-only immediate lock-and-amend action. An `editorial`
+  decision (`--decision`, with `amends`), and the decision locks as the change
+  lands (DEV-DEC-AS-COMMIT-1). `--pending` is still accepted but does nothing:
+  the CLI prints "decisions lock on upload" and doesn't send it. An `editorial`
   write that changes a Rules clause is refused unless
   `--meaning-unchanged REASON` is given (M05-10).
 - A new document is based on nothing. For a document Dev already has, pass
@@ -791,6 +815,41 @@ their output may be swallowed; the next visible call prints and acknowledges
 them. Unacknowledged amendments will join this preflight when the amendment API
 from AGENT-HARNESS-14 is available.
 
+### Result artifacts
+
+A run that succeeds can attach one text artifact, such as a benchmark table as
+JSON: `--artifact PATH`. It reaches the waiter whole, as the Result's
+`artifact` evidence item. The note is the content, redacted like the log
+tail. The ref is `NAME · BYTES bytes · sha256:HEX`. Dev keeps at most 10,000
+characters in a note, so an artifact that is missing, empty or larger fails the
+run (`Artifact not attached: …`). It never arrives cut.
+
+### Remote runs over SSM
+
+`nodii-dev run --remote-ssm INSTANCE SCRIPT` runs a local shell script on an EC2
+instance through SSM (`AWS-RunShellScript`), using your own `aws` CLI
+credentials (`--region` passes through). It is a watched run like a local one.
+It registers with `NODII_DEV_RUN_ID` as its waiter, heartbeats on every poll,
+and ends with the exit code, the remote log tail and, on success, the artifact
+(`--artifact` is a path on the instance, relative to the run directory).
+
+The script runs detached on the instance in its own session, from
+`/var/tmp/nodii-dev-runs/RUN_ID`, writing a log and then an exit-code file
+there. Every `--poll-seconds` (default 30), a short SSM command reads the log's
+size and tail and the exit code, and checks whether the process is alive. SSM
+keeps only the first 24,000 characters of a command's output, so the script's
+own invocation can't show progress. The run fails on:
+
+- a non-zero exit;
+- a process that is gone with no exit code (killed, or the instance restarted);
+- a missing run directory;
+- no new output, or no answer from the instance, for `--quiet-minutes`
+  (default 10).
+
+A quiet script is cancelled with its whole process group. A long job should
+print progress. Scripts are limited to 32 KB; copy larger code to the instance
+first.
+
 ## Build lanes and repository setup
 
 `coordinator start --machine NAME` registers the machine's one watched
@@ -808,7 +867,10 @@ target agent and machine, fresh account-capacity telemetry, repository grants,
 lane limit, open issues and (when `--figma` is present) the authenticated Figma
 account. Only after that passes does the CLI create one worktree per repository,
 atomically register the lane and watched run, and launch the runtime with the
-single-line brief `You are lane KEY. Run nodii-dev lane gather.`. Ordinary
+single-line brief `You are lane KEY. Run nodii-dev lane gather.`. It
+dispatches an agent only onto a started lane: if Dev registers the lane as
+anything but `building` (its start recorded), the CLI writes no marker, starts
+no runtime, records the launch failure, and exits `LANE_NOT_STARTED`. Ordinary
 notes use `--notes`; a scope-narrowing note uses `--narrowing-note` and must
 also name the remainder's destination with `--narrowing-remainder`.
 The launched process uses the already-provisioned lowercase identity (for
@@ -846,6 +908,19 @@ acknowledge a changed Freeze before continuing, and compact SessionStart uses
 the same backstop. `lane freeze add|drop|swap` makes a reasoned, version-checked
 change; `show|history` reads the current contract or its append-only history.
 
+A lane Gather warms the local picker (Gemma) as it starts, alongside Dev's
+requests. Dev's requests share a 60 s deadline. The deadline stops while the
+pick runs: the pick waits for the warm-up (up to 180 s), then the first pick
+has 120 s once the model is warm (`PICKER_TIMEOUT` past it, and the model is
+unloaded). Each pick is logged on this Mac (`~/.cache/nodii-dev/gather-timings.jsonl`,
+or `NODII_DEV_GATHER_TIMINGS`). Gather prints the pick's warm-up and pick time
+with this Mac's p50/p95, and `gather timings` prints the spread.
+If this Mac has no picker (the model isn't installed, or no Ollama answers),
+Gather falls back to the agent picker on the same shortlist. It prints
+`picker: agent (gemma4:12b not installed; run nodii-dev setup)` and the
+shortlist, then the agent records its pick with `--picker agent --shortlist ID
+--documents …`. A wrong model digest or a timeout still fails.
+
 `lane start` creates and starts a lane. It infers the repository (by short
 name, as Dev compares it), branch and worktree from git unless overridden, and resolves `--issue` keys to the UUIDs
 required by Dev. Lane keys are passed directly to every lane and Built
@@ -944,9 +1019,15 @@ nodii-dev requests resolve UUID --commit-sha abc1234 --resolution-md "shipped"
 nodii-dev open-questions answer UUID --decision-id D1420
 ```
 
-The CLI bundles Dev's OpenAPI document as the edge routes it (the edge does not
-serve Dev's own document), so `api list` works offline and lists only
-operations the edge exposes. The first-class resource families cover every tag: services,
+`api` and the resource commands read Dev's live catalog through the edge
+(`GET /devops/api/v1/openapi.json`), so an operation Dev adds after a CLI
+release is callable at once. The catalog is cached for 15 minutes in
+`~/.cache/nodii-dev/api-catalog.json` (`NODII_DEV_API_CATALOG_CACHE`),
+stamped with Dev's version and the document's sha256. When Dev cannot be read
+the CLI uses the last good copy, else the OpenAPI document bundled at release
+(the edge's routes only, so it works offline). `api catalog [--refresh]` shows
+which one is in use and why; `NODII_DEV_API_CATALOG=bundled` never asks Dev.
+The first-class resource families cover every tag: services,
 feature docs, contracts (gRPC, REST, outbox, sagas, tables), libraries,
 workers, projects, slices, SQL lookups, issues, backlogs, builds, changes,
 runtime, people, agents, inbox/gates, design, runbooks,

package/dist/api.js

@@ -1,16 +1,102 @@
-import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { stdin } from "node:process";
-import { CliError, devRawRequest, encode } from "./core.js";
+import { CliError, VERSION, devExchange, devRawRequest, encode, readConfig } from "./core.js";
 
 const methods = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
-// The Dev API as the platform edge routes it, bundled with the package (the
-// edge does not serve Dev's own document). Refresh: `npm run openapi:snapshot`.
+// The Dev API as the platform edge routes it, bundled with the package: the
+// fallback when Dev's live catalog cannot be read. Refresh: `npm run openapi:snapshot`.
 let bundled;
 export async function loadOpenApi() {
   bundled ??= JSON.parse(await readFile(new URL("./devops-openapi.json", import.meta.url), "utf8"));
   return bundled;
 }
 
+// Dev issue 99: an operation Dev added after this release is still callable.
+// The live catalog is read through the edge, cached for CATALOG_TTL_MS per
+// edge and stamped with Dev's version and the document's sha256. A refused or
+// malformed read is cached too, so a Dev without the route costs one request
+// per TTL. Unreachable or signed out: the last good copy, else the bundled one.
+export const LIVE_CATALOG_PATH = "/api/v1/openapi.json";
+export const CATALOG_TTL_MS = 15 * 60 * 1000;
+const CATALOG_TIMEOUT_MS = 4000;
+const TRANSIENT = new Set(["DEV_UNREACHABLE", "DEV_TIMEOUT", "NOT_LOGGED_IN", "LOGIN_REQUIRED", "OAUTH_LOGIN_REQUIRED", "KEYCHAIN_UNAVAILABLE"]);
+export const catalogCachePath = (env = process.env) =>
+  env.NODII_DEV_API_CATALOG_CACHE || join(homedir(), ".cache", "nodii-dev", "api-catalog.json");
+
+const isSpec = (value) => value && typeof value === "object" && typeof value.openapi === "string" && value.paths && typeof value.paths === "object";
+// Only Dev's own API is reachable through the edge's /devops prefix.
+const edgeReachable = (spec) => ({ ...spec, paths: Object.fromEntries(Object.entries(spec.paths).filter(([path]) => path.startsWith("/api/v1/"))) });
+
+async function readCache(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(path, value) {
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify(value), { mode: 0o600 });
+    await rename(tmp, path);
+  } catch {
+    // A cache that cannot be written only costs a refetch next time.
+  }
+}
+
+const bundledCatalog = async (reason) => ({ spec: await loadOpenApi(), source: "bundled", version: `@nodii/dev ${VERSION}`, reason });
+const cachedCatalog = (good, source, reason) => ({ spec: good.spec, source, version: good.version, sha256: good.sha256, fetchedAt: good.fetchedAt, reason });
+
+/**
+ * The operation catalog: `{ spec, source: live|cache|stale|bundled, version, sha256?, fetchedAt?, reason? }`.
+ * NODII_DEV_API_CATALOG=bundled skips Dev; `refresh` ignores the TTL.
+ */
+export async function loadCatalog({ refresh = false, env = process.env, now = Date.now() } = {}) {
+  if (env.NODII_DEV_API_CATALOG === "bundled") return bundledCatalog("NODII_DEV_API_CATALOG=bundled");
+  const config = await readConfig(false).catch(() => null);
+  if (!config?.edgeUrl) return bundledCatalog("not signed in");
+  const path = catalogCachePath(env);
+  const cache = await readCache(path);
+  const mine = cache?.edgeUrl === config.edgeUrl ? cache : null;
+  const fresh = mine && now - Date.parse(mine.checkedAt) < CATALOG_TTL_MS;
+  if (fresh && !refresh)
+    return mine.failure
+      ? mine.good ? cachedCatalog(mine.good, "stale", mine.failure) : bundledCatalog(mine.failure)
+      : cachedCatalog(mine.good, "cache");
+
+  let failure;
+  try {
+    const { payload } = await devExchange("GET", LIVE_CATALOG_PATH, undefined, { signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS) });
+    if (!isSpec(payload)) failure = `Dev's ${LIVE_CATALOG_PATH} is not an OpenAPI document`;
+    else {
+      const spec = edgeReachable(payload);
+      const sha256 = createHash("sha256").update(JSON.stringify(spec)).digest("hex");
+      const good = { spec, version: `Dev ${payload.info?.version ?? "unknown"}`, sha256, fetchedAt: new Date(now).toISOString() };
+      await writeCache(path, { edgeUrl: config.edgeUrl, checkedAt: good.fetchedAt, good, failure: null });
+      return cachedCatalog(good, "live");
+    }
+  } catch (error) {
+    const reason = `${error?.code ?? "ERROR"}: ${error?.message ?? String(error)}`;
+    // Signed out, offline, timed out or a 5xx says nothing about the route: not cached.
+    if (TRANSIENT.has(error?.code) || /^HTTP_5\d\d$/.test(error?.code ?? "") || !(error instanceof CliError))
+      return mine?.good ? cachedCatalog(mine.good, "stale", reason) : bundledCatalog(reason);
+    failure = reason;
+  }
+  await writeCache(path, { edgeUrl: config.edgeUrl, checkedAt: new Date(now).toISOString(), good: mine?.good ?? null, failure });
+  return mine?.good ? cachedCatalog(mine.good, "stale", failure) : bundledCatalog(failure);
+}
+
+export function describeCatalog(catalog) {
+  const stamp = [catalog.version, catalog.sha256 && `sha256 ${catalog.sha256.slice(0, 12)}`, catalog.fetchedAt && `fetched ${catalog.fetchedAt}`].filter(Boolean).join(", ");
+  const why = catalog.reason ? `; live catalog unavailable: ${catalog.reason}` : "";
+  return `catalog: ${catalog.source} (${stamp})${why}`;
+}
+
 export function operationsFrom(spec) {
   const out = [];
   for (const [path, item] of Object.entries(spec.paths ?? {}))
@@ -162,6 +248,12 @@ export const ALIASES = {
 
 // Decisions a person makes in Dev (operator authority): nodii-dev never sends them.
 export const PERSON_ONLY = new Set(["approveDesignGuidelineChangeSet", "rejectDesignGuidelineChangeSet", "mergeDesignRelease"]);
+// Signed-in staff only: Dev answers an agent with OPERATOR_REQUIRED by design.
+// nodii-dev still sends them, for a person signed in to the CLI.
+export const STAFF_ONLY = new Map([
+  ["ratifyAdDocument", "staff only: ratify on the document's Rules record page; an agent gets OPERATOR_REQUIRED"],
+]);
+
 export function refusePersonOnly(operationId) {
   if (PERSON_ONLY.has(operationId))
     throw new CliError("PERSON_ONLY", `${operationId} is a person's decision in Dev; nodii-dev does not send it.`, 2);

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import { stdin, stdout } from "node:process";
 import {
   CliError,
@@ -53,7 +54,7 @@ import {
 } from "./figma.js";
 export { figmaLock, submitMode } from "./figma.js";
 import { tuneCommand } from "./tune.js";
-import { TUNING_MODELS, measurePickerLatency } from "./gather.js";
+import { PICKER_MODEL, TUNING_MODELS, measurePickerLatency, pickTimingStats, pickTimingText, pickTimingsPath, readPickTimings } from "./gather.js";
 import { docsCommand, rulebookCommand, rulesCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import { designCheck, designCheckText, designRoles, designRolesText } from "./design.js";
@@ -66,10 +67,12 @@ import {
   findFirstClass,
   flagsToOperation,
   refusePersonOnly,
-  loadOpenApi,
+  describeCatalog,
+  loadCatalog,
   operationsFrom,
   parseParams,
   readBody,
+  STAFF_ONLY,
 } from "./api.js";
 import {
   agentWorkflowCommand,
@@ -91,6 +94,7 @@ import {
   showWaitingResults,
   superviseRun,
 } from "./runs.js";
+import { awsCli, superviseRemoteRun } from "./remote.js";
 
 const HELP = `nodii-dev ${VERSION}
 
@@ -108,7 +112,7 @@ Usage: nodii-dev <command> [options] [--json]
                                         # blocked and wont_do need --reason; done needs --dev-check
   inbox list|show
   drift file | request file
-  decisions list|get|search
+  decisions list|get|search             # get DEC-n reads the AD decision with its amends
   design entries|entry|guide
   design guideline list [--drafted] [--all] | show ENTRY
   design guideline propose ENTRY --file FILE.md [--summary TEXT] [--dry-run]
@@ -148,7 +152,7 @@ Usage: nodii-dev <command> [options] [--json]
   watchdog install [--interval SECONDS] # install/update the per-Mac launchd liveness sweep (default 60s)
   watchdog sweep                        # launchd entrypoint: report dead runs, stale sockets, unpushed worktrees
   docs check|validate|upload <path...> --class ruling|conformance|editorial
-       [--base CODE=VERSION] [--decision FILE] [--pending] [--conformance-ref REF]
+       [--base CODE=VERSION] [--decision FILE] [--conformance-ref REF]
        [--meaning-unchanged REASON] [--wait]
   docs ratify --domain KEY [--domain KEY ...] --decision FILE [--wait]
   docs parked [CODE] [--status pending|acknowledged]
@@ -169,6 +173,8 @@ Usage: nodii-dev <command> [options] [--json]
   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
+  gather timings [--model M] [--last N]  # this Mac's lane Gather picks: warm-up and first-pick p50/p95
+                                        # (each lane gather logs one; the first pick has 120 s once warm)
 
   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
@@ -189,9 +195,14 @@ Usage: nodii-dev <command> [options] [--json]
                                         # recorded trigger shortlist; with --shortlist/--documents it records
                                         # the pick (picker: agent) and the Clause map
   lane gather show [<key>] [--gather ID]  # the lane's Clause map (the Freeze references it, not its clauses)
-  run [--kind build|test_run|subagent|deploy] [--name TEXT] -- <command> [args...]
+  run [--kind build|test_run|subagent|deploy] [--name TEXT] [--artifact PATH] -- <command> [args...]
                                         # watched command: registers with NODII_DEV_RUN_ID,
-                                        # heartbeats, and records exit code + redacted log tail
+                                        # heartbeats, and records exit code + redacted log tail;
+                                        # --artifact attaches that file (text, <= 10,000 chars) to the Result
+  run --remote-ssm INSTANCE SCRIPT [--artifact PATH] [--quiet-minutes N] [--poll-seconds N] [--region R]
+                                        # SCRIPT runs detached on the EC2 instance through SSM (your aws CLI);
+                                        # fails on a non-zero exit, a vanished process, or no new output for
+                                        # 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 step <key> --side SIDE --start|--done|--block <step> [--reason TEXT]
@@ -220,7 +231,11 @@ Usage: nodii-dev <command> [options] [--json]
   agent lane-limit|grant|revoke
   people reveal <id> --reason TEXT | people refresh-names
 
-  api list [--tag TAG]
+  api list [--tag TAG]                  # staff-only operations are marked (ratifyAdDocument:
+                                        # agents get OPERATOR_REQUIRED by design)
+  api catalog [--refresh]               # which catalog api and resource commands use: Dev's live one
+                                        # (cached 15 min, version + sha256 stamped) or the bundled
+                                        # fallback, and why; NODII_DEV_API_CATALOG=bundled skips Dev
   api <operationId> [--param k=v] [--body @file|-|JSON]
   <resource> <action> [ID ...] [--field VALUE]
 
@@ -479,6 +494,29 @@ export async function main(argv = process.argv.slice(2)) {
     return console.log(VERSION);
   if (argv.length === 1 && ["--help", "-h"].includes(argv[0]))
     return console.log(HELP);
+  if (argv[0] === "run" && argv.some((x) => x === "--remote-ssm" || x.startsWith("--remote-ssm="))) {
+    const { args: scriptArgs, flags: remoteFlags } = parseArgs(argv.slice(1));
+    const single = (flag) => {
+      const value = remoteFlags[flag];
+      if (Array.isArray(value) || value === true) throw new CliError("USAGE", `run --${flag} needs one value.`, 2);
+      return value;
+    };
+    if (scriptArgs.length !== 1)
+      throw new CliError("USAGE", "run --remote-ssm INSTANCE SCRIPT [--artifact PATH] [--quiet-minutes N] [--poll-seconds N] [--region R] [--kind K] [--name TEXT]", 2);
+    const number = (flag) => (single(flag) === undefined ? undefined : Number(single(flag)));
+    const result = await superviseRemoteRun({
+      instance: single("remote-ssm"),
+      script: scriptArgs[0],
+      artifact: single("artifact"),
+      quietMinutes: number("quiet-minutes"),
+      pollSeconds: number("poll-seconds"),
+      kind: single("kind"),
+      name: single("name"),
+      aws: awsCli({ region: single("region") }),
+    });
+    process.exitCode = result.exitCode;
+    return;
+  }
   if (["run", "__run-supervisor"].includes(argv[0])) {
     const boundary = argv.indexOf("--");
     if (boundary === -1 || boundary === argv.length - 1)
@@ -494,6 +532,9 @@ export async function main(argv = process.argv.slice(2)) {
       );
     const kind = runFlags.kind;
     const name = runFlags.name;
+    const artifact = runFlags.artifact;
+    if (Array.isArray(artifact) || artifact === true)
+      throw new CliError("USAGE", "run --artifact needs one path.", 2);
     if (Array.isArray(kind) || kind === true)
       throw new CliError("USAGE", "run --kind needs one value.", 2);
     if (Array.isArray(name) || name === true)
@@ -506,7 +547,7 @@ export async function main(argv = process.argv.slice(2)) {
       stdout.on("error", ignoreBrokenPipe);
       process.stderr.on("error", ignoreBrokenPipe);
       try {
-        const result = await superviseRun({ command, kind, name });
+        const result = await superviseRun({ command, kind, name, artifact });
         process.exitCode = result.exitCode;
         return;
       } finally {
@@ -514,7 +555,7 @@ export async function main(argv = process.argv.slice(2)) {
         process.stderr.off("error", ignoreBrokenPipe);
       }
     }
-    const exitCode = await launchRunSupervisor(command, { kind, name });
+    const exitCode = await launchRunSupervisor(command, { kind, name, artifact: artifact && resolve(artifact) });
     process.exitCode = exitCode;
     return;
   }
@@ -523,17 +564,23 @@ export async function main(argv = process.argv.slice(2)) {
   const [command, action, ...rest] = args;
   if (!command || f.help || command === "help") return console.log(HELP);
   if (command === "api") {
-    const operations = operationsFrom(await loadOpenApi());
+    const catalog = await loadCatalog({ refresh: action === "catalog" && f.refresh === true });
+    const operations = operationsFrom(catalog.spec);
+    if (action === "catalog") {
+      const { spec: _spec, ...stamp } = catalog;
+      return emit({ ...stamp, operations: operations.length }, json, `${describeCatalog(catalog)}\n${operations.length} operations`);
+    }
     if (action === "list") {
+      if (!json) console.error(`# ${describeCatalog(catalog)}`);
       const selected = f.tag === undefined || f.tag === true
         ? operations
         : operations.filter((x) => x.tags.some((t) => t.toLowerCase() === String(f.tag).toLowerCase()));
-      return emit(selected.map(({ operationId, method, path, tags }) => ({ operationId, method, path, tags })), json,
-        (rows) => rows.map((x) => `${x.operationId}\t${x.method}\t${x.path}\t${x.tags.join(",")}`).join("\n"));
+      return emit(selected.map(({ operationId, method, path, tags }) => ({ operationId, method, path, tags, ...(STAFF_ONLY.has(operationId) ? { staffOnly: true } : {}) })), json,
+        (rows) => rows.map((x) => `${x.operationId}\t${x.method}\t${x.path}\t${x.tags.join(",")}${x.staffOnly ? `\t# ${STAFF_ONLY.get(x.operationId)}` : ""}`).join("\n"));
     }
     if (!action) throw new CliError("USAGE", "api needs an operationId or list", 2);
     const entry = operations.find((x) => x.operationId === action);
-    if (!entry) throw new CliError("UNKNOWN_OPERATION", `No OpenAPI operationId: ${action}`, 2);
+    if (!entry) throw new CliError("UNKNOWN_OPERATION", `No OpenAPI operationId: ${action} (${describeCatalog(catalog)})`, 2);
     refusePersonOnly(entry.operationId);
     const parsed = await readBody(f.body);
     const request = buildOperationRequest(entry, parseParams(f.param), parsed?.value);
@@ -599,6 +646,15 @@ export async function main(argv = process.argv.slice(2)) {
     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 === "timings") {
+    const last = f.last === undefined ? 50 : Number(f.last);
+    if (!Number.isInteger(last) || last < 1) throw new CliError("USAGE", "gather timings [--model M] [--last N]", 2);
+    const model = typeof f.model === "string" ? f.model : PICKER_MODEL;
+    const path = pickTimingsPath();
+    const entries = await readPickTimings({ path, model, last });
+    const stats = pickTimingStats(entries);
+    return emit({ model, path, ...stats, entries }, json, () => pickTimingText(stats, { model, path }));
+  }
   if (command === "gather" && action === "tune") {
     const result = await tuneCommand(rest[0], rest.slice(1), f);
     emit(result.payload, json, result.human);
@@ -786,6 +842,21 @@ export async function main(argv = process.argv.slice(2)) {
     f.requestHash = requestHash({ toService: f.toService, kind: requireFlag(f, "kind"), specMd });
   }
   if (command === "decisions") {
+    // A DEC-* id is an AD-era decision: getAdDecision carries its amends; the
+    // pre-dev /decisions route knows none of them.
+    if (action === "get" && /^DEC-\d+$/i.test(rest[0] ?? ""))
+      return emit(
+        await devRequest("GET", `/api/v1/ad-decisions/${encode(rest[0].toUpperCase())}`),
+        json,
+        ({ data: d }) => [
+          `${d.id}\t${d.status}\t${d.title}`,
+          ...(d.ruling ? ["", d.ruling] : []),
+          "",
+          d.amends?.length
+            ? `Amends (${d.amends.length}):\n${d.amends.map((a) => `  ${a.clauseId ?? a.docCode}\t${a.effect}\t${a.docCode} ${a.previousVersion ?? "-"} -> ${a.version}${a.documentTitle ? `\t${a.documentTitle}` : ""}`).join("\n")}`
+            : "Amends: none",
+        ].join("\n"),
+      );
     if (action === "get")
       return emit(
         await devRequest("GET", `/api/v1/decisions/${encode(rest[0])}`),
@@ -1038,7 +1109,8 @@ export async function main(argv = process.argv.slice(2)) {
     }
   }
   if (Object.hasOwn(GROUPS, command)) {
-    const operations = operationsFrom(await loadOpenApi());
+    const catalog = await loadCatalog();
+    const operations = operationsFrom(catalog.spec);
     let entry = findFirstClass(operations, command, action);
     if (command === "drift" && action === "resolve" && f.status === "accepted-as-canonical")
       entry = operations.find((x) => x.operationId === "acceptDrift");
@@ -1053,7 +1125,7 @@ export async function main(argv = process.argv.slice(2)) {
     if (!entry) {
       const tags = Array.isArray(GROUPS[command]) ? GROUPS[command] : [GROUPS[command]];
       const available = operations.filter((x) => x.tags.some((t) => tags.includes(t))).map((x) => x.operationId).join(", ");
-      throw new CliError("USAGE", `Unknown ${command} action: ${action}. OpenAPI operations: ${available}`, 2);
+      throw new CliError("USAGE", `Unknown ${command} action: ${action}. OpenAPI operations: ${available} (${describeCatalog(catalog)})`, 2);
     }
     const built = flagsToOperation(entry, rest, f);
     if (command === "requests" && action === "answer")

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