@nodii/dev 0.6.26 → 0.6.28

package/README.md

@@ -135,6 +135,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 design entries [--kind KIND] [--group GROUP] [--q TEXT]
 nodii-dev design entry KEY
 nodii-dev design guide PAGE_TYPE
@@ -308,6 +310,7 @@ nodii-dev lane step KEY --side backend|frontend --start|--done|--block STEP [--r
                     # --reason is kept as a lane note; on a step already blocked,
                     # --block --reason records the new reason (Dev issue 125 moves it onto the step)
 nodii-dev lane evidence KEY --pr|--commit|--figma|--deploy|--dev-check REF
+nodii-dev lane subagent-quota KEY N
 nodii-dev lane heartbeat KEY [--note TEXT]
 nodii-dev lane review KEY --file REVIEW.json
 nodii-dev lane reviews KEY
@@ -345,7 +348,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]
+                      [--base CODE=VERSION ...] [--decision DECISION.json] [--pending]
                       [--conformance-ref PR|REPO@SHA] [--meaning-unchanged REASON]
                       [--wait [--wait-minutes N]]
 nodii-dev docs ratify --domain KEY [--domain KEY ...] --decision DECISION.json [--wait]
@@ -542,9 +545,12 @@ 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`), and the decision locks with the new
-  versions or nothing is written. An `editorial` write that changes a Rules
-  clause is refused unless `--meaning-unchanged REASON` is given (M05-10).
+  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`
+  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
   the version you started from with `--base CODE=VERSION` (M05-11). The CLI
   never fills it in from Dev, so a stale edit is refused instead of
@@ -686,6 +692,30 @@ Doctor may refresh the access token, as any command does. The permission table
 is kept by hand from Dev's route policy until Dev's OpenAPI names each
 operation's permission (requested in Dev).
 
