@nodii/dev 0.6.27 → 0.6.29

package/README.md

@@ -97,6 +97,8 @@ nodii-dev agent heartbeat
 nodii-dev agents spawn SERVICE [--repo-root DIR]
 nodii-dev agents cowork-tick [--json]
 nodii-dev agents cowork-tick --plist [--interval SECONDS]
+nodii-dev watchdog install [--interval SECONDS]
+nodii-dev watchdog sweep
 
 nodii-dev issues list [--service ID] [--project KEY] [--status STATUS]
                        [--kind KIND] [--priority PRIORITY] [--claimed true|false]
@@ -135,6 +137,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,7 +312,9 @@ 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 resume KEY
 nodii-dev lane review KEY --file REVIEW.json
 nodii-dev lane reviews KEY
 nodii-dev lane land KEY
@@ -345,7 +351,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]
@@ -355,8 +361,22 @@ nodii-dev harness install [--include-drafts] [--adopt PATH,...] [--dry-run] [--s
 nodii-dev harness update [--include-drafts] [--adopt PATH,...] [--dry-run] [--system]
 nodii-dev harness check [--json]               # 0 current, 1 differs from Dev, 2 no harness
 nodii-dev harness update --check               # the same check
+nodii-dev watchdog install [--interval SECONDS] # install/update com.nodii.watchdog in ~/Library/LaunchAgents
+nodii-dev watchdog sweep                        # launchd entrypoint; normally not run by hand
 ```
 
+The per-Mac watchdog runs outside agent sessions. Run `watchdog install` once
+with the machine coordinator's config; it refuses a lane or unassigned agent.
+Every sweep reports three host facts to Dev: watched run processes that exited
+without ending their run, `/tmp/cc-socks/<pid>.sock` sockets whose process is
+gone, and watched worktrees whose HEAD has commits absent from its configured
+remote branch. Each observation is posted to the watched run by the machine
+coordinator; `process_dead` transitions it to explicit `orphan` immediately.
+Run launchers and wrappers persist one owner-only record per process under
+`~/.config/nodii-dev/watchdog/runs/`; the plist itself contains only absolute
+command/config paths, its schedule, and log paths, while OAuth credentials
+remain in the machine keychain.
+
 `harness install` and `harness update` merge the safety hooks into both
 `.claude/settings.json` and `.codex/hooks.json`; every installed hook invokes
 only `nodii-dev`. The
@@ -542,9 +562,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,8 +709,61 @@ 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
 
+`coordinator start --machine NAME` registers the machine's one watched
+coordinator run and shows its running lanes, orphaned runs and unclaimed
+results. A live second coordinator is refused; a coordinator whose heartbeat
+watchdog has recorded it orphaned is recorded as the predecessor of the
+takeover.
+
+`lane launch KEY` replaces the manual worktree/start/process sequence. It
+requires the issue (whose title supplies both lane title and objective), done
+check, build kind and side, runtime profile and model, subagent quota, and
+repeated `--repo NAME=/SOURCE` plus
+`--branch NAME=BRANCH` pairs. The Hub preflight checks the coordinator waiter,
+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
+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
+example `~/.config/nodii-dev/agents/lane-ah-12.json`), never the coordinator's
+Dev identity.
+
+Objective, scope and rule changes are durable `lane amend` records, never chat
+messages. Every CLI call from a launched worktree checks the current watched
+run's acknowledgement version. A pending change is printed and blocks the
+call until `lane gather --delta` serves the current rules and acknowledges the
+newest displayed version. `NODII_DEV_RUN_ID` makes this check per subagent run,
+so one child cannot acknowledge for its siblings.
+
 `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
@@ -697,6 +773,23 @@ 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.
+
+`lane resume` asks Dev to reserve a fresh run for an orphaned lane, then launches
+the allowlisted Codex or Claude runtime as a detached headless process in the
+same worktree. Dev keeps the lane's finished steps intact and returns the next
+unfinished step together with its bounded recovery packet. The CLI sends that
+packet over the new process's stdin (never its argv), saves its exact PID and
+append-only log under `~/.config/nodii-dev/runs/<run-id>/`, and reports a local
+spawn failure back to Dev so the reservation is not left running. Human output
+identifies the replacement run, PID, step and last pushed commit without
+echoing the dead run's log tail; `--json` retains the complete server response.
+Dev refuses a third attempt after two identical deaths.
+
 `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 +871,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

@@ -99,10 +99,12 @@ export const GROUPS = {
   "approval-kinds": "ApprovalKinds", "notification-registry": "Notification registry", skills: "Skills", "open-questions": "OpenQuestions",
   decisions: "Decisions", drift: "Drift", requests: "Requests", pipelines: "Pipelines", slices: "Slices", "sql-lookups": "SqlLookups",
   runners: "Runners", routing: "Routing", usage: "Usage", audit: "AuditLog", reconciliation: "Reconciliation", cron: "Cron", health: "Health",
-  composite: "Composite", "service-edges": "ServiceEdges", lanes: "Lanes",
+  composite: "Composite", "service-edges": "ServiceEdges", lanes: "Lanes", runs: "Runs",
+  releases: "Releases", operate: "Operate",
   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",
 };
@@ -153,6 +155,8 @@ export const ALIASES = {
   "standardizations:list": "listStandardizations", "standardizations:show": "getStandardization", "standardizations:update": "updateStandardization",
   "archive:search": "searchPreDevArchive", "archive:resolve": "resolvePreCitation",
   "harness:show": "generateHarness", "harness:methodology": "getHarnessMethodologyVersion",
+  "runs:register": "registerRun", "runs:show": "getRun", "runs:heartbeat": "heartbeatRun", "runs:end": "endRun",
+  "runs:results": "listRunResults", "runs:acknowledge": "acknowledgeResult",
   "terminology:list": "listTerminology", "terminology:show": "getTerminologyTerm", "terminology:create": "createTerminologyTerm", "terminology:update": "updateTerminologyTerm",
 };
 

package/dist/cli.js

@@ -53,6 +53,7 @@ export { figmaLock, submitMode } from "./figma.js";
 import { docsCommand, rulebookCommand, rulesCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import { designCheck, designCheckText, designRoles, designRolesText } from "./design.js";
+import { watchdogCommand } from "./watchdog.js";
 import {
   ALIASES,
   GROUPS,
@@ -74,6 +75,18 @@ import {
   nextCommand,
   peopleCommand,
 } from "./lanes.js";
+import {
+  amendmentGuard,
+  amendLaneCommand,
+  coordinatorCommand,
+  gatherLaneCommand,
+  launchLaneCommand,
+} from "./starting.js";
+import {
+  launchRunSupervisor,
+  showWaitingResults,
+  superviseRun,
+} from "./runs.js";
 
 const HELP = `nodii-dev ${VERSION}
 
@@ -127,8 +140,10 @@ Usage: nodii-dev <command> [options] [--json]
                                         # --system stages managed hooks and only prints operator-reviewed sudo commands
   harness check                         # 0 current, 1 differs from Dev, 2 not installed
   harness update --check                # the same check
+  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] [--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,11 +152,27 @@ 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)
 
