@nodii/dev 0.6.34 → 0.6.36

package/README.md

@@ -131,18 +131,21 @@ nodii-dev decisions create|lock|supersede|amend
 
 nodii-dev lane gather [KEY] [--delta] [--objective TEXT] [--done-check TEXT]
                         [--paths A,B] [--components K,L]
+nodii-dev lane gather show [KEY] [--gather ID]
 nodii-dev lane freeze add KEY --section SECTION --file ITEM.json --reason TEXT
 nodii-dev lane freeze drop KEY --section SECTION --item ID --reason TEXT
 nodii-dev lane freeze swap KEY --section SECTION [--item ID] --file VALUE.json --reason TEXT
 nodii-dev lane freeze show KEY
 nodii-dev lane freeze history KEY
 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 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
@@ -152,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
@@ -369,7 +373,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]
@@ -404,7 +408,13 @@ changes, production-secret/test-auth bypasses, cleanup of Docker resources the
 run did not create, and deploy/apply commands without an exact grant. Allowed
 calls produce no output. Codex receives runtime-native `Bash` and `apply_patch`
 matchers, JSON denials, and `additionalContext` nudges. A compact session start
-prints the current lane Freeze again.
+prints the current lane Freeze again, with how to fetch its full Clause map.
+
+The Freeze pins only the ⚑ (counter-instinct) clauses, in full. Every other
+Gather clause stays in the Clause map, which the Freeze references by Gather
+id, listing one-line gists in rank order up to the 1,500-token cap ("+N more
+in Clause map"). `lane gather show` prints the whole Clause map and
+`rules show <ID>` prints one clause in full.
 
 Hard blocks apply only after Dev proves the current agent, branch and worktree
 belong to an active lane. Interactive or otherwise unproven sessions receive
@@ -612,10 +622,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
@@ -783,6 +792,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
@@ -800,7 +844,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
@@ -838,6 +885,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

package/dist/api.js

@@ -162,6 +162,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";
@@ -70,6 +71,7 @@ import {
   operationsFrom,
   parseParams,
   readBody,
+  STAFF_ONLY,
 } from "./api.js";
 import {
   agentWorkflowCommand,
@@ -91,6 +93,7 @@ import {
   showWaitingResults,
   superviseRun,
 } from "./runs.js";
+import { awsCli, superviseRemoteRun } from "./remote.js";
 
 const HELP = `nodii-dev ${VERSION}
 
@@ -148,7 +151,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]
@@ -156,6 +159,7 @@ Usage: nodii-dev <command> [options] [--json]
   rules core                            # the generated core (M05-33); refused over the cap
   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 show CLAUSE_ID                  # one clause in full, from the current document version
   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
@@ -168,6 +172,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
@@ -187,9 +193,15 @@ Usage: nodii-dev <command> [options] [--json]
                                         # the lane agent picks instead of local Gemma: alone it prints the
                                         # recorded trigger shortlist; with --shortlist/--documents it records
                                         # the pick (picker: agent) and the Clause map
-  run [--kind build|test_run|subagent|deploy] [--name TEXT] -- <command> [args...]
+  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] [--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]
@@ -218,7 +230,8 @@ 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 <operationId> [--param k=v] [--body @file|-|JSON]
   <resource> <action> [ID ...] [--field VALUE]
 
@@ -477,6 +490,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)
@@ -492,6 +528,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)
@@ -504,7 +543,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 {
@@ -512,7 +551,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;
   }
@@ -526,8 +565,8 @@ export async function main(argv = process.argv.slice(2)) {
       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);
@@ -597,6 +636,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);

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