metergraph-cli 0.2.1 → 0.2.2

package/src/setup-refusal.js

@@ -0,0 +1,172 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+// What the --json --no-browser background waiter is doing with an approval
+// it received, so the agent's rerun can report it instead of asking the
+// person for another approval. The waiter is the only writer: a foreground
+// run reports a refusal directly and never records one.
+//
+//   redeeming  the waiter holds an approval and is redeeming it (possibly
+//              waiting out a short Retry-After). A rerun waits for it.
+//   refused    the service refused the redemption: the rate budget until
+//              retry_at, or the workspace's key cap. A rerun reports it.
+//
+// The record names the setup family, the waiter's process and the approval
+// it came from. It holds no credential. It is a separate file, not a field of
+// setup.json, so an older CLI that validates setup.json strictly keeps
+// reading the project. Any read problem is treated as no record.
+//
+// The file lives in the project, so its content is untrusted: a record can
+// only delay setup for as long as this CLI would ever write it for. A
+// redeeming record expiring, or a refusal retrying, further out than that is
+// ignored and removed, so a crafted or committed record cannot block setup.
+const FILE = "setup-refusal.json";
+const MAX_BYTES = 1024;
+const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const KEYS = "approval_id,expires_at,family_id,pid,reason,retry_at,schema_version,state";
+export const REFUSAL_REASONS = Object.freeze(["setup_rate_limited", "setup_key_limit"]);
+// A redeeming record outlives no waiter: redemption plus two Retry-After
+// waits takes well under this. A rate refusal is reported for at most this.
+const MAX_RECORD_MS = 10 * 60 * 1000;
+const MAX_RATE_WAIT_MS = 5 * 60 * 1000;
+
+const fileFor = (root) => path.join(root, ".metergraph", FILE);
+const isTime = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+
+function valid(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) ||
+      Object.keys(value).sort().join() !== KEYS || value.schema_version !== 2 ||
+      !UUID.test(value.family_id) || !UUID.test(value.approval_id) ||
+      !Number.isInteger(value.pid) || value.pid < 1 || !isTime(value.expires_at)) return false;
+  if (value.state === "redeeming") return value.reason === null && value.retry_at === null;
+  if (value.state === "refused") {
+    return REFUSAL_REASONS.includes(value.reason) &&
+      (value.reason === "setup_key_limit" ? value.retry_at === null : isTime(value.retry_at));
+  }
+  return false;
+}
+
+function read(root) {
+  const file = fileFor(root);
+  let fd;
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_BYTES) return null;
+    fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+    const opened = fs.fstatSync(fd);
+    if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size > MAX_BYTES) return null;
+    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(fs.readFileSync(fd)));
+    return valid(value) ? value : null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+// Best effort: a record that cannot be written only means a rerun asks for a
+// new approval, as it did before records existed.
+function write(root, value) {
+  if (!valid(value)) return false;
+  const dir = path.join(root, ".metergraph");
+  const temp = path.join(dir, `.refusal.${randomBytes(8).toString("hex")}.tmp`);
+  try {
+    if (!fs.lstatSync(dir).isDirectory()) return false;
+    const fd = fs.openSync(temp, "wx", 0o600);
+    try { fs.writeFileSync(fd, `${JSON.stringify(value)}\n`); }
+    finally { fs.closeSync(fd); }
+    fs.renameSync(temp, fileFor(root));
+    return true;
+  } catch {
+    try { fs.unlinkSync(temp); } catch { /* no temp */ }
+    return false;
+  }
+}
+
+export function clearSetupRefusal(root) {
+  try {
+    const stat = fs.lstatSync(fileFor(root));
+    if (stat.isFile() || stat.isSymbolicLink()) fs.unlinkSync(fileFor(root));
+  } catch { /* nothing to clear */ }
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+// The waiter's handle on one approval it received. Every method is best
+// effort and only ever touches this approval's own record.
+export function waiterRecord(root, familyId, now = Date.now) {
+  const approvalId = randomUUID();
+  const base = () => ({ schema_version: 2, family_id: familyId, approval_id: approvalId, pid: process.pid,
+    expires_at: new Date(now() + MAX_RECORD_MS).toISOString() });
+  return {
+    // Early, as soon as an approval arrives: never replaces another waiter
+    // that is still alive. With force, once this waiter has won the setup
+    // state for its redemption, it takes the record over.
+    redeeming: ({ force = false } = {}) => {
+      const current = read(root);
+      if (!force && current?.state === "redeeming" && current.approval_id !== approvalId &&
+          current.pid !== process.pid && alive(current.pid) && Date.parse(current.expires_at) > now()) return false;
+      return write(root, { ...base(), state: "redeeming", reason: null, retry_at: null });
+    },
+    refused: (reason, retryAfterSeconds = null) => write(root, { ...base(), state: "refused", reason,
+      retry_at: reason === "setup_rate_limited"
+        ? new Date(now() + Math.min((retryAfterSeconds ?? 60) * 1000, MAX_RATE_WAIT_MS)).toISOString()
+        : null }),
+    // Any other outcome: drop a redeeming record this waiter left behind.
+    settle: () => {
+      const record = read(root);
+      if (record?.approval_id === approvalId && record.state === "redeeming") clearSetupRefusal(root);
+    },
+  };
+}
+
+// What a run should report before asking for an approval, or null to
+// proceed. familyId and delivered describe the saved setup state; a refusal
+// for another family, or for one already delivered, no longer applies.
+export function pendingRefusal(root, { familyId, delivered }, now = Date.now()) {
+  const record = read(root);
+  if (record === null) return null;
+  const expires = Date.parse(record.expires_at);
+  const retry = record.retry_at === null ? null : Date.parse(record.retry_at);
+  if (expires <= now || expires > now + MAX_RECORD_MS || (retry !== null && retry > now + MAX_RATE_WAIT_MS)) {
+    clearSetupRefusal(root);
+    return null;
+  }
+  // A delivered family has nothing pending, whatever the record says.
+  if (delivered) {
+    clearSetupRefusal(root);
+    return null;
+  }
+  if (record.state === "redeeming") {
+    if (record.pid === process.pid || !alive(record.pid)) {
+      clearSetupRefusal(root);
+      return null;
+    }
+    // A live waiter matters only for the saved family, or before any state
+    // is saved (a combined sign in writes it after the approval). A record
+    // for another family does not block this setup.
+    if (familyId !== null && record.family_id !== familyId) return null;
+    return { reason: "setup_in_progress", retryAfter: 5 };
+  }
+  if (record.family_id !== familyId) {
+    clearSetupRefusal(root);
+    return null;
+  }
+  if (record.reason === "setup_rate_limited") {
+    const remaining = Math.ceil((Date.parse(record.retry_at) - now) / 1000);
+    if (remaining > 0) return { reason: record.reason, retryAfter: remaining };
+    clearSetupRefusal(root);
+    return null;
+  }
+  clearSetupRefusal(root);
+  return { reason: record.reason, retryAfter: null };
+}

package/src/setup-state.js

@@ -101,10 +101,12 @@ export function readSetupState(root) {
   }
 }
 
