@indigoai-us/hq-cli 5.345.175 → 5.345.177

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.103","bundleSha256":"3ed362bac2c75d32a61b0e26b4253813af96458579920a798fd38a9583e855f9","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.104","bundleSha256":"40c72e049db21ee4551fa737676d8022cd090149ede9e3c9e53a9fae3f28dadc","formatVersion":1}

package/dist/lib/bot/cli-update.d.ts

@@ -23,6 +23,15 @@
  * that target for CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS instead of restarting
  * again. Restarts are also capped per window, so an install that keeps
  * flipping cannot turn into a restart loop.
+ *
+ * The same watcher covers the macOS HQ.app launcher. A bot's LaunchAgent runs
+ * `HQ.app/Contents/MacOS/hq-sync-menubar --hq-launchd-task node hq bot run`, and
+ * that launcher is what macOS privacy (TCC) attributes the bot's file access
+ * to. When an HQ.app update replaces the launcher binary under a running bot,
+ * every coding-tool turn after that fails within milliseconds ("An unknown
+ * error occurred (Unexpected)") because ~/Documents access no longer resolves,
+ * until the bot is restarted under the new launcher. So a changed launcher
+ * binary is handled like an updated CLI: confirm, drain, exit for launchd.
  */
 import type { BotLogger } from "./log.js";
 /**
@@ -62,7 +71,18 @@ export interface CliUpdate {
     from: string;
     to: string;
     packageRoot: string;
+    /** "launcher": the HQ.app launcher binary was replaced; the CLI version is unchanged. */
+    reason?: "launcher";
+}
+/** One line for the log and the exit reason. */
+export declare function describeCliUpdate(update: CliUpdate): string;
+/** Identity of a file on disk: an app update replaces the inode or changes size/mtime. */
+export interface LauncherStamp {
+    ino: number;
+    size: number;
+    mtimeMs: number;
 }
