@nodii/dev 0.6.3 → 0.6.5

package/README.md

@@ -45,7 +45,9 @@ asks you to run `nodii-dev login`.
 `nodii-dev` is only the Dev control CLI. The local-stack CLI is `./nodii-stack`,
 run from the `nodii-local-stack` checkout (renamed per operator ruling G3-6,
 with no alias under the old name). Typing one of its verbs here, such as
-`nodii-dev doctor`, fails and names the `./nodii-stack` command instead.
+`nodii-dev provenance`, fails and names the `./nodii-stack` command instead.
+`nodii-dev doctor` is this CLI's own preflight (below); `./nodii-stack doctor`
+checks the local stack.
 
 Every command accepts `--json`; without it, output is formatted for humans.
 Dev failures print Dev's error code to stderr and exit non-zero.
@@ -57,6 +59,7 @@ nodii-dev login [--no-browser] [--scope KEYS]
 nodii-dev logout
 nodii-dev whoami                   # OAuth identity plus the registered agent
 nodii-dev config show
+nodii-dev doctor [--json]          # preflight: everything a lane needs, read-only
 
 nodii-dev api list [--tag TAG] [--json]
 nodii-dev api OPERATION_ID [--param name=value ...] [--body @file|-|JSON]
@@ -75,6 +78,8 @@ nodii-dev issues create --service ID --title TEXT [--body TEXT|--body-file FILE]
 nodii-dev issues update ISSUE [the same mutable fields]
 nodii-dev issues claim ISSUE [--ttl MINUTES]
 nodii-dev issues release ISSUE [--note TEXT]
+nodii-dev issues transition ISSUE --to todo|in_progress|in_review|blocked|done|wont_do
+                            [--reason TEXT] [--dev-check REF] [--json]
 
 nodii-dev inbox list [--service ID] [--kind drift|request|question]
 nodii-dev inbox show drift|request|question ID
@@ -191,7 +196,33 @@ nodii-dev docs parked [CODE] [--status pending|acknowledged]
 
 nodii-dev harness install [--include-drafts] [--adopt PATH,...] [--dry-run]
 nodii-dev harness update [--include-drafts] [--adopt PATH,...] [--dry-run]
-nodii-dev harness update --check               # exit 1 when Dev would write anything different
+nodii-dev harness check [--json]               # 0 current, 1 differs from Dev, 2 no harness
+nodii-dev harness update --check               # the same check
+```
+
+### Moving an issue: `issues transition`
+
+`issues transition` moves an issue along Dev's status map (MW1-16) with
+Dev's `transitionIssue` operation. It checks MW1-17 before sending anything,
+and refuses with `USAGE` (exit 2) when a move lacks what it needs:
+
+| `--to` | Needs |
+|---|---|
+| `blocked` | `--reason` naming the blocking condition and who or what clears it (`cleared by …`, `waiting on …`, `until …`) |
+| `wont_do` | `--reason` saying why |
+| `done` | `--dev-check REF` citing the lane's dev-check evidence (MW3-36); a merge alone never makes an issue done |
+
+`--reason` and `--dev-check` are optional for the other moves, and
+`--dev-check` goes only with `done`. Dev keeps one note per transition, so
+the CLI sends the reason, then `Dev check: REF` on its own line, as that
+note. A move Dev refuses (for example `ISSUE_ILLEGAL_TRANSITION`, with the
+allowed set in its details, or `CLAIM_HELD_BY_OTHER`) exits 1 with Dev's
+error code unchanged (MW1-61).
+
+```text
+nodii-dev issues transition TKT-412 --to blocked \
+  --reason "edge route /tickets 404s on dev; cleared by the nodii-edge lane deploying it"
+nodii-dev issues transition TKT-412 --to done --dev-check "lane:tkt-412 dev probe GET /tickets/412 200"
 ```
 
 ## AD documents
@@ -252,10 +283,50 @@ source documents moved, and each file created, updated or removed. It
 removes only files, blocks and hook entries it wrote, and it refuses (writing
 nothing) when one of its files was edited by hand.
 
+`harness check` (MW5-4) compares the repository with what Dev would generate
+now and writes nothing. `harness update --check` is the same check. It asks
+Dev with the options install recorded, and exits:
+
+- `0` when every file matches and the stamp names the methodology version Dev
+  serves: `Harness is current: REPO, methodology VERSION, N files match Dev.`
+- `1` when anything differs. It prints one line per difference: the
+  methodology version, each source document that moved, each file that is
+  missing, differs from Dev's or is no longer generated, and each file edited
+  by hand since nodii-dev wrote it. `--json` gives the same as `current`,
+  `installed`, `available`, `sources`, `changes` and `conflicts`.
+- `2` with `HARNESS_NOT_INSTALLED` when the repository has no harness. The
+  message lists the files `harness install` would write.
+
+Inside a lane, a failed check is noted in the step, and the harness files
+are left alone; the repository's orchestrator runs `harness update` in a
+`chore` lane (MW5-8).
+
+## Preflight: `doctor`
+
+Run `nodii-dev doctor` from the lane's worktree, with the lane agent's config,
+before `lane start`. It only reads, and prints one line per check: `OK`,
+`MISSING` (with the command that fixes it) or `CANNOT CHECK` (with why). It
+exits 0 only when every check is `OK`. `--json` returns the same checks as
+`{ data: { ok, configPath, configSource, checks: [{ key, status, message, fix?, ... }] } }`.
+
+| Check | What it reads |
+| --- | --- |
+| `config` | Which config file is in use: `NODII_DEV_CONFIG_PATH` or the default `~/.config/nodii-dev/config.json`, and whether it is an OAuth login. |
+| `signed_in` | The refresh credential in the keychain, and an access token from it. When nodii-auth rejects the sign-in, it says whether the grant **expired**, was **revoked** or was **replaced**, if the server named which (otherwise it says the server did not). A rejected credential is reported, never cleared. |
+| `agent` | The agent on this config (`agentId`), as Dev reads it back. |
+| `permissions` | The sign-in's permissions against what lane commands need (`devops.issues`, `lanes`, `agents` `.read`/`.write`, `devops.machines.manage`, `devops.decisions.read`/`.write`/`.lock` for Figma locks, `devops.rulebook.read`). Each missing key is listed, with whether the installation has not consented to it or no role grants it. |
+| `machine` | The machine this agent is assigned to and its coordinator. No machine means `lane start` would fail with `MACHINE_REQUIRED`. |
+| `repo` | Whether the repository in this directory is the agent's home repository or granted to it. Repositories are compared by short name (`nodii-clis`, not `owner/nodii-clis`), as Dev compares them. Dev does not let an OAuth agent read its own grants yet (requested in Dev), so a repository other than the home one is `CANNOT CHECK`. |
+| `lane_limit` | The agent's active lanes against its lane limit. A full limit is `OK` when a lane on this branch holds the slot. |
+
+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).
+
 ## Build lanes and repository setup
 
-`lane start` creates and starts a lane. It infers the repository, branch and
-worktree from git unless overridden, and resolves `--issue` keys to the UUIDs
+`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
 acknowledgement route. `next` reads the lane's generated
 API steps and prints the exact next `lane step` command. Server refusals,