-export function newSetupState(origin, workspaceId, profile, client) {
+// familyId is given when the family was already named in an approval, as a
+// combined sign-in and ingest approval does; otherwise a new one is chosen.
+export function newSetupState(origin, workspaceId, profile, client, familyId = randomUUID()) {
   return withSetupState({ schema_version: 1, origin, workspace_id: workspaceId,
     deployment_profile: profile, selected_client: client, skill_status: client === null ? "skipped" : "pending",
-    family_id: randomUUID(), key_id: null, phase: "unsubmitted" });
+    family_id: familyId, key_id: null, phase: "unsubmitted" });
 }
 
 // Compare-and-swap under a project-local exclusive lock. A concurrent setup

package/src/setup.js

@@ -1,4 +1,7 @@
-import { detectRemoteSession, openBrowser } from "./auth-browser.js";
+import { randomUUID } from "node:crypto";
+
+import { openBrowser } from "./auth-browser.js";
+import { classifyEnvironment, remoteSetupAction } from "./environment.js";
 import { readBinding, resolveProject } from "./auth-binding.js";
 import { startCallbackListener } from "./auth-callback.js";
 import { openUrl, runLogin } from "./auth-login.js";
@@ -9,6 +12,9 @@ import { AUTH_HTTP_TIMEOUT_MS } from "./constants.js";
 import { preflightEnv, currentEnvValues, commitEnv, isAppToken } from "./setup-env.js";
 import { newSetupState, readSetupState, setupReceipt, withSetupState, writeSetupState } from "./setup-state.js";
 import { runSkill } from "./skill.js";
