@great-arrow/cli 0.1.65 → 0.1.67

package/README.md

@@ -31,7 +31,9 @@ gad login
 gad login --no-browser
 
 # Direct personal token (CI/CD, headless). Stored as-is; no auto-refresh.
-gad login --token gad_xxxxx
+# Over a signed-in OAuth session it takes a gad_v1_ token, keeps the session
+# when handed the session's own access token, and otherwise needs --force.
+gad login --token gad_v1_xxxxx
 
 # Check who you are (shows auth type + access-token expiry)
 gad whoami
@@ -47,11 +49,13 @@ gad logout
 gad auth token [--json]
 ```
 
-Credentials live in your OS keychain (Keychain Access / libsecret / Credential
-Vault). OAuth access tokens are short-lived and refreshed automatically; `GAD_TOKEN`
-in the environment always takes precedence for CI.
-
-Tokens are stored in the OS keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service). You can also set `GAD_TOKEN` as an environment variable.
+Credentials live in your mode-`0600` `~/.great-arrow/credential` store (inside
+`0700` `~/.great-arrow/`) and/or your OS keychain (Keychain Access / libsecret /
+Credential Vault). Keeping `~/.great-arrow/credential` synced and reading it
+first avoids repeated macOS Keychain `cdhash` password prompts when multiple
+Node.js versions (`nvm`, `volta`, Homebrew) or the stdio MCP proxy access
+automatically refreshed OAuth tokens. `GAD_TOKEN` in the environment always
+takes precedence for CI.
 
 ## Commands
 

package/dist/index.js

@@ -108,7 +108,7 @@ var require_polyfills = __commonJS({
       }
       if (platform2 === "win32") {
         fs6.rename = typeof fs6.rename !== "function" ? fs6.rename : (function(fs$rename) {
-          function rename3(from, to, cb) {
+          function rename4(from, to, cb) {
             var start = Date.now();
             var backoff = 0;
             fs$rename(from, to, function CB(er) {
@@ -128,8 +128,8 @@ var require_polyfills = __commonJS({
               if (cb) cb(er);
             });
           }
-          if (Object.setPrototypeOf) Object.setPrototypeOf(rename3, fs$rename);
-          return rename3;
+          if (Object.setPrototypeOf) Object.setPrototypeOf(rename4, fs$rename);
+          return rename4;
         })(fs6.rename);
       }
       fs6.read = typeof fs6.read !== "function" ? fs6.read : (function(fs$read) {
@@ -2082,7 +2082,7 @@ var require_polyfills2 = __commonJS({
       }
       if (platform2 === "win32") {
         fs6.rename = typeof fs6.rename !== "function" ? fs6.rename : (function(fs$rename) {
-          function rename3(from, to, cb) {
+          function rename4(from, to, cb) {
             var start = Date.now();
             var backoff = 0;
             fs$rename(from, to, function CB(er) {
@@ -2102,8 +2102,8 @@ var require_polyfills2 = __commonJS({
               if (cb) cb(er);
             });
           }
-          if (Object.setPrototypeOf) Object.setPrototypeOf(rename3, fs$rename);
-          return rename3;
+          if (Object.setPrototypeOf) Object.setPrototypeOf(rename4, fs$rename);
+          return rename4;
         })(fs6.rename);
       }
       fs6.read = typeof fs6.read !== "function" ? fs6.read : (function(fs$read) {
@@ -9437,7 +9437,7 @@ function isNodeError(value) {
 
 // src/lib/version.ts
 var CLI_PACKAGE_NAME = "@great-arrow/cli";
-var CLI_VERSION = "0.1.65";
+var CLI_VERSION = "0.1.67";
 var GAD_INSTALL_VERSION = "2026.08.08";
 var GAD_INSTALL_MIN_VERSION = "2026.06.22";
 var GAD_INSTALL_HEADER = "X-GAD-Install-Version";
@@ -9450,7 +9450,14 @@ import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 
 // src/lib/keychain.ts
-import { mkdir, writeFile, readFile, unlink } from "node:fs/promises";
+import {
+  chmod,
+  mkdir,
+  readFile,
+  rename,
+  unlink,
+  writeFile
+} from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 
@@ -9465,10 +9472,70 @@ function debugSwallow(scope, err2) {
 // src/lib/keychain.ts
 var SERVICE = "GreatArrowDigital";
 var ACCOUNT = "api-token";
+var LOGGED_OUT_TOMBSTONE = "LOGGED_OUT";
 function slotFilePath(account) {
   if (account === ACCOUNT) return join(homedir(), ".great-arrow", "credential");
   return join(homedir(), ".great-arrow", "slots", encodeURIComponent(account));
 }
+function tokenMigratedMarkerPath() {
+  return join(homedir(), ".great-arrow", "credential.migrated");
+}
+function isWellFormedTokenContent(trimmed) {
+  if (trimmed === "" || trimmed === LOGGED_OUT_TOMBSTONE) return false;
+  if (trimmed.startsWith("{") || /\s/.test(trimmed)) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed !== "object" || parsed === null) return false;
+      const o = parsed;
+      return o.tokenType === "oauth" && typeof o.accessToken === "string" && o.accessToken.length > 0 && typeof o.refreshToken === "string" && o.refreshToken.length > 0 && typeof o.accessExpiresAt === "number" && typeof o.refreshExpiresAt === "number" && typeof o.clientId === "string" && typeof o.apiUrl === "string";
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+async function inspectTokenFile() {
+  const filePath = slotFilePath(ACCOUNT);
+  try {
+    const raw = await readFile(filePath, "utf-8");
+    try {
+      await chmod(dirname(filePath), 448);
+      await chmod(filePath, 384);
+    } catch (chmodErr) {
+      debugSwallow("keychain.inspectTokenFile(chmod)", chmodErr);
+    }
+    const trimmed = raw.trim();
+    if (trimmed === LOGGED_OUT_TOMBSTONE) {
+      return { status: "tombstone" };
+    }
+    if (!isWellFormedTokenContent(trimmed)) {
+      return { status: "corrupt" };
+    }
+    return { status: "valid", value: trimmed };
+  } catch (err2) {
+    const code = err2?.code;
+    const msg = err2 instanceof Error ? err2.message : "";
+    if (code === "ENOENT" || msg.includes("ENOENT")) {
+      return { status: "missing" };
+    }
+    debugSwallow("keychain.inspectTokenFile", err2);
+    return { status: "corrupt" };
+  }
+}
+async function hasTokenMigratedMarker() {
+  try {
+    const raw = await readFile(tokenMigratedMarkerPath(), "utf-8");
+    return raw.trim() !== "";
+  } catch (err2) {
+    const code = err2?.code;
+    const msg = err2 instanceof Error ? err2.message : "";
+    if (code === "ENOENT" || msg.includes("ENOENT")) {
+      return false;
+    }
+    debugSwallow("keychain.hasTokenMigratedMarker", err2);
+    return true;
+  }
+}
 async function loadEntry(account) {
   try {
     const { AsyncEntry } = await import("@napi-rs/keyring");
@@ -9486,24 +9553,114 @@ async function readFileFallback(account) {
     return null;
   }
 }
+async function writeAtomicProtectedFile(path10, value) {
+  const dir = dirname(path10);
+  const tmpPath = `${path10}.tmp.${process.pid}.${Date.now()}`;
+  try {
+    await mkdir(dir, { recursive: true, mode: 448 });
+    await chmod(dir, 448);
+    await writeFile(tmpPath, value, { mode: 384 });
+    await chmod(tmpPath, 384);
+    await rename(tmpPath, path10);
+    return true;
+  } catch (err2) {
+    try {
+      await unlink(tmpPath);
+    } catch (cleanupErr) {
+      debugSwallow("keychain.writeFileFallback(cleanup)", cleanupErr);
+    }
+    debugSwallow("keychain.writeFileFallback", err2);
+    return false;
+  }
+}
+async function writeFileFallback(account, value) {
+  if (account === ACCOUNT && preferFileStoreWithoutKeyring()) {
+    const priorState = await inspectTokenFile();
+    if (priorState.status === "valid" || priorState.status === "tombstone") {
+      if (!await writeAtomicProtectedFile(tokenMigratedMarkerPath(), "1")) {
+        return false;
+      }
+      return writeAtomicProtectedFile(slotFilePath(ACCOUNT), value);
+    }
+    if (!await writeAtomicProtectedFile(slotFilePath(ACCOUNT), value)) {
+      return false;
+    }
+    if (!await writeAtomicProtectedFile(tokenMigratedMarkerPath(), "1")) {
+      await removeFileFallback(ACCOUNT);
+      return false;
+    }
+    return true;
+  }
+  return writeAtomicProtectedFile(slotFilePath(account), value);
+}
 async function getSecretSlot(account) {
-  const entry = await loadEntry(account);
+  if (account !== ACCOUNT) {
+    const entry2 = await loadEntry(account);
+    if (entry2) {
+      try {
+        const value = await entry2.getPassword();
+        if (value) return value;
+      } catch (err2) {
+        debugSwallow("keychain.getSecretSlot", err2);
+      }
+    }
+    return readFileFallback(account);
+  }
+  const fileState = await inspectTokenFile();
+  if (fileState.status === "tombstone" || fileState.status === "corrupt") {
+    return null;
+  }
+  if (preferFileStoreWithoutKeyring()) {
+    if (fileState.status === "valid") return fileState.value;
+    if (await hasTokenMigratedMarker()) {
+      return null;
+    }
+    const entry2 = await loadEntry(ACCOUNT);
+    if (entry2) {
+      try {
+        const value = await entry2.getPassword();
+        const trimmed = value?.trim() ?? "";
+        if (trimmed && isWellFormedTokenContent(trimmed)) {
+          const migrated = await writeFileFallback(ACCOUNT, trimmed);
+          if (!migrated) {
+            return null;
+          }
+          return trimmed;
+        }
+      } catch (err2) {
+        debugSwallow("keychain.getSecretSlot", err2);
+      }
+    }
+    return null;
+  }
+  const entry = await loadEntry(ACCOUNT);
   if (entry) {
     try {
       const value = await entry.getPassword();
-      if (value) return value;
+      const trimmed = value?.trim() ?? "";
+      if (trimmed && isWellFormedTokenContent(trimmed)) {
+        return trimmed;
+      }
     } catch (err2) {
       debugSwallow("keychain.getSecretSlot", err2);
     }
   }
-  return readFileFallback(account);
+  return fileState.status === "valid" ? fileState.value : null;
+}
+function preferFileStoreWithoutKeyring() {
+  return process.platform === "darwin" && !process.env.VITEST && process.env.GAD_FORCE_KEYRING !== "1";
 }
 async function setSecretSlot(account, value) {
+  if (account === ACCOUNT && preferFileStoreWithoutKeyring()) {
+    return writeFileFallback(ACCOUNT, value);
+  }
   const entry = await loadEntry(account);
   if (entry) {
     try {
       await entry.setPassword(value);
-      await removeFileFallback(account);
+      if (!await removeFileFallback(account)) {
+        return false;
+      }
       return true;
     } catch (err2) {
       debugSwallow("keychain.setSecretSlot", err2);
@@ -9515,25 +9672,47 @@ async function setSecretSlot(account, value) {
       return false;
     }
   }
-  try {
-    const path10 = slotFilePath(account);
-    await mkdir(dirname(path10), { recursive: true, mode: 448 });
-    await writeFile(path10, value, { mode: 384 });
-    return true;
-  } catch {
-    return false;
-  }
+  return writeFileFallback(account, value);
 }
 async function deleteSecretSlot(account) {
-  const entry = await loadEntry(account);
+  if (account !== ACCOUNT) {
+    const entry2 = await loadEntry(account);
+    if (entry2) {
+      try {
+        await entry2.deletePassword();
+      } catch (err2) {
+        debugSwallow("keychain.deleteSecretSlot", err2);
+      }
+    }
+    await removeFileFallback(account);
+    return;
+  }
+  let keychainCleared = false;
+  const entry = await loadEntry(ACCOUNT);
   if (entry) {
     try {
       await entry.deletePassword();
+      keychainCleared = true;
     } catch (err2) {
       debugSwallow("keychain.deleteSecretSlot", err2);
     }
+  } else {
+    keychainCleared = true;
+  }
+  const tombstoned = await writeFileFallback(ACCOUNT, LOGGED_OUT_TOMBSTONE);
+  if (!tombstoned) {
+    if (preferFileStoreWithoutKeyring()) {
+      throw new Error(
+        "Could not remove stored credentials from keychain or credential file."
+      );
+    }
+    const removed = await removeFileFallback(ACCOUNT);
+    if (!keychainCleared || !removed) {
+      throw new Error(
+        "Could not remove stored credentials from keychain or credential file."
+      );
+    }
   }
-  await removeFileFallback(account);
 }
 function getToken() {
   return getSecretSlot(ACCOUNT);
@@ -9547,10 +9726,13 @@ function deleteToken() {
 async function removeFileFallback(account) {
   try {
     await unlink(slotFilePath(account));
+    return true;
   } catch (err2) {
-    if (err2?.code !== "ENOENT") {
-      debugSwallow("keychain.removeFileFallback", err2);
+    if (err2?.code === "ENOENT") {
+      return true;
     }
+    debugSwallow("keychain.removeFileFallback", err2);
+    return false;
   }
 }
 
@@ -9563,16 +9745,17 @@ function isOAuthCredential(value) {
 function parseStoredValue(raw) {
   if (!raw) return null;
   const trimmed = raw.trim();
-  if (trimmed === "") return null;
-  if (trimmed.startsWith("{")) {
+  if (trimmed === "" || trimmed === "LOGGED_OUT") return null;
+  if (trimmed.startsWith("{") || /\s/.test(trimmed)) {
     try {
       const parsed = JSON.parse(trimmed);
       if (isOAuthCredential(parsed)) {
         return { kind: "oauth", credential: parsed };
       }
     } catch {
-      return { kind: "pat", token: trimmed };
+      return null;
     }
+    return null;
   }
   return { kind: "pat", token: trimmed };
 }
@@ -9594,6 +9777,17 @@ async function clearStoredCredential() {
   await deleteToken();
 }
 
+// src/lib/token-login-guard.ts
+function decideTokenLogin(input2) {
+  const { token, stored, force } = input2;
+  if (stored?.kind !== "oauth") return { action: "store" };
+  if (token === stored.credential.accessToken) {
+    return { action: "keep-oauth", reason: "same-access-token" };
+  }
+  if (token.startsWith("gad_v1_") || force) return { action: "store" };
+  return { action: "refuse", reason: "would-replace-oauth" };
+}
+
 // src/lib/cli-locator.ts
 import {
   chmodSync,
@@ -10369,7 +10563,10 @@ var loginCommand = new Command("login").description("Authenticate the CLI with y
 ).option(
   "--no-browser",
   "Print the authorize URL instead of opening a browser"
-).option("--scope <list>", "OAuth scope to request", "mcp").action(
+).option("--scope <list>", "OAuth scope to request", "mcp").option(
+  "--force",
+  "With --token: replace a signed-in OAuth session even if the token may be short-lived"
+).action(
   async (options) => {
     const fmt = createFormatter({
       json: false,
@@ -10380,6 +10577,24 @@ var loginCommand = new Command("login").description("Authenticate the CLI with y
     const config2 = await loadConfig();
     const apiUrl = DEFAULT_API_URL;
     if (options.token) {
+      const decision = decideTokenLogin({
+        token: options.token,
+        stored: await loadStoredCredential(),
+        force: options.force === true
+      });
+      if (decision.action === "keep-oauth") {
+        fmt.success(
+          "Already signed in: that is your OAuth session's current access token. Keeping the self-refreshing session."
+        );
+        return;
+      }
+      if (decision.action === "refuse") {
+        fmt.error(
+          "You are signed in with a self-refreshing OAuth session, and this token is not a personal API token (gad_v1_\u2026). Storing it would replace the session, and if it is an OAuth access token it stops working within the hour. Use a gad_v1_ token, or pass --force to replace the session anyway."
+        );
+        process.exitCode = 1;
+        return;
+      }
       const stored = await savePatToken(options.token);
       if (!stored) {
         fmt.error(
@@ -10750,12 +10965,24 @@ var logoutCommand = new Command("logout").description("Remove stored authenticat
       tokenTypeHint: "refresh_token"
     });
   }
-  await clearStoredCredential();
+  let clearError = null;
+  try {
+    await clearStoredCredential();
+  } catch (err2) {
+    clearError = err2;
+  }
   const config2 = await loadConfig();
   if (config2.token) {
     config2.token = "";
     await saveConfig(config2);
   }
+  if (clearError) {
+    fmt.error(
+      clearError instanceof Error ? clearError.message : "Could not remove stored authentication credentials."
+    );
+    process.exitCode = 1 /* AUTH_ERROR */;
+    return;
+  }
   fmt.success("Logged out successfully.");
 });
 
@@ -11072,7 +11299,7 @@ function getCommandWorkspaceTarget(options = {}) {
 }
 
 // ../local-runtime/src/abortable.ts
-function abortable(run3, signal) {
+function abortable(run4, signal) {
   return new Promise((resolve5, reject) => {
     const abort = () => {
       signal.removeEventListener("abort", abort);
@@ -11082,11 +11309,11 @@ function abortable(run3, signal) {
     signal.addEventListener("abort", abort, { once: true });
     Promise.resolve().then(() => {
       signal.throwIfAborted();
-      return run3();
+      return run4();
     }).then(resolve5, reject).finally(() => signal.removeEventListener("abort", abort));
   });
 }
-async function withLocalDeadline(deadlineMs, run3, parentSignal) {
+async function withLocalDeadline(deadlineMs, run4, parentSignal) {
   if (!Number.isSafeInteger(deadlineMs) || deadlineMs <= 0 || deadlineMs > 36e5)
     throw new Error("Invalid local operation deadline");
   const controller = new AbortController();
@@ -11096,7 +11323,7 @@ async function withLocalDeadline(deadlineMs, run3, parentSignal) {
     deadlineMs
   );
   try {
-    return await abortable(() => run3(signal), signal);
+    return await abortable(() => run4(signal), signal);
   } finally {
     clearTimeout(timer);
   }
@@ -11258,6 +11485,7 @@ async function withNativeResponse(context2, path10, init, consume, parentSignal)
 
 // src/lib/client.ts
 var DEFAULT_TIMEOUT_MS2 = 3e4;
+var PRESENCE_TIMEOUT_MS = 4e4;
 var MAX_RETRIES = 5;
 var BASE_DELAY_MS = 1e3;
 function detectGitOrigin() {
@@ -11649,6 +11877,47 @@ var GadClient = class {
         })();
     }
   }
+  /**
+   * One request with NO retry, bounded by `AbortSignal.timeout`. For the
+   * agent-presence routes: a replayed long-poll doubles a hold and the caller
+   * already owns the loop and its backoff. Returns the status and parsed body
+   * (null when not JSON) so the caller can read a 404 itself; a timeout or
+   * network failure throws.
+   */
+  async requestOnce(method, path10, opts = {}) {
+    const qs = opts.params && Object.keys(opts.params).length > 0 ? `?${new URLSearchParams(opts.params).toString()}` : "";
+    const signal = AbortSignal.timeout(opts.timeoutMs ?? PRESENCE_TIMEOUT_MS);
+    const headers = this.buildHeaders();
+    if (method === "GET") delete headers["Content-Type"];
+    if (this.getToken) {
+      const getToken2 = this.getToken;
+      headers.Authorization = `Bearer ${await new Promise(
+        (resolve5, reject) => {
+          signal.addEventListener(
+            "abort",
+            () => reject(networkError("Session renewal timed out.")),
+            { once: true }
+          );
+          getToken2().then(resolve5, reject);
+        }
+      )}`;
+    }
+    const response = await fetch(`${this.apiUrl}${path10}${qs}`, {
+      method,
+      headers,
+      ...opts.body !== void 0 && { body: JSON.stringify(opts.body) },
+      redirect: "error",
+      cache: "no-store",
+      signal
+    });
+    let body = null;
+    try {
+      body = await response.json();
+    } catch {
+      body = null;
+    }
+    return { status: response.status, body };
+  }
   /**
    * Make a GET request to a REST API endpoint.
    *
@@ -12393,8 +12662,8 @@ function text(value) {
 }
 function formatTodoDetail(todo) {
   const assignees = Array.isArray(todo.assignees) ? todo.assignees.map((a) => `${text(a.displayName)} (${text(a.type)})`).join(", ") : "";
-  const run3 = todo.lastRun ?? null;
-  const lastRun = run3 ? `${text(run3.status)} \u2014 ${text(run3.agentName)}` : "";
+  const run4 = todo.lastRun ?? null;
+  const lastRun = run4 ? `${text(run4.status)} \u2014 ${text(run4.agentName)}` : "";
   return {
     id: text(todo.id),
     title: text(todo.title),
@@ -14599,11 +14868,11 @@ function inspectConfiguredHooks(hooks, deps) {
 // src/lib/suggest-hook.ts
 import { existsSync as existsSync3 } from "node:fs";
 import {
-  chmod,
+  chmod as chmod2,
   copyFile,
   mkdir as mkdir4,
   readFile as readFile3,
-  rename,
+  rename as rename2,
   unlink as unlink2,
   writeFile as writeFile3
 } from "node:fs/promises";
@@ -14694,7 +14963,7 @@ async function atomicWrite(path10, content, mode) {
   await mkdir4(dirname4(path10), { recursive: true });
   const tmp = `${path10}.tmp-${process.pid}`;
   await writeFile3(tmp, content, mode === void 0 ? "utf8" : { mode });
-  await rename(tmp, path10);
+  await rename2(tmp, path10);
 }
 function hasHookCredential(content) {
   try {
@@ -14721,7 +14990,7 @@ async function enableSuggestHook(opts) {
   );
   await mkdir4(dirname4(p.scriptPath), { recursive: true, mode: 448 });
   await copyFile(opts.packagedScript, p.scriptPath);
-  await chmod(p.scriptPath, 493);
+  await chmod2(p.scriptPath, 493);
   if (plan.changed) await atomicWrite(p.settingsPath, plan.content);
   return { changed: plan.changed };
 }
@@ -15219,8 +15488,8 @@ function fingerprint(value) {
 }
 function describeStoredCredential(raw) {
   const trimmed = raw?.trim();
-  if (!trimmed) return null;
-  if (trimmed.startsWith("{")) {
+  if (!trimmed || trimmed === "LOGGED_OUT") return null;
+  if (trimmed.startsWith("{") || /\s/.test(trimmed)) {
     try {
       const parsed = asObject3(JSON.parse(trimmed));
       const refreshToken = parsed?.refreshToken;
@@ -15258,7 +15527,9 @@ function freshness(shape) {
   return shape.refreshExpiresAt ?? shape.accessExpiresAt ?? 0;
 }
 function auditCredentialStores(input2) {
-  const keychain = describeStoredCredential(input2.keychain);
+  const loggedOut = input2.file?.trim() === "LOGGED_OUT";
+  const effectiveKeychain = loggedOut || input2.fileAuthoritative ? null : input2.keychain;
+  const keychain = describeStoredCredential(effectiveKeychain);
   const file2 = describeStoredCredential(input2.file);
   const findings = [];
   if (!keychain && !file2) {
@@ -15389,14 +15660,16 @@ function planMigration(input2) {
     if ((store.shape.refreshExpiresAt ?? 0) <= input2.now) return true;
     return Boolean(effective) && freshness(store.shape) <= freshness(effective);
   }).map((store) => store.path);
-  const keychain = describeStoredCredential(input2.keychain);
+  const loggedOut = input2.file?.trim() === "LOGGED_OUT";
+  const keychain = loggedOut || input2.fileAuthoritative ? null : describeStoredCredential(input2.keychain);
   const file2 = describeStoredCredential(input2.file);
   let syncKeychainToFile = false;
   if (keychain && keychain.kind !== "corrupt") {
     const keychainUsable = keychain.kind !== "oauth" || (keychain.refreshExpiresAt ?? 0) > input2.now;
     if (keychainUsable) {
-      if (!file2) syncKeychainToFile = true;
-      else if (keychain.fingerprint !== file2.fingerprint) {
+      if (!file2 && !loggedOut && !input2.fileAuthoritative) {
+        syncKeychainToFile = true;
+      } else if (file2 && keychain.fingerprint !== file2.fingerprint) {
         syncKeychainToFile = freshness(keychain) > freshness(file2);
       }
     }
@@ -16668,10 +16941,10 @@ async function mcpJsonAtRiskOfCommit(dir) {
   try {
     const { execFile: execFile5 } = await import("node:child_process");
     const { promisify: promisify2 } = await import("node:util");
-    const run3 = promisify2(execFile5);
-    await run3("git", ["rev-parse", "--is-inside-work-tree"], { cwd: dir });
+    const run4 = promisify2(execFile5);
+    await run4("git", ["rev-parse", "--is-inside-work-tree"], { cwd: dir });
     try {
-      await run3("git", ["check-ignore", "-q", ".mcp.json"], { cwd: dir });
+      await run4("git", ["check-ignore", "-q", ".mcp.json"], { cwd: dir });
       return false;
     } catch {
       return true;
@@ -16763,7 +17036,7 @@ async function pathExists(path10) {
 async function installCodexConfig(apiUrl, token, repoUrl) {
   const { homedir: homedir11 } = await import("node:os");
   const { join: join13 } = await import("node:path");
-  const { chmod: chmod3, copyFile: copyFile3, mkdir: mkdir9, readFile: readFile9, writeFile: writeFile7 } = await import("node:fs/promises");
+  const { chmod: chmod4, copyFile: copyFile3, mkdir: mkdir9, readFile: readFile9, writeFile: writeFile7 } = await import("node:fs/promises");
   const codexDir = join13(homedir11(), ".codex");
   const configPath = join13(codexDir, "config.toml");
   const envPath = join13(codexDir, ".env");
@@ -16787,7 +17060,7 @@ async function installCodexConfig(apiUrl, token, repoUrl) {
     upsertEnvValue(existingEnv, "GREAT_ARROW_TOKEN", token),
     "utf8"
   );
-  await chmod3(envPath, 384);
+  await chmod4(envPath, 384);
   return { configPath, envPath };
 }
 var startCommand = new Command("start").description(
@@ -17191,9 +17464,9 @@ async function resolveProxyScript(override) {
 async function runProxyDiagnostics(scriptPath) {
   const { execFile: execFile5 } = await import("node:child_process");
   const { promisify: promisify2 } = await import("node:util");
-  const run3 = promisify2(execFile5);
+  const run4 = promisify2(execFile5);
   try {
-    const { stdout } = await run3(
+    const { stdout } = await run4(
       process.execPath,
       [scriptPath, "--print-diagnostics"],
       { timeout: 1e4, maxBuffer: 1024 * 1024 }
@@ -17219,8 +17492,8 @@ async function findLegacyStores(cwd) {
   try {
     const { execFile: execFile5 } = await import("node:child_process");
     const { promisify: promisify2 } = await import("node:util");
-    const run3 = promisify2(execFile5);
-    const { stdout } = await run3("git", ["worktree", "list", "--porcelain"], {
+    const run4 = promisify2(execFile5);
+    const { stdout } = await run4("git", ["worktree", "list", "--porcelain"], {
       cwd,
       timeout: 5e3
     });
@@ -17279,17 +17552,31 @@ async function probeEndpoint() {
 async function applyMigration(plan) {
   const { homedir: homedir11 } = await import("node:os");
   const { join: join13 } = await import("node:path");
-  const { mkdir: mkdir9, rename: rename3, writeFile: writeFile7 } = await import("node:fs/promises");
+  const { chmod: chmod4, mkdir: mkdir9, rename: rename4, unlink: unlink3, writeFile: writeFile7 } = await import("node:fs/promises");
   const applied = [];
   const dir = join13(homedir11(), ".great-arrow");
   await mkdir9(dir, { recursive: true, mode: 448 });
+  await chmod4(dir, 448);
+  const writeAtomic0600 = async (target, raw) => {
+    const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
+    try {
+      await writeFile7(tmp, raw, { mode: 384, flag: "wx" });
+      await chmod4(tmp, 384);
+      await rename4(tmp, target);
+    } catch (err2) {
+      try {
+        await unlink3(tmp);
+      } catch (cleanupErr) {
+        debugSwallow("mcp.applyMigration(cleanup)", cleanupErr);
+      }
+      throw err2;
+    }
+  };
   if (plan.seedFrom) {
     const raw = await readIfExists(plan.seedFrom);
     if (raw !== null) {
       const target = join13(dir, OAUTH_CRED_FILENAME);
-      const tmp = `${target}.tmp`;
-      await writeFile7(tmp, raw, { mode: 384 });
-      await rename3(tmp, target);
+      await writeAtomic0600(target, raw);
       applied.push(`Copied ${plan.seedFrom} \u2192 ${target}`);
     }
   }
@@ -17297,9 +17584,8 @@ async function applyMigration(plan) {
     const raw = await readKeychainOnly();
     if (raw) {
       const target = join13(dir, "credential");
-      const tmp = `${target}.tmp`;
-      await writeFile7(tmp, raw, { mode: 384 });
-      await rename3(tmp, target);
+      await writeAtomic0600(target, raw);
+      await writeAtomic0600(join13(dir, "credential.migrated"), "1");
       applied.push(`Wrote the keychain credential to ${target}`);
     }
   }
@@ -17329,10 +17615,14 @@ var doctorSubcommand = new Command("doctor").description(
     const diagnostics = proxyPath ? await runProxyDiagnostics(proxyPath) : null;
     const entries = await scanConnections();
     const duplicates = detectDuplicates(entries);
-    const keychain = await readKeychainOnly();
     const credentialFile = await readIfExists(
       join13(home, ".great-arrow", "credential")
     );
+    const credentialMigrated = await readIfExists(
+      join13(home, ".great-arrow", "credential.migrated")
+    ) !== null;
+    const fileAuthoritative = credentialFile?.trim() === "LOGGED_OUT" || credentialMigrated || process.platform === "darwin" && credentialFile !== null;
+    const keychain = fileAuthoritative ? null : await readKeychainOnly();
     const userStore = await readIfExists(
       join13(home, ".great-arrow", OAUTH_CRED_FILENAME)
     );
@@ -17342,6 +17632,7 @@ var doctorSubcommand = new Command("doctor").description(
       ...auditCredentialStores({
         keychain,
         file: credentialFile,
+        fileAuthoritative,
         now: Date.now()
       }),
       await probeEndpoint()
@@ -17367,6 +17658,7 @@ var doctorSubcommand = new Command("doctor").description(
       userStore,
       keychain,
       file: credentialFile,
+      fileAuthoritative,
       now: Date.now()
     });
     const applied = options.migrate ? await applyMigration(plan) : [];
@@ -17749,6 +18041,137 @@ var agentsCommand = new Command("agents").description(
   process.stdout.write(renderAgentsNow(result) + "\n");
 });
 
+// src/commands/inbox.ts
+var BACKOFF_BASE_MS = 15e3;
+var BACKOFF_MAX_MS = 12e4;
+var DEFAULT_MAX_MINUTES = 50;
+var PRESENCE_NOT_ENABLED = "Agent presence is not enabled.";
+function waitBackoffMs(emptyHolds) {
+  if (emptyHolds < 3) return 0;
+  return Math.min(2 ** (emptyHolds - 3) * BACKOFF_BASE_MS, BACKOFF_MAX_MS);
+}
+function asMessage(body) {
+  if (!body || typeof body !== "object") return null;
+  const b = body;
+  return b.status === "message" && typeof b.messageId === "string" && typeof b.block === "string" ? { messageId: b.messageId, block: b.block } : null;
+}
+async function runInboxWait(o) {
+  const sleep2 = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = o.now ?? Date.now;
+  const write = o.write ?? ((t) => void process.stdout.write(t));
+  const writeErr = o.writeErr ?? ((t) => void process.stderr.write(t));
+  const stopAt = now() + (o.maxMinutes ?? DEFAULT_MAX_MINUTES) * 6e4;
+  let emptyHolds = 0;
+  while (now() < stopAt) {
+    const params = { as: o.as };
+    if (o.after) params.after = o.after;
+    if (o.waitingOn !== void 0) params.waiting_on = o.waitingOn;
+    let res = null;
+    try {
+      res = await o.request(params);
+    } catch {
+      res = null;
+    }
+    if (res?.status === 404) {
+      writeErr(`${PRESENCE_NOT_ENABLED}
+`);
+      return 2;
+    }
+    const msg = res && res.status === 200 ? asMessage(res.body) : null;
+    if (msg) {
+      const block = msg.block.endsWith("\n") ? msg.block : `${msg.block}
+`;
+      write(`${block}after=${msg.messageId}
+`);
+      return 0;
+    }
+    const gap = Math.min(waitBackoffMs(emptyHolds++), stopAt - now());
+    if (gap > 0) await sleep2(gap);
+  }
+  return 3;
+}
+function parseMaxMinutes(raw) {
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_MINUTES;
+}
+var waitCommand = new Command("wait").description(
+  "Wait for a peer's message to this connection; run as a background task"
+).requiredOption("--as <id>", "Your connection id (from agent_inbox)").option("--after <id>", "Only wake for messages newer than this id").option("--waiting-on <text>", "What you are waiting on, shown to peers").option("--max-minutes <n>", "Give up after this many minutes", "50").action(
+  async (opts) => {
+    const auth = await resolveAuth();
+    const client2 = new GadClient({
+      token: auth.token,
+      getToken: auth.getToken,
+      apiUrl: auth.apiUrl
+    });
+    process.exitCode = await runInboxWait({
+      request: (params) => client2.requestOnce("GET", "/api/agent-comms/wait", { params }),
+      as: opts.as,
+      after: opts.after,
+      waitingOn: opts.waitingOn,
+      maxMinutes: parseMaxMinutes(opts.maxMinutes)
+    });
+  }
+);
+var inboxCommand = new Command("inbox").description("Agent inbox \u2014 wait for a peer's message").addCommand(waitCommand);
+
+// src/commands/presence.ts
+function doNotDisturbBody(raw, as) {
+  if (raw.trim().toLowerCase() === "off") {
+    return { action: "do_not_disturb", as, minutes: null };
+  }
+  const minutes = Number(raw);
+  if (!Number.isFinite(minutes) || minutes <= 0) {
+    throw new CliError(
+      `Expected a number of minutes or "off", got "${raw}".`,
+      3 /* VALIDATION_ERROR */
+    );
+  }
+  return { action: "do_not_disturb", as, minutes };
+}
+async function sendPresence(o) {
+  const write = o.write ?? ((t) => void process.stdout.write(t));
+  const writeErr = o.writeErr ?? ((t) => void process.stderr.write(t));
+  const res = await o.request(o.body);
+  if (res.status === 404) {
+    writeErr(`${PRESENCE_NOT_ENABLED}
+`);
+    return 2;
+  }
+  if (res.status < 200 || res.status >= 300) {
+    writeErr(`Presence update failed (HTTP ${res.status}).
+`);
+    return res.status === 401 || res.status === 403 ? 1 /* AUTH_ERROR */ : res.status === 400 ? 3 /* VALIDATION_ERROR */ : 2 /* NETWORK_ERROR */;
+  }
+  const b = o.body;
+  write(
+    b.action === "sign_off" ? "Signed off.\n" : b.minutes === null ? "Do not disturb is off.\n" : `Do not disturb for ${b.minutes} minutes.
+`
+  );
+  return 0;
+}
+async function run2(body) {
+  const auth = await resolveAuth();
+  const client2 = new GadClient({
+    token: auth.token,
+    getToken: auth.getToken,
+    apiUrl: auth.apiUrl
+  });
+  process.exitCode = await sendPresence({
+    request: (b) => client2.requestOnce("POST", "/api/agent-comms/presence", { body: b }),
+    body
+  });
+}
+var presenceCommand = new Command("presence").description("Tell peers you are away: do not disturb, or sign off").addCommand(
+  new Command("do-not-disturb").description("Tell peers not to disturb you for a while, or turn it off").argument("<minutes|off>", "Minutes (up to 480), or off").requiredOption("--as <id>", "Your connection id (from agent_inbox)").action(async (raw, opts) => {
+    await run2(doNotDisturbBody(raw, opts.as));
+  })
+).addCommand(
+  new Command("sign-off").description("Mark this connection as signed off").requiredOption("--as <id>", "Your connection id (from agent_inbox)").action(async (opts) => {
+    await run2({ action: "sign_off", as: opts.as });
+  })
+);
+
 // src/commands/ask.ts
 var ORCHESTRATOR_TIMEOUT_MS = 9e4;
 var ANSWER_FIELDS = [
@@ -38970,7 +39393,7 @@ function visit(schema, fnOrHandlers) {
     return h ? h(node2, rewritten) : node2;
   };
   const cache = /* @__PURE__ */ new Map();
-  function run3(s2) {
+  function run4(s2) {
     const cached2 = cache.get(s2);
     if (cached2 === RESOLVING) {
       return new $ZodLazy({
@@ -38996,21 +39419,21 @@ function visit(schema, fnOrHandlers) {
         let changed = false;
         const newShape = {};
         for (const k of keys) {
-          const mapped = run3(oldShape[k]);
+          const mapped = run4(oldShape[k]);
           if (mapped !== oldShape[k])
             changed = true;
           newShape[k] = mapped;
         }
         let newCatchall = def.catchall;
         if (def.catchall) {
-          newCatchall = run3(def.catchall);
+          newCatchall = run4(def.catchall);
           if (newCatchall !== def.catchall)
             changed = true;
         }
         return changed ? clone(s2, { ...def, shape: newShape, catchall: newCatchall }) : s2;
       }
       case "array": {
-        const mapped = run3(def.element);
+        const mapped = run4(def.element);
         return mapped === def.element ? s2 : clone(s2, { ...def, element: mapped });
       }
       case "tuple": {
@@ -39018,14 +39441,14 @@ function visit(schema, fnOrHandlers) {
         let changed = false;
         const newItems = [];
         for (const item of oldItems) {
-          const mapped = run3(item);
+          const mapped = run4(item);
           if (mapped !== item)
             changed = true;
           newItems.push(mapped);
         }
         let newRest = def.rest;
         if (def.rest) {
-          newRest = run3(def.rest);
+          newRest = run4(def.rest);
           if (newRest !== def.rest)
             changed = true;
         }
@@ -39033,12 +39456,12 @@ function visit(schema, fnOrHandlers) {
       }
       case "record":
       case "map": {
-        const newKey = run3(def.keyType);
-        const newVal = run3(def.valueType);
+        const newKey = run4(def.keyType);
+        const newVal = run4(def.valueType);
         return newKey === def.keyType && newVal === def.valueType ? s2 : clone(s2, { ...def, keyType: newKey, valueType: newVal });
       }
       case "set": {
-        const newVal = run3(def.valueType);
+        const newVal = run4(def.valueType);
         return newVal === def.valueType ? s2 : clone(s2, { ...def, valueType: newVal });
       }
       case "union": {
@@ -39046,7 +39469,7 @@ function visit(schema, fnOrHandlers) {
         let changed = false;
         const newOptions = [];
         for (const opt of oldOptions) {
-          const mapped = run3(opt);
+          const mapped = run4(opt);
           if (mapped !== opt)
             changed = true;
           newOptions.push(mapped);
@@ -39054,8 +39477,8 @@ function visit(schema, fnOrHandlers) {
         return changed ? clone(s2, { ...def, options: newOptions }) : s2;
       }
       case "intersection": {
-        const newLeft = run3(def.left);
-        const newRight = run3(def.right);
+        const newLeft = run4(def.left);
+        const newRight = run4(def.right);
         return newLeft === def.left && newRight === def.right ? s2 : clone(s2, { ...def, left: newLeft, right: newRight });
       }
       case "optional":
@@ -39067,23 +39490,23 @@ function visit(schema, fnOrHandlers) {
       case "nonoptional":
       case "promise":
       case "success": {
-        const newInner = run3(def.innerType);
+        const newInner = run4(def.innerType);
         return newInner === def.innerType ? s2 : clone(s2, { ...def, innerType: newInner });
       }
       case "pipe": {
-        const newIn = run3(def.in);
-        const newOut = run3(def.out);
+        const newIn = run4(def.in);
+        const newOut = run4(def.out);
         return newIn === def.in && newOut === def.out ? s2 : clone(s2, { ...def, in: newIn, out: newOut });
       }
       case "function": {
-        const newInput = run3(def.input);
-        const newOutput = run3(def.output);
+        const newInput = run4(def.input);
+        const newOutput = run4(def.output);
         return newInput === def.input && newOutput === def.output ? s2 : clone(s2, { ...def, input: newInput, output: newOutput });
       }
       case "lazy": {
         const original = def.getter;
         const { _cachedInner, ...rest } = def;
-        return clone(s2, { ...rest, getter: () => run3(original()) });
+        return clone(s2, { ...rest, getter: () => run4(original()) });
       }
       // A leaf by choice: `parts` are regex fragments, not data positions.
       case "template_literal":
@@ -39114,7 +39537,7 @@ function visit(schema, fnOrHandlers) {
       }
     }
   }
-  return run3(schema);
+  return run4(schema);
 }
 
 // ../../node_modules/zod/v4/classic/deep-partial.js
@@ -49743,11 +50166,11 @@ import { Writable } from "node:stream";
 // src/lib/keys-apply.ts
 import { spawn } from "node:child_process";
 import {
-  chmod as chmod2,
+  chmod as chmod3,
   mkdir as mkdir8,
   readFile as readFile7,
   realpath,
-  rename as rename2,
+  rename as rename3,
   stat as stat2,
   writeFile as writeFile6
 } from "node:fs/promises";
@@ -49853,8 +50276,8 @@ function formatEnvValue(value, quote) {
 async function writeAtomic(path10, content, mode) {
   const tmp = `${path10}.tmp`;
   await writeFile6(tmp, content, { mode });
-  await chmod2(tmp, mode);
-  await rename2(tmp, path10);
+  await chmod3(tmp, mode);
+  await rename3(tmp, path10);
 }
 async function applyEnvFile(path10, key, value) {
   const file2 = expandHome(path10);
@@ -50304,7 +50727,7 @@ function helperKind(raw) {
   if (/^store\b/.test(v)) return "store";
   return "other";
 }
-function run2(file2, args) {
+function run3(file2, args) {
   return new Promise((done) => {
     execFile4(
       file2,
@@ -50315,10 +50738,10 @@ function run2(file2, args) {
   });
 }
 async function detectGhCli() {
-  return await run2("gh", ["--version"]) !== null;
+  return await run3("gh", ["--version"]) !== null;
 }
 async function detectGitHelper() {
-  const out2 = await run2("git", [
+  const out2 = await run3("git", [
     "config",
     "--get-urlmatch",
     "credential.helper",
@@ -50547,29 +50970,29 @@ function statusCommand4() {
     const runId = requireRunId(runArg);
     const { client: client2, apiUrl } = await keysContext();
     const res = await client2.get(`/api/key-rotation/runs/${runId}`);
-    const run3 = res?.run ?? {};
+    const run4 = res?.run ?? {};
     if (g.json) {
-      out(JSON.stringify(run3));
+      out(JSON.stringify(run4));
       return;
     }
     const c = createColor(g.noColor || g.quiet);
     out(
-      `${c.bold(`Run ${runId}`)}  ${s(run3.state)}` + (s(run3.waitingOn) ? c.dim(`  waiting on ${s(run3.waitingOn)}`) : "")
+      `${c.bold(`Run ${runId}`)}  ${s(run4.state)}` + (s(run4.waitingOn) ? c.dim(`  waiting on ${s(run4.waitingOn)}`) : "")
     );
-    for (const st of run3.steps ?? []) {
+    for (const st of run4.steps ?? []) {
       const detail = s(st.detailCode);
       out(
         `  ${s(st.step)} ${c.dim(s(st.targetKind))}  ${s(st.status)}` + (detail ? c.dim(` (${detail})`) : "")
       );
     }
-    const open4 = (run3.checklist ?? []).filter((i) => i.ticked !== true);
+    const open4 = (run4.checklist ?? []).filter((i) => i.ticked !== true);
     if (open4.length > 0) {
       out(c.yellow("Checklist (tick these in the browser):"));
       for (const item of open4) {
         out(`  \u2610 ${s(item.label)}  ${c.cyan(s(item.href))}`);
       }
     }
-    for (const d of run3.devices ?? []) {
+    for (const d of run4.devices ?? []) {
       out(`  device ${s(d.label)}  ${s(d.state)}`);
     }
     out(c.dim(`${apiUrl}${keyRotationRunPath(runId)}`));
@@ -50910,6 +51333,8 @@ var COMMANDS = [
   "smoke",
   "agent",
   "ask",
+  "inbox",
+  "presence",
   "runtime",
   "open",
   "completions"
@@ -50951,6 +51376,12 @@ _gad_completions() {
     agent)
       COMPREPLY=( $(compgen -W "list invoke" -- "\${cur}") )
       ;;
+    inbox)
+      COMPREPLY=( $(compgen -W "wait" -- "\${cur}") )
+      ;;
+    presence)
+      COMPREPLY=( $(compgen -W "do-not-disturb sign-off" -- "\${cur}") )
+      ;;
     runtime)
       COMPREPLY=( $(compgen -W "status set sync policy" -- "\${cur}") )
       ;;
@@ -50986,6 +51417,8 @@ _gad() {
     'smoke:Run smoke tests'
     'agent:Manage agents (list, invoke)'
     'ask:Ask the orchestrator a question'
+    'inbox:Agent inbox (wait)'
+    'presence:Agent presence (do-not-disturb, sign-off)'
     'runtime:Choose your computer or the cloud per lane'
     'open:Open an app surface in the browser'
     'completions:Generate shell completions'
@@ -51021,6 +51454,14 @@ _gad() {
       subcommands=('list:List agents' 'invoke:Invoke an agent')
       _describe -t subcommands 'agent subcommands' subcommands
       ;;
+    inbox)
+      subcommands=('wait:Wait for a peer message')
+      _describe -t subcommands 'inbox subcommands' subcommands
+      ;;
+    presence)
+      subcommands=('do-not-disturb:Do not disturb for a while, or off' 'sign-off:Sign off this connection')
+      _describe -t subcommands 'presence subcommands' subcommands
+      ;;
     runtime)
       subcommands=('status:Where each lane runs' 'set:Set a lane' 'sync:Apply to this checkout' 'policy:Workspace policy')
       _describe -t subcommands 'runtime subcommands' subcommands
@@ -51049,6 +51490,8 @@ function generateFish() {
     smoke: "Run smoke tests",
     agent: "Manage agents",
     ask: "Ask the orchestrator a question",
+    inbox: "Agent inbox",
+    presence: "Agent presence",
     runtime: "Choose your computer or the cloud per lane",
     open: "Open an app surface in the browser",
     completions: "Generate shell completions"
@@ -51087,6 +51530,13 @@ function generateFish() {
       list: "List agents",
       invoke: "Invoke an agent"
     },
+    inbox: {
+      wait: "Wait for a peer message"
+    },
+    presence: {
+      "do-not-disturb": "Do not disturb for a while, or off",
+      "sign-off": "Sign off this connection"
+    },
     runtime: {
       status: "Where each lane runs",
       set: "Set a lane",
@@ -54566,6 +55016,8 @@ program2.addCommand(integrations_default);
 program2.addCommand(mcp_default);
 program2.addCommand(agentCommand);
 program2.addCommand(agentsCommand);
+program2.addCommand(inboxCommand);
+program2.addCommand(presenceCommand);
 program2.addCommand(askCommand());
 program2.addCommand(localCommand());
 program2.addCommand(runtimeCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@great-arrow/cli",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "GreatArrow.ai CLI tool",
   "type": "module",
   "bin": {