@nodii/dev 0.6.2 → 0.6.4

package/README.md

@@ -24,9 +24,15 @@ live `devops.*` key except `devops.releases.promote`, which is never granted.
 Login uses the RFC 8628 device flow and opens the verification page on an
 interactive terminal unless `--no-browser` is passed. Refresh tokens are
 stored only in macOS Keychain or Linux Secret Service (`secret-tool`); the CLI
-refuses plaintext fallback. Access tokens stay in memory. Every API call goes
-to the edge's `/devops` prefix with the OAuth bearer and the registered
-`x-agent-id`. `logout` revokes the refresh chain before erasing local
+refuses plaintext fallback. The current access token is kept there too, so
+every nodii-dev process on the machine shares it instead of refreshing on each
+run; refreshes take turns under a per-user lock. A refresh clears the saved
+sign-in only when nodii-auth answers `invalid_grant` (expired, revoked or
+replayed). A 429, 5xx, timeout, network error or proxy error page keeps it and
+fails with `OAUTH_REFRESH_UNAVAILABLE` (exit 1) after a few retries. Every API
+call goes to the edge's `/devops` prefix with the OAuth bearer and the
+registered `x-agent-id`; signing in again as the same person keeps that
+registration. `logout` revokes the refresh chain before erasing local
 credentials. `--auth-url`, `--edge-url`, and `--tenant-hint` select another real
 deployment.
 
@@ -39,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.
@@ -51,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]
@@ -246,10 +255,32 @@ 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.
 
+## 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,6 +55,7 @@ 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
   inbox list|show
@@ -101,7 +103,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 = "";
@@ -145,9 +148,12 @@ async function login(flags, json) {
     noBrowser: Boolean(flags["no-browser"]),
     scope: flags.scope,
     output: json ? console.error : console.log,
+    previous,
   });
-  return emit({ loggedIn: true, provider: "oauth", credentialStorage: result.storage }, json,
-    `OAuth login complete; refresh credential stored in ${result.storage}. Run \`nodii-dev agent register --name NAME\` next.`);
+  return emit({ loggedIn: true, provider: "oauth", credentialStorage: result.storage, agentId: result.agentId }, json,
+    result.agentId
+      ? `OAuth login complete; refresh credential stored in ${result.storage}. Kept agent registration ${result.agentId}.`
+      : `OAuth login complete; refresh credential stored in ${result.storage}. Run \`nodii-dev agent register --name NAME\` next.`);
 }
 
 async function issues(action, args, f, json) {
@@ -269,6 +275,13 @@ 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 === "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"].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);

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.2";
+export const VERSION = "0.6.4";
 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, api transitionIssue" },
+  { 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/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

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
-import { open, rm, stat } from "node:fs/promises";
-import { platform } from "node:os";
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rm, stat, utimes } from "node:fs/promises";
+import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { CliError, configPath, readConfig, writeConfig } from "./core.js";
 
@@ -29,6 +30,7 @@ export function requestedScope(scope) {
 
 const service = "dev.nodii.cli.oauth";
 const account = (clientId) => `refresh:${clientId}`;
+const accessAccount = (clientId) => `access:${clientId}`;
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 function run(command, args, { input } = {}) {
@@ -43,42 +45,83 @@ function run(command, args, { input } = {}) {
   });
 }
 
