@indigoai-us/hq-cli 5.345.156 → 5.345.160

package/dist/lib/bot/run.js

@@ -85,7 +85,7 @@ import { SIGN_IN_RETRY_MS, signInNeededText } from "./runtime-sign-in.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, readBotSession, writeBotSession } from "./session.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";
@@ -309,6 +309,8 @@ function defaultSleep(ms, signal) {
  * one did not: `delivered` is how many parts the person has, so a retry starts
  * where it stopped instead of repeating what they already read.
  */
+class CompanyBindingError extends Error {
+}
 class PartialPostError extends Error {
     parts;
     delivered;
@@ -453,6 +455,11 @@ export async function runBot(deps) {
     // Personal: every turn acts as the owner. Company: every turn acts as the bot.
     const kind = effectiveBotKind(config);
     const companies = effectiveBotCompanies(config);
+    // A single membership is unambiguous; personal and multi-company bots stay unbound.
+    const companySlug = config.companySlug ?? (kind === "company" && companies.length === 1 ? companies[0] : undefined);
+    const companyScopeKey = kind === "company" || companySlug !== undefined
+        ? JSON.stringify({ kind, companies: [...companies].sort(), companySlug: companySlug ?? null })
+        : undefined;
     const lockDeps = defaultPidLockDeps({
         pid,
         ...(deps.isProcessAlive ? { isProcessAlive: deps.isProcessAlive } : {}),
@@ -521,7 +528,7 @@ export async function runBot(deps) {
     // A restart is the owner's "try again" after signing in: start clean.
     setStatus({ ...fallback(), pid, state: "starting", canDrainForPromotion: false, runtimeSignIn: null, cliVersion });
     log("info", `starting ${config.name} on hq-cli ${cliVersion} (${config.runtime}, ${kind} bot${companies.length ? ` of ${companies.join(", ")}` : ""}) as ${config.agentUid} for ${config.ownerUid}`);
-    log("info", `${runtime.id} binary: ${describeRuntimeBinary(runtime, turnEnv(process.env, kind, config.agentUid, config.companySlug), turnCwd)}`);
+    log("info", `${runtime.id} binary: ${describeRuntimeBinary(runtime, turnEnv(process.env, kind, config.agentUid, companySlug), turnCwd)}`);
     deps.cliUpdate?.startup(log);
     try {
         const record = await api.getAgent(config.agentUid);
@@ -541,6 +548,15 @@ export async function runBot(deps) {
         await finish("failed", 0, `could not verify bot identity: ${err instanceof Error ? err.message : String(err)}`);
         return { stop: async () => { }, done, status: () => null, idle: () => true };
     }
+    try {
+        const scope = ensureBotCompanyScope(dir, companyScopeKey);
+        if (scope.reset)
+            log("info", "company scope changed or was unverified; archived prior conversations before starting fresh");
+    }
+    catch {
+        await finish("failed", 0, "could not isolate previous company conversations; settle any pending work under the previous settings and check workspace permissions before restarting");
+        return { stop: async () => { }, done, status: () => null, idle: () => true };
+    }
     // ── System prompt ──────────────────────────────────────────────────────────
     // A pack worker's bot gets the pack's "Pack setup" section (and the HQ setup
     // takeover when the pack asks for it and setup is unfinished).
@@ -563,14 +579,14 @@ export async function runBot(deps) {
             workerDir: config.workerDir,
             workerSource: config.workerSource,
             workerId: config.workerId,
-            companySlug: config.companySlug,
+            companySlug,
             kind,
             companies,
             memoryDir: config.memoryDir,
             sources: readPromptSources(config.hqRoot, config.workerDir, undefined, {
                 memoryDir: config.memoryDir,
                 workerSource: config.workerSource,
-                companySlug: config.companySlug,
+                companySlug,
             }),
         });
     const systemPromptFile = path.join(dir, "system-prompt.md");
@@ -878,8 +894,18 @@ export async function runBot(deps) {
      * A DM with no session (or whose resume id is gone) gets the recent thread
      * prepended so a one-word reply still has the question it answers.
      */
+    const bindingNotices = new Set();
     const executeTurn = async (prompt, sessionScope, tReceived, stream = {}, historyEventId) => {
-        const live = readBotConfig(dir) ?? config;
+        const fresh = readBotConfig(dir);
+        if (!fresh)
+            throw new CompanyBindingError(`I couldn't read my company settings. Please restart ${config.name} after restoring its configuration; this work is still pending.`);
+        const live = fresh;
+        const liveCompanies = effectiveBotCompanies(live);
+        const liveCompanySlug = live.companySlug ?? (effectiveBotKind(live) === "company" && liveCompanies.length === 1 ? liveCompanies[0] : undefined);
+        if (liveCompanySlug !== companySlug || effectiveBotKind(live) !== kind ||
+            JSON.stringify([...liveCompanies].sort()) !== JSON.stringify([...companies].sort())) {
+            throw new CompanyBindingError(`My company settings changed. Please restart ${config.name} to load them before I continue; this work is still pending.`);
+        }
         const remembered = readStatus()?.claudePermissionMode;
         const actsPurelyForOwner = sessionScope === "dm" || sessionScope.startsWith("job:");
         const composePrompt = async (session) => {
@@ -920,22 +946,22 @@ export async function runBot(deps) {
             return next;
         };
         const runAttempt = async (session, turnPrompt) => {
-            // Company bind (worker-sourced bots): HQ's company hooks key on
+            // Company bind (worker-sourced and single-company bots): HQ's company hooks key on
             // workspace/sessions/<sid>/meta.yaml, so the session id is fixed up front
             // and the meta file written before every turn (idempotent; covers session
             // 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, config.companySlug);
+            const env = turnEnv(process.env, kind, config.agentUid, companySlug);
             let bind = { env };
-            if (config.companySlug) {
+            if (companySlug) {
                 try {
-                    ensureBotSessionMeta(config.hqRoot, sid, config.companySlug, undefined, now);
-                    bind = { newSessionId: sid, env: { ...env, HQ_SESSION_ID: sid } };
+                    ensureBotSessionMeta(config.hqRoot, sid, liveCompanySlug, undefined, now);
                 }
-                catch (err) {
-                    log("warn", `company bind failed for ${config.companySlug}: ${err instanceof Error ? err.message : String(err)}`);
+                catch {
+                    throw new CompanyBindingError(`I couldn't bind this session to ${companySlug}. Please check the bot's workspace permissions and retry; this work is still pending.`);
                 }
+                bind = { newSessionId: sid, env: { ...env, HQ_SESSION_ID: sid } };
             }
             const tTurnStart = now().getTime();
             // Model and thinking level are read fresh each turn, so a change from the
@@ -997,6 +1023,7 @@ export async function runBot(deps) {
                     v: 1,
                     runtime: config.runtime,
                     sessionId: turn.sessionId,
+                    ...(companyScopeKey !== undefined ? { companyScopeKey } : {}),
                     turns: (session?.turns ?? 0) + 1,
                     updatedAt: now().toISOString(),
                 }, sessionScope);
@@ -1143,7 +1170,18 @@ export async function runBot(deps) {
             await poster.abandon();
             const excerpt = err instanceof RuntimeError ? err.stderrExcerpt : err instanceof Error ? err.message : String(err);
             const aborted = (err instanceof RuntimeError && err.aborted) || controller.signal.aborted;
-            const started = !(err instanceof RuntimeError) || err.started;
+            if (err instanceof CompanyBindingError) {
+                setStatus({ lastError: err.message });
+                log("warn", err.message);
+                if (!bindingNotices.has(args.sessionScope)) {
+                    try {
+                        await args.sendToPerson(err.message);
+                        bindingNotices.add(args.sessionScope);
+                    }
+                    catch { /* Keep the notice retryable if delivery failed. */ }
+                }
+            }
+            const started = !(err instanceof CompanyBindingError) && (!(err instanceof RuntimeError) || err.started);
             return { outcome: { ok: false, started, aborted, excerpt, error: err }, poster };
         }
         finally {
@@ -1180,7 +1218,7 @@ export async function runBot(deps) {
         }
         await sendToTarget(target, notice.text, rootEventId, "human");
     };
-    const postOne = async (target, body, rootEventId, audience) => {
+    const postOne = async (target, body, rootEventId, audience, omitFromHistory = false) => {
         const root = rootEventId ? { rootEventId } : {};
         if (target.kind === "dm") {
             const posted = await api.sendDm({
@@ -1189,7 +1227,7 @@ export async function runBot(deps) {
                 ...root,
                 ...(audience ? { audience } : {}),
             });
-            if (audience !== "agent") {
+            if (audience !== "agent" && !omitFromHistory) {
                 const eventId = posted && typeof posted === "object" && "eventId" in posted && typeof posted.eventId === "string"
                     ? posted.eventId
                     : undefined;
@@ -1235,10 +1273,10 @@ export async function runBot(deps) {
      * PartialPostError naming how many parts got through, so the caller can save
      * exactly the remainder.
      */
-    const sendParts = async (target, parts, from, rootEventId, onDelivered, audience) => {
+    const sendParts = async (target, parts, from, rootEventId, onDelivered, audience, omitFromHistory = false) => {
         for (let i = Math.max(0, from); i < parts.length; i += 1) {
             try {
-                await postOne(target, parts[i], rootEventId, audience);
+                await postOne(target, parts[i], rootEventId, audience, omitFromHistory);
             }
             catch (err) {
                 throw new PartialPostError(parts, i, err);
@@ -1459,7 +1497,7 @@ export async function runBot(deps) {
         const parts = marker.replyParts ?? splitBody(recoveryBody(marker));
         const from = marker.replyParts ? Math.min(Math.max(0, marker.replyPartsDelivered ?? 0), parts.length) : 0;
         try {
-            await sendParts(marker.target, parts, from, marker.rootEventId, (count) => patchInflight(dir, marker.messageId, { replyParts: parts, replyPartsDelivered: count }));
+            await sendParts(marker.target, parts, from, marker.rootEventId, (count) => patchInflight(dir, marker.messageId, { replyParts: parts, replyPartsDelivered: count }), undefined, marker.omitFromHistory);
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
@@ -1471,12 +1509,12 @@ export async function runBot(deps) {
                     // no part of this run reached the chat yet.
                     const headerOut = (marker.progressPosted ?? 0) > 0 || (err instanceof PartialPostError ? err.delivered : from) > 0;
                     const text = marker.jobHeader && !headerOut ? `${marker.jobHeader}${UNDELIVERABLE_JOB_REPORT_TEXT}` : UNDELIVERABLE_JOB_REPORT_TEXT;
-                    await postOne(marker.target, text, marker.rootEventId).catch(() => undefined);
+                    await postOne(marker.target, text, marker.rootEventId, undefined, marker.omitFromHistory).catch(() => undefined);
                     // Giving up on DELIVERY is not giving up on the RUN: report it.
                     await reportRecoveredJobRun(marker);
                 }
                 else {
-                    await postOne(marker.target, UNDELIVERABLE_REPLY_TEXT, marker.rootEventId).catch(() => undefined);
+                    await postOne(marker.target, UNDELIVERABLE_REPLY_TEXT, marker.rootEventId, undefined, marker.omitFromHistory).catch(() => undefined);
                 }
                 await closeMarker(marker, isKickoff);
                 return true;
@@ -1592,6 +1630,10 @@ export async function runBot(deps) {
             workingNotice: false,
         });
         await clearThinking();
+        if (!outcome.ok && outcome.error instanceof CompanyBindingError) {
+            clearInflight(dir, KICKOFF_MESSAGE_ID);
+            return;
+        }
         if (outcome.ok) {
             // The kickoff never runs silenceable, so outcome.silent is never set here.
             if (poster.postedCount === 0) {
@@ -1758,6 +1800,11 @@ export async function runBot(deps) {
             workingNotice: false,
             ...(quietJob ? { suppressOutput: true } : {}),
         });
+        if (!outcome.ok && outcome.error instanceof CompanyBindingError) {
+            clearInflight(dir, id);
+            attempts.delete(id);
+            return;
+        }
         if (outcome.ok) {
             if (!quietJob && !reportDelivered(outcome.reply)) {
                 // The work finished but the REPORT did not fully reach the DM — even if
@@ -2076,6 +2123,11 @@ export async function runBot(deps) {
         });
         // The model saw the note once its turn ran. A turn that never started, or
         // one held for a coding-tool sign-in, runs again and keeps the note for it.
+        if (!outcome.ok && outcome.error instanceof CompanyBindingError) {
+            clearInflight(dir, id);
+            attempts.delete(id);
+            return;
+        }
         if (setupNote && !toolOffer && (outcome.ok || (outcome.started && !isSignInFailure(outcome.excerpt)))) {
             try {
                 patchSetupIntroState(dir, { notePending: false });

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

@@ -10,10 +10,24 @@ export interface BotSessionFile {
     v: 1;
     runtime: BotRuntimeId;
     sessionId: string;
+    /** Company/membership fingerprint under which this transcript was created. */
+    companyScopeKey?: string;
     turns: number;
     updatedAt: string;
 }
 export declare function readBotSession(dir: string, runtime: BotRuntimeId, scope?: BotSessionScope): BotSessionFile | null;
 export declare function writeBotSession(dir: string, session: BotSessionFile, scope?: BotSessionScope): void;
 export declare function clearBotSession(dir: string, scope?: BotSessionScope): void;
+/**
+ * Run once at startup, before reading or appending conversation state. A scope
+ * change must never resume a prior company's model session or replay its DM
+ * history. Preserve those files privately for recovery, then record the new
+ * scope. Filesystem failures propagate so callers cannot start a model turn.
+ * Legacy personal bots retain their existing history; company bots require
+ * positive scope evidence and archive legacy, unproven conversations once.
+ */
+export declare function ensureBotCompanyScope(dir: string, companyScopeKey: string | undefined): {
+    reset: boolean;
+    archiveDir?: string;
+};
 //# sourceMappingURL=session.d.ts.map

package/dist/lib/bot/session.js

@@ -6,6 +6,8 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { omitInflightRecoveryHistory, readInflightTurns } from "./inflight.js";
 import { botSessionPath } from "./paths.js";
 export function readBotSession(dir, runtime, scope = "dm") {
     const p = botSessionPath(dir, scope);
@@ -36,4 +38,72 @@ export function clearBotSession(dir, scope = "dm") {
         /* already gone */
     }
 }
+/**
+ * Run once at startup, before reading or appending conversation state. A scope
+ * change must never resume a prior company's model session or replay its DM
+ * history. Preserve those files privately for recovery, then record the new
+ * scope. Filesystem failures propagate so callers cannot start a model turn.
+ * Legacy personal bots retain their existing history; company bots require
+ * positive scope evidence and archive legacy, unproven conversations once.
+ */
+export function ensureBotCompanyScope(dir, companyScopeKey) {
+    const marker = path.join(dir, "company-scope.json");
+    const hasMarker = fs.existsSync(marker);
+    if (!hasMarker && companyScopeKey === undefined)
+        return { reset: false };
+    const expected = companyScopeKey ?? null;
+    let provenPreviousScope = false;
+    if (hasMarker) {
+        // Read errors fail closed. Invalid JSON is unproven provenance and resets.
+        const body = fs.readFileSync(marker, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            parsed = null;
+        }
+        provenPreviousScope = Boolean(parsed && typeof parsed === "object" &&
+            parsed.v === 1 &&
+            (typeof parsed.companyScopeKey === "string" ||
+                parsed.companyScopeKey === null));
+        if (parsed && typeof parsed === "object" &&
+            parsed.v === 1 &&
+            parsed.companyScopeKey === expected) {
+            return { reset: false };
+        }
+    }
+    // A known company switch must settle recovery under its previous scope.
+    // Legacy bots have no scope evidence: isolate their model context below,
+    // but leave delivery/job markers intact for the existing recovery path.
+    // Recovery only settles saved work; it never resumes the old model session.
+    // Match recovery's tolerant parser so corrupt markers do not brick startup.
+    const pending = readInflightTurns(dir, { strictIo: true });
+    if (provenPreviousScope && pending.length > 0) {
+        throw new Error("Bot company settings changed with pending work. Restore the previous company settings and settle pending work before switching companies.");
+    }
+    if (!provenPreviousScope)
+        omitInflightRecoveryHistory(dir, pending);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const names = fs.readdirSync(dir).filter((name) => /^(?:session|dm-history)(?:-[A-Za-z0-9_-]+)?\.json$/.test(name));
+    let archiveDir;
+    if (names.length) {
+        const archiveRoot = path.join(dir, "company-scope-archives");
+        fs.mkdirSync(archiveRoot, { recursive: true, mode: 0o700 });
+        archiveDir = path.join(archiveRoot, randomUUID());
+        fs.mkdirSync(archiveDir, { mode: 0o700 });
+        for (const name of names)
+            fs.renameSync(path.join(dir, name), path.join(archiveDir, name));
+    }
+    // Commit the new provenance only after every old conversation was isolated.
+    const tmp = path.join(dir, `.company-scope.${randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(tmp, `${JSON.stringify({ v: 1, companyScopeKey: expected })}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, marker);
+    }
+    finally {
+        fs.rmSync(tmp, { force: true });
+    }
+    return { reset: names.length > 0, ...(archiveDir ? { archiveDir } : {}) };
+}
 //# sourceMappingURL=session.js.map

package/dist/lib/capacity/collectors/claude-oauth.d.ts

@@ -287,6 +287,12 @@ export declare function tokenFingerprint(token: string): string;
 export declare function readClaudeRefreshLast(root: string, home: string): ClaudeRefreshLastEntry | null;
 /** @deprecated prefer {@link revokedMarkerForCurrentCredential}; this is the pre-fingerprint shim. */
 export declare function isAccountRevokedPersisted(root: string, accountId: string): boolean;
+/**
+ * True when the capacity collector has recorded this refresh token as
+ * revoked (by token fingerprint, under any account). Lanes use it to tell a
+ * dead sign-in from an access token that Claude Code will renew at startup.
+ */
+export declare function isRefreshTokenRevoked(root: string, refreshToken: string): boolean;
 /**
  * Compare the persisted revoked marker (if any) against the refresh token the
  * caller is about to use.

package/dist/lib/capacity/collectors/claude-oauth.js

@@ -1556,6 +1556,18 @@ export function isAccountRevokedPersisted(root, accountId) {
     const file = readRefreshLast(root);
     return Object.prototype.hasOwnProperty.call(file.revokedAccounts, accountId);
 }
+/**
+ * True when the capacity collector has recorded this refresh token as
+ * revoked (by token fingerprint, under any account). Lanes use it to tell a
+ * dead sign-in from an access token that Claude Code will renew at startup.
+ */
+export function isRefreshTokenRevoked(root, refreshToken) {
+    const file = readRefreshLast(root);
+    const fp = tokenFingerprint(refreshToken);
+    if (file.revokedTokens[fp] !== undefined)
+        return true;
+    return Object.values(file.revokedAccounts).some((entry) => entry.fingerprint === fp);
+}
 /**
  * Compare the persisted revoked marker (if any) against the refresh token the
  * caller is about to use.

package/dist/lib/capacity/lane-login.d.ts

@@ -20,6 +20,12 @@ export interface LaneLoginInput {
      * login confirms sign-in through this probe. Defaults to the lanes probe.
      */
     probeProvider?: Ctx["probeProvider"];
+    /**
+     * Claude access-token expiry check for the post-login status. Defaults to
+     * the real Keychain/file read when the default probe is used; a caller that
+     * injects a probe passes its own reader or gets no expiry check.
+     */
+    readClaudeCredential?: Ctx["readClaudeCredential"];
 }
 export interface LaneLoginResult {
     id: string;

package/dist/lib/capacity/lane-login.js

@@ -13,6 +13,7 @@ import { createLaneAccountsHandlers } from "../../commands/lanes-accounts.js";
 import { effectiveAccountHome } from "../lanes/account-home.js";
 import { canonicalizeHome, DEFAULT_ACCOUNT_HOMES, loadLanesConfig } from "../lanes/config.js";
 import { resolveLanesHqRoot } from "../lanes/hq-root.js";
+import { readLaneClaudeCredential } from "../lanes/claude-credential.js";
 import { defaultProbe } from "../lanes/models.js";
 import { parseLaneProvider } from "../lanes/types.js";
 const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
@@ -108,6 +109,10 @@ function loginCtx(input, hqRoot) {
         existsSync: (target) => fs.existsSync(target),
         spawnLogin: defaultHomeEnv(input.spawnLogin ?? defaultSpawnLogin, input.homedir ?? os.homedir),
         probeProvider: defaultHomeProbe(input.probeProvider ?? defaultProbe, input.homedir ?? os.homedir),
+        // Always a real field: the Proxy below turns a missing one into a throwing
+        // function, which accountStatus would call and report as a failed check.
+        readClaudeCredential: input.readClaudeCredential ??
+            (input.probeProvider === undefined ? readLaneClaudeCredential : undefined),
     };
     return new Proxy(fields, {
         get(target, prop) {

package/dist/lib/core-utils/worktree.js

@@ -42,6 +42,8 @@ export function createWorktree(args = [], options = {}) {
         }
     }
     const die = (message) => { line(stderr, `ERROR: ${message}`); return 1; };
+    // Accept "--base origin/<branch>" as well as "--base <branch>"; fetch and ref lookups add origin/ themselves.
+    base = base.replace(/^origin\//, "");
     if (!name)
         return die("--name is required (kebab-case slug, e.g. 'fix-login-bug')");
     if (name.includes("/") || name.includes(" "))

package/dist/lib/daemon/exit-cause.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Classifies why a supervised long-running unit stopped, so the supervisor can
+ * tell a failure that a restart will not fix (permanent) from one that may
+ * clear on its own (transient).
+ *
+ * Permanent causes stop the restart loop and hold the unit until a manual
+ * `hq daemon restart <unit>`, a command change, or a CLI update. Anything not
+ * recognised is transient, so an unknown failure keeps the bounded retry.
+ *
+ * Output is never substring-matched. Only npm's own diagnostic line
+ * (`npm error code <CODE>` from npm 10+, `npm ERR! code <CODE>` from older
+ * npm) counts, and only for a code in PERMANENT_NPM_CODES. The Desktop app
+ * uses the same prefixes and list.
+ */
+export type PermanentExitCause = "missing-binary" | "not-executable" | "package-resolution" | "engine-mismatch" | "permission-denied" | "bad-config" | "auth-refused";
+export type ExitCause = {
+    kind: "transient";
+} | {
+    kind: "permanent";
+    cause: PermanentExitCause;
+    detail: string;
+};
+export interface ExitEvidence {
+    code: number | null;
+    signal: string | null;
+    /** The launch error, when the process could not be started. */
+    spawnError?: unknown;
+    /** Output the process wrote during this run only (not earlier runs). */
+    outputTail?: string;
+}
+/**
+ * npm error codes that a retry cannot fix without a change by a person.
+ * Network and cache codes (ECONNRESET, ETIMEDOUT, ENOTFOUND, EAI_AGAIN,
+ * ECONNREFUSED, EINTEGRITY, EPERM, EBUSY, ENOSPC) stay transient on purpose.
+ */
+export declare const PERMANENT_NPM_CODES: Readonly<Record<string, PermanentExitCause>>;
+/** The first npm error code line naming a permanent code, as `{ code, line }`. */
+export declare function permanentNpmCode(output: string): {
+    code: string;
+    cause: PermanentExitCause;
+} | undefined;
+export declare function classifyExit(evidence: ExitEvidence): ExitCause;
+//# sourceMappingURL=exit-cause.d.ts.map

package/dist/lib/daemon/exit-cause.js

@@ -0,0 +1,88 @@
+/**
+ * Classifies why a supervised long-running unit stopped, so the supervisor can
+ * tell a failure that a restart will not fix (permanent) from one that may
+ * clear on its own (transient).
+ *
+ * Permanent causes stop the restart loop and hold the unit until a manual
+ * `hq daemon restart <unit>`, a command change, or a CLI update. Anything not
+ * recognised is transient, so an unknown failure keeps the bounded retry.
+ *
+ * Output is never substring-matched. Only npm's own diagnostic line
+ * (`npm error code <CODE>` from npm 10+, `npm ERR! code <CODE>` from older
+ * npm) counts, and only for a code in PERMANENT_NPM_CODES. The Desktop app
+ * uses the same prefixes and list.
+ */
+/**
+ * npm error codes that a retry cannot fix without a change by a person.
+ * Network and cache codes (ECONNRESET, ETIMEDOUT, ENOTFOUND, EAI_AGAIN,
+ * ECONNREFUSED, EINTEGRITY, EPERM, EBUSY, ENOSPC) stay transient on purpose.
+ */
+export const PERMANENT_NPM_CODES = {
+    ETARGET: "package-resolution", // no version matches the requested range or tag
+    E404: "package-resolution", // package or version not in the registry
+    EINVALIDPACKAGENAME: "package-resolution",
+    EUNSUPPORTEDPROTOCOL: "package-resolution", // unsupported spec, e.g. a bad URL scheme
+    EBADENGINE: "engine-mismatch", // engine-strict and node does not satisfy engines
+    EACCES: "permission-denied", // cache or prefix not writable by this user
+    E401: "auth-refused",
+    E403: "auth-refused",
+    ENEEDAUTH: "auth-refused",
+};
+const NPM_CODE_PREFIXES = ["npm error code ", "npm ERR! code "];
+/** sysexits.h EX_NOPERM / EX_CONFIG, and the shell's not-executable / not-found codes. */
+const EXIT_CODE_CAUSES = {
+    77: { cause: "auth-refused", detail: "exit code 77 (permission or auth refused)" },
+    78: { cause: "bad-config", detail: "exit code 78 (configuration error)" },
+    126: { cause: "not-executable", detail: "exit code 126 (command not executable)" },
+    127: { cause: "missing-binary", detail: "exit code 127 (command not found)" },
+};
+/** Launch errno codes, read from the error's `code` field only. */
+const SPAWN_ERROR_CAUSES = {
+    ENOENT: "missing-binary",
+    EACCES: "not-executable",
+    ENOEXEC: "not-executable",
+};
+function errorCode(err) {
+    if (err && typeof err === "object" && "code" in err && typeof err.code === "string") {
+        return err.code;
+    }
+    return undefined;
+}
+/** The first npm error code line naming a permanent code, as `{ code, line }`. */
+export function permanentNpmCode(output) {
+    for (const raw of output.split(/\r?\n/)) {
+        const line = raw.trim();
+        for (const prefix of NPM_CODE_PREFIXES) {
+            if (!line.startsWith(prefix))
+                continue;
+            const code = line.slice(prefix.length).split(/\s+/)[0] ?? "";
+            const cause = Object.prototype.hasOwnProperty.call(PERMANENT_NPM_CODES, code) ? PERMANENT_NPM_CODES[code] : undefined;
+            if (cause)
+                return { code, cause };
+        }
+    }
+    return undefined;
+}
+export function classifyExit(evidence) {
+    if (evidence.spawnError !== undefined) {
+        const code = errorCode(evidence.spawnError);
+        const cause = code ? SPAWN_ERROR_CAUSES[code] : undefined;
+        if (cause)
+            return { kind: "permanent", cause, detail: `could not start (${code})` };
+    }
+    // A process killed by a signal says nothing about its own configuration.
+    if (evidence.signal)
+        return { kind: "transient" };
+    if (evidence.code === 0)
+        return { kind: "transient" };
+    if (evidence.code !== null) {
+        const byCode = EXIT_CODE_CAUSES[evidence.code];
+        if (byCode)
+            return { kind: "permanent", ...byCode };
+    }
+    const npm = evidence.outputTail ? permanentNpmCode(evidence.outputTail) : undefined;
+    if (npm)
+        return { kind: "permanent", cause: npm.cause, detail: `npm error code ${npm.code}` };
+    return { kind: "transient" };
+}
+//# sourceMappingURL=exit-cause.js.map

package/dist/lib/daemon/handoff.d.ts

@@ -9,6 +9,8 @@ import { type MachineType } from "./machine-type.js";
 import { type DaemonPaths } from "./paths.js";
 /** A live daemon runs `unitId` (or held it after it was stopped from outside). */
 export declare function daemonSupervises(paths: DaemonPaths, unitId: string, alive?: (pid: number) => boolean): boolean;
+/** Current supervisor hold, including its explicit recovery command; never infer one from stale state. */
+export declare function daemonHoldReason(paths: DaemonPaths, unitId: string, alive?: (pid: number) => boolean): string | null;
 /**
  * A live daemon runs the service `unitId` belongs to (`bots` for
  * `bots:<name>`), so it will run this instance once its plan includes it. For

package/dist/lib/daemon/handoff.js

@@ -16,7 +16,7 @@ import { detectMachineType } from "./machine-type.js";
 import { daemonPaths } from "./paths.js";
 import { writeControlRequest } from "./requests.js";
 /** Statuses where the daemon itself owns the unit's process. */
-const OWNED = new Set(["running", "backoff", "exited", "idle", "stopped"]);
+const OWNED = new Set(["running", "backoff", "exited", "idle", "stopped", "held"]);
 const RECENT_HOSTED_DAEMON_MS = 5 * 60_000;
 /** The updater's postinstall may run in the short gap before the desktop app relaunches its daemon. */
 function recentlyHostedDaemon(paths) {
@@ -44,6 +44,11 @@ export function daemonSupervises(paths, unitId, alive = (pid) => isDaemonProcess
     const unit = liveState(paths, alive)?.units?.find((u) => u.id === unitId);
     return unit !== undefined && OWNED.has(unit.status);
 }
+/** Current supervisor hold, including its explicit recovery command; never infer one from stale state. */
+export function daemonHoldReason(paths, unitId, alive = (pid) => isDaemonProcess(pid)) {
+    const unit = liveState(paths, alive)?.units?.find((u) => u.id === unitId);
+    return unit?.status === "held" ? unit.reason ?? `held; \`hq daemon restart ${unitId}\` retries` : null;
+}
 /**
  * A live daemon runs the service `unitId` belongs to (`bots` for
  * `bots:<name>`), so it will run this instance once its plan includes it. For

package/dist/lib/daemon/hq-child-bootstrap.mjs

@@ -43,14 +43,31 @@ function updateRequestIsActive(requestPath) {
     const pid = request.pid;
     if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
         throw new Error("The HQ CLI update request is invalid");
+    // Same staleness rule as src/utils/package-use-lease.ts: a request written
+    // before the current boot (pid may be reused), or whose pid is gone (ESRCH)
+    // or owned by another user (EPERM), is not a live updater.
+    let stale = false;
     try {
-        process.kill(pid, 0);
+        stale = fs.statSync(requestPath).mtimeMs < Date.now() - os.uptime() * 1000 - 5_000;
     }
     catch (error) {
-        if (error.code === "ESRCH") {
-            fs.rmSync(requestPath, { force: true });
+        if (error.code === "ENOENT")
             return false;
+        throw new Error("Unable to read the HQ CLI update request");
+    }
+    if (!stale) {
+        try {
+            process.kill(pid, 0);
         }
+        catch (error) {
+            const code = error.code;
+            if (code === "ESRCH" || code === "EPERM")
+                stale = true;
+        }
+    }
+    if (stale) {
+        fs.rmSync(requestPath, { force: true });
+        return false;
     }
     return true;
 }

package/dist/lib/daemon/paths.d.ts

@@ -8,6 +8,8 @@ export interface DaemonPaths {
     configPath: string;
     remoteControlPoolsPath: string;
     statePath: string;
+    /** Long-running units the supervisor holds down, with why (see unit-holds.ts). */
+    holdsPath: string;
     lockPath: string;
     logsDir: string;
     requestsDir: string;

package/dist/lib/daemon/paths.js

@@ -14,6 +14,7 @@ export function daemonPaths(home = os.homedir(), env = process.env) {
         configPath: path.join(root, "config.json"),
         remoteControlPoolsPath: path.join(root, "remote-control-pools.json"),
         statePath: path.join(root, "state.json"),
+        holdsPath: path.join(root, "holds.json"),
         lockPath: path.join(root, "daemon.pid"),
         logsDir,
         requestsDir: path.join(root, "requests"),