+export declare function statLauncher(p: string): LauncherStamp | null;
 interface CliUpdateLedger {
     v: 1;
     /** Written just before an update restart; settled by the next process. */
@@ -70,6 +90,7 @@ interface CliUpdateLedger {
         from: string;
         to: string;
         at: string;
+        reason?: "launcher";
     };
     /** ISO times of recent update restarts (for the per-window cap). */
     restarts: string[];
@@ -95,6 +116,9 @@ export interface CliUpdateWatcherOptions {
     dir: string;
     /** The script this process was launched with (process.argv[1]); null = do not watch. */
     entry: string | null;
+    /** The HQ.app launcher binary that started this process (macOS LaunchAgent); null = do not watch. */
+    launcher?: string | null;
+    statLauncher?: (p: string) => LauncherStamp | null;
     runningVersion?: string;
     now?: () => number;
     read?: (entry: string) => InstalledCliRead;
@@ -107,6 +131,18 @@ export interface CliUpdateWatcherOptions {
     cooldownMs?: number;
 }
 export declare function createCliUpdateWatcher(opts: CliUpdateWatcherOptions): CliUpdateWatch;
+/**
+ * The HQ.app launcher binary this process runs under, or null. A LaunchAgent
+ * written for HQ.app runs `<HQ.app>/Contents/MacOS/hq-sync-menubar
+ * --hq-launchd-task node hq ...`; the launcher spawns node and waits, so it is
+ * the direct parent. Only a parent whose command line carries the launcher
+ * flag counts.
+ */
+export declare function detectHqAppLauncher(opts?: {
+    platform?: NodeJS.Platform;
+    ppid?: number;
+    parentCommand?: (pid: number) => string | null;
+}): string | null;
 /**
  * Who starts this bot again after it exits.
  *

package/dist/lib/bot/cli-update.js

@@ -23,7 +23,17 @@
  * that target for CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS instead of restarting
  * again. Restarts are also capped per window, so an install that keeps
  * flipping cannot turn into a restart loop.
+ *
+ * The same watcher covers the macOS HQ.app launcher. A bot's LaunchAgent runs
+ * `HQ.app/Contents/MacOS/hq-sync-menubar --hq-launchd-task node hq bot run`, and
+ * that launcher is what macOS privacy (TCC) attributes the bot's file access
+ * to. When an HQ.app update replaces the launcher binary under a running bot,
+ * every coding-tool turn after that fails within milliseconds ("An unknown
+ * error occurred (Unexpected)") because ~/Documents access no longer resolves,
+ * until the bot is restarted under the new launcher. So a changed launcher
+ * binary is handled like an updated CLI: confirm, drain, exit for launchd.
  */
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import semver from "semver";
@@ -98,6 +108,22 @@ export function readInstalledCli(entry, io = fs) {
     }
     return { ok: false, reason: `no ${CLI_NAME} package.json above ${real}` };
 }
+/** One line for the log and the exit reason. */
+export function describeCliUpdate(update) {
+    return update.reason === "launcher"
+        ? `HQ.app was updated (${update.packageRoot}); restarting under the new launcher`
+        : `hq-cli updated ${update.from} -> ${update.to}; restarting to load it`;
+}
+export function statLauncher(p) {
+    try {
+        const st = fs.statSync(p);
+        return { ino: st.ino, size: st.size, mtimeMs: st.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+const sameStamp = (a, b) => a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs;
 function ledgerPath(dir) {
     return path.join(dir, CLI_UPDATE_LEDGER_FILE);
 }
@@ -133,6 +159,19 @@ export function createCliUpdateWatcher(opts) {
     const restartWindowMs = opts.restartWindowMs ?? CLI_UPDATE_RESTART_WINDOW_MS;
     const cooldownMs = opts.cooldownMs ?? CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS;
     const { dir, entry } = opts;
+    const launcher = opts.launcher ?? null;
+    const stat = opts.statLauncher ?? statLauncher;
+    /** The launcher as it was when this process started; null = not watched. */
+    const launcherBaseline = launcher ? stat(launcher) : null;
+    let launcherCandidate = null;
+    let launcherSeen = 0;
+    let lastLauncherNote = null;
+    const launcherNote = (log, level, message) => {
+        if (message === lastLauncherNote)
+            return;
+        lastLauncherNote = message;
+        log(level, message);
+    };
     let nextCheckAt = now() + checkIntervalMs;
     let candidate = null;
     let seen = 0;
@@ -151,6 +190,10 @@ export function createCliUpdateWatcher(opts) {
     return {
         runningVersion,
         startup(log) {
+            if (launcher && launcherBaseline)
+                log("info", `watching ${launcher} for HQ.app updates`);
+            else if (launcher)
+                log("warn", `not watching for HQ.app updates: ${launcher} is not readable`);
             if (!entry) {
                 log("info", "not watching for hq-cli updates (no entry script)");
                 return;
@@ -159,7 +202,10 @@ export function createCliUpdateWatcher(opts) {
             const pending = ledger.pending;
             if (pending) {
                 delete ledger.pending;
-                if (runningVersion === pending.to) {
+                if (pending.reason === "launcher") {
+                    log("info", `restarted after an HQ.app update; now running hq-cli ${runningVersion}`);
+                }
+                else if (runningVersion === pending.to) {
                     log("info", `hq-cli update converged: now running ${runningVersion} (was ${pending.from})`);
                     if (ledger.blocked?.version === runningVersion)
                         delete ledger.blocked;
@@ -183,60 +229,132 @@ export function createCliUpdateWatcher(opts) {
             log("info", `watching ${entry} for hq-cli updates (running ${runningVersion})`);
         },
         poll(log) {
-            if (!entry)
+            if (!entry && !launcherBaseline)
                 return null;
             const at = now();
             if (at < nextCheckAt)
                 return null;
             nextCheckAt = at + checkIntervalMs;
-            const installed = read(entry);
-            if (!installed.ok) {
-                candidate = null;
-                seen = 0;
-                note(log, "warn", `hq-cli install not readable, not restarting: ${installed.reason}`);
-                return null;
-            }
-            if (installed.version === runningVersion) {
-                candidate = null;
-                seen = 0;
-                lastNote = null;
-                return null;
-            }
-            if (rewriteInProgress(installed.packageRoot)) {
-                candidate = null;
-                seen = 0;
-                note(log, "info", `hq-cli ${installed.version} is still being installed; waiting for it to finish`);
-                return null;
-            }
-            if (candidate === installed.version)
-                seen += 1;
-            else {
-                candidate = installed.version;
-                seen = 1;
-            }
-            if (seen < confirmations) {
-                note(log, "info", `hq-cli ${installed.version} is installed (running ${runningVersion}); confirming before restarting`);
-                return null;
-            }
-            const ledger = readCliUpdateLedger(dir);
-            if (ledger.blocked?.version === installed.version && at < Date.parse(ledger.blocked.until)) {
-                note(log, "warn", `not restarting for hq-cli ${installed.version}: an earlier restart for it did not load it (retry after ${ledger.blocked.until})`);
-                return null;
-            }
-            if (recentRestarts(ledger, at).length >= restartLimit) {
-                note(log, "warn", `not restarting for hq-cli ${installed.version}: already restarted ${restartLimit} times for updates in the last ${Math.round(restartWindowMs / 60_000)} minutes`);
-                return null;
-            }
-            return { from: runningVersion, to: installed.version, packageRoot: installed.packageRoot };
+            return pollCli(log, at) ?? pollLauncher(log, at);
         },
         recordRestart(update) {
             const at = now();
             const ledger = readCliUpdateLedger(dir);
             ledger.restarts = [...recentRestarts(ledger, at), new Date(at).toISOString()];
-            ledger.pending = { from: update.from, to: update.to, at: new Date(at).toISOString() };
+            ledger.pending = {
+                from: update.from,
+                to: update.to,
+                at: new Date(at).toISOString(),
+                ...(update.reason ? { reason: update.reason } : {}),
+            };
             writeCliUpdateLedger(dir, ledger);
         },
     };
+    function underRestartCap(log, at, what, say = note) {
+        if (recentRestarts(readCliUpdateLedger(dir), at).length < restartLimit)
+            return true;
+        say(log, "warn", `not restarting for ${what}: already restarted ${restartLimit} times for updates in the last ${Math.round(restartWindowMs / 60_000)} minutes`);
+        return false;
+    }
+    function pollLauncher(log, at) {
+        if (!launcher || !launcherBaseline)
+            return null;
+        const current = stat(launcher);
+        if (!current) {
+            // Mid-replace: the old bundle is gone and the new one is not there yet.
+            launcherCandidate = null;
+            launcherSeen = 0;
+            launcherNote(log, "info", `${launcher} is missing (HQ.app being replaced?); waiting`);
+            return null;
+        }
+        if (sameStamp(current, launcherBaseline)) {
+            launcherCandidate = null;
+            launcherSeen = 0;
+            lastLauncherNote = null;
+            return null;
+        }
+        if (launcherCandidate && sameStamp(current, launcherCandidate))
+            launcherSeen += 1;
+        else {
+            launcherCandidate = current;
+            launcherSeen = 1;
+        }
+        if (launcherSeen < confirmations) {
+            launcherNote(log, "info", `${launcher} changed (HQ.app update); confirming before restarting`);
+            return null;
+        }
+        if (!underRestartCap(log, at, "the HQ.app update", launcherNote))
+            return null;
+        return { from: runningVersion, to: runningVersion, packageRoot: launcher, reason: "launcher" };
+    }
+    function pollCli(log, at) {
+        if (!entry)
+            return null;
+        const installed = read(entry);
+        if (!installed.ok) {
+            candidate = null;
+            seen = 0;
+            note(log, "warn", `hq-cli install not readable, not restarting: ${installed.reason}`);
+            return null;
+        }
+        if (installed.version === runningVersion) {
+            candidate = null;
+            seen = 0;
+            lastNote = null;
+            return null;
+        }
+        if (rewriteInProgress(installed.packageRoot)) {
+            candidate = null;
+            seen = 0;
+            note(log, "info", `hq-cli ${installed.version} is still being installed; waiting for it to finish`);
+            return null;
+        }
+        if (candidate === installed.version)
+            seen += 1;
+        else {
+            candidate = installed.version;
+            seen = 1;
+        }
+        if (seen < confirmations) {
+            note(log, "info", `hq-cli ${installed.version} is installed (running ${runningVersion}); confirming before restarting`);
+            return null;
+        }
+        const ledger = readCliUpdateLedger(dir);
+        if (ledger.blocked?.version === installed.version && at < Date.parse(ledger.blocked.until)) {
+            note(log, "warn", `not restarting for hq-cli ${installed.version}: an earlier restart for it did not load it (retry after ${ledger.blocked.until})`);
+            return null;
+        }
+        if (!underRestartCap(log, at, `hq-cli ${installed.version}`))
+            return null;
+        return { from: runningVersion, to: installed.version, packageRoot: installed.packageRoot };
+    }
+}
+/**
+ * The HQ.app launcher binary this process runs under, or null. A LaunchAgent
+ * written for HQ.app runs `<HQ.app>/Contents/MacOS/hq-sync-menubar
+ * --hq-launchd-task node hq ...`; the launcher spawns node and waits, so it is
+ * the direct parent. Only a parent whose command line carries the launcher
+ * flag counts.
+ */
+export function detectHqAppLauncher(opts = {}) {
+    if ((opts.platform ?? process.platform) !== "darwin")
+        return null;
+    const ppid = opts.ppid ?? process.ppid;
+    if (!ppid || ppid <= 1)
+        return null;
+    const parentCommand = opts.parentCommand ??
+        ((pid) => {
+            const r = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 5_000 });
+            return r.status === 0 ? r.stdout.trim() : null;
+        });
+    const command = parentCommand(ppid);
+    if (!command)
+        return null;
+    const flag = command.indexOf(" --hq-launchd-task ");
+    if (flag <= 0)
+        return null;
+    const binary = command.slice(0, flag);
+    return binary.endsWith("/Contents/MacOS/hq-sync-menubar") ? binary : null;
 }
 export function detectBotSupervisor(name, opts = {}) {
     const env = opts.env ?? process.env;

package/dist/lib/bot/run.d.ts

@@ -56,6 +56,7 @@ import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "
 import { type BotSessionScope } from "./paths.js";
 import { type DecisionDmClient } from "./decisions.js";
 import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js";
+import { type RuntimeSignInCheck } from "./runtime-sign-in.js";
 import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
 import { type BotState, type BotStatusFile } from "./status.js";
 import { type CliUpdate, type CliUpdateWatch } from "./cli-update.js";
@@ -197,6 +198,15 @@ export interface BotRunDeps {
      * thread are recorded through it. Unset leaves every owner DM on the model path.
      */
     decisions?: DecisionDmClient;
+    /**
+     * The bot's own sign-in check (runtime-sign-in-check.ts), run with the
+     * turn's environment at start, before each turn, and while signed out.
+     * Injected in tests; unset runs the runtime's status command. A runtime
+     * with no status command answers `signedIn: null` and turns run as before.
+     */
+    checkSignIn?: (env: NodeJS.ProcessEnv) => Promise<RuntimeSignInCheck>;
+    /** How often to ask the tool again while it is signed out (default SIGN_IN_CHECK_MS). */
+    signInCheckMs?: number;
 }
 export declare const KICKOFF_MESSAGE_ID = "kickoff";
 /**
@@ -219,6 +229,17 @@ export declare const KICKOFF_MESSAGE_ID = "kickoff";
  * Pure so the rule is unit-testable.
  */
 export declare function turnEnv(base: NodeJS.ProcessEnv, kind: BotKind, agentUid?: string, companySlug?: string): NodeJS.ProcessEnv;
+/** The account name this process runs as, or null when the OS cannot say. */
+export declare function osUserName(): string | null;
+/**
+ * Claude Code keys its macOS Keychain login on `$USER` (falling back to the
+ * literal "unknown"), so a tool spawned from an environment without USER
+ * reads a different Keychain item than the owner's terminal and is signed
+ * out. launchd and the HQ app's launcher may leave it unset; fill it (and
+ * LOGNAME) from the account this process runs as. Never overrides a USER
+ * already set. Pure.
+ */
+export declare function withOsUser(env: NodeJS.ProcessEnv, name?: string | null): NodeJS.ProcessEnv;
 /** The core worker HQ's setup bot runs. */
 export declare const SETUP_WORKER_ID = "setup";
 /**

package/dist/lib/bot/run.js

@@ -50,6 +50,7 @@ import { ownerContextBlock } from "./owner-context.js";
 import { randomUUID } from "node:crypto";
 import { hasPromotionHold } from "./promotion-hold.js";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { fullJitterDelayMs } from "../mesh/live/backoff.js";
 import { acquirePidLock, defaultPidLockDeps, releasePidLock } from "../mesh/live/daemon/pid-lock.js";
@@ -82,14 +83,15 @@ import { resolveRoomMentionsForBot, roomPostHasMentionTokens, } from "./room-men
 import { buildJobTurnPrompt, isCatchUpRun, isJobItem, jobReportHeader, jobRunOutput, machineTimeZone, planJobRuns, stripJobHeader, SUPERSEDED_DISPOSITION } from "./job-run.js";
 import { botJobQuietOptionEnabled } from "./job-quiet-flag.js";
 import { clearPendingJobCompletion, isCompletionDue, isCompletionExpired, isCompletionForOtherAgent, readPendingJobCompletions, recordPendingJobCompletion } from "./job-completions.js";
-import { SIGN_IN_RETRY_MS, signInNeededText } from "./runtime-sign-in.js";
+import { SIGN_IN_CHECK_FRESH_MS, SIGN_IN_CHECK_MS, SIGN_IN_RETRY_MS, signInNeededText, signedOutExcerpt, } from "./runtime-sign-in.js";
+import { checkRuntimeSignIn } from "./runtime-sign-in-check.js";
 import { classifyRuntimeError, classifyRuntimeFailure, runtimeDidNotFinishText, runtimeFailureReason, runtimeFailureText, runtimeRepairNotice, withRetrySuggestion, } from "./runtime-failure.js";
 import { HQ_BOT_AGENT_UID_ENV } from "../../commands/onboard-bot-membership.js";
 import { captureHeartbeatIdentityMismatch, identityMismatchMessage, isHeartbeatIdentityMismatch, } from "../heartbeat-identity.js";
 import { clearBotSession, ensureBotCompanyScope, readBotSession, writeBotSession } from "./session.js";
 import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
 import { CLI_VERSION } from "../../cli-version.js";
-import { CLI_UPDATE_RESTART_EXIT_CODE } from "./cli-update.js";
+import { CLI_UPDATE_RESTART_EXIT_CODE, describeCliUpdate } from "./cli-update.js";
 import { createInboxMqttWakeFlagReader, createInboxPollBackoffFlagReader, safeErrorClass } from "./inbox-poll-backoff-flag.js";
 import { createInboxWakeWatcher } from "./inbox-wake.js";
 import { workMeshRoot } from "../mesh/live/paths.js";
@@ -195,6 +197,29 @@ export function turnEnv(base, kind, agentUid, companySlug) {
     }
     return env;
 }
+/** The account name this process runs as, or null when the OS cannot say. */
+export function osUserName() {
+    try {
+        const name = os.userInfo().username?.trim();
+        return name || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Claude Code keys its macOS Keychain login on `$USER` (falling back to the
+ * literal "unknown"), so a tool spawned from an environment without USER
+ * reads a different Keychain item than the owner's terminal and is signed
+ * out. launchd and the HQ app's launcher may leave it unset; fill it (and
+ * LOGNAME) from the account this process runs as. Never overrides a USER
+ * already set. Pure.
+ */
+export function withOsUser(env, name = osUserName()) {
+    if (env.USER?.trim() || !name)
+        return env;
+    return { ...env, USER: name, ...(env.LOGNAME?.trim() ? {} : { LOGNAME: name }) };
+}
 /** The core worker HQ's setup bot runs. */
 export const SETUP_WORKER_ID = SETUP_BOT_WORKER_ID;
 /**
@@ -495,7 +520,7 @@ export async function runBot(deps) {
         cliUpdatePending = update;
         stopping = true;
         const busy = running.size;
-        log("info", `hq-cli updated ${update.from} -> ${update.to}; restarting to load it${busy ? ` after ${busy} running turn${busy === 1 ? "" : "s"} finish${busy === 1 ? "es" : ""}` : ""}`);
+        log("info", `${describeCliUpdate(update)}${busy ? ` after ${busy} running turn${busy === 1 ? "" : "s"} finish${busy === 1 ? "es" : ""}` : ""}`);
         return true;
     };
     // ── Preflight: creds, pid lock, owner verification ─────────────────────────
@@ -714,14 +739,17 @@ export async function runBot(deps) {
     /** Conversations already told this time that the bot needs a sign-in. */
     const toldAboutSignIn = new Set();
     const isSignInFailure = (excerpt) => classifyRuntimeFailure(excerpt) === "signed-out";
-    const markSignInBroken = (excerpt) => {
-        nextSignInRetryAt = now().getTime() + signInRetryMs;
+    const markSignInBroken = (excerpt, state = "expired", bump = true) => {
+        if (bump)
+            nextSignInRetryAt = now().getTime() + signInRetryMs;
         modelHealth = "degraded";
         if (signInIssue)
             return;
-        signInIssue = { state: "expired", runtime: config.runtime, since: now().toISOString() };
+        signInIssue = { state, runtime: config.runtime, since: now().toISOString() };
         setStatus({ runtimeSignIn: signInIssue, lastError: excerpt.slice(0, 400) });
-        log("warn", `${runtime.id} needs to sign in again on this computer; holding turns and retrying every ${Math.round(signInRetryMs / 1000)}s`);
+        log("warn", state === "signed-out"
+            ? `${runtime.id} is not signed in on this computer (its own check); holding turns and checking every ${Math.round(signInCheckMs / 1000)}s`
+            : `${runtime.id} needs to sign in again on this computer; holding turns and retrying every ${Math.round(signInRetryMs / 1000)}s`);
     };
     const markSignInWorks = () => {
         if (!signInIssue)
@@ -731,6 +759,70 @@ export async function runBot(deps) {
         setStatus({ runtimeSignIn: null });
         log("info", `${runtime.id} sign-in works again; resuming`);
     };
+    // ── The bot's own sign-in check ────────────────────────────────────────────
+    // The tool is asked in the turn's environment (not the owner's shell): at
+    // start, before a turn, and on a timer while it says signed out, so a
+    // message is never spent on a turn that cannot start and the app can read
+    // the answer before it sends a job.
+    const signInCheckMs = Math.max(0, deps.signInCheckMs ?? SIGN_IN_CHECK_MS);
+    const checkSignIn = deps.checkSignIn ?? ((env) => checkRuntimeSignIn({ runtime, env, cwd: turnCwd, now }));
+    let lastSignInCheck = null;
+    let nextSignInCheckAt = 0;
+    /** Ask the tool; record the answer in status.json; return it. */
+    const runSignInCheck = async (reason) => {
+        const env = withOsUser(turnEnv(process.env, kind, config.agentUid, companySlug));
+        let check;
+        try {
+            check = await checkSignIn(env);
+        }
+        catch (err) {
+            check = { signedIn: null, checkedAt: now().toISOString(), detail: err instanceof Error ? err.message : String(err) };
+        }
+        lastSignInCheck = check;
+        nextSignInCheckAt = now().getTime() + signInCheckMs;
+        setStatus({ runtimeSignInCheck: check });
+        if (check.signedIn === false) {
+            // A repeat "no" while already held does not push the retry out again:
+            // the hold's own timer decides when a real turn gets to disagree.
+            markSignInBroken(signedOutExcerpt(runtime.id), "signed-out", signInIssue == null);
+        }
+        else if (check.signedIn === true) {
+            if (signInIssue) {
+                // The tool answers for itself now: the held messages run at once.
+                nextSignInRetryAt = 0;
+                markSignInWorks();
+            }
+        }
+        else if (check.detail) {
+            log("debug", `sign-in check (${reason}) could not tell: ${check.detail}`);
+        }
+        return check;
+    };
+    /** When a real turn last ran despite the tool saying "signed out". */
+    let lastTurnDespiteSignedOutAt = now().getTime();
+    /**
+     * Before a turn: a fresh "signed in" stands; anything else is asked again.
+     * The tool's status command only knows about its own account sign-in, so a
+     * tool that works some other way (an API key, Bedrock, Vertex) says "no"
+     * and would be held forever. Once per retry window a real turn runs anyway
+     * and its outcome decides: success clears the hold, a sign-in failure
+     * keeps it.
+     */
+    const signedOutBeforeTurn = async () => {
+        const fresh = lastSignInCheck?.signedIn === true && now().getTime() - new Date(lastSignInCheck.checkedAt).getTime() < SIGN_IN_CHECK_FRESH_MS;
+        if (fresh)
+            return false;
+        const check = await runSignInCheck("turn");
+        if (check.signedIn !== false)
+            return false;
+        const t = now().getTime();
+        if (signInRetryMs > 0 && t - lastTurnDespiteSignedOutAt >= signInRetryMs) {
+            lastTurnDespiteSignedOutAt = t;
+            log("info", `${runtime.id} still says it is not signed in; letting one turn try so a tool signed in another way is not held forever`);
+            return false;
+        }
+        return true;
+    };
     /** Say once per conversation that the bot cannot work until its tool signs in. */
     const tellSignInNeeded = async (conversation, post, kickoff = false, retryOf) => {
         if (toldAboutSignIn.has(conversation))
@@ -741,7 +833,7 @@ export async function runBot(deps) {
                 runtime: config.runtime,
                 botName: config.name,
                 context: kickoff ? "kickoff" : "message",
-                text: signInNeededText(config.runtime, kickoff),
+                text: signInNeededText(config.runtime, kickoff, signInIssue?.state ?? "expired"),
                 ...(retryOf ? { retryOf } : {}),
             }));
             toldAboutSignIn.add(conversation);
@@ -955,7 +1047,7 @@ export async function runBot(deps) {
             // resets). Claude gets the full hook set via its payload session id;
             // Codex/Grok only see HQ_SESSION_ID.
             const sid = session?.sessionId ?? randomUUID();
-            const env = turnEnv(process.env, kind, config.agentUid, companySlug);
+            const env = withOsUser(turnEnv(process.env, kind, config.agentUid, companySlug));
             let bind = { env };
             if (companySlug) {
                 try {
@@ -966,6 +1058,12 @@ export async function runBot(deps) {
                 }
                 bind = { newSessionId: sid, env: { ...env, HQ_SESSION_ID: sid } };
             }
+            // The tool's own word first: a turn on a signed-out tool cannot start,
+            // and its failure text varies by version (on 2026-10-28 it was a bare
+            // "unknown error" that read as a crash). Held like any sign-in failure.
+            if (await signedOutBeforeTurn()) {
+                throw new RuntimeError(`${runtime.id} is not signed in on this computer`, signedOutExcerpt(runtime.id), 1, { started: false, durationMs: 0 });
+            }
             const tTurnStart = now().getTime();
             // Model and thinking level are read fresh each turn, so a change from the
             // bot's profile (`hq bot set`) applies to the next message without a restart.
@@ -1020,6 +1118,14 @@ export async function runBot(deps) {
                 setStatus({ runtimeModelFallback: null });
             }
             log("info", `model turn done in ${Math.round((now().getTime() - tTurnStart) / 1000)}s (${Math.round((tTurnStart - tReceived) / 1000)}s before it)`);
+            // Clears a reported runtime crash (runtimeCrashSinceStart): the tool works again.
+            // Stamped with when the turn STARTED, so a long turn begun before a crash
+            // that finishes after it does not clear the crash for turns that follow.
+            // Never moves backwards: two turns run side by side, and an older one
+            // finishing last must not bring back a crash a newer turn already cleared.
+            const prevOk = Date.parse(readStatus()?.lastTurnOkAt ?? "");
+            if (!Number.isFinite(prevOk) || tTurnStart > prevOk)
+                setStatus({ lastTurnOkAt: new Date(tTurnStart).toISOString() });
             // A brief job's session is one run long; nothing resumes it.
             if (turn.sessionId && !isBriefJobSessionScope(sessionScope)) {
                 writeBotSession(dir, {
@@ -2431,6 +2537,10 @@ export async function runBot(deps) {
         attempts.delete(id);
         log("error", `turn on ${id} ${outcome.aborted ? "stopped by the owner" : "failed"} after it started; told the owner, not re-run`);
     };
+    // The bot's first look at its tool's sign-in, so `hq bot status` and the
+    // app know before any message arrives. A tool that cannot be asked changes
+    // nothing; the first turn then reports for itself.
+    await runSignInCheck("start");
     // The kickoff runs alongside the heartbeat, before the first inbox poll, so
     // an owner message sent meanwhile is answered after it in the same session.
     const kickoff = kickoffAfterIntro
@@ -2532,6 +2642,13 @@ export async function runBot(deps) {
             }
             if (modelHoldUntil)
                 liftModelHold();
+            // While the tool says it is signed out, ask it again on a timer (cheap,
+            // no turn): the moment it is signed in, the held messages run.
+            if (signInIssue && busyLanes.size === 0 && now().getTime() >= nextSignInCheckAt) {
+                await runSignInCheck("watch");
+                if (!signInIssue)
+                    pump();
+            }
             // A kickoff held for a sign-in retries on the same timer as messages.
             if (busyLanes.size === 0 &&
                 (!signInIssue || now().getTime() >= nextSignInRetryAt) &&
@@ -2662,7 +2779,7 @@ export async function runBot(deps) {
         catch (err) {
             log("warn", `could not record the update restart: ${err instanceof Error ? err.message : String(err)}`);
         }
-        void finish("stopped", CLI_UPDATE_RESTART_EXIT_CODE, `hq-cli updated ${update.from} -> ${update.to}; restarting to load it`, () => deps.onCliUpdateRestart?.(update, log));
+        void finish("stopped", CLI_UPDATE_RESTART_EXIT_CODE, describeCliUpdate(update), () => deps.onCliUpdateRestart?.(update, log));
     });
     return { stop, done, status: readStatus, idle: () => pending.size === 0 };
 }

package/dist/lib/bot/runtime/claude.d.ts

@@ -15,7 +15,7 @@
  * carries the final text and session_id.
  * Verified against Claude Code 2.1.258 on 2026-09-12 (fixtures/claude-stream.ndjson).
  */
-import type { BotRuntime } from "./types.js";
+import type { BotRuntime, SpawnResult } from "./types.js";
 export declare const CLAUDE_PERMISSION_MODE_ENV = "HQ_BOT_CLAUDE_PERMISSION_MODE";
 export declare const DEFAULT_CLAUDE_PERMISSION_MODE = "bypassPermissions";
 export declare const GATED_CLAUDE_PERMISSION_MODE = "acceptEdits";
@@ -84,4 +84,10 @@ export interface ClaudeRuntimeOptions {
     systemBinDirs?: readonly string[];
 }
 export declare function createClaudeRuntime(env?: NodeJS.ProcessEnv, opts?: ClaudeRuntimeOptions): BotRuntime;
+/**
+ * `claude auth status --json` prints `{"loggedIn": true|false, ...}` and
+ * exits 0 either way. Null when the output is not that (an older CLI, or a
+ * tool that could not run at all).
+ */
+export declare function parseClaudeAuthStatus(result: SpawnResult): boolean | null;
 //# sourceMappingURL=claude.d.ts.map

package/dist/lib/bot/runtime/claude.js

@@ -230,6 +230,35 @@ export function createClaudeRuntime(env = process.env, opts = {}) {
         failureReason(stdout) {
             return messagesStreamFailure(stdout);
         },
+        signInStatus: { args: ["auth", "status", "--json"], parse: parseClaudeAuthStatus },
     };
 }
+/**
+ * `claude auth status --json` prints `{"loggedIn": true|false, ...}` and
+ * exits 0 either way. Null when the output is not that (an older CLI, or a
+ * tool that could not run at all).
+ */
+export function parseClaudeAuthStatus(result) {
+    const text = result.stdout ?? "";
+    const start = text.indexOf("{");
+    if (start >= 0) {
+        try {
+            const parsed = JSON.parse(text.slice(start));
+            if (typeof parsed.loggedIn === "boolean")
+                return parsed.loggedIn;
+        }
+        catch {
+            /* fall through to the loose match */
+        }
+    }
+    const m = /"loggedIn"\s*:\s*(true|false)/.exec(text);
+    if (m)
+        return m[1] === "true";
+    const plain = `${text}\n${result.stderr ?? ""}`;
+    if (/\bnot logged in\b/i.test(plain))
+        return false;
+    if (/\blogged in\b/i.test(plain))
+        return true;
+    return null;
+}
 //# sourceMappingURL=claude.js.map