-export async function storeRefreshToken(clientId, token, os = platform()) {
+async function keychainStore(name, secret, os) {
   if (os === "darwin") {
-    await run("security", ["add-generic-password", "-U", "-a", account(clientId), "-s", service, "-w", token]);
+    if (!/^[A-Za-z0-9_.:-]+$/.test(name)) throw new CliError("KEYCHAIN_UNAVAILABLE", "The OAuth client id has characters the Keychain helper cannot take; nothing was stored.", 2);
+    // Through `security -i` on stdin, so the secret never appears in argv
+    // (visible to `ps`). The interactive parser splits on whitespace and reads
+    // quotes, so a secret outside a token's own alphabet falls back to argv
+    // rather than being dropped (it may be a refresh token just rotated).
+    if (/^[A-Za-z0-9._~+/=-]+$/.test(secret)) await run("security", ["-i"], { input: `add-generic-password -U -a ${name} -s ${service} -w ${secret}\n` });
+    else await run("security", ["add-generic-password", "-U", "-a", name, "-s", service, "-w", secret]);
     return "macOS Keychain";
   }
   if (os === "linux") {
     try {
-      await run("secret-tool", ["store", "--label=nodii-dev OAuth", "service", service, "account", account(clientId)], { input: token });
+      await run("secret-tool", ["store", "--label=nodii-dev OAuth", "service", service, "account", name], { input: secret });
       return "Secret Service";
     } catch {}
   }
   throw new CliError("KEYCHAIN_UNAVAILABLE", "OAuth refresh tokens require macOS Keychain or Linux Secret Service. No credential was stored; re-run login when a keychain is available.", 2);
 }
 
+async function keychainLoad(name, os) {
+  if (os === "darwin") return (await run("security", ["find-generic-password", "-a", name, "-s", service, "-w"])).trim();
+  if (os === "linux") return (await run("secret-tool", ["lookup", "service", service, "account", name])).trim();
+  throw new Error("no keychain");
+}
+
+async function keychainDelete(name, os) {
+  try {
+    if (os === "darwin") await run("security", ["delete-generic-password", "-a", name, "-s", service]);
+    else if (os === "linux") await run("secret-tool", ["clear", "service", service, "account", name]);
+  } catch {}
+}
+
+export async function storeRefreshToken(clientId, token, os = platform()) {
+  return keychainStore(account(clientId), token, os);
+}
+
 export async function loadRefreshToken(clientId, os = platform()) {
   try {
-    if (os === "darwin") return (await run("security", ["find-generic-password", "-a", account(clientId), "-s", service, "-w"])).trim();
-    if (os === "linux") return (await run("secret-tool", ["lookup", "service", service, "account", account(clientId)])).trim();
+    const token = await keychainLoad(account(clientId), os);
+    if (token) return token;
   } catch {}
   throw new CliError("OAUTH_LOGIN_REQUIRED", "OAuth credentials are unavailable; run `nodii-dev login` again.", 2);
 }
 
 export async function deleteRefreshToken(clientId, os = platform()) {
+  await keychainDelete(account(clientId), os);
+}
+
+// The access token is cached beside the refresh token so that every nodii-dev
+// process on the machine shares one: without it each command rotated the
+// refresh token, and N lanes rotated it N times as often.
+export async function loadAccessToken(clientId, os = platform()) {
   try {
-    if (os === "darwin") await run("security", ["delete-generic-password", "-a", account(clientId), "-s", service]);
-    else if (os === "linux") await run("secret-tool", ["clear", "service", service, "account", account(clientId)]);
-  } catch {}
+    const cached = JSON.parse(Buffer.from(await keychainLoad(accessAccount(clientId), os), "base64url").toString("utf8"));
+    return typeof cached?.token === "string" && Number.isFinite(cached.expiresAt) ? cached : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function storeAccessToken(clientId, cached, os = platform()) {
+  try { await keychainStore(accessAccount(clientId), Buffer.from(JSON.stringify(cached)).toString("base64url"), os); } catch {}
 }
 
-async function oauthPost(authUrl, path, fields, fetchImpl = fetch) {
+export async function deleteAccessToken(clientId, os = platform()) {
+  await keychainDelete(accessAccount(clientId), os);
+}
+
+async function oauthPost(authUrl, path, fields, fetchImpl = fetch, timeoutMs = REFRESH_TIMEOUT_MS) {
   let response;
   try {
     response = await fetchImpl(`${authUrl.replace(/\/$/, "")}${path}`, {
       method: "POST",
       headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
       body: new URLSearchParams(fields),
+      signal: AbortSignal.timeout(timeoutMs),
     });
   } catch (error) {
     throw new CliError("AUTH_UNREACHABLE", `Cannot reach nodii-auth: ${error.message}`, 1);
@@ -112,7 +155,20 @@ function openBrowser(url) {
   child.unref();
 }
 
-export async function deviceLogin({ clientId, authUrl = DEFAULT_AUTH_URL, edgeUrl = DEFAULT_EDGE_URL, tenantHint = PLATFORM_TENANT, noBrowser = false, scope, fetchImpl = fetch, output = console.log }) {
+/**
+ * The agent registration a new login keeps. Dev binds an agent to the person,
+ * the app and the installation, so signing in again as the same person through
+ * the same installation keeps it; anything else starts unregistered.
+ */
+export function keptAgent(previous, { clientId, person, installationId, edgeUrl }) {
+  if (!previous?.agentId || !person) return null;
+  if (previous.clientId !== clientId || previous.person !== person) return null;
+  if ((previous.installationId ?? null) !== (installationId ?? null)) return null;
+  if (edgeUrl && previous.edgeUrl && previous.edgeUrl.replace(/\/$/, "") !== edgeUrl.replace(/\/$/, "")) return null;
+  return previous.agentId;
+}
+
+export async function deviceLogin({ clientId, authUrl = DEFAULT_AUTH_URL, edgeUrl = DEFAULT_EDGE_URL, tenantHint = PLATFORM_TENANT, noBrowser = false, scope, fetchImpl = fetch, output = console.log, previous = null, lock = withRefreshLock }) {
   const requested = requestedScope(scope);
   const start = await oauthPost(authUrl, "/oauth/device/authorize", {
     client_id: clientId, tenant_hint: tenantHint, ...(requested ? { scope: requested } : {}),
@@ -123,61 +179,287 @@ export async function deviceLogin({ clientId, authUrl = DEFAULT_AUTH_URL, edgeUr
   if (!noBrowser && process.stdout.isTTY) openBrowser(d.verification_uri_complete ?? d.verification_uri);
   const token = await pollDeviceToken({ authUrl, clientId, deviceCode: d.device_code, interval: d.interval, expiresIn: d.expires_in, fetchImpl });
   if (!token.refresh_token) throw new CliError("OAUTH_REFRESH_MISSING", "nodii-auth did not return a refresh token.", 1);
-  const storage = await storeRefreshToken(clientId, token.refresh_token);
+  const storage = await lock(async () => {
+    const stored = await storeRefreshToken(clientId, token.refresh_token);
+    await deleteAccessToken(clientId);
+    return stored;
+  }, { clientId });
   const claims = decodeClaims(token.access_token);
-  await writeConfig({ authProvider: "oauth", authUrl, edgeUrl, clientId, tenantHint, agentId: null, person: claims.sub ?? null, installationId: claims.metadata?.oauth_app_installation_id ?? claims.oauth_app_installation_id ?? null });
-  return { storage, claims };
+  const person = claims.sub ?? null;
+  const installationId = claims.metadata?.oauth_app_installation_id ?? claims.oauth_app_installation_id ?? null;
+  const agentId = keptAgent(previous, { clientId, person, installationId, edgeUrl });
+  await writeConfig({ authProvider: "oauth", authUrl, edgeUrl, clientId, tenantHint, agentId, person, installationId });
+  return { storage, claims, agentId };
 }
 
 export function decodeClaims(token) {
   try { return JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf8")); } catch { return {}; }
 }
 
-export async function withRefreshLock(fn, { sleep = wait } = {}) {
-  const path = join(dirname(configPath()), "oauth-refresh.lock");
-  for (let attempt = 0; attempt < 300; attempt++) {
+// ONE lock per OAuth client per user, beside the Keychain item it guards. It
+// used to live next to the config file, so two processes with different
+// NODII_DEV_CONFIG_PATH values shared the credential but not the lock.
+export function refreshLockPath(clientId = DEFAULT_CLIENT_ID) {
+  return join(homedir(), ".config/nodii-dev", `oauth-refresh-${String(clientId).replace(/[^A-Za-z0-9_.-]/g, "_")}.lock`);
+}
+
+const LOCK_STALE_MS = 30_000;
+const LOCK_LIVE_STALE_MS = 120_000;
+const LOCK_BEAT_MS = 5_000;
+const LOCK_WAIT_MS = 90_000;
+const RECLAIM_STALE_MS = 10_000;
+
+function ownerPid(owner) {
+  const pid = Number.parseInt(owner, 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === "EPERM"; }
+}
+
+async function readOwner(path) {
+  try { return await readFile(path, "utf8"); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function lockAge(path) {
+  try { return Date.now() - (await stat(path)).mtimeMs; } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+// A lock is reclaimable at once when its holder's pid is gone; when the file
+// names no pid yet (being written, or left by 0.6.2) after `staleMs` without a
+// touch; and from a live holder only after LOCK_LIVE_STALE_MS — far longer than
+// any refresh, so a holder that slept with the laptop is not robbed on waking.
+function reclaimable(owner, age, staleMs) {
+  const pid = ownerPid(owner);
+  if (pid !== null && !pidAlive(pid)) return true;
+  return age > Math.max(staleMs, pid === null ? staleMs : LOCK_LIVE_STALE_MS);
+}
+
+// Reclaims are serialized through `<lock>.reclaim`, taken with O_EXCL: two
+// waiters that both judged the same dead lock cannot both delete — the second
+// would otherwise delete the lock the first had just re-created.
+async function reclaim(path, seen, staleMs) {
+  const guard = `${path}.reclaim`;
+  const mine = `${process.pid}:${randomUUID()}`;
+  let handle;
+  try {
+    handle = await open(guard, "wx", 0o600);
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const holder = await readOwner(guard);
+    const age = await lockAge(guard);
+    if (holder !== null && age !== null && age > RECLAIM_STALE_MS && (await readOwner(guard)) === holder) await rm(guard, { force: true });
+    return;
+  }
+  try {
+    try { await handle.writeFile(mine); } finally { await handle.close(); }
+    const owner = await readOwner(path);
+    const age = await lockAge(path);
+    if (owner === seen && age !== null && reclaimable(owner, age, staleMs) && (await readOwner(guard)) === mine) await rm(path, { force: true });
+  } finally {
+    if ((await readOwner(guard)) === mine) await rm(guard, { force: true });
+  }
+}
+
+async function acquire(path, { sleep, waitMs, staleMs }) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const owner = `${process.pid}:${randomUUID()}`;
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    let handle;
     try {
-      const handle = await open(path, "wx", 0o600);
-      try { return await fn(); } finally { await handle.close(); await rm(path, { force: true }); }
+      handle = await open(path, "wx", 0o600);
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
-      try {
-        if (Date.now() - (await stat(path)).mtimeMs > 60_000) {
-          await rm(path, { force: true });
-          continue;
-        }
-      } catch (statError) {
-        if (statError.code !== "ENOENT") throw statError;
-      }
-      await sleep(100);
+      const seen = await readOwner(path);
+      const age = await lockAge(path);
+      if (seen !== null && age !== null && reclaimable(seen, age, staleMs)) await reclaim(path, seen, staleMs);
+      else await sleep(50 + Math.floor(Math.random() * 100));
+      continue;
     }
+    try { await handle.writeFile(owner); } finally { await handle.close(); }
+    const beat = setInterval(async () => {
+      try { if ((await readOwner(path)) === owner) await utimes(path, new Date(), new Date()); } catch {}
+    }, Math.max(250, Math.min(LOCK_BEAT_MS, Math.floor(staleMs / 3))));
+    beat.unref();
+    return {
+      held: async () => (await readOwner(path)) === owner,
+      release: async () => {
+        clearInterval(beat);
+        if ((await readOwner(path)) === owner) await rm(path, { force: true });
+      },
+    };
+  }
+  throw new CliError("OAUTH_REFRESH_BUSY", "Timed out waiting for another nodii-dev token refresh; the saved sign-in was kept. Retry the command.", 1);
+}
+
+// 0.6.2 and earlier locked `oauth-refresh.lock` beside the config file. While
+// both versions may run on one machine, this release takes that lock too
+// (always after its own, so the order is fixed). 0.6.2 reclaims it after 60 s
+// without a touch, which the heartbeat prevents.
+export const legacyRefreshLockPath = () => join(dirname(configPath()), "oauth-refresh.lock");
+
+/**
+ * Run `fn` holding the cross-process refresh lock. The holder writes its owner
+ * id into the file and touches it every few seconds; a waiter reclaims the
+ * lock only from a holder that exited or went quiet, one reclaimer at a time,
+ * and a holder only ever removes its own lock file. `fn` receives `held()`, to
+ * confirm the lock is still its own before acting on the shared credential.
+ */
+export async function withRefreshLock(fn, { clientId, path = refreshLockPath(clientId), legacyPath = path === refreshLockPath(clientId) ? legacyRefreshLockPath() : null,
+  sleep = wait, waitMs = LOCK_WAIT_MS, staleMs = LOCK_STALE_MS } = {}) {
+  const locks = [await acquire(path, { sleep, waitMs, staleMs })];
+  try {
+    if (legacyPath && legacyPath !== path) locks.push(await acquire(legacyPath, { sleep, waitMs, staleMs: Math.max(staleMs, 60_000) }));
+    const held = async () => (await Promise.all(locks.map((l) => l.held()))).every(Boolean);
+    return await fn({ held });
+  } finally {
+    for (const l of locks.reverse()) await l.release();
   }
-  throw new CliError("OAUTH_REFRESH_BUSY", "Timed out waiting for another nodii-dev token refresh.", 1);
 }
 
+// What a refresh answer means for the stored credential. Only the server saying
+// the GRANT is dead (RFC 6749 § 5.2 invalid_grant: expired, revoked, replayed)
+// ends the sign-in. Everything else — 429, 5xx, a timeout, no network, an HTML
+// error page from a proxy or CDN, a 2xx without tokens — says nothing about the
+// grant, so the credential is kept.
+const DEAD_GRANT_ERRORS = new Set(["invalid_grant", "expired_token", "token_revoked"]);
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+export const REFRESH_TIMEOUT_MS = 10_000;
+const REFRESH_ATTEMPTS = 4;
+const RETRY_AFTER_CAP_MS = 5_000;
+// The whole refresh, retries included, fits well inside the lock's wait
+// (LOCK_WAIT_MS) so a waiter behind it sees the real outcome, not BUSY.
+export const REFRESH_BUDGET_MS = 25_000;
+// No request starts with less than this left: one cut off after the server
+// rotated the token would lose the new token and replay the old one next run.
+const MIN_ATTEMPT_MS = 5_000;
+
+export function classifyRefresh(result) {
+  if (result.ok && result.body.access_token && result.body.refresh_token) return "ok";
+  if (result.status >= 400 && result.status < 500 && DEAD_GRANT_ERRORS.has(result.body.error)) return "dead";
+  if (result.status === 0 || result.ok || RETRYABLE_STATUS.has(result.status) || result.status >= 500 || !result.json) return "retry";
+  return "refused";
+}
+
+async function postRefresh(authUrl, clientId, refreshToken, fetchImpl, timeoutMs) {
+  let response;
+  try {
+    response = await fetchImpl(`${authUrl.replace(/\/$/, "")}/oauth/token`, {
+      method: "POST",
+      headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ grant_type: "refresh_token", client_id: clientId, refresh_token: refreshToken }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    return { ok: false, status: 0, body: {}, json: false, reason: error?.name === "TimeoutError" ? "timeout" : "unreachable" };
+  }
+  let raw = "";
+  try { raw = await response.text(); } catch {}
+  let body = {};
+  let json = false;
+  try { const parsed = JSON.parse(raw); if (parsed && typeof parsed === "object") { body = parsed; json = true; } } catch {}
+  const retryAfter = Number.parseInt(response.headers?.get?.("retry-after") ?? "", 10);
+  return { ok: response.ok, status: response.status, body, json, retryAfterMs: Number.isFinite(retryAfter) ? retryAfter * 1000 : undefined };
+}
+
+const describe = (result) => result.status === 0 ? (result.reason === "timeout" ? "timed out" : "nodii-auth unreachable") : `HTTP ${result.status}${result.json && typeof result.body.error === "string" ? ` ${result.body.error}` : ""}`;
+
 export class OAuthAuthProvider {
   #accessToken;
   #expiresAt = 0;
   #refreshPromise;
-  constructor({ fetchImpl = fetch, loadToken = loadRefreshToken, storeToken = storeRefreshToken, deleteToken = deleteRefreshToken, lock = withRefreshLock } = {}) {
-    Object.assign(this, { fetchImpl, loadToken, storeToken, deleteToken, lock });
+  constructor({ fetchImpl = fetch, loadToken = loadRefreshToken, storeToken = storeRefreshToken, deleteToken = deleteRefreshToken, lock = withRefreshLock,
+    loadAccess, storeAccess, deleteAccess, sleep = wait, timeoutMs = REFRESH_TIMEOUT_MS, budgetMs = REFRESH_BUDGET_MS } = {}) {
+    // Injected token storage (tests) gets no shared access cache unless one is
+    // injected too, so a test never reads or writes the real Keychain.
+    const realStorage = loadToken === loadRefreshToken;
+    Object.assign(this, { fetchImpl, loadToken, storeToken, deleteToken, lock, sleep, timeoutMs, budgetMs,
+      loadAccess: loadAccess ?? (realStorage ? loadAccessToken : async () => null),
+      storeAccess: storeAccess ?? (realStorage ? storeAccessToken : async () => {}),
+      deleteAccess: deleteAccess ?? (realStorage ? deleteAccessToken : async () => {}) });
+  }
+  #usable(cached) {
+    if (!cached || Date.now() >= cached.expiresAt - 60_000) return false;
+    this.#accessToken = cached.token;
+    this.#expiresAt = cached.expiresAt;
+    return true;
   }
   async accessToken() {
     if (this.#accessToken && Date.now() < this.#expiresAt - 30_000) return this.#accessToken;
-    this.#refreshPromise ??= this.lock(async () => {
+    this.#refreshPromise ??= (async () => {
       const config = await readConfig();
-      const refresh = await this.loadToken(config.clientId);
-      const result = await oauthPost(config.authUrl, "/oauth/token", { grant_type: "refresh_token", client_id: config.clientId, refresh_token: refresh }, this.fetchImpl);
-      if (!result.ok || !result.body.refresh_token) {
+      // Another process may have refreshed already: its access token is shared.
+      if (this.#usable(await this.loadAccess(config.clientId))) return this.#accessToken;
+      return this.lock(async ({ held } = {}) => {
+        // Re-checked under the lock: a process that held it before us has just
+        // rotated the refresh token and cached the access token it got.
+        if (this.#usable(await this.loadAccess(config.clientId))) return this.#accessToken;
+        return this.#refresh(config, held ?? (async () => true));
+      }, { clientId: config.clientId });
+    })().finally(() => { this.#refreshPromise = undefined; });
+    return this.#refreshPromise;
+  }
+  async #attempt(config, refresh, deadline, held) {
+    const floor = Math.min(MIN_ATTEMPT_MS, this.timeoutMs);
+    let result;
+    for (let attempt = 1; ; attempt++) {
+      if (result && deadline - Date.now() < floor) return { kind: classifyRefresh(result), result, attempts: attempt - 1 };
+      // Never present the refresh token without the lock: a second holder
+      // would present the same one, and the server revokes the chain on reuse.
+      if (!(await held())) throw new CliError("OAUTH_REFRESH_BUSY", "Lost the refresh lock to another nodii-dev process; the saved sign-in was kept. Retry the command.", 1);
+      result = await postRefresh(config.authUrl, config.clientId, refresh, this.fetchImpl, Math.max(floor, Math.min(this.timeoutMs, deadline - Date.now())));
+      const kind = classifyRefresh(result);
+      if (kind !== "retry" || attempt >= REFRESH_ATTEMPTS) return { kind, result, attempts: attempt };
+      const backoff = 500 * 2 ** (attempt - 1) + Math.floor(Math.random() * 250);
+      const pause = Math.min(Math.max(backoff, result.retryAfterMs ?? 0), RETRY_AFTER_CAP_MS);
+      if (Date.now() + pause + floor > deadline) return { kind, result, attempts: attempt };
+      await this.sleep(pause);
+    }
+  }
+  async #refresh(config, held) {
+    const deadline = Date.now() + this.budgetMs;
+    let refresh = await this.loadToken(config.clientId);
+    let outcome = await this.#attempt(config, refresh, deadline, held);
+    if (outcome.kind === "dead" || outcome.kind === "refused") {
+      // The stored token may have moved while this one was refused (a login,
+      // or a 0.6.2 process outside this lock). One more try with it.
+      const current = await this.loadToken(config.clientId).catch(() => null);
+      if (current && current !== refresh && deadline - Date.now() >= Math.min(MIN_ATTEMPT_MS, this.timeoutMs)) {
+        refresh = current;
+        outcome = await this.#attempt(config, refresh, deadline, held);
+      }
+    }
+    const { kind, result, attempts } = outcome;
+    if (kind === "dead") {
+      // Clear only the token the server rejected, never one stored since.
+      const current = await this.loadToken(config.clientId).catch(() => null);
+      const cleared = current === refresh;
+      if (cleared) {
         await this.deleteToken(config.clientId);
-        throw new CliError("OAUTH_LOGIN_REQUIRED", "OAuth refresh failed and the saved credential was cleared; run `nodii-dev login` again.", 2);
+        await this.deleteAccess(config.clientId);
       }
-      await this.storeToken(config.clientId, result.body.refresh_token);
-      this.#accessToken = result.body.access_token;
-      this.#expiresAt = Date.now() + result.body.expires_in * 1000;
-      return this.#accessToken;
-    }).finally(() => { this.#refreshPromise = undefined; });
-    return this.#refreshPromise;
+      // 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);
+    if (kind === "refused")
+      throw new CliError("OAUTH_REFRESH_FAILED", `nodii-auth refused the refresh (${describe(result)}); the saved credential was kept.`, 1);
+    const body = result.body;
+    for (let attempt = 1; ; attempt++) {
+      try { await this.storeToken(config.clientId, body.refresh_token); break; } catch (error) {
+        if (attempt >= 3) throw error;
+        await this.sleep(200 * attempt);
+      }
+    }
+    this.#accessToken = body.access_token;
+    this.#expiresAt = Date.now() + Number(body.expires_in ?? 0) * 1000;
+    await this.storeAccess(config.clientId, { token: this.#accessToken, expiresAt: this.#expiresAt });
+    return this.#accessToken;
   }
   async headers() {
     const config = await readConfig();
@@ -185,11 +467,16 @@ export class OAuthAuthProvider {
   }
 }
 
-export async function revokeOAuth(config, fetchImpl = fetch) {
-  const token = await loadRefreshToken(config.clientId);
-  try {
-    await oauthPost(config.authUrl, "/oauth/revoke", { token, token_type_hint: "refresh_token", client_id: config.clientId }, fetchImpl);
-  } finally {
-    await deleteRefreshToken(config.clientId);
-  }
+export async function revokeOAuth(config, fetchImpl = fetch, lock = withRefreshLock) {
+  // Under the refresh lock, so a refresh in flight cannot store a new token
+  // after logout has cleared the old one.
+  await lock(async () => {
+    try {
+      const token = await loadRefreshToken(config.clientId);
+      await oauthPost(config.authUrl, "/oauth/revoke", { token, token_type_hint: "refresh_token", client_id: config.clientId }, fetchImpl);
+    } finally {
+      await deleteRefreshToken(config.clientId);
+      await deleteAccessToken(config.clientId);
+    }
+  }, { clientId: config.clientId });
 }

package/package.json

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