cleargate 0.3.0 → 0.5.0

package/dist/cli.js

@@ -14,7 +14,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "cleargate",
-  version: "0.3.0",
+  version: "0.5.0",
   private: false,
   type: "module",
   description: "Planning framework for Claude Code agents \u2014 sprint/epic/story protocol, four-agent loop (architect/developer/qa/reporter), Karpathy-style awareness wiki.",
@@ -318,13 +318,294 @@ function matchesGlob(filePath, glob) {
 
 // src/commands/join.ts
 import * as os from "os";
+
+// src/auth/identity-flow.ts
+import * as readline from "readline";
+var IdentityFlowError = class extends Error {
+  constructor(code, message) {
+    super(message ?? code);
+    this.code = code;
+    this.name = "IdentityFlowError";
+  }
+  code;
+};
+var DeviceFlowError = class extends Error {
+  constructor(code, message) {
+    super(message ?? code);
+    this.code = code;
+    this.name = "DeviceFlowError";
+  }
+  code;
+};
+async function pickProvider(opts) {
+  const available = opts.available ?? ["github", "email"];
+  if (opts.flag !== void 0) {
+    const flagLower = opts.flag.toLowerCase();
+    if (!available.includes(flagLower)) {
+      throw new IdentityFlowError(
+        "provider_unknown",
+        `cleargate: unknown provider '${opts.flag}'. Available: ${available.join(", ")}`
+      );
+    }
+    return flagLower;
+  }
+  if (!opts.isTTY) {
+    throw new IdentityFlowError(
+      "provider_required",
+      "cleargate: --auth required in non-interactive mode"
+    );
+  }
+  if (available.length === 1) {
+    return available[0];
+  }
+  return promptPicker(available, opts);
+}
+var PROVIDER_LABELS = {
+  github: "GitHub OAuth",
+  email: "Email magic-link"
+};
+async function promptPicker(options, { stdin, stdout } = {}) {
+  const write = stdout ?? ((s) => process.stdout.write(s));
+  write("How would you like to verify your email?\n");
+  options.forEach((p, i) => {
+    write(`  ${i + 1}. ${PROVIDER_LABELS[p]}
+`);
+  });
+  write(`Choice [1-${options.length}]: `);
+  const inputStream = stdin ?? process.stdin;
+  return new Promise((resolve14, reject) => {
+    let settled = false;
+    const rl = readline.createInterface({
+      input: inputStream,
+      output: void 0,
+      terminal: false
+    });
+    rl.once("line", (line) => {
+      settled = true;
+      rl.close();
+      const idx = parseInt(line.trim(), 10) - 1;
+      if (isNaN(idx) || idx < 0 || idx >= options.length) {
+        reject(
+          new IdentityFlowError(
+            "invalid_choice",
+            `cleargate: invalid choice '${line.trim()}'. Enter a number between 1 and ${options.length}.`
+          )
+        );
+        return;
+      }
+      resolve14(options[idx]);
+    });
+    rl.once("error", (err) => {
+      if (!settled) {
+        settled = true;
+        reject(err);
+      }
+    });
+    rl.once("close", () => {
+      if (!settled) {
+        settled = true;
+        reject(new IdentityFlowError("provider_required", "cleargate: no provider selected"));
+      }
+    });
+  });
+}
+function defaultSleep(ms) {
+  return new Promise((resolve14) => setTimeout(resolve14, ms));
+}
+async function startDeviceFlow(opts) {
+  const sleepFn = opts.sleepFn ?? defaultSleep;
+  let currentIntervalMs = opts.intervalOverrideMs !== void 0 ? opts.intervalOverrideMs : Math.max(opts.interval, 5) * 1e3;
+  const expiresAtMs = Date.now() + opts.expiresIn * 1e3;
+  const deadline = expiresAtMs + (opts.deadlineGraceMs ?? 1e4);
+  while (Date.now() < deadline) {
+    await sleepFn(currentIntervalMs);
+    let pollRes;
+    try {
+      pollRes = await opts.fetchPoll(opts.deviceCode);
+    } catch {
+      throw new DeviceFlowError("unreachable");
+    }
+    if (pollRes.status === 403) {
+      let body2 = {};
+      try {
+        body2 = await pollRes.json();
+      } catch {
+      }
+      if (body2["error"] === "access_denied") {
+        throw new DeviceFlowError("access_denied");
+      }
+      throw new DeviceFlowError("not_admin");
+    }
+    if (pollRes.status === 410) {
+      throw new DeviceFlowError("expired_token");
+    }
+    if (!pollRes.status || pollRes.status < 200 || pollRes.status >= 300) {
+      if (pollRes.status >= 500 || pollRes.status < 100) {
+        throw new DeviceFlowError("server_error");
+      }
+    }
+    let body;
+    try {
+      body = await pollRes.json();
+    } catch {
+      throw new DeviceFlowError("server_error");
+    }
+    const errorField = body["error"];
+    if (typeof errorField === "string") {
+      if (errorField === "authorization_pending") {
+        continue;
+      }
+      if (errorField === "slow_down") {
+        const retryAfter = body["interval"];
+        if (typeof retryAfter === "number") {
+          const bumped = retryAfter * 1e3;
+          if (bumped > currentIntervalMs) {
+            currentIntervalMs = bumped;
+          }
+        } else {
+          currentIntervalMs += 5e3;
+        }
+        continue;
+      }
+      if (errorField === "access_denied") {
+        throw new DeviceFlowError("access_denied");
+      }
+      if (errorField === "expired_token") {
+        throw new DeviceFlowError("expired_token");
+      }
+      throw new DeviceFlowError("server_error");
+    }
+    if (body["pending"] === true) {
+      const shouldApplyBump = opts.sleepFn !== void 0 || opts.intervalOverrideMs === void 0;
+      if (shouldApplyBump && typeof body["retry_after"] === "number") {
+        const bumped = body["retry_after"] * 1e3;
+        if (bumped > currentIntervalMs) {
+          currentIntervalMs = bumped;
+        }
+      }
+      continue;
+    }
+    if (typeof body["access_token"] === "string") {
+      return { accessToken: body["access_token"] };
+    }
+    if (typeof body["admin_token"] === "string") {
+      return { accessToken: body["admin_token"] };
+    }
+    throw new DeviceFlowError("server_error");
+  }
+  throw new DeviceFlowError("timeout");
+}
+function mapProviderError(httpStatus, errorCode, retryAfterSeconds) {
+  if (httpStatus === 400) {
+    switch (errorCode) {
+      case "provider_not_allowed":
+        return {
+          message: "cleargate: this invite requires a different provider \u2014 re-run with `--auth <pinned>`",
+          exitCode: 9,
+          retryable: true
+        };
+      case "provider_unknown":
+        return {
+          message: "cleargate: server does not have that provider registered \u2014 contact the project admin",
+          exitCode: 9,
+          retryable: false
+        };
+      case "identity_proof_required":
+        return {
+          message: "cleargate: this CLI is out of date \u2014 please upgrade and retry (`npm i -g cleargate@latest`)",
+          exitCode: 11,
+          retryable: false
+        };
+      default:
+        return {
+          message: "cleargate: invalid request to server (please file a bug)",
+          exitCode: 7,
+          retryable: false
+        };
+    }
+  }
+  if (httpStatus === 403 && errorCode === "email_mismatch") {
+    return {
+      message: "cleargate: verified email does not match the invitee \u2014 ask your admin to re-issue the invite",
+      exitCode: 10,
+      retryable: false
+    };
+  }
+  if (httpStatus === 404) {
+    return {
+      message: "cleargate: invite not found",
+      exitCode: 4,
+      retryable: false
+    };
+  }
+  if (httpStatus === 410) {
+    switch (errorCode) {
+      case "invite_expired":
+        return {
+          message: "cleargate: invite expired. Request a new invite",
+          exitCode: 3,
+          retryable: false
+        };
+      case "invite_already_consumed":
+        return {
+          message: "cleargate: invite already consumed. Request a new invite",
+          exitCode: 3,
+          retryable: false
+        };
+      case "challenge_expired":
+        return {
+          message: "cleargate: code expired. Re-run `cleargate join <url>` to start over",
+          exitCode: 3,
+          retryable: false
+        };
+      default:
+        return {
+          message: "cleargate: invite no longer valid. Request a new invite",
+          exitCode: 3,
+          retryable: false
+        };
+    }
+  }
+  if (httpStatus === 429) {
+    const retryHint = retryAfterSeconds !== void 0 ? `${retryAfterSeconds}` : "900";
+    return {
+      message: `cleargate: too many requests. Retry after ${retryHint}s`,
+      exitCode: 8,
+      retryable: true
+    };
+  }
+  if (httpStatus === 502 && errorCode === "provider_error") {
+    return {
+      message: "cleargate: code didn't match. Try again, or restart with `cleargate join <url>`",
+      exitCode: 12,
+      retryable: true
+    };
+  }
+  if (httpStatus >= 500) {
+    return {
+      message: `cleargate: server error ${httpStatus}`,
+      exitCode: 6,
+      retryable: false
+    };
+  }
+  return {
+    message: `cleargate: unexpected error ${httpStatus} ${errorCode}`,
+    exitCode: 7,
+    retryable: false
+  };
+}
+
+// src/commands/join.ts
+import * as readline2 from "readline";
 var UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var GITHUB_DEVICE_FLOW_URL = "https://github.com/login/oauth/access_token";
 async function joinHandler(opts) {
   const fetchFn = opts.fetch ?? globalThis.fetch;
   const stdout = opts.stdout ?? ((s) => process.stdout.write(s));
   const stderr = opts.stderr ?? ((s) => process.stderr.write(s));
   const exit = opts.exit ?? ((c) => process.exit(c));
   const hostname3 = opts.hostname ?? (() => os.hostname());
+  const isTTY = opts.isTTY ?? process.stdin.isTTY === true;
   let token;
   let baseUrl;
   try {
@@ -355,60 +636,309 @@ async function joinHandler(opts) {
     exit(5);
     return;
   }
-  let response;
-  try {
-    response = await fetchFn(`${baseUrl}/join/${token}`, { method: "POST" });
-  } catch (err) {
-    stderr(
-      `cleargate: cannot reach ${baseUrl} (${err instanceof Error ? err.message : String(err)}).
-`
-    );
-    exit(2);
+  if (opts.nonInteractive && !opts.auth) {
+    stderr("cleargate: --auth required in non-interactive mode\n");
+    exit(1);
     return;
   }
-  if (response.status === 410) {
-    const body = await response.json().catch(() => ({}));
-    if (body.error === "invite_expired") {
-      stderr("cleargate: invite expired. Request a new invite.\n");
-    } else {
-      stderr("cleargate: invite already consumed. Request a new invite.\n");
-    }
-    exit(3);
+  if (opts.nonInteractive && opts.auth === "email" && !opts.code) {
+    stderr("cleargate: --code required for email provider in non-interactive mode\n");
+    exit(1);
     return;
   }
-  if (response.status === 404) {
-    stderr("cleargate: invite not found.\n");
-    exit(4);
+  if (opts.nonInteractive && opts.auth === "github") {
+    stderr("cleargate: GitHub auth requires browser interaction; use `--auth email` for non-interactive flows\n");
+    exit(1);
     return;
   }
-  if (response.status === 429) {
-    const retry = response.headers.get("retry-after") ?? "900";
-    stderr(`cleargate: too many requests. Retry after ${retry}s.
+  let provider;
+  try {
+    provider = await pickProvider({
+      flag: opts.auth,
+      isTTY: !opts.nonInteractive && isTTY,
+      available: ["github", "email"],
+      stdin: opts.stdin,
+      stdout
+    });
+  } catch (err) {
+    if (err instanceof IdentityFlowError) {
+      stderr(`${err.message}
 `);
-    exit(8);
-    return;
+      exit(1);
+      return;
+    }
+    throw err;
   }
-  if (response.status >= 500) {
-    stderr(`cleargate: server error ${response.status}.
-`);
-    exit(6);
+  let challengeRes;
+  try {
+    challengeRes = await fetchFn(`${baseUrl}/join/${token}/challenge`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({ provider })
+    });
+  } catch (err) {
+    stderr(
+      `cleargate: cannot reach ${baseUrl} (${err instanceof Error ? err.message : String(err)}).
+`
+    );
+    exit(2);
     return;
   }
-  if (!response.ok) {
-    stderr(`cleargate: unexpected status ${response.status}.
+  if (!challengeRes.ok) {
+    const body = await challengeRes.json().catch(() => ({}));
+    const { message, exitCode } = mapProviderError(
+      challengeRes.status,
+      body.error ?? "",
+      parseRetryAfter(challengeRes)
+    );
+    stderr(`${message}
 `);
-    exit(7);
+    exit(exitCode);
     return;
   }
-  let rawBody;
+  let challengeBody;
   try {
-    rawBody = await response.json();
+    challengeBody = await challengeRes.json();
   } catch {
     stderr("cleargate: server returned non-JSON response.\n");
     exit(7);
     return;
   }
-  const b = rawBody;
+  const challengeId = challengeBody.challenge_id;
+  const clientHints = challengeBody.client_hints;
+  let completeRawBody;
+  if (provider === "github") {
+    const deviceCode = clientHints["device_code"];
+    const userCode = clientHints["user_code"];
+    const verificationUri = clientHints["verification_uri"];
+    const expiresIn = typeof clientHints["expires_in"] === "number" ? clientHints["expires_in"] : 900;
+    const interval = typeof clientHints["interval"] === "number" ? clientHints["interval"] : 5;
+    stdout(`Open the following URL in your browser and enter the code:
+`);
+    stdout(`  URL:  ${verificationUri}
+`);
+    stdout(`  Code: ${userCode}
+`);
+    stdout(`  (Code expires in ${Math.floor(expiresIn / 60)} minutes)
+`);
+    stdout("Waiting for authorization...\n");
+    let accessToken;
+    try {
+      const result = await startDeviceFlow({
+        deviceCode,
+        interval,
+        expiresIn,
+        fetchPoll: async (dc) => {
+          const res = await fetchFn(GITHUB_DEVICE_FLOW_URL, {
+            method: "POST",
+            headers: {
+              Accept: "application/json",
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              device_code: dc,
+              grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+            })
+          });
+          return {
+            status: res.status,
+            json: () => res.json()
+          };
+        },
+        ...opts.sleepFn !== void 0 ? { sleepFn: opts.sleepFn } : {},
+        ...opts.intervalOverrideMs !== void 0 ? { intervalOverrideMs: opts.intervalOverrideMs } : {}
+      });
+      accessToken = result.accessToken;
+    } catch (err) {
+      if (err instanceof DeviceFlowError) {
+        switch (err.code) {
+          case "access_denied":
+            stderr("cleargate: access denied \u2014 you declined authorization in the browser.\n");
+            exit(5);
+            return;
+          case "expired_token":
+            stderr("cleargate: device code expired \u2014 please re-run `cleargate join <url>`.\n");
+            exit(5);
+            return;
+          case "unreachable":
+            stderr("cleargate: cannot reach GitHub. Check your connection and retry.\n");
+            exit(2);
+            return;
+          default:
+            stderr(`cleargate: GitHub device flow error: ${err.code}
+`);
+            exit(6);
+            return;
+        }
+      }
+      stderr("cleargate: unexpected error during GitHub device flow\n");
+      exit(6);
+      return;
+    }
+    let completeRes;
+    try {
+      completeRes = await fetchFn(`${baseUrl}/join/${token}/complete`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ challenge_id: challengeId, proof: { access_token: accessToken } })
+      });
+    } catch (err) {
+      stderr(`cleargate: cannot reach ${baseUrl} (${err instanceof Error ? err.message : String(err)}).
+`);
+      exit(2);
+      return;
+    }
+    if (!completeRes.ok) {
+      const body = await completeRes.json().catch(() => ({}));
+      const { message, exitCode } = mapProviderError(
+        completeRes.status,
+        body.error ?? "",
+        parseRetryAfter(completeRes)
+      );
+      stderr(`${message}
+`);
+      exit(exitCode);
+      return;
+    }
+    try {
+      completeRawBody = await completeRes.json();
+    } catch {
+      stderr("cleargate: server returned non-JSON response.\n");
+      exit(7);
+      return;
+    }
+  } else {
+    const sentTo = typeof clientHints["sent_to"] === "string" ? clientHints["sent_to"] : "(unknown)";
+    const maxRetries = 3;
+    stdout(`We sent a 6-digit code to ${sentTo}.
+`);
+    if (opts.code !== void 0) {
+      let completeRes;
+      try {
+        completeRes = await fetchFn(`${baseUrl}/join/${token}/complete`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Accept: "application/json" },
+          body: JSON.stringify({ challenge_id: challengeId, proof: { code: opts.code } })
+        });
+      } catch (err) {
+        stderr(`cleargate: cannot reach ${baseUrl} (${err instanceof Error ? err.message : String(err)}).
+`);
+        exit(2);
+        return;
+      }
+      if (!completeRes.ok) {
+        const body = await completeRes.json().catch(() => ({}));
+        const { message, exitCode } = mapProviderError(
+          completeRes.status,
+          body.error ?? "",
+          parseRetryAfter(completeRes)
+        );
+        stderr(`${message}
+`);
+        exit(exitCode);
+        return;
+      }
+      try {
+        completeRawBody = await completeRes.json();
+      } catch {
+        stderr("cleargate: server returned non-JSON response.\n");
+        exit(7);
+        return;
+      }
+    } else {
+      let readNextLine2 = function() {
+        if (lineQueue.length > 0) return Promise.resolve(lineQueue.shift());
+        if (rlClosed) return Promise.resolve("");
+        return new Promise((resolve14) => {
+          lineWaiters.push(resolve14);
+        });
+      };
+      var readNextLine = readNextLine2;
+      const inputStream = opts.stdin ?? process.stdin;
+      const rl = readline2.createInterface({
+        input: inputStream,
+        output: void 0,
+        terminal: false
+      });
+      const lineQueue = [];
+      const lineWaiters = [];
+      let rlClosed = false;
+      rl.on("line", (line) => {
+        const waiter = lineWaiters.shift();
+        if (waiter) {
+          waiter(line);
+        } else {
+          lineQueue.push(line);
+        }
+      });
+      rl.once("close", () => {
+        rlClosed = true;
+        for (const waiter of lineWaiters.splice(0)) {
+          waiter("");
+        }
+      });
+      let succeeded = false;
+      try {
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+          stdout("Enter code: ");
+          const otpCode = (await readNextLine2()).trim();
+          let completeRes;
+          try {
+            completeRes = await fetchFn(`${baseUrl}/join/${token}/complete`, {
+              method: "POST",
+              headers: { "Content-Type": "application/json", Accept: "application/json" },
+              body: JSON.stringify({ challenge_id: challengeId, proof: { code: otpCode } })
+            });
+          } catch (err) {
+            stderr(`cleargate: cannot reach ${baseUrl} (${err instanceof Error ? err.message : String(err)}).
+`);
+            exit(2);
+            return;
+          }
+          if (completeRes.ok) {
+            try {
+              completeRawBody = await completeRes.json();
+            } catch {
+              stderr("cleargate: server returned non-JSON response.\n");
+              exit(7);
+              return;
+            }
+            succeeded = true;
+            break;
+          }
+          const body = await completeRes.json().catch(() => ({}));
+          const errorCode = body.error ?? "";
+          if (completeRes.status === 410 || errorCode === "challenge_expired") {
+            const { message, exitCode } = mapProviderError(completeRes.status, errorCode, parseRetryAfter(completeRes));
+            stderr(`${message}
+`);
+            exit(exitCode);
+            return;
+          }
+          if (completeRes.status === 403 || completeRes.status >= 400 && completeRes.status < 500 && errorCode !== "provider_error") {
+            const { message, exitCode } = mapProviderError(completeRes.status, errorCode, parseRetryAfter(completeRes));
+            stderr(`${message}
+`);
+            exit(exitCode);
+            return;
+          }
+          if (attempt < maxRetries) {
+            stderr(`cleargate: code didn't match. ${maxRetries - attempt} attempt${maxRetries - attempt === 1 ? "" : "s"} remaining.
+`);
+          }
+        }
+      } finally {
+        rl.close();
+      }
+      if (!succeeded) {
+        stderr(`cleargate: code didn't match after ${maxRetries} tries. Run \`cleargate join <url>\` again to get a new code.
+`);
+        exit(12);
+        return;
+      }
+    }
+  }
+  const b = completeRawBody;
   if (typeof b.refresh_token !== "string" || typeof b.project_name !== "string") {
     stderr("cleargate: server returned unexpected response shape.\n");
     exit(7);
@@ -431,6 +961,12 @@ async function joinHandler(opts) {
     exit(99);
   }
 }
+function parseRetryAfter(res) {
+  const hdr = res.headers?.get?.("retry-after");
+  if (!hdr) return void 0;
+  const n = parseInt(hdr, 10);
+  return isNaN(n) ? void 0 : n;
+}
 
 // src/commands/stamp.ts
 import * as fs4 from "fs";
@@ -1617,13 +2153,13 @@ async function readDriftState(projectRoot) {
 }
 
 // src/lib/prompts.ts
-import * as readline from "readline";
+import * as readline3 from "readline";
 async function promptYesNo(question, defaultYes, opts) {
   const stdoutFn = opts?.stdout ?? ((s) => process.stdout.write(s));
   stdoutFn(question + "\n");
   const inputStream = opts?.stdin ?? process.stdin;
   return new Promise((resolve14) => {
-    const rl = readline.createInterface({
+    const rl = readline3.createInterface({
       input: inputStream,
       output: void 0,
       // we handle output ourselves
@@ -1654,7 +2190,7 @@ async function promptEmail(question, defaultValue, opts) {
   stdoutFn(question + "\n");
   const inputStream = opts?.stdin ?? process.stdin;
   return new Promise((resolve14) => {
-    const rl = readline.createInterface({
+    const rl = readline3.createInterface({
       input: inputStream,
       output: void 0,
       // we handle output ourselves
@@ -3004,7 +3540,7 @@ ${row}
 // src/commands/wiki-audit-status.ts
 import * as fs19 from "fs";
 import * as path20 from "path";
-import * as readline2 from "readline";
+import * as readline4 from "readline";
 var TERMINAL = /* @__PURE__ */ new Set(["Completed", "Done", "Abandoned", "Closed", "Resolved"]);
 async function wikiAuditStatusHandler(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -3143,7 +3679,7 @@ async function wikiAuditStatusHandler(opts = {}) {
       answer = await opts.promptReader();
     } else {
       answer = await new Promise((resolve14) => {
-        const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
+        const rl = readline4.createInterface({ input: process.stdin, output: process.stdout });
         rl.question(`apply ${fixable.length} changes? [y/N] `, (ans) => {
           rl.close();
           resolve14(ans);
@@ -7814,9 +8350,6 @@ import * as fs33 from "fs";
 import * as path43 from "path";
 import * as os5 from "os";
 var DEFAULT_MCP_URL = "http://localhost:3000";
-function sleep(ms) {
-  return new Promise((resolve14) => setTimeout(resolve14, ms));
-}
 function resolveMcpUrl(mcpUrlFlag, env) {
   return (mcpUrlFlag ?? (env ?? process.env)["CLEARGATE_MCP_URL"] ?? DEFAULT_MCP_URL).replace(/\/$/, "");
 }
@@ -7837,7 +8370,6 @@ async function adminLoginHandler(opts = {}) {
   const stdout = opts.stdout ?? ((msg) => process.stdout.write(msg + "\n"));
   const stderr = opts.stderr ?? ((msg) => process.stderr.write(msg + "\n"));
   const exitFn = opts.exit ?? ((code) => process.exit(code));
-  const sleepFn = opts.sleepFn ?? sleep;
   const mcpBase = resolveMcpUrl(opts.mcpUrl, opts.env);
   let startData;
   try {
@@ -7864,79 +8396,95 @@ async function adminLoginHandler(opts = {}) {
   stdout(`  Code: ${startData.user_code}`);
   stdout(`  (Code expires in ${Math.floor(startData.expires_in / 60)} minutes)`);
   stdout("Waiting for authorization...");
-  let currentInterval = opts.intervalOverrideMs ?? Math.max(startData.interval, 5) * 1e3;
-  const expiresAtMs = Date.now() + startData.expires_in * 1e3;
-  const deadline = expiresAtMs + 1e4;
-  let successData = null;
-  while (Date.now() < deadline) {
-    await sleepFn(currentInterval);
-    let pollRes;
-    try {
-      pollRes = await fetchFn(`${mcpBase}/admin-api/v1/auth/device/poll`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Accept: "application/json" },
-        body: JSON.stringify({ device_code: startData.device_code })
-      });
-    } catch (err) {
-      stderr(`cleargate: error: network error while polling (${err instanceof Error ? err.message : String(err)})`);
-      return exitFn(3);
-    }
-    if (pollRes.status === 403) {
-      const body = await pollRes.json().catch(() => ({}));
-      if (body.error === "access_denied") {
-        stderr("cleargate: error: access denied \u2014 you declined authorization in the browser.");
-        return exitFn(5);
-      }
-      stderr("cleargate: error: your GitHub account is not authorized as an admin user.");
-      return exitFn(4);
-    }
-    if (pollRes.status === 410) {
-      stderr("cleargate: error: device code expired \u2014 please run `cleargate admin login` again.");
-      return exitFn(5);
-    }
-    if (!pollRes.ok) {
-      const body = await pollRes.json().catch(() => ({}));
-      stderr(`cleargate: error: unexpected server response ${pollRes.status}: ${body.error ?? "unknown"}`);
-      return exitFn(6);
-    }
-    const pollBody = await pollRes.json();
-    if (pollBody.pending) {
-      const shouldApplyBump = opts.sleepFn !== void 0 || opts.intervalOverrideMs === void 0;
-      if (shouldApplyBump && pollBody.retry_after !== void 0) {
-        const bumped = pollBody.retry_after * 1e3;
-        if (bumped > currentInterval) {
-          currentInterval = bumped;
+  let capturedSuccessBody = null;
+  const fetchPollCapture = async (deviceCode) => {
+    const res = await fetchFn(`${mcpBase}/admin-api/v1/auth/device/poll`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({ device_code: deviceCode })
+    });
+    const originalJson = res.json.bind(res);
+    return {
+      status: res.status,
+      json: async () => {
+        const body = await originalJson();
+        if (body["pending"] === false) {
+          capturedSuccessBody = body;
         }
+        return body;
+      }
+    };
+  };
+  try {
+    await startDeviceFlow({
+      deviceCode: startData.device_code,
+      interval: startData.interval,
+      expiresIn: startData.expires_in,
+      fetchPoll: fetchPollCapture,
+      // Only pass sleepFn if the caller explicitly injected one (test seam).
+      // When sleepFn is omitted, startDeviceFlow uses its own defaultSleep.
+      // This preserves the original bump-suppression logic:
+      // shouldApplyBump = (sleepFn provided) || (intervalOverrideMs not set).
+      ...opts.sleepFn !== void 0 ? { sleepFn: opts.sleepFn } : {},
+      ...opts.intervalOverrideMs !== void 0 ? { intervalOverrideMs: opts.intervalOverrideMs } : {},
+      deadlineGraceMs: 1e4
+    });
+  } catch (err) {
+    if (err instanceof DeviceFlowError) {
+      switch (err.code) {
+        case "access_denied":
+          stderr("cleargate: error: access denied \u2014 you declined authorization in the browser.");
+          return exitFn(5);
+        case "not_admin":
+          stderr("cleargate: error: your GitHub account is not authorized as an admin user.");
+          return exitFn(4);
+        case "expired_token":
+          stderr("cleargate: error: device code expired \u2014 please run `cleargate admin login` again.");
+          return exitFn(5);
+        case "timeout":
+          stderr("cleargate: error: timed out waiting for authorization. Please try again.");
+          return exitFn(5);
+        case "unreachable":
+          stderr(`cleargate: error: network error while polling`);
+          return exitFn(3);
+        default:
+          stderr(`cleargate: error: unexpected server response`);
+          return exitFn(6);
       }
-      continue;
     }
-    successData = pollBody;
-    break;
+    stderr(`cleargate: error: unexpected error during device flow`);
+    return exitFn(6);
   }
-  if (!successData) {
+  if (!capturedSuccessBody) {
     stderr("cleargate: error: timed out waiting for authorization. Please try again.");
     return exitFn(5);
   }
+  const successBody = capturedSuccessBody;
   const authFilePath = resolveAuthFilePath(opts);
   try {
-    writeAdminAuth(authFilePath, successData.admin_token);
+    writeAdminAuth(authFilePath, successBody.admin_token);
   } catch (err) {
     stderr(`cleargate: error: failed to write ${authFilePath}: ${err instanceof Error ? err.message : String(err)}`);
     return exitFn(99);
   }
-  stdout(`Logged in successfully. Token expires ${successData.expires_at}.`);
+  stdout(`Logged in successfully. Token expires ${successBody.expires_at}.`);
   stdout(`Credentials saved to ${authFilePath} (chmod 600).`);
 }
 
 // src/cli.ts
 var program = new Command();
 program.name("cleargate").description("ClearGate CLI \u2014 connects AI agent teams to the ClearGate MCP server").version(package_default.version, "-V, --version").option("--profile <name>", "configuration profile to use", "default").option("--mcp-url <url>", "MCP server URL (overrides config file and env)").showHelpAfterError("(use `cleargate --help`)");
-program.command("join <invite-url>").description("join a ClearGate workspace using an invite URL").action(async (inviteUrl, _opts, command) => {
+program.command("join <invite-url>").description("join a ClearGate workspace using an invite URL").option("--auth <provider>", "identity provider: github | email").option("--non-interactive", "fail instead of prompting (CI mode)").option("--code <code>", "OTP code for non-interactive email auth").action(async (inviteUrl, _opts, command) => {
   const globals = command.parent.opts();
+  const cmdOpts = command.opts();
   await joinHandler({
     inviteUrl,
     profile: globals.profile,
-    mcpUrlFlag: globals.mcpUrl
+    mcpUrlFlag: globals.mcpUrl,
+    // FLASHCARD #cli #commander #optional-key: only set keys when defined
+    ...cmdOpts.auth !== void 0 ? { auth: cmdOpts.auth } : {},
+    ...cmdOpts.nonInteractive === true ? { nonInteractive: true } : {},
+    ...cmdOpts.code !== void 0 ? { code: cmdOpts.code } : {}
   });
 });
 program.command("init").description("initialise a repo with ClearGate scaffold (CLAUDE.md block, hook config, agents, templates)").option("--force", "overwrite existing files that differ from the bundled payload").option("--yes", "non-interactive: accept all defaults without prompting").action(async (opts) => {