@indigoai-us/hq-cloud 6.14.48 → 6.14.49

package/dist/read-only-state-dir.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only-state-dir.test.js","sourceRoot":"","sources":["../src/read-only-state-dir.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.14.48",
-  "description": "HQ by Indigo cloud sync engine \u2014 bidirectional S3 sync for mobile access",
+  "version": "6.14.49",
+  "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/src/cli/reindex.test.ts

@@ -695,7 +695,8 @@ describe("reindex", () => {
     const claudeSlug = (p: string): string => p.replace(/[^a-zA-Z0-9]/g, "-");
     const grokKey = (p: string): string => encodeURIComponent(p);
 
-    const dest = (): string => path.join(root, "workspace", ".session-logs");
+    const dest = (reindexRoot = root): string =>
+      path.join(reindexRoot, "workspace", ".session-logs");
 
     beforeEach(() => {
       claudeDir = fs.mkdtempSync(path.join(os.tmpdir(), "ms-claude-"));
@@ -746,6 +747,30 @@ describe("reindex", () => {
       return abs;
     }
 
+    // Build the real root under a canonical tmp path so this fixture remains
+    // stable even when the platform itself exposes its temp directory via a
+    // symlink (for example, /tmp -> /private/tmp on macOS).
+    function makeSymlinkRoot(): { realRoot: string; linkRoot: string; cleanup: () => void } | null {
+      const fixtureDir = fs.mkdtempSync(
+        path.join(fs.realpathSync.native(os.tmpdir()), "ms-session-log-alias-"),
+      );
+      const realRoot = path.join(fixtureDir, "real-hq");
+      const linkRoot = path.join(fixtureDir, "hq-alias");
+      fs.mkdirSync(realRoot);
+      try {
+        fs.symlinkSync(realRoot, linkRoot, "dir");
+      } catch (err) {
+        fs.rmSync(fixtureDir, { recursive: true, force: true });
+        if ((err as NodeJS.ErrnoException).code === "EPERM") return null;
+        throw err;
+      }
+      return {
+        realRoot,
+        linkRoot,
+        cleanup: () => fs.rmSync(fixtureDir, { recursive: true, force: true }),
+      };
+    }
+
     // ── Claude ──────────────────────────────────────────────────────────────
     it("claude: captures the HQ-root project AND descendant projects under claude/", () => {
       const rootName = seedClaude(root);
@@ -776,6 +801,23 @@ describe("reindex", () => {
       expect(fs.readFileSync(path.join(dest(), "orphan.txt"), "utf8")).toBe("keep\n");
     });
 
+    it("claude: captures a realpath-keyed project when reindex uses a symlink alias", () => {
+      const fixture = makeSymlinkRoot();
+      if (!fixture) return; // Symlink-restricted host (for example, Windows without Developer Mode).
+      try {
+        const realName = seedClaude(fixture.realRoot);
+        const aliasName = claudeSlug(fixture.linkRoot);
+
+        expect(reindex({ repoRoot: fixture.linkRoot }).status).toBe(0);
+
+        const c = path.join(dest(fixture.realRoot), "claude");
+        expect(fs.readFileSync(path.join(c, realName, "session.jsonl"), "utf8")).toBe("claude\n");
+        expect(fs.existsSync(path.join(c, aliasName))).toBe(false);
+      } finally {
+        fixture.cleanup();
+      }
+    });
+
     // ── Grok ────────────────────────────────────────────────────────────────
     it("grok: captures the HQ-root and descendant cwd folders under grok/, excludes others", () => {
       const rootName = seedGrok(root);
@@ -790,6 +832,25 @@ describe("reindex", () => {
       expect(fs.existsSync(path.join(g, grokKey("/tmp/benchmark")))).toBe(false);
     });
 
+    it("grok: captures a realpath-keyed session when reindex uses a symlink alias", () => {
+      const fixture = makeSymlinkRoot();
+      if (!fixture) return; // Symlink-restricted host (for example, Windows without Developer Mode).
+      try {
+        const realName = seedGrok(fixture.realRoot);
+
+        expect(reindex({ repoRoot: fixture.linkRoot }).status).toBe(0);
+
+        expect(
+          fs.readFileSync(
+            path.join(dest(fixture.realRoot), "grok", realName, "uuid-1", "chat_history.jsonl"),
+            "utf8",
+          ),
+        ).toBe("grok\n");
+      } finally {
+        fixture.cleanup();
+      }
+    });
+
     // ── Codex ───────────────────────────────────────────────────────────────
     it("codex: captures rollouts whose recorded cwd is the HQ tree, mirroring the date path", () => {
       seedCodex(root, ["2026", "07", "13"], "rollout-root.jsonl");
@@ -805,6 +866,24 @@ describe("reindex", () => {
       expect(fs.existsSync(path.join(cx, "rollout-other.jsonl"))).toBe(false);
     });
 
+    it("codex: captures a realpath-keyed rollout when reindex uses a symlink alias", () => {
+      const fixture = makeSymlinkRoot();
+      if (!fixture) return; // Symlink-restricted host (for example, Windows without Developer Mode).
+      try {
+        seedCodex(path.join(fixture.realRoot, "workspace", "worktrees", "x"), ["2026", "07", "13"], "rollout-real.jsonl");
+
+        expect(reindex({ repoRoot: fixture.linkRoot }).status).toBe(0);
+
+        expect(
+          fs.existsSync(
+            path.join(dest(fixture.realRoot), "codex", "2026", "07", "13", "rollout-real.jsonl"),
+          ),
+        ).toBe(true);
+      } finally {
+        fixture.cleanup();
+      }
+    });
+
     it("codex: skips a rollout already captured and unchanged (mtime guard)", () => {
       const src = seedCodex(root, ["2026", "07", "13"], "rollout-a.jsonl");
       expect(reindex({ repoRoot: root }).status).toBe(0);
@@ -827,6 +906,35 @@ describe("reindex", () => {
       expect(fs.readFileSync(destFile, "utf8")).toContain("NEW");
     });
 
+    it("captures exact-root and descendant entries once when the root is already canonical", () => {
+      const canonicalRoot = fs.realpathSync.native(root);
+      const claudeNames = [
+        seedClaude(canonicalRoot),
+        seedClaude(path.join(canonicalRoot, "workspace", "worktrees", "x")),
+      ];
+      const grokNames = [
+        seedGrok(canonicalRoot),
+        seedGrok(path.join(canonicalRoot, "repos", "private", "x")),
+      ];
+      seedCodex(canonicalRoot, ["2026", "07", "15"], "rollout-root.jsonl");
+      seedCodex(
+        path.join(canonicalRoot, "workspace", "worktrees", "x"),
+        ["2026", "07", "15"],
+        "rollout-sub.jsonl",
+      );
+
+      expect(reindex({ repoRoot: canonicalRoot }).status).toBe(0);
+
+      expect(fs.readdirSync(path.join(dest(canonicalRoot), "claude")).sort()).toEqual(
+        claudeNames.sort(),
+      );
+      expect(fs.readdirSync(path.join(dest(canonicalRoot), "grok")).sort()).toEqual(grokNames.sort());
+      expect(fs.readdirSync(path.join(dest(canonicalRoot), "codex", "2026", "07", "15")).sort()).toEqual([
+        "rollout-root.jsonl",
+        "rollout-sub.jsonl",
+      ]);
+    });
+
     // ── Cross-harness ─────────────────────────────────────────────────────────
     it("all three harnesses land side-by-side under their own subfolders", () => {
       seedClaude(root);

package/src/cli/reindex.ts

@@ -266,6 +266,23 @@ function copySessionLogs(root: string): void {
   }
 }
 
+// Candidate spellings of the HQ root to match harness-recorded cwds against:
+// the lexical root AND its realpath. Harnesses key logs by the cwd the user
+// actually ran in, which may reach the same tree through a symlink or a
+// case-different spelling (macOS volumes are case-insensitive); realpath
+// canonicalizes both. Best-effort: realpath may throw if root is gone.
+// De-duplicated, lexical root first (stable, preferred dest naming).
+function hqRootCandidates(root: string): string[] {
+  const out = [root];
+  try {
+    const real = fs.realpathSync.native(root);
+    if (real && real !== root) out.push(real);
+  } catch {
+    // best-effort — a missing/unreadable root just means no realpath candidate
+  }
+  return out;
+}
+
 /** `fs.statSync` without throwing (follows symlinks; null when missing). */
 function statOrNull(p: string): fs.Stats | null {
   try {
@@ -300,9 +317,9 @@ function copyClaudeSessionLogs(root: string, destBase: string): void {
   const projectsDir = path.join(configDir, "projects");
   if (!isDir(projectsDir)) return;
 
-  const slug = root.replace(/[^a-zA-Z0-9]/g, "-");
+  const slugs = [...new Set(hqRootCandidates(root).map((r) => r.replace(/[^a-zA-Z0-9]/g, "-")))];
   for (const entry of globEntries(projectsDir)) {
-    if (entry !== slug && !entry.startsWith(`${slug}-`)) continue;
+    if (!slugs.some((slug) => entry === slug || entry.startsWith(`${slug}-`))) continue;
     const src = path.join(projectsDir, entry);
     if (!isDir(src)) continue;
     copyTreeOverlay(src, path.join(destBase, "claude", entry), "claude session logs");
@@ -318,9 +335,9 @@ function copyGrokSessionLogs(root: string, destBase: string): void {
   const sessionsDir = path.join(grokHome, "sessions");
   if (!isDir(sessionsDir)) return;
 
-  const key = encodeURIComponent(root);
+  const keys = [...new Set(hqRootCandidates(root).map((r) => encodeURIComponent(r)))];
   for (const entry of globEntries(sessionsDir)) {
-    if (entry !== key && !entry.startsWith(`${key}%2F`)) continue;
+    if (!keys.some((key) => entry === key || entry.startsWith(`${key}%2F`))) continue;
     const src = path.join(sessionsDir, entry);
     if (!isDir(src)) continue;
     copyTreeOverlay(src, path.join(destBase, "grok", entry), "grok session logs");
@@ -340,7 +357,8 @@ function copyCodexSessionLogs(root: string, destBase: string): void {
   if (!isDir(sessionsDir)) return;
 
   const destDir = path.join(destBase, "codex");
-  const rootPrefix = root.endsWith(path.sep) ? root : root + path.sep;
+  const candidates = hqRootCandidates(root);
+  const prefixes = candidates.map((r) => (r.endsWith(path.sep) ? r : r + path.sep));
 
   for (const abs of walkFiles(sessionsDir)) {
     if (!abs.endsWith(".jsonl")) continue;
@@ -355,7 +373,7 @@ function copyCodexSessionLogs(root: string, destBase: string): void {
 
     const cwd = readCodexRolloutCwd(abs);
     if (cwd === null) continue;
-    if (cwd !== root && !cwd.startsWith(rootPrefix)) continue;
+    if (!candidates.includes(cwd) && !prefixes.some((prefix) => cwd.startsWith(prefix))) continue;
 
     if (!safeMkdir(path.dirname(dest), "codex session-log dir")) continue;
     try {

package/src/cognito-auth.ts

@@ -97,9 +97,39 @@ export class CognitoRefreshError extends CognitoAuthError {
 // Token cache (~/.hq/cognito-tokens.json)
 // ---------------------------------------------------------------------------
 
-const HQ_DIR = path.join(os.homedir(), ".hq");
-const TOKEN_FILE = path.join(HQ_DIR, "cognito-tokens.json");
-const TOKEN_INVALIDATION_PREFIX = `${TOKEN_FILE}.invalid.`;
+/**
+ * Root for hq CLI state: the token cache and its refresh lock.
+ *
+ * `HQ_STATE_DIR` overrides it, mirroring the existing `HQ_MACHINE_CREDS_FILE`
+ * override for the creds path. Before this existed the location was
+ * `os.homedir()/.hq` with NO escape hatch, which made every auth path — machine
+ * identity included — require a writable HOME. A child job running with a
+ * read-only HQ state directory therefore died on a *cache write* before it ever
+ * reached the network:
+ *
+ *     EACCES: permission denied, open '…/.hq/cognito-tokens.json.lock.candidate.…'
+ *
+ * Pointing HQ_STATE_DIR at a writable tmpfs lets such a job authenticate while
+ * leaving the credentials themselves wherever they are.
+ *
+ * Resolved per call (not once at import) so a caller can set it during startup
+ * and so tests can exercise both branches.
+ */
+export function hqStateDir(): string {
+  const override = process.env.HQ_STATE_DIR?.trim();
+  return override !== undefined && override.length > 0
+    ? override
+    : path.join(os.homedir(), ".hq");
+}
+
+/** The Cognito token cache file inside {@link hqStateDir}. */
+export function tokenCacheFile(): string {
+  return path.join(hqStateDir(), "cognito-tokens.json");
+}
+
+function tokenInvalidationPrefix(): string {
+  return `${tokenCacheFile()}.invalid.`;
+}
 
 /** Stable, non-secret identity for one access-token generation. */
 export function accessTokenFingerprint(accessToken: string): string {
@@ -108,7 +138,7 @@ export function accessTokenFingerprint(accessToken: string): string {
 
 function invalidationPathForFingerprint(fingerprint: string): string | null {
   return /^[a-f0-9]{64}$/i.test(fingerprint)
-    ? `${TOKEN_INVALIDATION_PREFIX}${fingerprint.toLowerCase()}`
+    ? `${tokenInvalidationPrefix()}${fingerprint.toLowerCase()}`
     : null;
 }
 
@@ -123,8 +153,8 @@ export function invalidateCachedTokensByFingerprint(
   if (!fingerprint) return;
   const invalidationPath = invalidationPathForFingerprint(fingerprint);
   if (!invalidationPath) return;
-  if (!fs.existsSync(HQ_DIR)) {
-    fs.mkdirSync(HQ_DIR, { recursive: true, mode: 0o700 });
+  if (!fs.existsSync(hqStateDir())) {
+    fs.mkdirSync(hqStateDir(), { recursive: true, mode: 0o700 });
   }
   try {
     fs.writeFileSync(invalidationPath, "", { mode: 0o600, flag: "wx" });
@@ -144,46 +174,81 @@ function tokenIsInvalidated(accessToken: string): boolean {
   return marker !== null && fs.existsSync(marker);
 }
 
+/**
+ * True for the errno family a read-only / not-writable state directory raises.
+ *
+ * A job whose HQ state dir is mounted read-only (container, restricted
+ * sandbox, root-owned dir entered as another user) must still be able to
+ * AUTHENTICATE — persisting the session is an optimisation, not a requirement.
+ */
+function isNotWritableError(err: unknown): boolean {
+  const code = (err as NodeJS.ErrnoException | undefined)?.code;
+  return code === "EROFS" || code === "EACCES" || code === "EPERM";
+}
+
+/**
+ * Process-local fallback used when the state directory cannot be written.
+ *
+ * Keeps the cache semantics intact for the life of the process instead of
+ * failing the call outright. It is deliberately NOT a substitute for the shared
+ * on-disk cache: a fresh subprocess starts empty and re-mints.
+ */
+let inMemoryCachedTokens: CognitoTokens | null = null;
+
 export function loadCachedTokens(): CognitoTokens | null {
-  if (!fs.existsSync(TOKEN_FILE)) return null;
+  if (!fs.existsSync(tokenCacheFile())) return inMemoryCachedTokens;
   try {
-    const raw = fs.readFileSync(TOKEN_FILE, "utf-8");
+    const raw = fs.readFileSync(tokenCacheFile(), "utf-8");
     const tokens = JSON.parse(raw) as CognitoTokens;
     if (!tokens.accessToken || tokenIsInvalidated(tokens.accessToken)) return null;
     return tokens;
   } catch {
-    return null;
+    return inMemoryCachedTokens;
   }
 }
 
 export function saveCachedTokens(tokens: CognitoTokens): void {
-  if (!fs.existsSync(HQ_DIR)) {
-    fs.mkdirSync(HQ_DIR, { recursive: true, mode: 0o700 });
-  }
-  const invalidationPath = invalidationPathForFingerprint(
-    accessTokenFingerprint(tokens.accessToken),
-  );
-  if (invalidationPath && fs.existsSync(invalidationPath)) {
-    fs.unlinkSync(invalidationPath);
+  // Remember in-process FIRST: whatever happens to the disk write below, this
+  // process must not lose a session it already successfully minted.
+  inMemoryCachedTokens = tokens;
+  try {
+    if (!fs.existsSync(hqStateDir())) {
+      fs.mkdirSync(hqStateDir(), { recursive: true, mode: 0o700 });
+    }
+    const invalidationPath = invalidationPathForFingerprint(
+      accessTokenFingerprint(tokens.accessToken),
+    );
+    if (invalidationPath && fs.existsSync(invalidationPath)) {
+      fs.unlinkSync(invalidationPath);
+    }
+    const tmpPath = path.join(
+      hqStateDir(),
+      `.cognito-tokens.json.tmp.${process.pid}`,
+    );
+    fs.writeFileSync(tmpPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+    fs.renameSync(tmpPath, tokenCacheFile());
+  } catch (err) {
+    // A read-only state dir degrades to the in-memory cache. Any other error
+    // (disk full, corrupt path) is still a real fault and propagates.
+    if (!isNotWritableError(err)) throw err;
   }
-  const tmpPath = path.join(HQ_DIR, `.cognito-tokens.json.tmp.${process.pid}`);
-  fs.writeFileSync(tmpPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
-  fs.renameSync(tmpPath, TOKEN_FILE);
 }
 
 export function clearCachedTokens(): void {
-  if (fs.existsSync(TOKEN_FILE)) fs.unlinkSync(TOKEN_FILE);
-  if (!fs.existsSync(HQ_DIR)) return;
-  const markerPrefix = `${path.basename(TOKEN_FILE)}.invalid.`;
-  for (const entry of fs.readdirSync(HQ_DIR)) {
+  if (fs.existsSync(tokenCacheFile())) fs.unlinkSync(tokenCacheFile());
+  if (!fs.existsSync(hqStateDir())) return;
+  const markerPrefix = `${path.basename(tokenCacheFile())}.invalid.`;
+  for (const entry of fs.readdirSync(hqStateDir())) {
     if (entry.startsWith(markerPrefix)) {
-      fs.unlinkSync(path.join(HQ_DIR, entry));
+      fs.unlinkSync(path.join(hqStateDir(), entry));
     }
   }
 }
 
 /** Advisory lockfile guarding the read→refresh→save cycle (see withRefreshLock). */
-const REFRESH_LOCK_FILE = `${TOKEN_FILE}.lock`;
+function refreshLockFile(): string {
+  return `${tokenCacheFile()}.lock`;
+}
 
 /** Thrown when the refresh lock can't be acquired within the deadline. */
 export class RefreshLockTimeoutError extends Error {
@@ -196,7 +261,7 @@ export class RefreshLockTimeoutError extends Error {
 /** The pid recorded in the lockfile, or null if absent/empty/malformed. */
 function readLockOwnerPid(): number | null {
   try {
-    const pid = Number.parseInt(fs.readFileSync(REFRESH_LOCK_FILE, "utf-8").trim(), 10);
+    const pid = Number.parseInt(fs.readFileSync(refreshLockFile(), "utf-8").trim(), 10);
     return Number.isInteger(pid) && pid > 0 ? pid : null;
   } catch {
     return null;
@@ -244,23 +309,38 @@ function processAlive(pid: number): boolean {
 async function withRefreshLock<T>(fn: () => Promise<T>): Promise<T> {
   const timeoutMs = 20_000;
   const pollMs = 50;
-  if (!fs.existsSync(HQ_DIR)) {
-    fs.mkdirSync(HQ_DIR, { recursive: true, mode: 0o700 });
+  try {
+    if (!fs.existsSync(hqStateDir())) {
+      fs.mkdirSync(hqStateDir(), { recursive: true, mode: 0o700 });
+    }
+  } catch (err) {
+    if (!isNotWritableError(err)) throw err;
+    return await fn();
   }
   // Publish a fully-written inode with an atomic hard link. Creating the lock
   // itself and then writing the pid leaves an observable empty-file window in
   // which a contender can misclassify and unlink a live holder's lock.
-  const candidate = `${REFRESH_LOCK_FILE}.candidate.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
-  fs.writeFileSync(candidate, String(process.pid), {
-    flag: "wx",
-    mode: 0o600,
-  });
+  const candidate = `${refreshLockFile()}.candidate.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
+  try {
+    fs.writeFileSync(candidate, String(process.pid), {
+      flag: "wx",
+      mode: 0o600,
+    });
+  } catch (err) {
+    if (!isNotWritableError(err)) throw err;
+    // The state dir is not writable, so NO process can be persisting to this
+    // cache — there is nothing to serialize against and the lock's only job is
+    // moot. Run unlocked rather than failing the caller's authentication on a
+    // lockfile we neither need nor can create. (Before this, a read-only state
+    // dir raised EACCES here, killing machine auth before any network call.)
+    return await fn();
+  }
   const deadline = Date.now() + timeoutMs;
   let held = false;
   try {
     for (;;) {
       try {
-        fs.linkSync(candidate, REFRESH_LOCK_FILE);
+        fs.linkSync(candidate, refreshLockFile());
         held = true;
         break;
       } catch (err) {
@@ -268,7 +348,7 @@ async function withRefreshLock<T>(fn: () => Promise<T>): Promise<T> {
         const owner = readLockOwnerPid();
         if (owner === null || (owner !== process.pid && !processAlive(owner))) {
           try {
-            fs.unlinkSync(REFRESH_LOCK_FILE); // crashed/malformed holder — reclaim
+            fs.unlinkSync(refreshLockFile()); // crashed/malformed holder — reclaim
           } catch {
             /* raced with another reclaimer */
           }
@@ -283,7 +363,7 @@ async function withRefreshLock<T>(fn: () => Promise<T>): Promise<T> {
     // Release ONLY our own lock — never clobber a successor's.
     if (held && readLockOwnerPid() === process.pid) {
       try {
-        fs.unlinkSync(REFRESH_LOCK_FILE);
+        fs.unlinkSync(refreshLockFile());
       } catch {
         /* already released */
       }
@@ -544,6 +624,48 @@ export function isMachineIdentity(): boolean {
   return loadMachineCreds() !== null;
 }
 
+/**
+ * Whether the caller declared this process MUST run as a machine identity
+ * (`HQ_REQUIRE_MACHINE_IDENTITY=1`).
+ *
+ * Set it on unattended runners — child jobs, workers, skill subprocesses. It
+ * converts the worst failure mode in this module into a clear one.
+ *
+ * Without it, a machine context that cannot find its credentials does not
+ * error: `isMachineIdentity()` returns false and the caller quietly proceeds to
+ * the HUMAN Cognito path. On a headless box that means "launching browser
+ * sign-in" and a hang until something times out — observed in production, and
+ * reported by a client as child jobs "falling back to refreshing a human HQ
+ * session". The cause (a different HOME, so a different creds path) is nowhere
+ * in that message.
+ */
+export function machineIdentityRequired(): boolean {
+  const raw = process.env.HQ_REQUIRE_MACHINE_IDENTITY?.trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes";
+}
+
+/**
+ * Throw a typed, diagnosable error when machine identity is REQUIRED but the
+ * creds file is not readable. Names the exact path checked and how it was
+ * derived, so the fix (set `HQ_MACHINE_CREDS_FILE`, or restore HOME) is
+ * readable straight off the error. No-op when not required or already a
+ * machine identity.
+ */
+export function assertMachineIdentityWhenRequired(): void {
+  if (!machineIdentityRequired() || isMachineIdentity()) return;
+  const explicit = process.env.HQ_MACHINE_CREDS_FILE?.trim();
+  const source =
+    explicit !== undefined && explicit.length > 0
+      ? "HQ_MACHINE_CREDS_FILE"
+      : `os.homedir()=${os.homedir()}`;
+  throw new CognitoAuthError(
+    `HQ_REQUIRE_MACHINE_IDENTITY is set but no usable machine credentials were ` +
+      `found at ${machineCredsFilePath()} (path from ${source}). Refusing to ` +
+      `fall back to an interactive human session. Set HQ_MACHINE_CREDS_FILE to ` +
+      `the credentials file, or run with the HOME that owns it.`,
+  );
+}
+
 interface InitiateAuthResponse {
   AuthenticationResult?: {
     AccessToken?: string;
@@ -1231,6 +1353,11 @@ export async function getValidAccessToken(
     return machine.idToken;
   }
 
+  // Past this point we are on the HUMAN path (cache -> refresh -> browser).
+  // An unattended runner that declared itself a machine must fail here with a
+  // diagnosable error rather than silently trying to sign a person in.
+  assertMachineIdentityWhenRequired();
+
   let cached = loadCachedTokens();
 
   // Stale-pool detection: if the cached access token was issued by a