@nodii/dev 0.6.10 → 0.6.12

package/dist/doctor.js

@@ -4,7 +4,7 @@ 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";
-import { figmaFileKey, notRegisteredHint } from "./figma.js";
+import { figmaFileKey, figmaLockCheck, holdsSet, notRegisteredHint, scopeText } from "./figma.js";
 
 /**
  * What a lane's commands need, in Dev's route policy (staffRuleFor in Dev's
@@ -237,6 +237,19 @@ export async function doctorCommand(deps = {}) {
         const file = (await request("GET", `/api/v1/design/files/${encode(fileKey)}`)).data;
         checks.push(ok("figma_file", `${fileKey} is registered: ${file.name} (${file.kind}${file.module ? `, ${file.module}` : ""})`,
           { fileKey, registered: true }));
+        // The lock scopes this agent holds in the file (DEC-0032).
+        if (config.agentId) {
+          try {
+            const held = (await figmaLockCheck(fileKey, config.agentId, request)).data;
+            const mine = holdsSet(held);
+            const scopes = mine ? (held.scopes ?? []) : [];
+            checks.push(ok("figma_scopes", mine
+              ? `${held.changeSetId} (${held.state}) holds ${scopes.length ? scopes.map(scopeText).join(", ") : "the whole file"}`
+              : `holds no scopes in ${fileKey}`, { fileKey, changeSetId: mine ? held.changeSetId : null, scopes }));
+          } catch (error) {
+            checks.push(cannot("figma_scopes", `checkDesignFileLock failed (${devReason(error)})`, { fileKey }));
+          }
+        }
       } catch (error) {
         if (error?.code === "DESIGN_FILE_NOT_FOUND")
           checks.push(missing("figma_file", `${fileKey} is NOT registered: run figma file add; figma lock fails with DESIGN_FILE_NOT_FOUND`,

package/dist/figma.js

@@ -68,7 +68,7 @@ export async function figmaResubmit(id, file, { request = devRequest, read = (f)
     return await request("POST", `/api/v1/design/change-sets/${encode(id)}/resubmit`, body);
   } catch (error) {
     const say = RESUBMIT_REFUSALS[error?.code];
-    if (!say) throw error;
+    if (!say) throw scopeRefusal(error, id) ?? error;
     throw new CliError(error.code, say(id, error.details, error.message), error.exitCode ?? 1, error.details);
   }
 }
@@ -104,3 +104,177 @@ export function figmaChangeSetText(cs) {
   if (cs.previousRounds?.length) lines.push(`${cs.previousRounds.length} earlier-round item(s) replaced by a re-submit; --json lists them.`);
   return lines.join("\n");
 }
+
+// Scoped design locks (DEC-0032, MW1-57.6 to 57.9). A scope is written
+// kind:id on the command line: component:NODE, page:NODE, foundations, or
+// create:PAGE:NAME. A node id from a figma.com link (12-34) is Figma's 12:34.
+const nodeId = (text) => (/^\d+-\d+$/.test(text) ? text.replace("-", ":") : text);
+const SCOPE_USAGE = "--scope component:NODE_ID | page:NODE_ID | foundations | create:PAGE_ID:NAME";
+
+export function parseScope(value) {
+  const text = typeof value === "string" ? value.trim() : "";
+  const bad = () => new CliError("USAGE", `bad scope ${JSON.stringify(text)}: use ${SCOPE_USAGE}`, 2);
+  if (text === "foundations") return { kind: "foundations" };
+  const create = text.match(/^create:(\d+[:-]\d+):(.*)$/);
+  if (create && create[2].trim() && create[2].trim().length <= 200)
+    return { kind: "create", pageId: nodeId(create[1]), name: create[2].trim() };
+  // Dev takes a scope at a top-level node: a plain id, never an instance's (I1:2;3:4).
+  const node = text.match(/^(component|page):(\d+[:-]\d+)$/);
+  if (!node) throw bad();
+  return { kind: node[1], nodeId: nodeId(node[2]) };
+}
+
+/** Every --scope flag as a scope; none at all is a whole-file lock (MW1-57.9). */
+export function scopesFrom(flags) {
+  const given = flags.scope === undefined ? [] : [flags.scope].flat();
+  return given.map((value) => {
+    if (value === true) throw new CliError("USAGE", `--scope needs a value: ${SCOPE_USAGE}`, 2);
+    return parseScope(value);
+  });
+}
+
+export const scopeText = (s) =>
+  !s ? "?"
+    : s.kind === "foundations" ? "foundations"
+    : s.kind === "file" ? "whole file"
+    : s.kind === "create" ? `create:${s.pageId}:${s.name}`
+    : `${s.kind}:${s.nodeId}`;
+
+const conflictText = (message, details) => {
+  const held = details?.heldBy;
+  if (!held) return message;
+  return [
+    message,
+    `${scopeText(details.requested)} overlaps ${scopeText(held.scope)}, held by ${held.changeSetId}${held.title ? ` "${held.title}"` : ""}.`,
+    `Claim a scope that doesn't overlap, or wait until ${held.changeSetId} reaches awaiting_publish (scopes release there).`,
+  ].join("\n");
+};
+
+const FOUNDATIONS_ID = /^(?:S:|VariableID:|VariableCollectionId:)/;
+
+/** Dev's WRITE_OUT_OF_SCOPE, with what to do about it (MW1-57.7). */
+export function outOfScopeText(message, details, id = details?.changeSetId ?? "CHANGE_SET") {
+  const ids = details?.nodeIds ?? [];
+  if (details?.reason === "unknown-ids" || (ids.length && ids.every((x) => x === "unknown")))
+    return [
+      message,
+      `The write returned no node ids, so Dev can't check it against ${id}'s scopes.`,
+      `Return the ids you wrote from the script, then run: nodii-dev figma log-write ${id} --tool TOOL --nodes ID,ID`,
+    ].join("\n");
+  const foundations = ids.filter((x) => FOUNDATIONS_ID.test(x));
+  return [
+    message,
+    ...(ids.length ? [`Out of scope: ${ids.join(", ")}`] : []),
+    ...(foundations.length
+      ? [`Styles and variables (${foundations.join(", ")}) need the foundations scope: nodii-dev figma scope add ${id} --scope foundations`]
+      : []),
+    `Widen with nodii-dev figma scope add ${id} --scope component:NODE_ID|page:NODE_ID if the scope is free, or revert the node exactly to how it was at the set's base version, then submit again.`,
+  ].join("\n");
+}
+
+// Keep Dev's code and message; add what to do next.
+function scopeRefusal(error, id) {
+  if (error?.code === "SCOPE_CONFLICT")
+    return new CliError(error.code, conflictText(error.message, error.details), error.exitCode ?? 1, error.details);
+  if (error?.code === "WRITE_OUT_OF_SCOPE")
+    return new CliError(error.code, outOfScopeText(error.message, error.details, id), error.exitCode ?? 1, error.details);
+  return null;
+}
+
+/** A change-set route whose scope refusals say what to do next. */
+const changeSetCall = (id, request) => async (method, path, body) => {
+  try {
+    return await request(method, path, body);
+  } catch (error) {
+    throw scopeRefusal(error, id) ?? error;
+  }
+};
+
+/** A file route that names the `figma file add` command for an unregistered file. */
+const fileCall = (key, request) => async (method, path, body) => {
+  try {
+    return await request(method, path, body);
+  } catch (error) {
+    if (error?.code === "DESIGN_FILE_NOT_FOUND")
+      throw new CliError(error.code, notRegisteredHint(key), error.exitCode ?? 1, error.details);
+    throw scopeRefusal(error) ?? error;
+  }
+};
+
+/** May this agent write to the file? Its own set, state and scopes (checkDesignFileLock). */
+export const figmaLockCheck = (fileKey, agentId, request = devRequest) =>
+  request("GET", `/api/v1/design/files/${encode(fileKey)}/lock/check?agentId=${encode(agentId)}`);
+
+/** Whether a lock check answers for this agent's own set (it holds one), not another agent's. */
+export const holdsSet = (check) => Boolean(check?.changeSetId) && (check.allowed || check.reason === "change-set-not-editable");
+
+const isWholeFile = (scopes) => !scopes?.length || scopes.some((s) => s.kind === "file");
+
+export async function figmaLock(value, title, { scopes = [], request = devRequest } = {}) {
+  const key = figmaFileKey(value);
+  const result = await fileCall(key, request)("POST", `/api/v1/design/files/${encode(key)}/lock`, {
+    changeSetTitle: title,
+    ...(scopes.length ? { scopes } : {}),
+  });
+  // A Dev that doesn't know scopes ignores them and locks the whole file,
+  // which blocks every other lane: say so loudly instead of exiting 0.
+  if (scopes.length && isWholeFile(result?.data?.scopes))
+    throw new CliError(
+      "SCOPES_NOT_APPLIED",
+      `Dev locked the whole of ${key} as ${result?.data?.id ?? "a change set"}, not the scopes asked for (this Dev predates scoped locks). It blocks every other change set on the file: run nodii-dev figma abandon ${result?.data?.id ?? "CHANGE_SET"}.`,
+      1,
+      result?.data,
+    );
+  return result;
+}
+
+export const figmaLockText = (cs) =>
+  [
+    `${cs.id}  ${cs.state ?? "editing"}  ${cs.title}`,
+    isWholeFile(cs.scopes)
+      ? `Locked the whole of ${cs.fileKey}: this conflicts with every other change set on the file. Claim scopes instead with ${SCOPE_USAGE}.`
+      : `Holds ${cs.scopes.length} scope(s) in ${cs.fileKey}: ${cs.scopes.map(scopeText).join(", ")}`,
+  ].join("\n");
+
+export async function figmaScopeAdd(id, scopes, { request = devRequest } = {}) {
+  if (!id || !scopes.length) throw new CliError("USAGE", `figma scope add CHANGE_SET ${SCOPE_USAGE} [--scope ...]`, 2);
+  return changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/scopes`, { scopes });
+}
+
+export const figmaSubmit = (id, payload, { request = devRequest } = {}) =>
+  changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/submit`, payload);
+
+export const figmaLogWrite = (id, tool, nodeIds, { request = devRequest } = {}) =>
+  changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/writes`, { tool, nodeIds });
+
+/** One publish for the file: every awaiting_publish set on it (MW1-57.8). */
+export async function figmaFilePublished(value, payload, { request = devRequest } = {}) {
+  const key = figmaFileKey(value);
+  return fileCall(key, request)("POST", `/api/v1/design/files/${encode(key)}/published`, payload);
+}
+
+// A change set id (CS-123) takes the per-set route; a file key or link takes the file's.
+export const isChangeSetId = (value) => typeof value === "string" && /^CS-\d+$/i.test(value);
+
+export async function figmaPublishPlan(value, { request = devRequest } = {}) {
+  const key = figmaFileKey(value);
+  return fileCall(key, request)("GET", `/api/v1/design/files/${encode(key)}/publish-plan`);
+}
+
+const planLine = (x) => `  ${x.nodeId ?? scopeText(x)}  ${x.name ?? ""}  (${x.changeSetId} ${x.state}${x.title ? `: ${x.title}` : ""})`;
+
+/** The publish plan as two groups: what to publish, and what to leave unchecked in Figma's publish dialog. */
+export function figmaPublishPlanText(plan) {
+  const publish = plan.publish ?? [];
+  const leave = plan.leaveUnchecked ?? [];
+  return [
+    `Publish plan for ${plan.fileKey}${plan.sinceVersion ? ` (changes since version ${plan.sinceVersion})` : ""}`,
+    `publish (${publish.length}): sets awaiting publish`,
+    ...(publish.length ? publish.map(planLine) : ["  nothing awaiting publish"]),
+    `leave unchecked (${leave.length}): sets still editing or in review`,
+    ...(leave.length ? leave.map(planLine) : ["  none"]),
+    ...(publish.length
+      ? [`After publishing in Figma: nodii-dev figma published ${plan.fileKey} --figma-version VERSION`]
+      : []),
+  ].join("\n");
+}

package/dist/hooks.js

@@ -1,4 +1,5 @@
 import { CliError, devRequest } from "./core.js";
+import { figmaLockCheck, outOfScopeText } from "./figma.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -88,10 +89,7 @@ export async function preHook(payload, request = devRequest) {
   const { agentId } = await config();
   let response;
   try {
-    response = await request(
-      "GET",
-      `/api/v1/design/files/${encodeURIComponent(fileKey)}/lock/check?agentId=${encodeURIComponent(agentId)}`,
-    );
+    response = await figmaLockCheck(fileKey, agentId, request);
   } catch (error) {
     throw new CliError(
       "FIGMA_CHECK_FAILED",
@@ -111,17 +109,14 @@ export async function preHook(payload, request = devRequest) {
   return { allowed: true, fileKey, changeSetId: response.data.changeSetId };
 }
 
-export async function postHook(payload, request = devRequest) {
+export async function postHook(payload, request = devRequest, config = async () => (await import("./core.js")).readConfig()) {
   const name = payload.tool_name ?? "";
   if (!isFigmaTool(name) || isReadTool(name))
     return { logged: false, ignored: true };
   const fileKey = extractFileKey(payload.tool_input);
   if (!fileKey) return { logged: false, reason: "no file key" };
-  const { agentId } = await (await import("./core.js")).readConfig();
-  const checked = await request(
-    "GET",
-    `/api/v1/design/files/${encodeURIComponent(fileKey)}/lock/check?agentId=${encodeURIComponent(agentId)}`,
-  );
+  const { agentId } = await config();
+  const checked = await figmaLockCheck(fileKey, agentId, request);
   if (!checked.data?.allowed || !checked.data.changeSetId)
     return { logged: false, reason: checked.data?.reason ?? "lock denied" };
   const nodeIds = extractNodeIds({
@@ -129,14 +124,30 @@ export async function postHook(payload, request = devRequest) {
     response: payload.tool_response,
   });
   if (!nodeIds.length) nodeIds.push("unknown");
-  await request(
-    "POST",
-    `/api/v1/design/change-sets/${encodeURIComponent(checked.data.changeSetId)}/writes`,
-    { tool: name, nodeIds },
-  );
+  try {
+    await request(
+      "POST",
+      `/api/v1/design/change-sets/${encodeURIComponent(checked.data.changeSetId)}/writes`,
+      { tool: name, nodeIds },
+    );
+  } catch (error) {
+    // Name the set in the fix even when Dev's details leave it out.
+    if (error?.code === "WRITE_OUT_OF_SCOPE")
+      throw new CliError(error.code, error.message, error.exitCode ?? 1, { ...error.details, changeSetId: error.details?.changeSetId ?? checked.data.changeSetId });
+    throw error;
+  }
   return { logged: true, changeSetId: checked.data.changeSetId, nodeIds };
 }
 
+// What the post-hook says when logging a write fails. A write logged outside
+// the set's scopes (MW1-57.7) exits 2, so Claude Code shows the agent why its
+// submit will be refused; any other failure stays a note that blocks nothing.
+export function postHookFailure(error) {
+  if (error?.code === "WRITE_OUT_OF_SCOPE")
+    return { exitCode: 2, message: `nodii-dev post hook: WRITE_OUT_OF_SCOPE: ${outOfScopeText(error.message, error.details)}` };
+  return { exitCode: 0, message: `nodii-dev post hook: ${error?.code ?? "ERROR"}: ${error?.message ?? String(error)}` };
+}
+
 export const settingsSnippet = () => ({
   hooks: {
     PreToolUse: [

package/dist/oauth.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, 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";
@@ -45,73 +45,159 @@ function run(command, args, { input } = {}) {
   });
 }
 
-async function keychainStore(name, secret, os) {
+// `security -i` reads each command line into a 4096-byte buffer. A longer line
+// is cut there: the item is stored TRUNCATED and the rest of the line runs as a
+// second, failing command (Dev issue 88: the access-token cache, once the
+// JWT outgrew 4 KB, was stored cut short, every process read it as empty, and
+// every command rotated the shared refresh token). Lines stay well under it.
+export const SECURITY_LINE_MAX = 4000;
+// A secret longer than one line is stored in parts, then a header naming the
+// part count and the digest of the whole; a reader that sees a torn or partial
+// set (a writer mid-way) gets nothing rather than a wrong secret.
+const MAX_PARTS = 64;
+const CHUNKED = "chunked:v1:";
+const TOKEN_ALPHABET = /^[A-Za-z0-9._~+/=-]+$/;
+const part = (name, i) => `${name}:part:${i}`;
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const addLine = (name, svc, secret) => `add-generic-password -U -a ${name} -s ${svc} -w ${secret}`;
+// Whether `security -i` takes the secret whole on one stdin line.
+const fitsOneLine = (name, svc, secret) => TOKEN_ALPHABET.test(secret) && addLine(name, svc, secret).length <= SECURITY_LINE_MAX;
+const checkName = (name) => {
+  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);
+};
+
+async function keychainPut(name, secret, os, { exec, svc }) {
   if (os === "darwin") {
-    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);
+    checkName(name);
     // 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]);
+    if (fitsOneLine(name, svc, secret)) await exec("security", ["-i"], { input: `${addLine(name, svc, secret)}\n` });
+    else await exec("security", ["add-generic-password", "-U", "-a", name, "-s", svc, "-w", secret]);
     return "macOS Keychain";
   }
   if (os === "linux") {
     try {
-      await run("secret-tool", ["store", "--label=nodii-dev OAuth", "service", service, "account", name], { input: secret });
+      await exec("secret-tool", ["store", "--label=nodii-dev OAuth", "service", svc, "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();
+async function keychainGet(name, os, { exec, svc }) {
+  if (os === "darwin") return (await exec("security", ["find-generic-password", "-a", name, "-s", svc, "-w"])).trim();
+  if (os === "linux") return (await exec("secret-tool", ["lookup", "service", svc, "account", name])).trim();
   throw new Error("no keychain");
 }
 
-async function keychainDelete(name, os) {
+async function removeItem(name, os, { exec, svc }) {
   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 {}
+    if (os === "darwin") await exec("security", ["delete-generic-password", "-a", name, "-s", svc]);
+    else if (os === "linux") await exec("secret-tool", ["clear", "service", svc, "account", name]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Parts are numbered from 1 without gaps, so the first one missing ends the
+// sweep, whatever header (or none) the parts were written under.
+async function removeParts(name, from, os, kc) {
+  if (os !== "darwin") return;
+  for (let i = from; i <= MAX_PARTS && (await removeItem(part(name, i), os, kc)); i++);
+}
+
+export async function keychainStore(name, secret, os = platform(), { exec = run, svc = service } = {}) {
+  const kc = { exec, svc };
+  if (os !== "darwin" || !TOKEN_ALPHABET.test(secret) || fitsOneLine(name, svc, secret)) {
+    const stored = await keychainPut(name, secret, os, kc);
+    await removeParts(name, 1, os, kc);
+    return stored;
+  }
+  checkName(name);
+  const size = SECURITY_LINE_MAX - addLine(part(name, MAX_PARTS), svc, "").length;
+  const parts = [];
+  if (size >= 256) for (let i = 0; i < secret.length && parts.length <= MAX_PARTS; i += size) parts.push(secret.slice(i, i + size));
+  if (!parts.length || parts.length > MAX_PARTS) throw new CliError("KEYCHAIN_UNAVAILABLE", "The secret is too long for the Keychain helper; nothing was stored.", 2);
+  // The parts in one `security` run, then, only once they are all in, the
+  // header that names them (`security -i` goes on past a failed line).
+  await exec("security", ["-i"], { input: `${parts.map((chunk, i) => addLine(part(name, i + 1), svc, chunk)).join("\n")}\n` });
+  await exec("security", ["-i"], { input: `${addLine(name, svc, `${CHUNKED}${parts.length}:${sha256(secret)}`)}\n` });
+  await removeParts(name, parts.length + 1, os, kc);
+  return "macOS Keychain";
 }
 
-export async function storeRefreshToken(clientId, token, os = platform()) {
-  return keychainStore(account(clientId), token, os);
+export async function keychainLoad(name, os = platform(), { exec = run, svc = service } = {}) {
+  const value = await keychainGet(name, os, { exec, svc });
+  if (!value.startsWith(CHUNKED)) return value;
+  const [count, digest] = value.slice(CHUNKED.length).split(":");
+  const n = Number.parseInt(count, 10);
+  if (!Number.isInteger(n) || n < 1 || n > MAX_PARTS) throw new Error("bad chunk header");
+  let secret = "";
+  for (let i = 1; i <= n; i++) secret += await keychainGet(part(name, i), os, { exec, svc });
+  if (sha256(secret) !== digest) throw new Error("chunks do not match their header");
+  return secret;
 }
 
-export async function loadRefreshToken(clientId, os = platform()) {
+export async function keychainDelete(name, os = platform(), { exec = run, svc = service } = {}) {
+  const kc = { exec, svc };
+  await removeItem(name, os, kc);
+  await removeParts(name, 1, os, kc);
+}
+
+// Read back after writing: a store that "succeeds" but keeps something else (a
+// truncated write) loses the rotated token, and the next refresh replays the
+// old one, which revokes the whole chain.
+export async function storeRefreshToken(clientId, token, os = platform(), keychain = {}) {
+  const stored = await keychainStore(account(clientId), token, os, keychain);
+  if ((await keychainLoad(account(clientId), os, keychain).catch(() => null)) !== token)
+    throw new CliError("KEYCHAIN_WRITE_FAILED", "The refresh token read back from the keychain differs from the one written.", 1);
+  return stored;
+}
+
+export async function loadRefreshToken(clientId, os = platform(), keychain = {}) {
   try {
-    const token = await keychainLoad(account(clientId), os);
+    const token = await keychainLoad(account(clientId), os, keychain);
     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);
+export async function deleteRefreshToken(clientId, os = platform(), keychain = {}) {
+  await keychainDelete(account(clientId), os, keychain);
 }
 
 // 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()) {
+export async function loadAccessToken(clientId, os = platform(), keychain = {}) {
   try {
-    const cached = JSON.parse(Buffer.from(await keychainLoad(accessAccount(clientId), os), "base64url").toString("utf8"));
+    const cached = JSON.parse(Buffer.from(await keychainLoad(accessAccount(clientId), os, keychain), "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 {}
+let cacheWarned = false;
+
+// A cache that cannot be written is not fatal to this command, but every other
+// process would then refresh too, so it is said once, on stderr.
+export async function storeAccessToken(clientId, cached, os = platform(), keychain = {}) {
+  const value = Buffer.from(JSON.stringify(cached)).toString("base64url");
+  try {
+    await keychainStore(accessAccount(clientId), value, os, keychain);
+    if ((await keychainLoad(accessAccount(clientId), os, keychain)) === value) return;
+  } catch {}
+  if (cacheWarned) return;
+  cacheWarned = true;
+  process.stderr.write("nodii-dev: warning: the access token could not be cached in the keychain, so every nodii-dev process will refresh the sign-in.\n");
 }
 
-export async function deleteAccessToken(clientId, os = platform()) {
-  await keychainDelete(accessAccount(clientId), os);
+export async function deleteAccessToken(clientId, os = platform(), keychain = {}) {
+  await keychainDelete(accessAccount(clientId), os, keychain);
 }
 
 async function oauthPost(authUrl, path, fields, fetchImpl = fetch, timeoutMs = REFRESH_TIMEOUT_MS) {
@@ -326,7 +412,10 @@ export async function withRefreshLock(fn, { clientId, path = refreshLockPath(cli
 // 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;
+// A refresh is never cut off early: once the request is sent, nodii-auth may
+// rotate the token whether or not the answer arrives, so aborting it at 10 s
+// lost the successor and the next run replayed the old token (Dev issue 88).
+export const REFRESH_TIMEOUT_MS = 20_000;
 const REFRESH_ATTEMPTS = 4;
 const RETRY_AFTER_CAP_MS = 5_000;
 // The whole refresh, retries included, fits well inside the lock's wait
@@ -353,7 +442,10 @@ async function postRefresh(authUrl, clientId, refreshToken, fetchImpl, timeoutMs
       signal: AbortSignal.timeout(timeoutMs),
     });
   } catch (error) {
-    return { ok: false, status: 0, body: {}, json: false, reason: error?.name === "TimeoutError" ? "timeout" : "unreachable" };
+    // Only a connection that never opened is known not to have reached the
+    // server; a timeout or a dropped connection may follow a rotation.
+    const reason = error?.name === "TimeoutError" ? "timeout" : UNSENT_CODES.has(error?.cause?.code ?? error?.code) ? "unsent" : "unreachable";
+    return { ok: false, status: 0, body: {}, json: false, reason };
   }
   let raw = "";
   try { raw = await response.text(); } catch {}
@@ -364,12 +456,44 @@ async function postRefresh(authUrl, clientId, refreshToken, fetchImpl, timeoutMs
   return { ok: response.ok, status: response.status, body, json, retryAfterMs: Number.isFinite(retryAfter) ? retryAfter * 1000 : undefined };
 }
 
+// Node's (undici) and Bun's codes for a connection that never opened.
+const UNSENT_CODES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "UND_ERR_CONNECT_TIMEOUT", "ConnectionRefused", "FailedToOpenSocket"]);
+// The answers that show the token was not used, so it may be sent again: the
+// edge's rate limit, nodii-auth failing before it commits (500, 503), and a
+// non-JSON 4xx (a proxy or WAF refusing before nodii-auth; it answers JSON).
+// Anything else that is not an answer (a gateway timeout, a 2xx without
+// tokens, an HTML page) may follow a rotation, and is not sent again here.
+const RESEND_STATUS = new Set([429, 500, 503]);
+const mayResend = (result) => (result.status === 0 ? result.reason === "unsent" : RESEND_STATUS.has(result.status) || (result.status >= 400 && result.status < 500 && !result.json));
+
+// From the moment a refresh token is presented until its successor is stored,
+// the process must not die: nodii-auth has already marked the old token used,
+// so losing the new one means the next refresh replays the old one and the
+// server revokes the whole chain, signing out every process on the machine.
+// SIGINT, SIGTERM and SIGHUP are held over that window and re-raised on
+// release, which comes after the refresh lock is let go. SIGHUP is re-raised
+// only with a terminal attached: under nohup (no terminal) it was meant to be
+// ignored, and re-raising it would kill what nohup kept alive.
+export function holdSignals() {
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  let caught = null;
+  const hold = (signal) => { caught ??= signal; };
+  for (const signal of signals) process.on(signal, hold);
+  return {
+    release() {
+      for (const signal of signals) process.off(signal, hold);
+      if (caught && (caught !== "SIGHUP" || process.stdin.isTTY || process.stdout.isTTY)) process.kill(process.pid, caught);
+    },
+  };
+}
+
 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;
+  #signals;
   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
@@ -397,7 +521,7 @@ export class OAuthAuthProvider {
         // 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 });
+      }, { clientId: config.clientId }).finally(() => this.#release());
     })().finally(() => { this.#refreshPromise = undefined; });
     return this.#refreshPromise;
   }
@@ -409,9 +533,15 @@ export class OAuthAuthProvider {
       // 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);
+      // Signals wait while a token is in flight; on success, until it is stored.
+      this.#signals ??= holdSignals();
       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 !== "ok") this.#release();
       if (kind !== "retry" || attempt >= REFRESH_ATTEMPTS) return { kind, result, attempts: attempt };
+      // A request that may have reached the server is not sent again with the
+      // same token: if it was rotated, that is a replay and revokes the chain.
+      if (!mayResend(result)) 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 };
@@ -461,6 +591,11 @@ export class OAuthAuthProvider {
     await this.storeAccess(config.clientId, { token: this.#accessToken, expiresAt: this.#expiresAt });
     return this.#accessToken;
   }
+  #release() {
+    const signals = this.#signals;
+    this.#signals = undefined;
+    signals?.release();
+  }
   async headers() {
     const config = await readConfig();
     return { authorization: `Bearer ${await this.accessToken()}`, ...(config.agentId ? { "x-agent-id": config.agentId } : {}) };

package/package.json

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