+## Watched commands and Results
+
+The harness launcher supplies `NODII_DEV_RUN_ID`, the UUID of the current lane,
+coordinator, or subagent run. Use `nodii-dev run -- COMMAND ARGS...` for work
+whose completion must survive the calling agent. The command registers a child
+run with that UUID as its waiter, starts an out-of-process supervisor, and
+preserves the command's exit code. `--kind` defaults to `build`; `--name`
+overrides the executable name shown in Dev without storing command arguments.
+
+The supervisor heartbeats once a minute while the command runs. At completion
+it records the executable, exit code, signal when applicable, and the final 8
+KiB of combined stdout/stderr. Credential-shaped values, bearer tokens, private
+keys, and credentials embedded in URLs are redacted before the tail leaves the
+machine. The command is executed directly, never through a shell. Because the
+supervisor is detached from the launching process, the terminal record still
+lands when that process is killed.
+
+Every subsequent `nodii-dev` call in the waiter context prints unacknowledged
+Results before doing its requested work. A Result is acknowledged only after
+it renders successfully. Hook calls deliberately leave Results pending because
+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.
+
 ## Build lanes and repository setup
 
 `lane start` creates and starts a lane. It infers the repository (by short
@@ -697,6 +727,12 @@ serves for that step (see Rule delivery). Server refusals,
 including operator-only actions, workflow blocks, lane limits and Built items
 that are not on dev, retain Dev's error code/message and exit non-zero.
 
+The machine coordinator sets a lane's subagent capacity with `lane
+subagent-quota KEY N` (`0` to `100`). Registering a subagent run consumes one
+slot; Dev refuses another registration with `SUBAGENT_QUOTA_REACHED` when the
+lane is full. A `done`, `handed_off`, or `failed` subagent run no longer counts,
+so the watchdog marking a killed process failed frees the slot.
+
 `setup` installs the Claude Code and Codex workflow harnesses in the current repository.
 It writes `.claude/skills/nodii-build-workflow/SKILL.md`, merges SessionStart,
 Stop and tool hooks into `.claude/settings.json` and `.codex/hooks.json`, and maintains one
@@ -778,7 +814,8 @@ runtime, people, agents, inbox/gates, design, runbooks,
 doctrine and exceptions, changelog, health verdicts, approval kinds,
 notification registry, skills, questions, decisions, drift, requests,
 pipelines, runners, routing, usage, audit, reconciliation, cron, composite
-surfaces, service edges, lanes, swaps, ideas, terminology, and the AD era: `rulebook`
+surfaces, service edges, lanes, swaps, ideas, terminology, watched runs,
+releases, operate surfaces, and the AD era: `rulebook`
 (documents, plus `rulebook versions CODE`), `ad-decisions`, `domains`, `standardizations`,
 `archive` (`archive resolve --ref pre:D1366`), and `harness methodology`. `api list` is the authoritative discovery view;
 `api OPERATION_ID` makes every operation callable even without an alias.

package/dist/api.js

@@ -103,6 +103,7 @@ export const GROUPS = {
   swaps: "Swaps", ideas: "Ideas", terminology: "Terminology", credentials: "Credentials",
   rulebook: "ad-documents", "ad-decisions": "ad-decisions", domains: "ad-domains", standardizations: "standardizations",
   archive: "archive", harness: "harness", utils: "utils",
+  runs: "Runs", releases: "Releases", operate: "Operate",
   // DEC-0020 rule delivery; `rules core|report|cap` are first-class (upload.js).
   rules: "rulebook",
 };

package/dist/cli.js

@@ -74,6 +74,11 @@ import {
   nextCommand,
   peopleCommand,
 } from "./lanes.js";
+import {
+  launchRunSupervisor,
+  showWaitingResults,
+  superviseRun,
+} from "./runs.js";
 
 const HELP = `nodii-dev ${VERSION}
 
@@ -128,7 +133,7 @@ Usage: nodii-dev <command> [options] [--json]
   harness check                         # 0 current, 1 differs from Dev, 2 not installed
   harness update --check                # the same check
   docs check|validate|upload <path...> --class ruling|conformance|editorial
-       [--base CODE=VERSION] [--decision FILE] [--conformance-ref REF]
+       [--base CODE=VERSION] [--decision FILE] [--pending] [--conformance-ref REF]
        [--meaning-unchanged REASON] [--wait]
   docs ratify --domain KEY [--domain KEY ...] --decision FILE [--wait]
   docs parked [CODE] [--status pending|acknowledged]
@@ -137,10 +142,15 @@ Usage: nodii-dev <command> [options] [--json]
   rules report [--section S] [--lane KEY]   # delivery totals per document; rules served per lane
   rules cap TOKENS                      # operator: set the core token cap (default 3000)
 
+  run [--kind build|test_run|subagent|deploy] [--name TEXT] -- <command> [args...]
+                                        # watched command: registers with NODII_DEV_RUN_ID,
+                                        # heartbeats, and records exit code + redacted log tail
+
   lane start <key> --title TEXT --kind KIND --side SIDE [--repo REPO] [--issue ISSUE]
   lane step <key> --side SIDE --start|--done|--block <step> [--reason TEXT]
                                         # --block --reason on a blocked step records its new reason
   lane evidence <key> --pr|--commit|--figma|--deploy|--dev-check REF
+  lane subagent-quota <key> <n>          # coordinator assigns 0-100 subagent slots
   lane heartbeat|land|verify|prioritize|deprioritize|stop <key>
   lane review <key> --file REVIEW.json  # base/head, outcome and clause-cited findings
   lane reviews <key>                    # stored review history for the lane
@@ -164,7 +174,8 @@ contracts, sagas, outbox-topics, tables, libraries, workers, projects, issues,
 backlogs, builds, changes, deploy-reports, runtime, people, agents, inbox,
 gate, design, runbooks, doctrine, changelog, health-verdicts, approval-kinds,
 notification-registry, skills, open-questions, decisions, drift, requests,
-rulebook, ad-decisions, domains, standardizations, archive, harness, and utils.
+rulebook, ad-decisions, domains, standardizations, archive, harness, utils,
+runs, releases, and operate.
 
 Run a command with --help or see the package README for all flags.`;
 
@@ -401,10 +412,51 @@ export async function figmaFileAdd(value, flags, { request = devRequest } = {})
 }
 
 export async function main(argv = process.argv.slice(2)) {
+  if (argv[0] !== "__run-supervisor")
+    await showWaitingResults({ acknowledge: argv[0] !== "hook" });
   if (argv.length === 1 && ["--version", "-v"].includes(argv[0]))
     return console.log(VERSION);
   if (argv.length === 1 && ["--help", "-h"].includes(argv[0]))
     return console.log(HELP);
+  if (["run", "__run-supervisor"].includes(argv[0])) {
+    const boundary = argv.indexOf("--");
+    if (boundary === -1 || boundary === argv.length - 1)
+      throw new CliError("USAGE", "run needs a command after `--`.", 2);
+    const { args: optionArgs, flags: runFlags } = parseArgs(
+      argv.slice(1, boundary),
+    );
+    if (optionArgs.length)
+      throw new CliError(
+        "USAGE",
+        `Unexpected run argument before \`--\`: ${optionArgs.join(" ")}`,
+        2,
+      );
+    const kind = runFlags.kind;
+    const name = runFlags.name;
+    if (Array.isArray(kind) || kind === true)
+      throw new CliError("USAGE", "run --kind needs one value.", 2);
+    if (Array.isArray(name) || name === true)
+      throw new CliError("USAGE", "run --name needs one value.", 2);
+    const command = argv.slice(boundary + 1);
+    if (argv[0] === "__run-supervisor") {
+      const ignoreBrokenPipe = (error) => {
+        if (error?.code !== "EPIPE") throw error;
+      };
+      stdout.on("error", ignoreBrokenPipe);
+      process.stderr.on("error", ignoreBrokenPipe);
+      try {
+        const result = await superviseRun({ command, kind, name });
+        process.exitCode = result.exitCode;
+        return;
+      } finally {
+        stdout.off("error", ignoreBrokenPipe);
+        process.stderr.off("error", ignoreBrokenPipe);
+      }
+    }
+    const exitCode = await launchRunSupervisor(command, { kind, name });
+    process.exitCode = exitCode;
+    return;
+  }
   const { args, flags: f } = parseArgs(argv);
   const json = Boolean(f.json);
   const [command, action, ...rest] = args;
