@nodii/dev 0.6.28 → 0.6.30

package/README.md

@@ -87,7 +87,7 @@ nodii-dev login [--no-browser] [--scope KEYS] [--force]
 nodii-dev logout
 nodii-dev whoami                   # OAuth identity plus the registered agent
 nodii-dev config show
-nodii-dev doctor [--figma-file KEY] [--json]   # preflight: everything a lane needs, read-only
+nodii-dev doctor [--figma-file KEY] [--json]   # preflight: Dev, hooks, local Ollama + Gather model, optional Figma
 
 nodii-dev api list [--tag TAG] [--json]
 nodii-dev api OPERATION_ID [--param name=value ...] [--body @file|-|JSON]
@@ -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]
@@ -127,6 +129,15 @@ nodii-dev decisions get D123
 nodii-dev decisions search WORDS
 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 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 open-questions list|show|answer
 nodii-dev feature-docs list|show|claim|release|status
 nodii-dev contracts grpc|rest|outbox|saga|table publish|status
@@ -312,6 +323,7 @@ nodii-dev lane step KEY --side backend|frontend --start|--done|--block STEP [--r
 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
@@ -358,8 +370,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
@@ -718,6 +744,42 @@ 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.
+
+Gather also persists the lane's bounded Freeze: the objective and done check,
+strict repository/Figma boundaries, the current pinned clauses, and the lane's
+lookups, decisions, and unconfirmed questions. Ordinary CLI calls print and
+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.
+
 `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
@@ -733,6 +795,17 @@ 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

package/dist/api.js

@@ -99,7 +99,8 @@ 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",
@@ -154,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

@@ -26,6 +26,7 @@ import { harnessCommand } from "./harness.js";
 import { hookRuntime, recordHookFire, safetyPostHook, safetyPreHook } from "./safety.js";
 import { doctorCommand } from "./doctor.js";
 import { dispatchManagedHook } from "./managed-hooks.js";
+import { freezeCommand } from "./freeze.js";
 import {
   figmaChangeSetShow,
   figmaChangeSetText,
@@ -53,6 +54,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 +76,13 @@ import {
   nextCommand,
   peopleCommand,
 } from "./lanes.js";
+import {
+  amendmentGuard,
+  amendLaneCommand,
+  coordinatorCommand,
+  gatherLaneCommand,
+  launchLaneCommand,
+} from "./starting.js";
 import {
   launchRunSupervisor,
   showWaitingResults,
@@ -87,8 +96,8 @@ Usage: nodii-dev <command> [options] [--json]
   login [--force] | logout | whoami | config show
                                         # login says so when the machine is already signed in; --force
                                         # replaces that one sign-in (never from a lane)
-  doctor [--figma-file KEY] [--json]    # preflight: sign-in, agent, permissions, machine, repo, lane slots
-                                        # and, given a key (or NODII_DEV_FIGMA_FILE), that Figma file's registration
+  doctor [--figma-file KEY] [--json]    # preflight: sign-in, agent, permissions, machine, repo, lane slots,
+                                        # local Ollama + pinned Gather model, and optional Figma registration
   agent register --name NAME | agent heartbeat
   issues list|show|create|update|claim|release
   issues comment ISSUE --body TEXT      # or --body-file FILE; issues update --comment TEXT|--comment-file FILE adds one too
@@ -127,11 +136,13 @@ Usage: nodii-dev <command> [options] [--json]
   figma file add FILE_KEY --name TEXT --kind design-system|surfaces|prototype [--module M]
                                         # register a Figma file in Dev so it can be locked
   hook claude-figma-pre|claude-figma-post|safety-pre|safety-post|session-start|managed-dispatch|print-settings
-  setup [--yes|--check]                 # dry-run by default
+  setup [--yes|--check]                 # dry-run by default; installs/checks Ollama and pulls the Gather model
   harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--system]
                                         # --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] [--pending] [--conformance-ref REF]
        [--meaning-unchanged REASON] [--wait]
@@ -140,8 +151,21 @@ Usage: nodii-dev <command> [options] [--json]
   rulebook list|show CODE [--version V]|diff CODE
   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 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] [--objective TEXT] [--done-check TEXT]
+                                        # infers a launched worktree; explicit contract inputs support manual lane start
   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
@@ -151,15 +175,21 @@ Usage: nodii-dev <command> [options] [--json]
                                         # --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 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 freeze add <key> --section SECTION --file ITEM.json --reason TEXT
+  lane freeze drop <key> --section SECTION --item ID --reason TEXT
+  lane freeze swap <key> --section SECTION [--item ID] --file VALUE.json --reason TEXT
+  lane freeze show|history <key>         # durable compact-safe contract and all versions
   lane non-issue <key> --reason TEXT --evidence TEXT --reroute KEY[,KEY]|none
                  --branch carried:KEY|dropped[:REASON] [--commits SHA[,SHA]]
                                         # DEC-0011: terminal non_issue; issue -> wont_do; slot frees
   lane list [--kind KIND] [--status STATUS] [--mine] [--cursor CURSOR]
   lane show <key> | next <key> [--paths A,B] [--components K,L] [--role R]
                                         # next step, plus the rules Dev serves for it (DEC-0020)
+  lane gather [key] [--delta] [--paths A,B] [--components K,L]
+                                        # local document pick; prints Lane contract then Clause map
   built list | built ack <key...>
   machine list|show|set-coordinator|assign|report
   agent lane-limit|grant|revoke
@@ -412,8 +442,12 @@ export async function figmaFileAdd(value, flags, { request = devRequest } = {})
 }
 
 export async function main(argv = process.argv.slice(2)) {
-  if (argv[0] !== "__run-supervisor")
+  // 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]))
@@ -523,6 +557,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));
@@ -541,6 +579,12 @@ 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" && action === "freeze")
+    return emitCommand(await freezeCommand(rest[0], rest.slice(1), 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.28";
+export const VERSION = "0.6.30";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -119,9 +119,30 @@ const staleCode = (raw) => {
   }
 };
 
-async function devFetch(method, path, bodyText, contentType, accept, extra = {}) {
-  const config = await readConfig();
-  const auth = await authProvider();
+const withSignal = (promise, signal) => {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason ?? new Error("aborted"));
+  return new Promise((resolvePromise, rejectPromise) => {
+    const abort = () => rejectPromise(signal.reason ?? new Error("aborted"));
+    signal.addEventListener("abort", abort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => { signal.removeEventListener("abort", abort); resolvePromise(value); },
+      (error) => { signal.removeEventListener("abort", abort); rejectPromise(error); },
+    );
+  });
+};
+
+async function devFetch(method, path, bodyText, contentType, accept, extra = {}, signal) {
+  const wait = async (promise) => {
+    try {
+      return await withSignal(promise, signal);
+    } catch (error) {
+      if (signal?.aborted) throw new CliError("DEV_TIMEOUT", `Dev request timed out: ${method} ${path}`, 1);
+      throw error;
+    }
+  };
+  const config = await wait(readConfig());
+  const auth = await wait(authProvider());
   const url = requestUrl(config, path);
   // The edge refuses a token minted before the principal's claims epoch with
   // 401 token_stale (refresh and retry once). The request never reached Dev,
@@ -132,26 +153,28 @@ async function devFetch(method, path, bodyText, contentType, accept, extra = {})
   for (;;) {
     const headers = { accept, ...extra };
     if (bodyText !== undefined) headers["content-type"] = contentType;
-    Object.assign(headers, await auth.headers({ method, path, body: bodyText ?? "" }));
+    Object.assign(headers, await wait(auth.headers({ method, path, body: bodyText ?? "" })));
     let response;
     try {
-      response = await fetch(url, { method, headers, body: bodyText });
+      response = await wait(fetch(url, { method, headers, body: bodyText, signal }));
     } catch (error) {
+      if (error?.code === "DEV_TIMEOUT") throw error;
+      if (signal?.aborted) throw new CliError("DEV_TIMEOUT", `Dev request timed out: ${method} ${path}`, 1);
       throw new CliError("DEV_UNREACHABLE", `Cannot reach Dev at ${new URL(url).origin}: ${error.message}`);
     }
-    const raw = await response.text();
+    const raw = await wait(response.text());
     if (response.status !== 401 || typeof auth.refreshStale !== "function" || !staleCode(raw)) return { response, raw };
     if (refreshed) return { response, raw };
     // A cached token that is stale too is not adopted twice: the next one is refreshed.
     const used = String(headers.authorization ?? "").replace(/^Bearer /, "");
-    if ((await auth.refreshStale(used, { force: adopted })) === "refreshed") refreshed = true;
+    if ((await wait(auth.refreshStale(used, { force: adopted }))) === "refreshed") refreshed = true;
     else adopted = true;
   }
 }
 
 /** A JSON call that keeps the status: `{ status, payload }`. Errors throw as devRawRequest's do. */
-export async function devExchange(method, path, bodyText, { contentType = "application/json", headers = {} } = {}) {
-  const { response, raw } = await devFetch(method, path, bodyText, contentType, "application/json", headers);
+export async function devExchange(method, path, bodyText, { contentType = "application/json", headers = {}, signal } = {}) {
+  const { response, raw } = await devFetch(method, path, bodyText, contentType, "application/json", headers, signal);
   let payload;
   try {
     payload = raw ? JSON.parse(raw) : {};
@@ -168,8 +191,8 @@ export async function devExchange(method, path, bodyText, { contentType = "appli
   return { status: response.status, payload };
 }
 
-export async function devRawRequest(method, path, bodyText, contentType = "application/json") {
-  return (await devExchange(method, path, bodyText, { contentType })).payload;
+export async function devRawRequest(method, path, bodyText, contentType = "application/json", options = {}) {
+  return (await devExchange(method, path, bodyText, { ...options, contentType })).payload;
 }
 
 /** A Dev route that answers with text (e.g. a document body as text/markdown). Errors are Dev's JSON. */
@@ -181,8 +204,8 @@ export async function devTextRequest(method, path) {
   throw new CliError(payload.code ?? `HTTP_${response.status}`, payload.message ?? `Dev returned HTTP ${response.status}`, 1, payload.details);
 }
 
-export const devRequest = (method, path, body) =>
-  devRawRequest(method, path, body === undefined ? undefined : JSON.stringify(body));
+export const devRequest = (method, path, body, options) =>
+  devRawRequest(method, path, body === undefined ? undefined : JSON.stringify(body), "application/json", options);
 
 /** A JSON call sent with `Prefer: respond-async` (RFC 7240): `{ status, payload }`, 202 when Dev took it as a job. */
 export const devAsyncRequest = async (method, path, body) =>
@@ -199,7 +222,7 @@ 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", "pending", "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 = [];