@indigoai-us/hq-cli 5.345.155 → 5.345.159

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"),

package/dist/lib/daemon/run.js

@@ -56,6 +56,7 @@ import { adoptChild, createChildTracker, finishSuccession, handoffEligible, read
 import { listSyncRunnerProcesses, readWatchRunnerOwnerStatus, syncHeartbeatTimeoutMs, syncRunnerNodeOptions, watchRunnerOwnerStatusPath, } from "./sync-runner.js";
 import { STOP_ESCALATION_MS, SYNC_RUNNER_PERSIST_GRACE_MS, createSupervisor, } from "./supervisor.js";
 import { userToolDirs } from "./tools.js";
+import { logOffset, readLogSince, readUnitHolds, writeUnitHolds } from "./unit-holds.js";
 import { daemonRunGuard } from "./lanes-reconcile-guard.js";
 export const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
 /** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
@@ -1002,10 +1003,13 @@ export async function runDaemon(opts) {
         }
         return plans;
     };
+    /** Where each unit's log ended when its current run started, so its exit is classified on that run's output only. */
+    const unitLogOffsets = new Map();
     const spawnUnit = (unit) => {
         const command = unit.command;
         if (!command || command.type === "internal")
             throw new Error(`${unit.id} has no process to start`);
+        unitLogOffsets.set(unit.id, logOffset(paths.unitLogPath(unit.id)));
         let [file, args] = command.type === "hq"
             ? daemonHqChildCommand(opts.nodeBinary, opts.hqBinary, command.args, stagedHqChildBootstrap?.bootstrapPath ?? null, cliPackagePrefix, childBootstrapHandoffWatchFlag.status().enabled)
             : command.type === "node"
@@ -1136,6 +1140,15 @@ export async function runDaemon(opts) {
         restartDaemon: () => restartDaemon(),
         runGuard: daemonRunGuard,
         writeState: (state) => writeJsonAtomic(paths.statePath, state),
+        holds: {
+            read: () => readUnitHolds(paths.holdsPath),
+            write: (holds) => writeUnitHolds(paths.holdsPath, holds),
+        },
+        exitOutputTail: (unitId) => {
+            // An adopted unit was started by an earlier daemon; its output start is unknown.
+            const offset = unitLogOffsets.get(unitId);
+            return offset === undefined ? undefined : readLogSince(paths.unitLogPath(unitId), offset);
+        },
         log,
         onSyncRunnerStopping: () => extendSyncShutdownCap?.(),
         syncOwnerBlockReason: () => {

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

@@ -3,6 +3,11 @@
  *
  * - long-running units are restarted after they exit, with per-unit backoff
  *   (1 s doubling to 60 s, reset once a unit has stayed up for a minute);
+ *   a unit that fails EPISODE_MAX_FAILURES times without a run of
+ *   EPISODE_HEALTHY_RESET_MS, or fails for a permanent cause (see exit-cause.ts), is held
+ *   instead. Permanent holds need a restart request, command change or CLI update.
+ *   Exhausted transient sync/mesh units make one durable supervised probe after
+ *   a 30-minute cooldown; a failed probe re-holds, and an explicit stop stays stopped;
  *   `on-failure` units stay down after a clean exit or a SIGTERM/SIGINT from
  *   outside, and any unit stays down after a stop request (`hq bot stop`),
  *   until a restart request;
@@ -26,6 +31,14 @@ import type { UnitPlan } from "./catalog.js";
 import type { MachineType } from "./machine-type.js";
 import type { ControlRequest } from "./requests.js";
 import { syncPassResult } from "./sync-runner.js";
+export declare const HEALTHY_RUN_MS = 60000;
+/**
+ * Failures in one episode before the unit is held: the first start plus five
+ * automatic retries. Matches the Desktop app's MAX_FAILURES.
+ */
+export declare const EPISODE_MAX_FAILURES = 6;
+/** A run this long ends the failure episode. Matches the Desktop app's HEALTHY_RUN_WINDOW. */
+export declare const EPISODE_HEALTHY_RESET_MS: number;
 export declare const STOP_ESCALATION_MS = 10000;
 export declare const SYNC_RUNNER_PERSIST_GRACE_MS = 60000;
 export declare const CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS = 60000;
@@ -42,7 +55,38 @@ export interface SupervisedChild {
     on(event: "error", handler: (err: Error) => void): unknown;
     kill(signal?: NodeJS.Signals | number): boolean;
 }
-type UnitStatus = "running" | "waiting" | "unavailable" | "backoff" | "exited" | "idle" | "stopped";
+type UnitStatus = "running" | "waiting" | "unavailable" | "backoff" | "exited" | "idle" | "stopped" | "held";
+/**
+ * Why a long-running unit is held down. `permanent`: the last exit had a cause
+ * a restart cannot fix. `exhausted`: EPISODE_MAX_FAILURES failures without a
+ * run of EPISODE_HEALTHY_RESET_MS. Persisted (see SupervisorDeps.holds)
+ * so a daemon restart keeps the unit held.
+ */
+export interface UnitHold {
+    kind: "permanent" | "exhausted";
+    /** A PermanentExitCause, or "transient" for an exhausted episode. */
+    cause: string;
+    detail: string;
+    /** Epoch ms when the hold started. */
+    since: number;
+    /** Failures in the episode that ended in the hold, the last one included. */
+    failures: number;
+    lastExit?: {
+        code: number | null;
+        signal: string | null;
+        at: number;
+    };
+    /** sha256 of the unit's plan key; a hold only applies to the command it was recorded for. */
+    keyHash: string;
+    /** Exhausted sync/mesh only: next durable supervised-probe deadline. */
+    retryAt?: number;
+    /** A probe claim remains durable until that running generation is healthy. */
+    probing?: boolean;
+    /** Explicit stop of a recovering unit; only an explicit restart clears it. */
+    retryStopped?: boolean;
+}
+/** The holds file: unit id to hold. */
+export type PersistedHolds = Record<string, UnitHold>;
 interface UnitState {
     id: string;
     service: string;
@@ -65,6 +109,8 @@ interface UnitState {
     lastPassResult?: ReturnType<typeof syncPassResult>;
     /** The pass-request folder the running child was started with; absent when it was not. */
     passRequestDir?: string;
+    /** Also retained during a supervised recovery probe or its explicit manual stop. */
+    hold?: UnitHold;
 }
 /** An app that runs the daemon as its own child process instead of an OS unit. */
 export type HostApp = "desktop";
@@ -119,6 +165,13 @@ export interface SupervisorDeps {
     adopt?: readonly AdoptedUnit[];
     /** Pre-run check for scheduled units that declare `runGuard`; a throw counts as `spawn`. */
     runGuard?: (unit: UnitPlan) => "spawn" | "idle" | "skip";
+    /** What a long-running unit wrote during the run that just ended, for exit classification. */
+    exitOutputTail?: (unitId: string) => string | undefined;
+    /** Durable storage for unit holds, so a held unit stays held across daemon restarts. */
+    holds?: {
+        read(): PersistedHolds;
+        write(holds: PersistedHolds): void;
+    };
 }
 export interface Supervisor {
     start(): void;