@@ -766,10 +818,6 @@ export async function main(argv = process.argv.slice(2)) {
       return;
     }
     if (["claude-figma-pre", "figma-pre"].includes(action)) {
-      // Fail closed: Claude Code only blocks a tool call on exit code 2, and
-      // treats any other non-zero exit as a non-blocking error that lets the
-      // write through. Every failure here (bad stdin, missing config, Dev
-      // error, lock denied) must therefore exit 2.
       let payload;
       try {
         payload = JSON.parse(await stdinText());
@@ -778,6 +826,9 @@ export async function main(argv = process.argv.slice(2)) {
         if (hookRuntime(payload) !== "codex") return emit(result, json, "allowed");
         return;
       } catch (error) {
+        // A known policy denial still blocks. Hook/runtime failures fail open
+        // and stay silent so a broken environment cannot stop the session.
+        if (!["FIGMA_FILE_KEY_MISSING", "FIGMA_LOCK_DENIED"].includes(error?.code)) return;
         if (payload && hookRuntime(payload) === "codex") {
           console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: `Blocked Figma write: ${error?.message ?? String(error)}` } }));
           return;
@@ -791,7 +842,6 @@ export async function main(argv = process.argv.slice(2)) {
       }
     }
     if (action === "safety-pre") {
-      // A malformed or unavailable safety check must not turn into permission.
       let payload;
       try {
         payload = JSON.parse(await stdinText());
@@ -803,6 +853,9 @@ export async function main(argv = process.argv.slice(2)) {
         else for (const nudge of nudges) console.log(nudge);
         return;
       } catch (error) {
+        // Only an evaluated safety rule may deny. Discovery, parsing, git,
+        // config and Dev errors fail open and produce no output.
+        if (!String(error?.code ?? "").startsWith("SAFETY_")) return;
         if (payload && hookRuntime(payload) === "codex") {
           console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: error?.message ?? String(error) } }));
           return;
@@ -821,14 +874,7 @@ export async function main(argv = process.argv.slice(2)) {
         payload = JSON.parse(await stdinText());
         await recordHookFire(payload).catch(() => {});
         await safetyPostHook(payload);
-      } catch (error) {
-        // A post-hook cannot undo a completed command; report state-tracking
-        // failure without making Claude treat the completed command as failed.
-        const message = `nodii-dev safety post hook: ${error?.code ?? "ERROR"}: ${error?.message ?? String(error)}`;
-        if (payload && hookRuntime(payload) === "codex")
-          console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: message } }));
-        else console.error(message);
-      }
+      } catch {}
       return;
     }
     if (action === "lane-heartbeat") {
@@ -854,6 +900,7 @@ export async function main(argv = process.argv.slice(2)) {
         return emit(await postHook(payload), json, "logged");
       } catch (error) {
         const outcome = postHookFailure(error);
+        if (!outcome.exitCode) return;
         if (hookRuntime(payload) === "codex")
           console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: outcome.message } }));
         else {

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.26";
+export const VERSION = "0.6.28";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -199,12 +199,16 @@ export async function checkLogin() {
 export const encode = (value) => encodeURIComponent(value);
 // Switches never take the next token as their value, so
 // `docs upload --wait rulebook/` keeps rulebook/ as a path.
-const SWITCHES = new Set(["json", "wait", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync", "force", "system"]);
+const SWITCHES = new Set(["json", "wait", "pending", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync", "force", "system"]);
 export function parseArgs(argv) {
   const flags = {};
   const args = [];
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
+    if (token === "--") {
+      args.push(...argv.slice(i + 1));
+      break;
+    }
     if (!token.startsWith("--")) {
       args.push(token);
       continue;