+  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
+              --issue KEY --repo NAME=/SOURCE --branch NAME=BRANCH [--repo ... --branch ...]
+              --machine NAME --runtime claude|codex --profile PATH --model MODEL --subagents N
+              [--base NAME=REF] [--worktree NAME=PATH] [--owned-path NAME=PATH]
+              [--figma FILE[=COMPONENT_SET[,SET]]] [--notes TEXT]
+              [--narrowing-note TEXT --narrowing-remainder DESTINATION]
+                                        # 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]         # infers a launched worktree; Delta required after an amendment
+  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 heartbeat|land|verify|prioritize|deprioritize|stop <key>
+  lane subagent-quota <key> <n>          # coordinator assigns 0-100 subagent slots
+  lane heartbeat|resume|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
   lane non-issue <key> --reason TEXT --evidence TEXT --reroute KEY[,KEY]|none
@@ -164,7 +195,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 +433,55 @@ 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") {
+    await amendmentGuard(argv);
+    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;
@@ -471,6 +548,10 @@ export async function main(argv = process.argv.slice(2)) {
     if (rest.length) throw new CliError("USAGE", `harness ${action} takes no arguments, got: ${rest.join(" ")}. Write a flag value as --include-drafts=false.`, 2);
     return emitCommand(await harnessCommand(action, f));
   }
+  if (command === "watchdog") {
+    if (rest.length) throw new CliError("USAGE", `watchdog ${action ?? ""} takes no arguments, got: ${rest.join(" ")}.`, 2);
+    return emitCommand(await watchdogCommand(action, f));
+  }
   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));
@@ -489,6 +570,10 @@ export async function main(argv = process.argv.slice(2)) {
     }
     return;
   }
+  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") return emitCommand(await laneCommand(action, rest, f));
   if (command === "next") return emitCommand(await nextCommand(action, f));
   if (command === "built") return emitCommand(await builtCommand(action, rest, f));

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.27";
+export const VERSION = "0.6.29";
 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", "delta"]);
 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;