@nodii/dev 0.6.17 → 0.6.21

package/dist/figma.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
-import { CliError, devRequest, encode } from "./core.js";
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError, devAsyncRequest, devRequest, encode } from "./core.js";
 
 /** A Figma file key, or the key inside a figma.com file link (a branch link's branch key). */
 export function figmaFileKey(value) {
@@ -55,7 +56,158 @@ export function resubmitPayload(text, file) {
   return body;
 }
 
-export async function figmaResubmit(id, file, { request = devRequest, read = (f) => readFile(f, "utf8") } = {}) {
+// Async submit, re-submit and dry run (`Prefer: respond-async`): a large set's
+// gate outlasts the edge's 30 s timeout (CS-2470 got a 504 while Dev went on to
+// answer 422), so Dev answers 202 with a job, polled here until it ends. A Dev
+// that ignores the header answers synchronously, which is taken as is.
+const JOB_POLL_MS = [1000, 2000, 3000, 5000];
+// Dev fails a job still running after 20 minutes (SUBMIT_JOB_LOST); stop a little later.
+const JOB_WAIT_MS = 25 * 60_000;
+const JOB_PROGRESS_MS = 15_000;
+const IN_PROGRESS = new Set(["SUBMIT_IN_PROGRESS", "CONFORMANCE_IN_PROGRESS"]);
+const GATEWAY = new Set(["HTTP_502", "HTTP_504"]);
+const TRANSIENT = new Set([...GATEWAY, "HTTP_503", "HTTP_429", "DEV_UNREACHABLE"]);
+const stderrLine = (line) => process.stderr.write(`${line}\n`);
+/** --sync sends the old synchronous call; the default (or --async) runs it as a job in Dev and polls it. */
+export function submitMode(f) {
+  if (f.sync && f.async) throw new CliError("USAGE", "pass --sync or --async, not both", 2);
+  return Boolean(f.sync);
+}
+const DONE = new Set(["succeeded", "failed"]);
+const jobName = (job) => (job.kind === "conformance" ? "dry run" : job.kind === "resubmit" ? "re-submit" : "submit");
+
+export const submitJobPath = (job) => `/api/v1/design/change-sets/${encode(job.changeSetId)}/submit-jobs/${encode(job.id)}`;
+
+/** A finished job as the synchronous call would have answered: `succeeded` is its 200 body, `failed` throws its error. */
+export function jobOutcome(job) {
+  if (job.state === "succeeded") return job.result ?? {};
+  const e = job.error ?? {};
+  if (e.code === "SUBMIT_JOB_LOST")
+    throw new CliError(e.code, `${e.message ?? "Dev lost this job"} (${jobName(job)} job ${job.id} on ${job.changeSetId}). Run the same command again.`, 1, { job });
+  // Never a gateway code: that reads as the edge's gateway on this command's own request.
+  throw new CliError(!e.code || GATEWAY.has(e.code) ? "SUBMIT_JOB_FAILED" : e.code, e.message ?? `Dev's ${jobName(job)} job ${job.id} failed with HTTP ${job.httpStatus}`, 1, e.details ?? { httpStatus: job.httpStatus });
+}
+
+/** Polls a running job (getDesignSubmitJob) with backoff until it ends, printing progress. */
+export async function pollSubmitJob(job, { request = devRequest, sleep = delay, progress = stderrLine, now = Date.now } = {}) {
+  const start = now();
+  let printed = start;
+  let misses = 0;
+  for (let n = 0; !DONE.has(job.state); n++) {
+    if (now() - start > JOB_WAIT_MS)
+      throw new CliError("SUBMIT_JOB_TIMEOUT", `Dev's ${jobName(job)} job ${job.id} is still running after ${Math.round(JOB_WAIT_MS / 60_000)} min; read ${job.changeSetId} with nodii-dev figma changeset show ${job.changeSetId} before running it again.`, 1, { job });
+    await sleep(JOB_POLL_MS[Math.min(n, JOB_POLL_MS.length - 1)]);
+    try {
+      job = { changeSetId: job.changeSetId, ...(await request("GET", submitJobPath(job))).data };
+      misses = 0;
+    } catch (error) {
+      if (error?.code === "SUBMIT_JOB_NOT_FOUND")
+        throw new CliError("SUBMIT_JOB_LOST", `Dev no longer knows ${jobName(job)} job ${job.id} on ${job.changeSetId} (it restarted). Read the set with nodii-dev figma changeset show ${job.changeSetId}, then run the same command again.`, 1, { job });
+      if (!TRANSIENT.has(error?.code)) throw error;
+      // A poll that hit the edge's gateway or a blip retries; the job runs on in Dev.
+      if (++misses > 5)
+        throw new CliError("SUBMIT_JOB_UNREACHABLE", `Lost touch with Dev (${error.code}) while its ${jobName(job)} job ${job.id} on ${job.changeSetId} ran; the job goes on in Dev. Do not send it again yet: read the set with nodii-dev figma changeset show ${job.changeSetId} in a few minutes.`, 1, { job, cause: error.code });
+      progress(`polling ${job.id} again (${error.code})`);
+      continue;
+    }
+    if (!DONE.has(job.state) && now() - printed >= JOB_PROGRESS_MS) {
+      printed = now();
+      progress(`${job.changeSetId}: ${jobName(job)} job ${job.id} still running (${Math.round((printed - start) / 1000)} s)`);
+    }
+  }
+  progress(`${job.changeSetId}: ${jobName(job)} job ${job.id} ${job.state}${job.httpStatus && job.state === "failed" ? ` (HTTP ${job.httpStatus})` : ""} after ${Math.round((now() - start) / 1000)} s`);
+  return jobOutcome(job);
+}
+
+/**
+ * Sends a change-set call with `Prefer: respond-async` and answers as the
+ * synchronous call does. A 409 SUBMIT_IN_PROGRESS or CONFORMANCE_IN_PROGRESS
+ * names the job already running for the set: that one is polled instead.
+ */
+export async function changeSetJob(method, path, body, { changeSetId, kind, send = devAsyncRequest, progress = stderrLine, ...poll } = {}) {
+  let job;
+  let adopted = null;
+  try {
+    const { status, payload } = await send(method, path, body);
+    if (status !== 202) return payload;
+    if (!payload?.data?.id)
+      throw new CliError("SUBMIT_UNCONFIRMED", `Dev took the ${kind === "conformance" ? "dry run" : kind} on ${changeSetId} as a job (202) but named no job; do not send it again yet: read the set with nodii-dev figma changeset show ${changeSetId}.`, 1, { changeSetId, payload });
+    job = { changeSetId, ...payload.data };
+    progress(`${job.changeSetId}: Dev is running the ${jobName(job)} as job ${job.id}; polling`);
+  } catch (error) {
+    if (!IN_PROGRESS.has(error?.code) || !error.details?.job?.id) throw error;
+    job = { changeSetId, ...error.details.job };
+    // A dry run never answers for a submit, nor a submit for a dry run.
+    if ((job.kind === "conformance") !== (kind === "conformance")) throw error;
+    progress(`a ${jobName(job)} is already running: ${job.id}; polling it`);
+    adopted = error;
+  }
+  if (!adopted) return pollSubmitJob(job, { progress, ...poll });
+  // An adopted job ran its own body, so its answer is never this command's: it
+  // ends as the 409 it met, with that job's outcome in the details.
+  let outcome;
+  try {
+    outcome = { result: await pollSubmitJob(job, { progress, ...poll }) };
+  } catch (error) {
+    outcome = { error: { code: error.code, message: error.message, details: error.details } };
+  }
+  // Polling that stopped (lost the edge, or timed out) leaves the job's end unknown.
+  const unknown = !outcome.result && ["SUBMIT_JOB_UNREACHABLE", "SUBMIT_JOB_TIMEOUT"].includes(outcome.error.code);
+  const ended = outcome.result ? "succeeded" : unknown ? `has no known outcome yet (${outcome.error.code})` : `failed (${outcome.error.code})`;
+  throw new CliError(
+    adopted.code,
+    `The ${jobName(job)} already running on ${changeSetId} (job ${job.id}) ${ended}; this command's body was not sent. Read the set with nodii-dev figma changeset show ${changeSetId}, then run it again ${unknown ? "only once that job has ended" : "if it still needs to go"}.`,
+    1,
+    { job, ...outcome },
+  );
+}
+
+// A submit lands an editing set in_review, a re-submit an applying one: only that move
+// from the call's own entry state counts, never a set that was in review already.
+const ENTRY = { submit: "editing", resubmit: "applying" };
+
+/**
+ * A submit or re-submit that met the edge's gateway (502/504) may still have
+ * landed in Dev (CS-2468 did): read the set and say which, never send again.
+ */
+async function afterGatewayTimeout(id, kind, before, error, { sync, request, progress }) {
+  let after = null;
+  try {
+    after = (await request("GET", `/api/v1/design/change-sets/${encode(id)}`)).data;
+  } catch {}
+  const status = error.code.replace("HTTP_", "HTTP ");
+  if (before?.state === ENTRY[kind] && after?.state === "in_review") {
+    progress(`Dev answered ${status} (the edge's gateway), but the submit landed: ${id} is ${after.state}. Its warnings were not returned; run nodii-dev figma changeset show ${id}.`);
+    return { data: after, warnings: [], landedAfterGatewayTimeout: true };
+  }
+  throw new CliError(
+    "SUBMIT_UNCONFIRMED",
+    [
+      `Dev answered ${status} (the edge's gateway timeout)${after ? ` and ${id} is still ${after.state}` : `, and ${id} could not be read`}.`,
+      "Dev may still be working on it: do not send it again yet.",
+      `Check with nodii-dev figma changeset show ${id} in a few minutes; if nothing changed, submit again${sync ? " without --sync, so Dev runs it as a job" : ""}.`,
+    ].join("\n"),
+    1,
+    { changeSetId: id, state: after?.state ?? null, gateway: error.code },
+  );
+}
+
+/** A submit or re-submit, async unless `sync`; a gateway timeout is checked against the set, not resent. */
+async function submitCall(id, kind, body, { sync = false, request = devRequest, progress = stderrLine, ...job } = {}) {
+  const path = `/api/v1/design/change-sets/${encode(id)}/${kind}`;
+  let before = null;
+  try {
+    before = (await request("GET", `/api/v1/design/change-sets/${encode(id)}`)).data;
+  } catch {}
+  try {
+    return sync ? await request("POST", path, body) : await changeSetJob("POST", path, body, { changeSetId: id, kind, request, progress, ...job });
+  } catch (error) {
+    if (!GATEWAY.has(error?.code)) throw error;
+    return afterGatewayTimeout(id, kind, before, error, { sync, request, progress });
+  }
+}
+
+export async function figmaResubmit(id, file, { request = devRequest, read = (f) => readFile(f, "utf8"), ...options } = {}) {
   if (!id || !file) throw new CliError("USAGE", "figma resubmit CHANGE_SET PAYLOAD.json", 2);
   let text;
   try {
@@ -65,7 +217,7 @@ export async function figmaResubmit(id, file, { request = devRequest, read = (f)
   }
   const body = resubmitPayload(text, file);
   try {
-    return await request("POST", `/api/v1/design/change-sets/${encode(id)}/resubmit`, body);
+    return await submitCall(id, "resubmit", body, { request, ...options });
   } catch (error) {
     const say = RESUBMIT_REFUSALS[error?.code];
     if (!say) throw scopeRefusal(error, id) ?? error;
@@ -185,6 +337,11 @@ export function conformanceLines(r) {
     lines.push(`${r.libraryUpdatePending.length} node(s) behind a library republish (not failures; accept the library update in this file, MW6-17):`);
     for (const f of r.libraryUpdatePending) lines.push(`  ${f.nodeId}\t${f.check ?? "libraryUpdatePending"}\t${f.detail}`);
   }
+  // Email is outside the app-UI gate (Dev issue 116): counted, never silent.
+  if (r.outOfScope?.length) {
+    lines.push(`out of scope: ${r.outOfScopeNodes ?? "?"} node(s) in ${r.outOfScope.length} part(s), not checked (email: the Email kit, email bodies, the block palette):`);
+    for (const f of r.outOfScope) lines.push(`  ${f.nodeId}\toutOfScope\t${f.detail}`);
+  }
   // Warnings never refuse: STALE_FIGMA_VERSION is one (Dev issue 92, until
   // Dev issue 107). With staleVersion, its wait is printed below instead.
   const warnings = (r.warnings ?? []).filter((f) => !(r.staleVersion && f.check === "STALE_FIGMA_VERSION"));
@@ -314,12 +471,15 @@ export const figmaScopeSetText = (id, data) =>
     ...(data?.released?.length ? [`Released for other sets: ${data.released.map(scopeText).join(", ")}`] : []),
   ].join("\n");
 
-export const figmaSubmit = (id, payload, { request = devRequest } = {}) =>
-  changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/submit`, payload);
+/** A submit, async unless `sync` (options: sync, request, send, progress, sleep). */
+export const figmaSubmit = (id, payload, { request = devRequest, ...options } = {}) =>
+  changeSetCall(id, (method, path, body) => submitCall(id, "submit", body, { request, ...options }))(
+    "POST", `/api/v1/design/change-sets/${encode(id)}/submit`, payload);
 
-/** checkDesignConformance: the submit gate's dry run on a change set; changes no state. Body: { figmaVersion?, items? }. */
-export const figmaConformance = (id, body = {}, { request = devRequest } = {}) =>
-  changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/conformance`, body);
+/** checkDesignConformance: the submit gate's dry run on a change set; changes no state. Body: { figmaVersion?, items? }. Async unless `sync`. */
+export const figmaConformance = (id, body = {}, { request = devRequest, sync = false, ...options } = {}) =>
+  changeSetCall(id, (method, path, b) => (sync ? request(method, path, b) : changeSetJob(method, path, b, { changeSetId: id, kind: "conformance", request, ...options })))(
+    "POST", `/api/v1/design/change-sets/${encode(id)}/conformance`, body);
 
 export const figmaLogWrite = (id, tool, nodeIds, { request = devRequest } = {}) =>
   changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/writes`, { tool, nodeIds });

package/dist/lanes.js

@@ -4,6 +4,8 @@ import { CliError, encode, devRequest, query, readConfig, requireFlag } from "./
 
 const execFileAsync = promisify(execFile);
 const via = { via: "nodii-dev" };
+// heartbeatLane's note limit.
+const BLOCK_NOTE_MAX = 500;
 
 const need = (value, usage) => {
   if (!value) throw new CliError("USAGE", usage, 2);
@@ -131,11 +133,31 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
     if (selected.length !== 1) throw new CliError("USAGE", "lane step needs exactly one of --start, --done, or --block.", 2);
     const side = requireFlag(flags, "side");
     const stepRef = need(flags[selected[0]] === true ? args[1] : flags[selected[0]], "lane step needs <key> --side <side> --start|--done|--block <step>");
+    const reason = typeof flags.reason === "string" ? flags.reason.trim() : "";
+    if (flags.reason !== undefined && (selected[0] !== "block" || !reason)) throw new CliError("USAGE", "--reason TEXT goes with --block.", 2);
     const lane = (await request("GET", `/api/v1/lanes/${encode(id)}`)).data;
     const step = lane.steps.find((x) => x.side === side && (x.id === stepRef || x.stepKey === stepRef));
     if (!step) throw new CliError("STEP_NOT_FOUND", `No ${side} step ${stepRef} on ${ref}.`, 1);
+    // Dev's blockLaneStep stores no reason and refuses a step that is already
+    // blocked (INVALID_STEP_STATE), so the reason is a lane heartbeat note
+    // until Dev issue 125 lets the step carry it.
+    const note = reason && `blocked ${side}/${step.stepKey}: ${reason}`;
+    if (note.length > BLOCK_NOTE_MAX) throw new CliError("USAGE", `--reason is too long: Dev keeps ${BLOCK_NOTE_MAX} characters of a lane note, and this one is ${note.length}.`, 2);
+    const recordReason = () => request("POST", `/api/v1/lanes/${encode(id)}/heartbeat`, { note, ...via });
+    if (selected[0] === "block" && step.state === "blocked") {
+      if (!reason) throw new CliError("USAGE", `${side}/${step.stepKey} on ${ref} is already blocked; pass --reason TEXT to record its new reason.`, 2);
+      await recordReason();
+      return { payload: { data: step, reason }, human: `${ref}: ${side}/${step.stepKey} is still blocked; new reason recorded.` };
+    }
     const payload = await request("POST", `/api/v1/lanes/${encode(id)}/steps/${encode(step.id)}/${selected[0]}`, via);
-    return { payload, human: `${ref}: ${side}/${step.stepKey} ${selected[0]}` };
+    if (reason) {
+      try {
+        await recordReason();
+      } catch (error) {
+        throw new CliError(error?.code ?? "LANE_NOTE_FAILED", `${side}/${step.stepKey} on ${ref} is blocked, but its reason was not recorded (${error?.message ?? error}). Run the same --block --reason again to record it.`, 1);
+      }
+    }
+    return { payload: reason ? { ...payload, reason } : payload, human: `${ref}: ${side}/${step.stepKey} ${selected[0]}${reason ? `: ${reason}` : ""}` };
   }
   if (action === "evidence") {
     const body = evidence(flags);

package/dist/oauth.js

@@ -1,9 +1,9 @@
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rm, stat, utimes } from "node:fs/promises";
+import { mkdir, open, readdir, 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";
+import { basename, dirname, join, resolve } from "node:path";
+import { CliError, authProvider, configPath, isOAuthConfig, readConfig, writeConfig } from "./core.js";
 
 // nodii-auth is reached through the platform edge (/oauth/device/authorize and
 // /oauth/token are public there), so auth and API calls share one host.
@@ -40,7 +40,7 @@ function run(command, args, { input } = {}) {
     child.stdout.on("data", (chunk) => { stdout += chunk; });
     child.stderr.on("data", () => {}); // Credential helpers can echo secrets in diagnostics.
     child.on("error", reject);
-    child.on("close", (code) => code === 0 ? resolve(stdout) : reject(new Error(`${command} failed`)));
+    child.on("close", (code) => code === 0 ? resolve(stdout) : reject(Object.assign(new Error(`${command} failed`), { exitCode: code })));
     if (input) child.stdin.end(input);
   });
 }
@@ -157,11 +157,20 @@ export async function storeRefreshToken(clientId, token, os = platform(), keycha
   return stored;
 }
 
+const SECURITY_NOT_FOUND = 44;
+
 export async function loadRefreshToken(clientId, os = platform(), keychain = {}) {
   try {
     const token = await keychainLoad(account(clientId), os, keychain);
     if (token) return token;
-  } catch {}
+  } catch (error) {
+    // `security` exits 44 for an item that is not there. Any other exit is a
+    // keychain that could not be read (locked, access denied): not a missing
+    // sign-in, so `login` must not replace it. `secret-tool lookup` exits 1
+    // for both, so on Linux the two cannot be told apart.
+    if (os === "darwin" && Number.isInteger(error?.exitCode) && error.exitCode !== SECURITY_NOT_FOUND)
+      throw new CliError("KEYCHAIN_UNAVAILABLE", "The keychain could not be read (locked or access denied); the saved sign-in was kept. Unlock it and retry.", 1);
+  }
   throw new CliError("OAUTH_LOGIN_REQUIRED", "OAuth credentials are unavailable; run `nodii-dev login` again.", 2);
 }
 
@@ -271,22 +280,150 @@ export async function deviceLogin({ clientId, authUrl = DEFAULT_AUTH_URL, edgeUr
     return stored;
   }, { clientId });
   const claims = decodeClaims(token.access_token);
-  const person = claims.sub ?? null;
-  const installationId = claims.metadata?.oauth_app_installation_id ?? claims.oauth_app_installation_id ?? null;
+  const { person, installationId } = signedInAs(claims);
   const agentId = keptAgent(previous, { clientId, person, installationId, edgeUrl });
   await writeConfig({ authProvider: "oauth", authUrl, edgeUrl, clientId, tenantHint, agentId, person, installationId });
   return { storage, claims, agentId };
 }
 
+/** Who an access token's claims sign in, and through which installation. */
+export const signedInAs = (claims) => ({ person: claims.sub ?? null, installationId: claims.metadata?.oauth_app_installation_id ?? claims.oauth_app_installation_id ?? null });
+
 export function decodeClaims(token) {
   try { return JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf8")); } catch { return {}; }
 }
 
+// ONE sign-in per machine (Dev issue 110). The refresh credential is kept in
+// the keychain under the OAuth client, not beside a config file, so every
+// config path on the machine shares it, an empty or new one included. A config
+// adds only routing (auth and edge URLs, tenant) and the agent.
+export const configHome = () => join(homedir(), ".config/nodii-dev");
+
+/** The OAuth configs in the config home and its agents/ other than the one in use, newest first. */
+export async function machineConfigs({ home = configHome(), current = configPath() } = {}) {
+  const agents = join(home, "agents");
+  const names = await readdir(agents).catch(() => []);
+  const files = new Set([resolve(home, "config.json"), ...names.filter((n) => n.endsWith(".json")).map((n) => resolve(agents, n))]);
+  files.delete(resolve(current));
+  const found = await Promise.all([...files].map(async (file) => {
+    try {
+      const config = JSON.parse(await readFile(file, "utf8"));
+      return isOAuthConfig(config) && config.clientId ? { config, mtime: (await stat(file)).mtimeMs } : null;
+    } catch {
+      return null;
+    }
+  }));
+  return found.filter(Boolean).sort((a, b) => b.mtime - a.mtime).map((x) => x.config);
+}
+
+/**
+ * The machine's sign-in for an OAuth client. `valid` when the shared access
+ * token is live or the keychain refresh credential refreshes; `dead` when
+ * nodii-auth refused the credential (invalid_grant); `refused` when it refused
+ * the refresh otherwise; `none` when the keychain holds none. Any other failure
+ * (auth unreachable, a refresh busy, a keychain that cannot be read) throws: it
+ * says nothing about the sign-in, so nothing may replace it. `check: false`
+ * only reads who the machine's configs name (state `unchecked`), without a
+ * refresh. `config` is the routing to write, never with an agent.
+ */
+export async function machineSignIn({ current = null, clientId, authUrl, edgeUrl, tenantHint, check = true, provider, configs = machineConfigs } = {}) {
+  // The client named, else the config's, else the machine's newest, else nodii-dev's own.
+  const wanted = clientId ?? (isOAuthConfig(current) ? current.clientId : undefined);
+  const known = isOAuthConfig(current) && (!wanted || current.clientId === wanted) ? current
+    : (await configs()).find((c) => !wanted || c.clientId === wanted) ?? null;
+  const id = wanted ?? known?.clientId ?? DEFAULT_CLIENT_ID;
+  // The credential is checked against the host it came from (a config's), so
+  // a refresh is never sent to another auth server, whose invalid_grant would
+  // clear the machine's one credential. A new device flow uses the current
+  // defaults instead (see login).
+  const config = { authProvider: "oauth", authUrl: authUrl ?? known?.authUrl ?? DEFAULT_AUTH_URL, edgeUrl: edgeUrl ?? known?.edgeUrl ?? DEFAULT_EDGE_URL,
+    clientId: id, tenantHint: tenantHint ?? known?.tenantHint ?? PLATFORM_TENANT };
+  const person = known?.person ?? null;
+  if (!check) return { state: "unchecked", person, config };
+  let token;
+  try {
+    token = await (provider ?? (await authProvider())).accessToken(config);
+  } catch (error) {
+    // nodii-auth refusing the refresh outright (a JSON 4xx other than
+    // invalid_grant, e.g. invalid_client) cannot be fixed by retrying either.
+    if (error?.code === "OAUTH_REFRESH_FAILED") return { state: "refused", person, refusal: error.details?.refusal ?? "refused", config };
+    if (error?.code !== "OAUTH_LOGIN_REQUIRED") throw error;
+    return error.details?.grant ? { state: "dead", person, grant: error.details.grant, config } : { state: "none", person, config };
+  }
+  const claims = signedInAs(decodeClaims(token));
+  const signedIn = claims.person ?? person;
+  const installationId = claims.installationId ?? (known?.person === signedIn ? known.installationId ?? null : null);
+  return { state: "valid", person: signedIn, config: { ...config, person: signedIn, installationId } };
+}
+
+const sameSignIn = (a, b) => isOAuthConfig(a) && ["authUrl", "edgeUrl", "clientId", "tenantHint", "person", "installationId"].every((k) => (a[k] ?? null) === (b[k] ?? null));
+
+/**
+ * `login --force` and `logout` replace or end the machine's one sign-in, for
+ * every lane at once, so a lane's config (named `lane-*.json`, as the
+ * coordinator names them) refuses both.
+ */
+export function refuseFromLane(command, path = configPath()) {
+  if (basename(path).startsWith("lane-"))
+    throw new CliError("USAGE", `${command} would end the machine's one sign-in for every lane; a lane never runs it. Ask the coordinator.`, 2);
+}
+
+/**
+ * `nodii-dev login`. A machine that already holds a valid sign-in says so and
+ * starts no device flow, writing its routing into an empty config path (the
+ * agent is kept only if it is bound to that same sign-in). A dead sign-in is
+ * named, then replaced by a device flow. `force` starts a device flow whatever
+ * the machine holds and names whom it replaces; a lane's config (named
+ * `lane-*.json`, as the coordinator names them) refuses it.
+ */
+export async function login({ force = false, previous = null, clientId, authUrl, edgeUrl, tenantHint, noBrowser, scope, output = console.log,
+  machine = machineSignIn, device = deviceLogin, write = writeConfig, path = configPath() } = {}) {
+  if (force) refuseFromLane("login --force", path);
+  const found = await machine({ current: previous, clientId, authUrl, edgeUrl, tenantHint, check: !force });
+  if (found.state === "valid") {
+    if (scope !== undefined)
+      throw new CliError("USAGE", `You're already signed in as ${found.person} on this machine. A different --scope replaces that one sign-in for every config path: ${basename(path).startsWith("lane-") ? "ask the coordinator" : "pass --force with it"}.`, 2);
+    if (sameSignIn(previous, found.config)) return { alreadySignedIn: true, person: found.person, agentId: previous.agentId ?? null };
+    const agentId = keptAgent(previous, found.config);
+    await write({ ...found.config, agentId });
+    return { alreadySignedIn: true, person: found.person, agentId };
+  }
+  // A lane never starts a device flow: it would replace every lane's sign-in, and no one watches a lane's terminal.
+  refuseFromLane("login (a new device sign-in)", path);
+  if (found.state === "dead")
+    output(`The saved sign-in${found.person ? ` of ${found.person}` : ""} on this machine is no longer accepted by nodii-auth (${found.grant?.error ?? "invalid_grant"}: expired, revoked or replayed). Starting a new sign-in.`);
+  if (found.state === "refused")
+    output(`nodii-auth refused to refresh the saved sign-in${found.person ? ` of ${found.person}` : ""} on this machine (${found.refusal}). Starting a new sign-in.`);
+  if (force) output(found.person ? `This replaces the sign-in of ${found.person} on this machine, for every config path that uses it.` : "This replaces the machine's sign-in, if it holds one (no config here names a person).");
+  // A new sign-in goes to the flags' hosts or the current defaults, as login always did, never an old config's.
+  const result = await device({ clientId: found.config.clientId, authUrl: authUrl ?? DEFAULT_AUTH_URL, edgeUrl: edgeUrl ?? DEFAULT_EDGE_URL, tenantHint: tenantHint ?? PLATFORM_TENANT,
+    noBrowser, scope, output, previous });
+  const dead = { dead: found.grant?.error ?? "invalid_grant", refused: found.refusal }[found.state];
+  return { ...result, alreadySignedIn: false, person: result.claims?.sub ?? null, ...(force ? { replaced: found.person ?? null } : {}),
+    ...(dead ? { replacedDeadSignIn: { person: found.person ?? null, error: dead } } : {}) };
+}
+
+/**
+ * The config for a command that needs a sign-in on a config path that has
+ * none yet (`agent register` on a fresh lane path): the machine's valid
+ * sign-in, written there without an agent.
+ */
+export async function adoptMachineSignIn({ machine = machineSignIn, write = writeConfig, env = process.env } = {}) {
+  const found = await machine({ clientId: env.NODII_DEV_OAUTH_CLIENT_ID, authUrl: env.NODII_DEV_AUTH_URL, edgeUrl: env.NODII_DEV_EDGE_URL, tenantHint: env.NODII_DEV_PLATFORM_TENANT_ID });
+  if (found.state !== "valid")
+    throw new CliError("NOT_LOGGED_IN", {
+      dead: "This machine's sign-in is no longer accepted by nodii-auth (invalid_grant). Run `nodii-dev login` first.",
+      refused: `nodii-auth refused to refresh this machine's sign-in (${found.refusal}). Run \`nodii-dev login\` first.`,
+    }[found.state] ?? "No sign-in on this machine. Run `nodii-dev login` first.", 2);
+  await write(found.config);
+  return found.config;
+}
+
 // 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`);
+  return join(configHome(), `oauth-refresh-${String(clientId).replace(/[^A-Za-z0-9_.-]/g, "_")}.lock`);
 }
 
 const LOCK_STALE_MS = 30_000;
@@ -510,10 +647,11 @@ export class OAuthAuthProvider {
     this.#expiresAt = cached.expiresAt;
     return true;
   }
-  async accessToken() {
+  /** `given`: the routing to use instead of the config file (a sign-in found on the machine). */
+  async accessToken(given) {
     if (this.#accessToken && Date.now() < this.#expiresAt - 30_000) return this.#accessToken;
     this.#refreshPromise ??= (async () => {
-      const config = await readConfig();
+      const config = given ?? await readConfig();
       // 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 } = {}) => {
@@ -599,7 +737,7 @@ export class OAuthAuthProvider {
     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);
+      throw new CliError("OAUTH_REFRESH_FAILED", `nodii-auth refused the refresh (${describe(result)}); the saved credential was kept.`, 1, { refusal: describe(result) });
     const body = result.body;
     for (let attempt = 1; ; attempt++) {
       try { await this.storeToken(config.clientId, body.refresh_token); break; } catch (error) {