+import { handoffPages } from "./environment.js";
+import { REFUSAL_REASONS, clearSetupRefusal, pendingRefusal, waiterRecord } from "./setup-refusal.js";
+import { isApprovalWaiter } from "./approval-handoff.js";
 import { ensureRepositoryIdentity, envRepository } from "./repository-identity.js";
 import { parseJsonObject } from "./http.js";
 import { deadline, failureOf, send, trapSignals } from "./transport.js";
@@ -37,8 +43,20 @@ const fail = (outcome, reason, status = "not_ready", receipt = null, next = null
 // keeps waiting; stdout has room for one line, so a second approval in the
 // same run is not started. The person approves, the run saves what it
 // finished, and the agent reruns setup, which resumes from the saved state.
+//
+// A first setup that has to sign in asks the sign-in consent to approve the
+// first ingest key as well, when the service advertises it, so the person
+// approves once. The sign-in grant and the ingest key stay separate
+// credentials: the receipt is redeemed here with its own PKCE verifier,
+// exactly as one from the ingest-only approval is. A service without that
+// support, a repair, a replacement or a project already signed in keeps the
+// separate ingest-only approval.
 export async function runSetup(options, progress = () => {}) {
-  if (options.runtime !== "local" || detectRemoteSession() !== null) return fail("unsupported", "run_on_local_machine");
+  const environment = options.environment ?? classifyEnvironment();
+  if (options.runtime !== "local" || environment.remote) {
+    const where = options.runtime !== "local" ? { kind: "declared_cloud" } : environment;
+    return fail("unsupported", "run_on_local_machine", "not_ready", null, remoteSetupAction(where, options.origin, options));
+  }
   const trap = trapSignals();
   let receipt = null;
   let loginVerified = false;
@@ -54,8 +72,14 @@ export async function runSetup(options, progress = () => {}) {
     }
     return current;
   };
-  const stop = (outcome, reason, status = "not_ready") => fail(outcome, reason, status, currentReceipt());
+  const stop = (outcome, reason, status = "not_ready", next = null) =>
+    fail(outcome, reason, status, currentReceipt(), next);
   let announced = false;
+  // Only the --json --no-browser background waiter records what it does with
+  // an approval; a foreground run reports directly.
+  const waiter = Boolean(options.announce) && isApprovalWaiter();
+  let record = null;
+  let refusalRecorded = false;
   const announce = options.announce ? (status, next) => {
     announced = true;
     options.announce(fail("action_required", "browser_approval_required", status, currentReceipt(), next).data);
@@ -73,6 +97,18 @@ export async function runSetup(options, progress = () => {}) {
         (bound !== null && (bound.origin !== saved.value.origin || bound.workspace_id !== saved.value.workspace_id)))) {
       return stop("conflict", "setup_binding_changed");
     }
+    // What an earlier --json --no-browser waiter is doing with an approval it
+    // received: still redeeming it, or refused by the service's budget. The
+    // rerun reports that instead of asking the person for another approval.
+    // It runs after the binding guard, so a rerun aimed at another deployment
+    // or workspace is refused as such and leaves the record for a correct
+    // rerun; the next action names the saved family's own deployment.
+    const pending = pendingRefusal(root, { familyId: saved?.value.family_id ?? null,
+      delivered: saved?.value.phase === "delivered" });
+    if (pending !== null) {
+      return stop(pending.reason === "setup_rate_limited" ? "rate_limited" : "conflict", pending.reason,
+        "delivery_pending", redeemNext(pending, saved?.value.origin ?? intendedOrigin));
+    }
     // An env key this setup does not own stops before any sign in, so the
     // refusal costs no approval and leaves the binding untouched. The check
     // after sign in stays, against a fresh read.
@@ -85,11 +121,27 @@ export async function runSetup(options, progress = () => {}) {
     if (bindingDiffers && !options.reconnect) return stop("conflict", "bound_to_other_workspace");
     let signedIn = bindingDiffers || options.reconnect ? { ok: false, outcome: "login_required" } :
       await verifiedSession({ project: root, configDir: options.configDir, cancel: trap.signal });
+    // An approved, unredeemed receipt for a new family, from a combined sign in.
+    let combined = null;
     if (!signedIn.ok && signedIn.outcome === "login_required") {
+      const familyId = randomUUID();
+      const ingestSetup = saved || options.repair ? null : { familyId,
+        // In the waiter, record the approval before anything else happens,
+        // so an immediate rerun waits instead of asking for another one.
+        onApproved: () => { if (waiter) record = waiterRecord(root, familyId); record?.redeeming(); },
+        supported: async (origin, profile, cancel) => {
+          const discovered = await discoverSetup(origin, profile, cancel);
+          return discovered.ok && discovered.loginSetup;
+        } };
       const login = await runLogin({ ...options, origin: intendedOrigin, workspace: intendedWorkspace,
-        project: root, reconnect: options.reconnect, expectedProfile: options.expectedProfile ?? null,
+        project: root, reconnect: options.reconnect, expectedProfile: options.expectedProfile ?? null, ingestSetup,
         announce: announce && ((data) => announce("login_pending", data.next_action)) }, progress);
-      if (login.outcome !== "ok") return stop(login.outcome, login.reason, "login_pending");
+      // Login's own next action (for example no_browser with a Metadata key
+      // alternative in a local container) is passed through.
+      if (login.outcome !== "ok") return stop(login.outcome, login.reason, "login_pending", login.data?.next_action ?? null);
+      if (login.ingestSetup && login.ingestSetup.familyId === familyId && RECEIPT.test(login.ingestSetup.code)) {
+        combined = login.ingestSetup;
+      }
       signedIn = await verifiedSession({ project: root, configDir: options.configDir, cancel: trap.signal });
     }
     if (!signedIn.ok) return stop(signedIn.outcome, signedIn.reason, "login_pending");
@@ -159,15 +211,21 @@ export async function runSetup(options, progress = () => {}) {
       return stop("conflict", "repair_requires_saved_key");
     }
 
+    // A combined sign in already approved a key for a new family. Anything
+    // that makes this anything but a first create drops the receipt unused;
+    // it expires without issuing a key.
+    if (previous !== null || options.repair) combined = null;
     // A verified rerun returned above without approval. From here a person
-    // must open an approval URL. A run that already announced its sign in URL
-    // has used its one JSON line, so it stops here and the rerun continues.
-    if (announced) return stop("action_required", "browser_approval_required", "approval_pending");
+    // must open an approval URL, unless the sign in approved the key too. A
+    // run that already announced its sign in URL has used its one JSON line,
+    // so it stops here and the rerun continues.
+    if (announced && combined === null) return stop("action_required", "browser_approval_required", "approval_pending");
     const setup = await discoverSetup(origin, profile, trap.signal);
     if (!setup.ok) return stop(setup.outcome, setup.reason);
 
     if (previous === null) {
-      writeSetupState(root, newSetupState(origin, workspaceId, profile, options.client), null);
+      writeSetupState(root, combined === null ? newSetupState(origin, workspaceId, profile, options.client)
+        : newSetupState(origin, workspaceId, profile, options.client, combined.familyId), null);
       previous = readSetupState(root);
       receipt = setupReceipt(previous.value);
     }
@@ -177,40 +235,19 @@ export async function runSetup(options, progress = () => {}) {
     // An acknowledged family is never implicitly replaced. Repair requires
     // the explicit flag and the key ID saved from its original issuance.
     if (intent === "replace_pending" && state.phase === "delivered") return stop("conflict", "repair_required");
-    const listener = await startCallbackListener();
-    let callback;
-    let clientId;
-    let pkce;
-    try {
-      const client = await clientFor(endpointsFor(origin), setup.offeredClientId, listener.redirectUri,
-        deadline(AUTH_HTTP_TIMEOUT_MS, trap.signal).signal);
-      if (!client.ok) return stop(client.outcome, client.reason);
-      clientId = client.clientId;
-      pkce = newPkce();
-      const pending = listener.wait({ state: pkce.state, issuer: `${origin}/v1/oauth`, requireIss: false,
-        timeoutMs: options.timeoutMs, cancel: trap.signal });
-      const url = new URL(`${origin}${SETUP_PATHS.authorize}`);
-      const params = {
-        client_id: clientId, redirect_uri: listener.redirectUri, state: pkce.state,
-        code_challenge: pkce.challenge, code_challenge_method: "S256",
-        workspace_id: workspaceId, family_id: state.family_id, intent,
-      };
-      if (intent === "repair") params.expected_key_id = state.key_id;
-      url.search = new URLSearchParams(params).toString();
-      if (trap.signal.aborted) return stop("authorization_failed", "cancelled");
-      if (options.noBrowser && announce) {
-        announce("approval_pending", openUrl(url.href, Math.round(options.timeoutMs / 1000), "approve ingest-only setup"));
-      } else if (options.noBrowser) progress(`Open this URL on this machine to approve ingest-only setup:\n${url.href}`);
-      else if (!(await openBrowser(url.href))) return stop("authorization_failed", "browser_unavailable");
-      else progress("Opened your browser for ingest-only setup approval.");
-      callback = await pending;
-    } finally {
-      await listener.close();
+    let approval;
+    if (combined !== null && intent === "create" && state.family_id === combined.familyId) {
+      approval = combined;
+      progress("Your sign-in approval also approved this project's ingest key.");
+    } else {
+      approval = await approveInBrowser({ origin, setup, workspaceId, state, intent, options, announce, progress,
+        cancel: trap.signal });
+      if (!approval.ok) return stop(approval.outcome, approval.reason);
+      if (waiter) {
+        record = waiterRecord(root, state.family_id);
+        record.redeeming();
+      }
     }
-    if (callback.kind === "denied") return stop("authorization_failed", "access_denied");
-    if (callback.kind === "timeout") return stop("authorization_failed", "timeout");
-    if (callback.kind === "cancelled") return stop("authorization_failed", "cancelled");
-    if (callback.kind !== "code" || !RECEIPT.test(callback.code)) return stop("authorization_failed", "callback_invalid");
 
     // Persist the ambiguity boundary before a single-use receipt is sent.
     // If the response is lost, a later run asks the browser to replace only
@@ -220,11 +257,22 @@ export async function runSetup(options, progress = () => {}) {
       return stop("conflict", "setup_state_changed");
     }
     writeSetupState(root, withSetupState(previous.value, { phase: "redeem_attempted" }), previous);
+    // This waiter won the state for its redemption: the record is now its own,
+    // even if another waiter's approval arrived first and wrote it.
+    if (waiter) {
+      record ??= waiterRecord(root, state.family_id);
+      record.redeeming({ force: true });
+    }
     previous = readSetupState(root);
-    const redeemed = await redeem(origin, { code: callback.code, client_id: clientId,
-      redirect_uri: listener.redirectUri, code_verifier: pkce.verifier,
-      family_id: state.family_id, workspace_id: workspaceId }, profile, trap.signal);
-    if (!redeemed.ok) return stop(redeemed.outcome, redeemed.reason, "delivery_pending");
+    const redeemed = await redeem(origin, { code: approval.code, client_id: approval.clientId,
+      redirect_uri: approval.redirectUri, code_verifier: approval.verifier,
+      family_id: state.family_id, workspace_id: workspaceId }, profile, trap.signal, progress);
+    if (!redeemed.ok) {
+      if (record !== null && REFUSAL_REASONS.includes(redeemed.reason)) {
+        refusalRecorded = record.refused(redeemed.reason, redeemed.retryAfter ?? null);
+      }
+      return stop(redeemed.outcome, redeemed.reason, "delivery_pending", redeemNext(redeemed, origin));
+    }
     const written = await commitEnv(plan, { token: redeemed.token, ingestUrl: origin, signal: trap.signal });
     const checked = await checkCredential(origin, redeemed.token, state, profile, trap.signal);
     if (!checked.ok || checked.keyId !== redeemed.keyId) return stop("verification_failed", "issued_key_unverified", "delivery_pending");
@@ -236,10 +284,59 @@ export async function runSetup(options, progress = () => {}) {
   } catch (error) {
     if (error instanceof Stop) return stop(error.outcome, error.reason);
     throw error;
-  } finally { trap.release(); }
+  } finally {
+    if (record !== null && !refusalRecorded) record.settle();
+    trap.release();
+  }
+}
+
+// The ingest-only approval at the setup authorization endpoint: the only
+// browser step for a repair or replacement, and the second one for a service
+// without the combined sign-in approval. Returns the receipt with the client,
+// redirect and verifier it must be redeemed with, or a stop reason.
+async function approveInBrowser({ origin, setup, workspaceId, state, intent, options, announce, progress, cancel }) {
+  const failed = (reason, outcome = "authorization_failed") => ({ ok: false, outcome, reason });
+  const listener = await startCallbackListener();
+  let callback;
+  let clientId;
+  let pkce;
+  try {
+    const client = await clientFor(endpointsFor(origin), setup.offeredClientId, listener.redirectUri,
+      deadline(AUTH_HTTP_TIMEOUT_MS, cancel).signal);
+    if (!client.ok) return failed(client.reason, client.outcome);
+    clientId = client.clientId;
+    pkce = newPkce();
+    const pending = listener.wait({ state: pkce.state, issuer: `${origin}/v1/oauth`, requireIss: false,
+      timeoutMs: options.timeoutMs, cancel });
+    const url = new URL(`${origin}${SETUP_PATHS.authorize}`);
+    const params = {
+      client_id: clientId, redirect_uri: listener.redirectUri, state: pkce.state,
+      code_challenge: pkce.challenge, code_challenge_method: "S256",
+      workspace_id: workspaceId, family_id: state.family_id, intent,
+    };
+    if (intent === "repair") params.expected_key_id = state.key_id;
+    url.search = new URLSearchParams(params).toString();
+    if (cancel.aborted) return failed("cancelled");
+    if (options.noBrowser && announce) {
+      announce("approval_pending", openUrl(url.href, Math.round(options.timeoutMs / 1000), "approve ingest-only setup"));
+    } else if (options.noBrowser) progress(`Open this URL on this machine to approve ingest-only setup:\n${url.href}`);
+    else if (!(await openBrowser(url.href))) return failed("browser_unavailable");
+    else progress("Opened your browser for ingest-only setup approval.");
+    callback = await pending;
+  } finally {
+    await listener.close();
+  }
+  if (callback.kind === "denied") return failed("access_denied");
+  if (callback.kind === "timeout") return failed("timeout");
+  if (callback.kind === "cancelled") return failed("cancelled");
+  if (callback.kind !== "code" || !RECEIPT.test(callback.code)) return failed("callback_invalid");
+  return { ok: true, code: callback.code, clientId, redirectUri: listener.redirectUri, verifier: pkce.verifier };
 }
 
 function finishSkill(root, options, envStatus) {
+  // Reached only with a verified, delivered credential, whether just issued
+  // or reused: no earlier refusal or redemption still applies.
+  clearSetupRefusal(root);
   let previous = readSetupState(root);
   if (previous === null || previous.value.phase !== "delivered") return fail("conflict", "setup_state_changed");
   if (previous.value.selected_client !== options.client) {
@@ -313,14 +410,91 @@ async function discoverSetup(origin, profile, cancel) {
   }
   const offered = offeredClientId(doc);
   if (offered === undefined) return { ok: false, outcome: "unsupported", reason: "setup_contract_mismatch" };
-  return { ok: true, offeredClientId: offered };
+  // Optional: a service that names it lets the sign-in consent approve the
+  // first ingest key too. Anything but true means the separate approval.
+  return { ok: true, offeredClientId: offered, loginSetup: doc.login_ingest_setup_supported === true };
 }
 
-async function redeem(origin, form, profile, cancel) {
-  const response = await send(origin, SETUP_PATHS.redeem, { method: "POST", form,
-    signal: deadline(AUTH_HTTP_TIMEOUT_MS, cancel).signal, maxBytes: 32768 });
-  const failed = failureOf(response);
-  if (failed) return { ok: false, ...failed };
+// The service budgets how many ingest keys setup may issue per person and per
+// workspace each minute. A refusal leaves the receipt unredeemed, and only
+// this process holds its PKCE verifier, so setup waits out a short
+// Retry-After and redeems the same receipt rather than asking for another
+// approval. It gives up after REDEEM_RETRIES waits.
+const REDEEM_RETRIES = 2;
+const MAX_RETRY_AFTER_SECONDS = 60;
+
+async function redeem(origin, form, profile, cancel, progress = () => {}) {
+  for (let attempt = 0; ; attempt += 1) {
+    const response = await send(origin, SETUP_PATHS.redeem, { method: "POST", form,
+      signal: deadline(AUTH_HTTP_TIMEOUT_MS, cancel).signal, maxBytes: 32768 });
+    const failed = failureOf(response);
+    if (failed) return { ok: false, ...failed };
+    if (response.status === 429) {
+      const wait = retryAfterSeconds(response);
+      if (wait === null || attempt >= REDEEM_RETRIES) {
+        return { ok: false, outcome: "rate_limited", reason: "setup_rate_limited", retryAfter: wait };
+      }
+      progress(`The service is pacing new ingest keys. Retrying in ${wait} seconds.`);
+      if (!(await pause(wait * 1000, cancel))) return { ok: false, outcome: "authorization_failed", reason: "cancelled" };
+      continue;
+    }
+    if (response.status === 409 && parseJsonObject(response)?.error === "setup_key_limit") {
+      return { ok: false, outcome: "conflict", reason: "setup_key_limit" };
+    }
+    return redeemResult(response, origin, form, profile);
+  }
+}
+
+// Seconds from Retry-After (or the body's retry_after_seconds), 1 to 60, or
+// null when the service gave no usable delay. The header must be whole
+// digits: "60junk" or "1.5" is unusable, as on the read path.
+const RETRY_AFTER = /^[0-9]{1,6}$/;
+
+function retryAfterSeconds(response) {
+  const raw = response.headers?.["retry-after"];
+  const header = typeof raw === "string" && RETRY_AFTER.test(raw.trim()) ? Number(raw.trim()) : null;
+  if (raw !== undefined && header === null) return null;
+  const body = parseJsonObject(response)?.retry_after_seconds;
+  const value = header !== null ? header : Number.isInteger(body) ? body : null;
+  return value !== null && value >= 1 && value <= MAX_RETRY_AFTER_SECONDS ? value : null;
+}
+
+function pause(ms, cancel) {
+  return new Promise((resolve) => {
+    if (cancel.aborted) return resolve(false);
+    const done = (value) => {
+      clearTimeout(timer);
+      cancel.removeEventListener("abort", onAbort);
+      resolve(value);
+    };
+    const onAbort = () => done(false);
+    const timer = setTimeout(() => done(true), ms);
+    cancel.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// The next action for a budget refusal. Nothing was issued, and a rerun asks
+// for a new approval.
+function redeemNext(result, origin) {
+  if (result.reason === "setup_in_progress") {
+    return { kind: "retry_later", retry_after_seconds: result.retryAfter ?? null,
+      message: "An earlier setup run for this project is still finishing an approval it received. Wait a " +
+        "few seconds, then run setup again; do not ask for another approval." };
+  }
+  if (result.reason === "setup_rate_limited") {
+    return { kind: "retry_later", retry_after_seconds: result.retryAfter ?? null,
+      message: "The service limits how many ingest keys setup can issue each minute for one person and one " +
+        "workspace. Nothing was issued. Wait a minute, then run setup again; it asks for a new approval." };
+  }
+  if (result.reason === "setup_key_limit") {
+    return { kind: "revoke_keys", url: handoffPages(origin).keys_url,
+      message: "This workspace has reached its limit of active CLI setup keys. Nothing was issued. Revoke " +
+        "unused CLI setup keys on the Keys page, then run setup again." };
+  }
+  return null;
+}
+
+function redeemResult(response, origin, form, profile) {
   if (response.status !== 200) return { ok: false, outcome: "authorization_failed", reason: "setup_redeem_rejected" };
   const body = parseJsonObject(response);
   if (body?.schema_version !== SCHEMA || body.token_type !== "ingest" || body.scope !== "ingest" ||

package/src/skill-bundle.js

@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
 // public skill at the manifest's source_url. The source has no version of its
 // own, so the revision is derived from the content hash. The hash is pinned
 // here as well as in the manifest, so editing either file alone is detected.
-const PINNED_SHA256 = "d527a67efc42a55245b9c2c8fd2687c1f31f553e154a6242d0f31466993e314e";
+const PINNED_SHA256 = "ebf784673eff0280d85974504f93c683a1dabfb54156c9d27e091131462e9d5f";
 
 const ASSET_DIR = new URL("../assets/skill/", import.meta.url);
 const MANIFEST_KEYS = ["file", "manifest_version", "name", "revision", "sha256", "size", "source_url"];
@@ -55,7 +55,7 @@ export function loadBundledSkill() {
 // The workflow skills that "skills install" writes, vendored from the public
 // skills repository at one commit. The manifest's own hash is pinned here, and
 // the manifest pins each skill's hash, so changing any file alone is detected.
-const PINNED_PACK_SHA256 = "c47c8920b633ddd9b52d0855f91361e4e193746a89d6a58f43902af6a38e9617";
+const PINNED_PACK_SHA256 = "11ab983875911c4c2ad03d2a3b7b9e9213c410e77f4ff2d27b4059354b00fe0c";
 
 const PACK_DIR = new URL("../assets/skills/", import.meta.url);
 const PACK_KEYS = ["commit", "manifest_version", "repository", "skills"];