package/dist/cli.js

@@ -25,6 +25,7 @@ import {
 import { heartbeatCurrentLane, postHook, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
 import { setupCommand } from "./setup.js";
 import { harnessCommand } from "./harness.js";
+import { doctorCommand } from "./doctor.js";
 import { docsCommand, rulebookCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import {
@@ -54,8 +55,11 @@ const HELP = `nodii-dev ${VERSION}
 Usage: nodii-dev <command> [options] [--json]
 
   login | logout | whoami | config show
+  doctor [--json]                       # preflight: sign-in, agent, permissions, machine, repo, lane slots
   agent register --name NAME | agent heartbeat
   issues list|show|create|update|claim|release
+  issues transition ISSUE --to STATUS [--reason TEXT] [--dev-check REF]
+                                        # blocked and wont_do need --reason; done needs --dev-check
   inbox list|show
   drift file | request file
   decisions list|get|search
@@ -67,7 +71,8 @@ Usage: nodii-dev <command> [options] [--json]
   hook claude-figma-pre|claude-figma-post|print-settings
   setup [--yes|--check]                 # dry-run by default
   harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run]
-  harness update --check                # exit 1 when Dev would write anything different
+  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]
        [--meaning-unchanged REASON] [--wait]
@@ -101,7 +106,8 @@ Run a command with --help or see the package README for all flags.`;
 
 // Verbs of the local-stack CLI, which shared this name until it became
 // ./nodii-stack (operator G3-6, no alias). Named here only to point there.
-const STACK_VERBS = new Set(["up", "down", "doctor", "sync", "seed", "wipe", "reset", "rebuild", "restart", "smoke", "urls", "peek", "trace", "stats", "bootstrap", "provenance", "stale", "status", "logs", "world", "totp", "token", "bench"]);
+// `doctor` is not one of them: `nodii-dev doctor` is this CLI's own preflight.
+const STACK_VERBS = new Set(["up", "down", "sync", "seed", "wipe", "reset", "rebuild", "restart", "smoke", "urls", "peek", "trace", "stats", "bootstrap", "provenance", "stale", "status", "logs", "world", "totp", "token", "bench"]);
 
 async function stdinText() {
   let value = "";
@@ -221,9 +227,44 @@ async function issues(action, args, f, json) {
       }),
       json,
     );
+  if (action === "transition")
+    return emit(
+      await devRequest("POST", `/api/v1/issues/${encode(ref)}/transition`, {
+        ...transitionBody(f),
+        onBehalfOf: config.person,
+      }),
+      json,
+      (p) => `${p.data.key} ${p.data.status} — ${p.data.title}`,
+    );
   throw new CliError("USAGE", `Unknown issues action: ${action}`, 2);
 }
 
+const ISSUE_STATUSES = ["todo", "in_progress", "in_review", "blocked", "done", "wont_do"];
+// A blocked reason names who or what clears it: "cleared by", "unblocks", "waiting on", "until".
+const CLEARED_BY = /\b(clear(s|ed)?|unblock(s|ed)?|wait(s|ing)? (on|for)|until)\b/i;
+
+/**
+ * transitionIssue's body ({ to, note }), with MW1-17 checked before anything
+ * is sent. Dev stores no separate reason or dev-check field: both go in the note.
+ */
+export function transitionBody(f) {
+  const to = requireFlag(f, "to");
+  if (!ISSUE_STATUSES.includes(to))
+    throw new CliError("USAGE", `--to must be one of ${ISSUE_STATUSES.join(", ")}`, 2);
+  const reason = typeof f.reason === "string" ? f.reason.trim() : "";
+  const devCheck = typeof f["dev-check"] === "string" ? f["dev-check"].trim() : "";
+  if (f["dev-check"] !== undefined && to !== "done")
+    throw new CliError("USAGE", "--dev-check goes with --to done", 2);
+  if (to === "blocked" && !CLEARED_BY.test(reason))
+    throw new CliError("USAGE", 'A move to blocked needs --reason naming the blocking condition and who or what clears it (MW1-17), e.g. --reason "waiting on PR #12 in nodii-edge; cleared by the edge lane merging it"', 2);
+  if (to === "wont_do" && !reason)
+    throw new CliError("USAGE", "A move to wont_do needs --reason saying why (MW1-17)", 2);
+  if (to === "done" && !devCheck)
+    throw new CliError("USAGE", "A move to done needs --dev-check REF citing the lane's dev-check evidence (MW1-17, MW3-36). A merge alone never makes an issue done.", 2);
+  const note = [reason, devCheck && `Dev check: ${devCheck}`].filter(Boolean).join("\n");
+  return { to, ...(note ? { note } : {}) };
+}
+
 export async function main(argv = process.argv.slice(2)) {
   if (argv.length === 1 && ["--version", "-v"].includes(argv[0]))
     return console.log(VERSION);
@@ -272,7 +313,14 @@ export async function main(argv = process.argv.slice(2)) {
   }
   const emitCommand = async (result) => emit(result.payload, json, result.human);
   if (command === "setup") return emitCommand(await setupCommand(f));
-  if (command === "harness" && ["install", "update"].includes(action)) {
+  if (command === "doctor") {
+    if (action) throw new CliError("USAGE", `doctor takes no arguments, got: ${[action, ...rest].join(" ")}`, 2);
+    const result = await doctorCommand();
+    emit(result.payload, json, result.human);
+    if (result.exitCode) process.exitCode = result.exitCode;
+    return;
+  }
+  if (command === "harness" && ["install", "update", "check"].includes(action)) {
     // `--include-drafts` is a switch: `--include-drafts false` would leave `false` here and turn drafts on.
     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));

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

package/dist/doctor.js

@@ -0,0 +1,235 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { devRequest, encode, isOAuthConfig, query, setAuthProvider } from "./core.js";
+import { OAuthAuthProvider, decodeClaims, loadRefreshToken } from "./oauth.js";
+import { inferGitContext, repoName } from "./lanes.js";
+
+/**
+ * What a lane's commands need, in Dev's route policy (staffRuleFor in Dev's
+ * src/lib/auth/staff-policy.ts): an area's reads need `.read` and its writes
+ * `.write`; every machine route needs `machines.manage`; Figma file locks live
+ * in the decisions area, and releasing one needs `decisions.lock`. Dev's
+ * OpenAPI does not name the permission per operation, so this table is kept
+ * by hand.
+ */
+export const LANE_PERMISSIONS = [
+  { key: "devops.issues.read", for: "issues list|show" },
+  { key: "devops.issues.write", for: "issues create|update|claim|release|transition" },
+  { key: "devops.lanes.read", for: "lane show|list, next" },
+  { key: "devops.lanes.write", for: "lane start|step|evidence|heartbeat|review|land|verify" },
+  { key: "devops.agents.read", for: "whoami, reading this agent" },
+  { key: "devops.agents.write", for: "agent register|heartbeat" },
+  { key: "devops.machines.manage", for: "machine show (this agent's machine and coordinator)" },
+  { key: "devops.decisions.read", for: "figma check" },
+  { key: "devops.decisions.write", for: "figma lock|log-write|submit|apply|published|abandon" },
+  { key: "devops.decisions.lock", for: "figma release" },
+  { key: "devops.rulebook.read", for: "rulebook show" },
+];
+
+// Lane statuses that hold one of the agent's lane slots (Dev's ACTIVE set).
+const ACTIVE = new Set(["queued", "building", "built", "review", "on_main"]);
+const LABEL = { ok: "OK", missing: "MISSING", cannot_check: "CANNOT CHECK" };
+
+const ok = (key, message, extra = {}) => ({ key, status: "ok", message, ...extra });
+const missing = (key, message, fix, extra = {}) => ({ key, status: "missing", message, ...(fix ? { fix } : {}), ...extra });
+const cannot = (key, message, extra = {}) => ({ key, status: "cannot_check", message: `cannot check: ${message}`, ...extra });
+const devReason = (error) => [error.code, error.details?.reason].filter(Boolean).join(" ") + (error.message ? `: ${error.message}` : "");
+
+/** expired, revoked, replaced, or unspecified — only what nodii-auth said. */
+export function grantReason(grant = {}) {
+  if (grant.error === "expired_token") return "expired";
+  if (grant.error === "token_revoked") return "revoked";
+  const said = String(grant.description ?? "").toLowerCase();
+  if (/revok/.test(said)) return "revoked";
+  if (/expir/.test(said)) return "expired";
+  if (/reuse|replay|rotat|replac|supersed/.test(said)) return "replaced";
+  return "unspecified";
+}
+
+async function readConfigFile(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    return { unreadable: error?.code ?? String(error) };
+  }
+  try { return JSON.parse(raw); } catch { return {}; }
+}
+
+/** A provider that never clears a rejected credential: doctor only looks. */
+export function lookingProvider(options = {}) {
+  const provider = new OAuthAuthProvider({ ...options, deleteToken: async () => {}, deleteAccess: async () => {} });
+  setAuthProvider(provider);
+  return provider;
+}
+
+async function allLanes(request, agentId) {
+  const lanes = [];
+  let cursor;
+  do {
+    const page = await request("GET", `/api/v1/lanes${query({ agent: agentId, cursor, limit: 200 })}`);
+    lanes.push(...(page.data ?? []));
+    cursor = page.nextCursor ?? undefined;
+  } while (cursor);
+  return lanes;
+}
+
+/**
+ * `nodii-dev doctor`: read-only preflight of everything a lane needs, so a
+ * missing permission, machine or grant shows before the lane starts.
+ */
+export async function doctorCommand(deps = {}) {
+  const env = deps.env ?? process.env;
+  const path = env.NODII_DEV_CONFIG_PATH ?? (deps.defaultConfigPath ?? (() => join(homedir(), ".config/nodii-dev/config.json")))();
+  const configSource = env.NODII_DEV_CONFIG_PATH ? "NODII_DEV_CONFIG_PATH" : "default";
+  const request = deps.request ?? devRequest;
+  const prefix = env.NODII_DEV_CONFIG_PATH ? `NODII_DEV_CONFIG_PATH=${env.NODII_DEV_CONFIG_PATH} ` : "";
+  const loginFix = `${prefix}nodii-dev login`;
+  const checks = [];
+
+  // 1. Config, and which file.
+  const config = await (deps.readConfigFile ?? readConfigFile)(path);
+  const configOk = isOAuthConfig(config);
+  if (config === null) checks.push(missing("config", `no config at ${path} (${configSource})`, loginFix));
+  else if (config.unreadable) checks.push(missing("config", `cannot read ${path} (${config.unreadable})`, `check the file's permissions, or ${loginFix}`));
+  else if (!configOk) checks.push(missing("config", `${path} is not an OAuth login (written before 0.5.0, or not valid JSON)`, loginFix));
+  else checks.push(ok("config", `${path} (${configSource})`));
+
+  // 2. Signed in: a stored credential, and an access token from it.
+  let claims = null;
+  if (!configOk) checks.push(missing("signed_in", "not signed in", loginFix));
+  else {
+    let stored = false;
+    try {
+      await (deps.loadRefreshToken ?? loadRefreshToken)(config.clientId);
+      stored = true;
+    } catch {
+      checks.push(missing("signed_in", "no stored sign-in credential for this app in the keychain", loginFix));
+    }
+    if (stored) {
+      try {
+        const token = await (deps.accessToken ?? (() => lookingProvider().accessToken()))();
+        claims = (deps.decodeClaims ?? decodeClaims)(token);
+        const minutes = Number.isFinite(claims.exp) ? Math.max(0, Math.floor((claims.exp * 1000 - Date.now()) / 60_000)) : null;
+        checks.push(ok("signed_in", `as person ${claims.sub ?? config.person} through installation ${config.installationId ?? "unknown"}${minutes === null ? "" : `; access token valid ${minutes} min`}`,
+          { person: claims.sub ?? config.person, installationId: config.installationId ?? null }));
+      } catch (error) {
+        if (error?.code === "OAUTH_LOGIN_REQUIRED" && error.details?.grant) {
+          const reason = grantReason(error.details.grant);
+          const why = reason === "unspecified"
+            ? `nodii-auth rejected the sign-in (${error.details.grant.error ?? "invalid_grant"}) and did not say whether it expired, was revoked or was replaced`
+            : `nodii-auth rejected the sign-in: ${reason}`;
+          checks.push(missing("signed_in", why, loginFix, { reason }));
+        } else if (error?.code === "OAUTH_LOGIN_REQUIRED") checks.push(missing("signed_in", "no stored sign-in credential for this app in the keychain", loginFix));
+        else if (error?.code === "OAUTH_REFRESH_FAILED") checks.push(missing("signed_in", error.message, loginFix));
+        else checks.push(cannot("signed_in", `${error?.code ?? "ERROR"}: ${error?.message ?? error}`));
+      }
+    }
+  }
+  const signedIn = claims !== null;
+
+  // 3. Agent registered on this config and recognised by Dev.
+  let agent = null;
+  const registerFix = `${prefix}nodii-dev agent register --name NAME`;
+  if (!signedIn) checks.push(cannot("agent", "needs a sign-in"));
+  else if (!config.agentId) checks.push(missing("agent", `no agent registered on ${path}`, registerFix));
+  else {
+    try {
+      agent = (await request("GET", `/api/v1/agents/${encode(config.agentId)}`)).data;
+      if (agent.status === "disconnected") {
+        checks.push(missing("agent", `agent ${agent.name} (${agent.id}) is disconnected`, registerFix));
+        agent = null;
+      } else checks.push(ok("agent", `${agent.name} (${agent.id}), ${agent.status}, role ${agent.role}`, { agentId: agent.id, name: agent.name }));
+    } catch (error) {
+      checks.push(missing("agent", `Dev does not recognise agent ${config.agentId} (${devReason(error)})`, registerFix));
+    }
+  }
+
+  // 4. Permissions: the installation's consent and the person's roles, as the token carries them.
+  if (!signedIn) checks.push(cannot("permissions", "needs a sign-in"));
+  else if (!Array.isArray(claims.permissions)) checks.push(cannot("permissions", "the access token carries no permissions claim"));
+  else {
+    const granted = new Set(claims.permissions);
+    const consented = new Set(Array.isArray(claims.grant_scope) ? claims.grant_scope : claims.permissions);
+    const gaps = LANE_PERMISSIONS.filter((x) => !granted.has(x.key)).map((x) => ({ key: x.key, for: x.for, why: consented.has(x.key) ? "no_role" : "not_consented" }));
+    if (!gaps.length) checks.push(ok("permissions", `all ${LANE_PERMISSIONS.length} permissions a lane needs are granted`, { missing: [] }));
+    else {
+      const text = gaps.map((x) => `${x.key} (${x.why === "not_consented" ? "installation has not consented" : "consented, but no role grants it"}; for ${x.for})`).join(", ");
+      const fixes = [
+        ...(gaps.some((x) => x.why === "not_consented") ? [`re-consent the nodii-dev installation, then ${loginFix}`] : []),
+        ...(gaps.some((x) => x.why === "no_role") ? ["ask a Dev admin for a role that grants the missing keys, then sign in again"] : []),
+      ];
+      checks.push(missing("permissions", `missing ${text}`, fixes.join("; "), { missing: gaps }));
+    }
+  }
+
+  // 5. Machine and its coordinator.
+  if (!agent) checks.push(cannot("machine", "needs a registered agent"));
+  else if (!agent.machineId)
+    checks.push(missing("machine", "this agent is not assigned to a machine; lane start fails with MACHINE_REQUIRED",
+      `ask the machine's coordinator: nodii-dev machine assign <machine> ${agent.id} --home-repo <repo>`));
+  else {
+    try {
+      const machine = (await request("GET", `/api/v1/machines/${encode(agent.machineId)}`)).data;
+      const coordinator = (machine.agents ?? []).find((x) => x.id === machine.coordinatorAgentId);
+      checks.push(ok("machine", `${machine.name} (${machine.id}); coordinator ${machine.coordinatorAgentId ? `${coordinator?.name ?? "agent"} (${machine.coordinatorAgentId})` : "none set"}`,
+        { machineId: machine.id, machineName: machine.name, coordinatorAgentId: machine.coordinatorAgentId ?? null, coordinatorName: coordinator?.name ?? null }));
+    } catch (error) {
+      checks.push(cannot("machine", `assigned to ${agent.machineId}, but getMachine failed (${devReason(error)})`, { machineId: agent.machineId }));
+    }
+  }
+
+  // 6. Home repo or a grant for the repository in this directory, by short name.
+  let context = null;
+  if (!agent) checks.push(cannot("repo", "needs a registered agent"));
+  else {
+    try {
+      context = await (deps.gitContext ?? inferGitContext)();
+    } catch (error) {
+      checks.push(cannot("repo", `${error?.code === "GIT_REQUIRED" ? "not in a git worktree on a branch" : (error?.message ?? error)}; run doctor from the lane's worktree`));
+    }
+    if (context) {
+      const repo = repoName(context.repo);
+      if (agent.homeRepo && repoName(agent.homeRepo) === repo) checks.push(ok("repo", `${repo} is this agent's home repository`, { repo, homeRepo: agent.homeRepo }));
+      else {
+        try {
+          const grants = (await request("GET", `/api/v1/agents/${encode(agent.id)}/repo-grants`)).data ?? [];
+          if (grants.some((x) => !x.revokedAt && repoName(x.repo) === repo)) checks.push(ok("repo", `${repo} is granted to this agent (home ${agent.homeRepo ?? "none"})`, { repo, homeRepo: agent.homeRepo ?? null }));
+          else checks.push(missing("repo", `${repo} is neither the home repository (${agent.homeRepo ?? "none"}) nor granted; lane start fails with REPO_NOT_GRANTED`,
+            `nodii-dev agent grant ${agent.id} ${repo}`, { repo, homeRepo: agent.homeRepo ?? null }));
+        } catch (error) {
+          checks.push(cannot("repo", `${repo} is not the home repository (${agent.homeRepo ?? "none"}), and listAgentRepoGrants failed (${devReason(error)})`, { repo, homeRepo: agent.homeRepo ?? null }));
+        }
+      }
+    }
+  }
+
+  // 7. Lane limit: a free slot, or a lane on this branch already holding one.
+  if (!agent) checks.push(cannot("lane_limit", "needs a registered agent"));
+  else {
+    try {
+      const active = (await allLanes(request, agent.id)).filter((x) => ACTIVE.has(x.status));
+      const limit = agent.laneLimit ?? 1;
+      const here = (x) => x.branch === context.branch && (!Array.isArray(x.repos) || x.repos.map(repoName).includes(repoName(context.repo)));
+      const mine = context && active.find(here);
+      const keys = active.map((x) => x.key).join(", ");
+      const extra = { active: active.length, limit, lanes: active.map((x) => x.key) };
+      if (active.length < limit) checks.push(ok("lane_limit", `${active.length} of ${limit} lane slots in use${keys ? ` (${keys})` : ""}`, extra));
+      else if (mine) checks.push(ok("lane_limit", `${active.length} of ${limit} lane slots in use; ${mine.key} on this branch holds one`, extra));
+      else checks.push(missing("lane_limit", `${active.length} of ${limit} lane slots in use (${keys}); lane start fails with LANE_LIMIT_REACHED`,
+        `land or stop a lane, or ask the coordinator: nodii-dev agent lane-limit ${agent.id} <n>`, extra));
+    } catch (error) {
+      checks.push(cannot("lane_limit", `listLanes failed (${devReason(error)})`));
+    }
+  }
+
+  const ready = checks.every((x) => x.status === "ok");
+  const width = Math.max(...checks.map((x) => x.key.length));
+  const human = (p) => [
+    ...p.data.checks.map((x) => `${LABEL[x.status].padEnd(12)} ${x.key.padEnd(width)}  ${x.message}${x.fix ? ` — fix: ${x.fix}` : ""}`),
+    p.data.ok ? "Ready for a lane." : `Not ready: ${p.data.checks.filter((x) => x.status !== "ok").map((x) => x.key).join(", ")}.`,
+  ].join("\n");
+  return { payload: { data: { ok: ready, configPath: path, configSource, checks } }, human, exitCode: ready ? 0 : 1 };
+}

package/dist/harness.js

@@ -290,33 +290,78 @@ export async function repoContext(cwd = process.cwd()) {
 const flagList = (value) => (value === undefined || value === true ? [] : [value].flat().flatMap((x) => String(x).split(",")).filter(Boolean));
 const changeLine = (c) => `${{ create: "+", remove: "-" }[c.action] ?? "~"} ${c.path}${["create", "update", "remove"].includes(c.action) ? "" : ` (${c.action})`}`;
 
+// What each planned change means for a check: how the file on disk differs from Dev's.
+const DIFFERENCE = {
+  create: "missing; Dev would create it",
+  update: "differs from Dev's",
+  "add block": "has no nodii-dev block",
+  merge: "hooks differ from Dev's",
+  remove: "Dev no longer generates it",
+  "remove block": "Dev no longer generates its block",
+  unmerge: "has hooks Dev no longer generates",
+};
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+/**
+ * `harness check` (and its alias `harness update --check`): compare the files
+ * on disk, and the methodology stamp, with what Dev would generate now (MW5-4,
+ * MW5-6). Writes nothing. Exit 0 when current, 1 when anything differs, 2
+ * when there is no harness.
+ */
+async function checkCommand(root, repo, state, fetchHarness) {
+  if (!state) {
+    let would;
+    try {
+      const plan = await planHarness(root, (await fetchHarness()).data, { install: true });
+      const paths = plan.changes.map((c) => c.path);
+      const taken = plan.conflicts.map((c) => c.path);
+      would = ` Dev would write ${plural(paths.length, "file")}: ${paths.join(", ")}.${taken.length ? ` ${plural(taken.length, "file")} ${taken.length === 1 ? "already exists and needs" : "already exist and need"} --adopt: ${taken.join(", ")}.` : ""}`;
+    } catch (error) {
+      would = ` Dev cannot say what install would write (${error?.code ?? "ERROR"}: ${error?.message ?? error}).`;
+    }
+    throw new CliError("HARNESS_NOT_INSTALLED", `No nodii-dev harness here.${would} Run \`nodii-dev harness install\` first.`, 2);
+  }
+  // Compare the files Dev would write now, not only the version: the
+  // CLAUDE.md block also changes when the service's domain becomes AD.
+  const harness = (await fetchHarness()).data;
+  const plan = await planHarness(root, harness, { install: false });
+  const moved = sourceChanges(state.sources, harness.sources);
+  const versionMoved = harness.methodologyVersion !== state.methodologyVersion;
+  const behind = versionMoved || moved.length > 0 || plan.changes.length > 0 || plan.conflicts.length > 0;
+  const payload = { data: { repo, current: !behind, installed: state.methodologyVersion, available: harness.methodologyVersion, sources: moved, changes: plan.changes.map(({ path, action: a, mode }) => ({ path, action: a, mode })), conflicts: plan.conflicts } };
+  const owned = Object.keys(state.files ?? {}).length;
+  if (!behind) return { payload, human: `Harness is current: ${repo}, methodology ${state.methodologyVersion}, ${plural(owned, "file")} ${owned === 1 ? "matches" : "match"} Dev.` };
+  process.exitCode = 1;
+  return {
+    payload,
+    human: [
+      `Harness differs from what Dev would generate for ${repo}:`,
+      ...(versionMoved ? [`  methodology: ${state.methodologyVersion} installed, ${harness.methodologyVersion} available`] : []),
+      ...moved.map((x) => `  source ${x}`),
+      ...plan.changes.map((c) => `  ${c.path}: ${DIFFERENCE[c.action] ?? c.action}`),
+      ...plan.conflicts.map((c) => `  ${c.path}: ${c.reason}`),
+      "Fix with `nodii-dev harness update` (inside a lane: note this in the step and leave the harness files alone; MW5-8).",
+    ].join("\n"),
+  };
+}
+
 export async function harnessCommand(action, flags, { request = devRequest, context = repoContext } = {}) {
-  if (!["install", "update"].includes(action)) throw new CliError("USAGE", "harness install|update [--repo NAME] [--service ID] [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--check]", 2);
+  if (!["install", "update", "check"].includes(action)) throw new CliError("USAGE", "harness install|update|check [--repo NAME] [--service ID] [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--check]", 2);
   if (flags.fleet || flags.all) throw new CliError("USAGE", "The harness is installed one service at a time, in that service's repository. There is no fleet mode.", 2);
   if (flags.root === true || flags.repo === true) throw new CliError("USAGE", "--root and --repo need a value.", 2);
   const ctx = flags.root ? { root: flags.root, repo: flags.repo } : await context();
   const repo = flags.repo && flags.repo !== true ? String(flags.repo) : ctx.repo;
   if (!repo) throw new CliError("USAGE", "Pass --repo NAME.", 2);
   const state = await readState(ctx.root);
-  // Update asks Dev for what install asked for, unless told otherwise.
-  const saved = action === "update" ? (state?.request ?? {}) : {};
+  // Update and check ask Dev for what install asked for, unless told otherwise.
+  const saved = action === "install" ? {} : (state?.request ?? {});
   const serviceId = flags.service && flags.service !== true ? String(flags.service) : (saved.serviceId ?? undefined);
   const includeDrafts = flags["include-drafts"] !== undefined ? flags["include-drafts"] !== "false" : Boolean(saved.includeDrafts);
   const params = { repo, serviceId, includeDrafts: includeDrafts ? "true" : undefined };
 
   if (action === "install" && flags.check) throw new CliError("USAGE", "--check goes with `harness update`; to preview an install use --dry-run.", 2);
-  if (action === "update" && flags.check) {
-    if (!state) throw new CliError("HARNESS_NOT_INSTALLED", "No nodii-dev harness here. Run `nodii-dev harness install` first.", 2);
-    // Compare the files Dev would write now, not only the version: the
-    // CLAUDE.md block also changes when the service's domain becomes AD.
-    const harness = (await request("GET", `/api/v1/harness${query(params)}`)).data;
-    const plan = await planHarness(ctx.root, harness, { install: false });
-    const moved = sourceChanges(state.sources, harness.sources);
-    const behind = harness.methodologyVersion !== state.methodologyVersion || plan.changes.length > 0 || plan.conflicts.length > 0;
-    const payload = { data: { repo, current: !behind, installed: state.methodologyVersion, available: harness.methodologyVersion, sources: moved, changes: plan.changes.map(({ path, action: a, mode }) => ({ path, action: a, mode })), conflicts: plan.conflicts } };
-    if (behind) process.exitCode = 1;
-    return { payload, human: behind ? [`Harness is behind: ${state.methodologyVersion} → ${harness.methodologyVersion}`, ...moved.map((x) => `  source ${x}`), ...plan.changes.map(changeLine), ...plan.conflicts.map((c) => `  conflict ${c.path}: ${c.reason}`), "Run `nodii-dev harness update`."].join("\n") : `Harness is current (${state.methodologyVersion}).` };
-  }
+  if (action === "check" && (flags["dry-run"] || flags.adopt)) throw new CliError("USAGE", "harness check writes nothing; --dry-run and --adopt go with install and update.", 2);
+  if (action === "check" || (action === "update" && flags.check)) return checkCommand(ctx.root, repo, state, () => request("GET", `/api/v1/harness${query(params)}`));
 
   const harness = (await request("GET", `/api/v1/harness${query(params)}`)).data;
   const plan = await planHarness(ctx.root, harness, { install: action === "install", adopt: flagList(flags.adopt), request: { ...(serviceId ? { serviceId } : {}), includeDrafts } });

package/dist/lanes.js

@@ -18,15 +18,21 @@ async function git(...args) {
   }
 }
 
+/**
+ * A repository as Dev names it: the short name. Dev compares a lane's repos
+ * exactly against the agent's home repo and grants, which are short names, so
+ * `owner/name` from the remote was refused as REPO_NOT_GRANTED.
+ */
+export const repoName = (remoteOrPath) => String(remoteOrPath).replace(/\/+$/, "").replace(/\.git$/, "").split(/[/:]/).filter(Boolean).at(-1);
+
 export async function inferGitContext() {
   const worktree = await git("rev-parse", "--show-toplevel");
   const branch = await git("branch", "--show-current");
   let repo;
   try {
-    const remote = await git("remote", "get-url", "origin");
-    repo = remote.replace(/\.git$/, "").replace(/^git@[^:]+:/, "").replace(/^https?:\/\/[^/]+\//, "");
+    repo = repoName(await git("remote", "get-url", "origin"));
   } catch {
-    repo = worktree.split("/").filter(Boolean).at(-1);
+    repo = repoName(worktree);
   }
   return { repo, branch: need(branch, "Detached HEAD: pass --branch."), worktree };
 }

package/dist/oauth.js

@@ -440,7 +440,10 @@ export class OAuthAuthProvider {
         await this.deleteToken(config.clientId);
         await this.deleteAccess(config.clientId);
       }
-      throw new CliError("OAUTH_LOGIN_REQUIRED", `nodii-auth no longer accepts this sign-in (invalid_grant: expired, revoked or replayed)${cleared ? " and the saved credential was cleared" : ""}; run \`nodii-dev login\` again.`, 2);
+      // What the server said, so `doctor` can name expired, revoked or replaced.
+      const said = (key) => (typeof result.body[key] === "string" ? result.body[key] : undefined);
+      const grant = Object.fromEntries([["error", said("error")], ["description", said("error_description")]].filter(([, v]) => v !== undefined));
+      throw new CliError("OAUTH_LOGIN_REQUIRED", `nodii-auth no longer accepts this sign-in (invalid_grant: expired, revoked or replayed)${cleared ? " and the saved credential was cleared" : ""}; run \`nodii-dev login\` again.`, 2, { grant });
     }
     if (kind === "retry")
       throw new CliError("OAUTH_REFRESH_UNAVAILABLE", `Could not refresh the sign-in (${describe(result)}) after ${attempts} attempt${attempts === 1 ? "" : "s"}; the saved credential was kept. Retry the command shortly.`, 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {