@indigoai-us/hq-cli 5.298.0 → 5.299.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [5.299.0] — 2026-09-30
+- Add `hq lanes accounts clear-quota` and clear future quota marks after successful lane turns.
+- On macOS, `hq daemon` retires a loaded legacy mesh LaunchAgent even when its plist is missing, and daemon uninstall boots the job out before deleting its plist. Mesh-owner wait logs now repeat at most every ten minutes.
+- Restore npm command links after a failed hq-cli self-update and repair or report missing links after successful installs.
+
 ## [5.298.0] — 2026-09-30
 - [feedback_d4a080e9-de79-4290-81c3-06ba26990a38] Preserve raw substring matches while normalizing company path searches.
 - `hq agents` now prints the Slack app settings link and the console paste link whenever an agent is waiting on its Slack app-level token, and follows the pending actions and paste URL the server returns.

package/dist/command-catalog.generated.d.ts

@@ -8990,6 +8990,29 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "JSON on stdout (always)";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "clear-quota";
+            readonly description: "Clear quota reset marks for a provider account";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <provider> <account-id>";
+            readonly arguments: readonly [{
+                readonly name: "provider";
+                readonly required: true;
+                readonly variadic: false;
+            }, {
+                readonly name: "account-id";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--model <model>";
+                readonly description: "Clear only this model's reset";
+            }, {
+                readonly flags: "--json";
+                readonly description: "JSON on stdout (always)";
+            }];
+            readonly subcommands: readonly [];
         }, {
             readonly name: "enable";
             readonly description: "Enable an account without touching credentials";

package/dist/command-catalog.generated.js

@@ -11601,6 +11601,36 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "clear-quota",
+                        "description": "Clear quota reset marks for a provider account",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <provider> <account-id>",
+                        "arguments": [
+                            {
+                                "name": "provider",
+                                "required": true,
+                                "variadic": false
+                            },
+                            {
+                                "name": "account-id",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--model <model>",
+                                "description": "Clear only this model's reset"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
                     {
                         "name": "enable",
                         "description": "Enable an account without touching credentials",

package/dist/commands/daemon.js

@@ -91,6 +91,7 @@ async function loadDefaults(over) {
                 home: dir ?? home,
                 existsSync: fs.existsSync,
                 listDir: (dir) => fs.readdirSync(dir),
+                launchdJobLoaded: (label) => run("launchctl", ["print", `gui/${process.getuid?.() ?? 0}/${label}`]).status === 0,
                 windowsTaskExists: (task) => run("schtasks.exe", ["/Query", "/TN", task]).status === 0,
             })),
         resolveHqRoot: over.resolveHqRoot ?? ((flag) => resolveDaemonHqRoot(flag, { env, cwd: process.cwd(), home })),

package/dist/commands/lanes-accounts.d.ts

@@ -17,6 +17,9 @@ export declare function createLaneAccountsHandlers(deps: LaneAccountsHandlerDeps
         host?: string;
         company?: string;
     }) => Promise<void>;
+    runAccountsClearQuota: (ctx: Ctx, providerRaw: string, accountIdRaw: string, opts: {
+        model?: string;
+    }) => Promise<void>;
     runAccountsEnable: (ctx: Ctx, providerRaw: string, accountId: string) => Promise<void>;
     runAccountsDisable: (ctx: Ctx, providerRaw: string, accountId: string, opts: {
         reason?: string;

package/dist/commands/lanes-accounts.js

@@ -8,7 +8,7 @@ import { AccountResolutionError, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, PROVIDER
 import { assertUniqueAccountHomes, providerCompactAfterMs } from "../lib/lanes/config.js";
 import { resolveLaneEffort } from "../lib/lanes/effort.js";
 import { LanesError } from "../lib/lanes/errors.js";
-import { accountQuotaView, loadQuotaState } from "../lib/lanes/quota.js";
+import { accountQuotaView, clearAccountQuota, loadQuotaState } from "../lib/lanes/quota.js";
 import { resolveLaneModel } from "../lib/lanes/spawn.js";
 export function createLaneAccountsHandlers(deps) {
     const { automaticBalanceMoveHistoryReason, ensureDir, laneWithRecoveredProviderSession, loadClaudeBalanceHostSnapshots, parseRemoteJson, prepareAccountMove, printJson, reconcileHostFromCtx, resolveCallerPath } = deps;
@@ -489,6 +489,29 @@ export function createLaneAccountsHandlers(deps) {
             home_source: home === account.home ? "default" : "host",
         });
     }
+    async function runAccountsClearQuota(ctx, providerRaw, accountIdRaw, opts) {
+        const provider = parseLaneProvider(providerRaw);
+        const account = accountIdRaw.trim();
+        if (!account) {
+            throw new AccountResolutionError("unknown_account", "account-id must be non-empty", { provider, account: accountIdRaw, enabled: [] });
+        }
+        const model = opts.model?.trim();
+        if (opts.model !== undefined && !model) {
+            throw new LanesError("invalid_model", "--model must be non-empty", {
+                provider,
+                account,
+            });
+        }
+        const cleared = clearAccountQuota(ctx.hqRoot(), provider, account, model === undefined ? {} : { model });
+        printJson({
+            ok: true,
+            action: "accounts.clear-quota",
+            provider,
+            account,
+            all_models_quota_reset_at: cleared.all_models_quota_reset_at,
+            model_quota_resets: cleared.model_quota_resets,
+        });
+    }
     async function runAccountsEnable(ctx, providerRaw, accountId) {
         const hqRoot = ctx.hqRoot();
         const provider = parseLaneProvider(providerRaw);
@@ -562,6 +585,7 @@ export function createLaneAccountsHandlers(deps) {
         runAccountsBalance,
         runAccountsLogin,
         runAccountsSetHome,
+        runAccountsClearQuota,
         runAccountsEnable,
         runAccountsDisable
     };

package/dist/commands/lanes.js

@@ -8453,6 +8453,16 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (provider, accountId, opts) => {
         await accountHandlers.runAccountsLogin(ctx, provider, accountId, opts);
     }));
+    accounts
+        .command("clear-quota")
+        .description("Clear quota reset marks for a provider account")
+        .argument("<provider>", "claude | codex | grok")
+        .argument("<account-id>", "Account id")
+        .option("--model <model>", "Clear only this model's reset")
+        .option("--json", "JSON on stdout (always)")
+        .action(wrap(async (provider, accountId, opts) => {
+        await accountHandlers.runAccountsClearQuota(ctx, provider, accountId, opts);
+    }));
     accounts
         .command("enable")
         .description("Enable an account without touching credentials")

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

@@ -3,8 +3,9 @@
  * still runs a service, the daemon leaves that service alone instead of
  * starting a second copy, and `hq daemon migrate` lists it.
  *
- * Detection only reads the filesystem (and asks schtasks on Windows). Nothing
- * here stops or removes a unit.
+ * Detection reads unit files and checks for an orphaned loaded macOS mesh job
+ * whose plist was removed. Windows scheduled tasks are probed through
+ * schtasks. Nothing here stops or removes a unit.
  */
 import type { ServiceName } from "./catalog.js";
 export interface LegacyUnit {
@@ -22,6 +23,8 @@ export interface LegacyProbeDeps {
     home: string;
     existsSync: (p: string) => boolean;
     listDir: (dir: string) => string[];
+    /** True when launchctl can print the GUI-domain job despite a missing plist. */
+    launchdJobLoaded: (label: string) => boolean;
     windowsTaskExists: (taskName: string) => boolean;
 }
 export declare function describeLegacyUnit(unit: LegacyUnit): string;

package/dist/lib/daemon/legacy.js

@@ -3,8 +3,9 @@
  * still runs a service, the daemon leaves that service alone instead of
  * starting a second copy, and `hq daemon migrate` lists it.
  *
- * Detection only reads the filesystem (and asks schtasks on Windows). Nothing
- * here stops or removes a unit.
+ * Detection reads unit files and checks for an orphaned loaded macOS mesh job
+ * whose plist was removed. Windows scheduled tasks are probed through
+ * schtasks. Nothing here stops or removes a unit.
  */
 import * as path from "node:path";
 const KIT_SERVICES = ["sync", "inbox", "heartbeat"];
@@ -52,8 +53,9 @@ function darwinUnits(deps) {
     const units = [];
     const at = (label) => path.join(dir, `${label}.plist`);
     const add = (unitId, service, label, migratable = true) => units.push({ unitId, service, kind: "launchd", name: label, path: at(label), migratable });
-    if (deps.existsSync(at("ai.getindigo.hq-mesh-daemon")))
-        add("mesh", "mesh", "ai.getindigo.hq-mesh-daemon");
+    const meshLabel = "ai.getindigo.hq-mesh-daemon";
+    if (deps.existsSync(at(meshLabel)) || deps.launchdJobLoaded(meshLabel))
+        add("mesh", "mesh", meshLabel);
     for (const file of safeList(deps, dir).sort()) {
         const m = /^ai\.getindigo\.hq-bot\.(.+)\.plist$/.exec(file);
         if (m)

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

@@ -17,11 +17,13 @@
  * folder, so nobody but root decides what gets installed there.
  */
 import type { RunCommand } from "../service-manager/launchd.js";
-import type { LegacyUnit } from "./legacy.js";
+import { type LegacyUnit } from "./legacy.js";
 export interface AdoptedUnit extends LegacyUnit {
     /** Where the unit's definition (plist, unit file, task XML) was moved. */
     movedTo: string;
     adoptedAt: number;
+    /** Launchd job was loaded, but its source plist no longer existed. */
+    definitionMissing?: true;
 }
 export interface MigrateDeps {
     run: RunCommand;
@@ -64,5 +66,12 @@ export interface RestoreResult {
 }
 export declare function readAdoptedUnits(recordPath: string): AdoptedUnit[];
 export declare function adoptLegacyUnits(units: readonly LegacyUnit[], deps: MigrateDeps): AdoptResult;
+/** Retire the migratable legacy mesh job and emit the daemon's operator-facing result lines. */
+export declare function retireLegacyMeshUnits(units: readonly LegacyUnit[], options: {
+    platform: NodeJS.Platform;
+    managed: boolean;
+    hosted: boolean;
+    meshEnabled: boolean;
+}, deps: MigrateDeps, log: (level: "info" | "warn", message: string) => void): AdoptResult;
 export declare function restoreLegacyUnits(deps: MigrateDeps): RestoreResult;
 //# sourceMappingURL=migrate.d.ts.map

package/dist/lib/daemon/migrate.js

@@ -18,6 +18,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { legacyMeshUnitsToRetire } from "./legacy.js";
 import { ensurePrivateDir } from "./paths.js";
 export function readAdoptedUnits(recordPath) {
     let text;
@@ -99,8 +100,10 @@ function adoptOne(unit, deps) {
             if (bootout.status !== 0 && deps.run("launchctl", ["print", target]).status === 0) {
                 must(deps.run, "launchctl", ["bootout", target]);
             }
+            if (!fs.existsSync(unit.path))
+                return { movedTo: unit.path, definitionMissing: true };
             moveFile(unit.path, to);
-            return to;
+            return { movedTo: to };
         }
         case "systemd-user":
         case "systemd-system": {
@@ -109,7 +112,7 @@ function adoptOne(unit, deps) {
             must(deps.run, ...systemctl(unit, deps, ["disable", "--now", unit.name]));
             moveFile(unit.path, to);
             deps.run(...systemctl(unit, deps, ["daemon-reload"]));
-            return to;
+            return { movedTo: to };
         }
         case "schtasks": {
             const xml = must(deps.run, "schtasks.exe", ["/Query", "/TN", unit.name, "/XML"]);
@@ -117,7 +120,7 @@ function adoptOne(unit, deps) {
             fs.writeFileSync(to, encodeTaskXml(xml), { mode: 0o600 });
             deps.run("schtasks.exe", ["/End", "/TN", unit.name]);
             must(deps.run, "schtasks.exe", ["/Delete", "/TN", unit.name, "/F"]);
-            return to;
+            return { movedTo: to };
         }
     }
 }
@@ -141,15 +144,15 @@ export function adoptLegacyUnits(units, deps) {
             continue;
         }
         const store = storeFor(unit.kind, deps);
-        let movedTo;
+        let adoptedFields;
         try {
-            movedTo = adoptOne(unit, deps);
+            adoptedFields = adoptOne(unit, deps);
         }
         catch (err) {
             result.failed.push({ unit, error: err.message });
             continue;
         }
-        const adopted = { ...unit, movedTo, adoptedAt: now() };
+        const adopted = { ...unit, ...adoptedFields, adoptedAt: now() };
         const next = [...recordOf(store), adopted];
         try {
             // Record each unit as soon as it is moved, so a failure later in the
@@ -165,7 +168,7 @@ export function adoptLegacyUnits(units, deps) {
                 restoreOne(adopted, deps);
             }
             catch (restoreErr) {
-                rollback = `; putting it back also failed (${restoreErr.message}), its definition is at ${movedTo}`;
+                rollback = `; putting it back also failed (${restoreErr.message}), its definition is at ${adopted.movedTo}`;
             }
             result.failed.push({ unit, error: `could not record the takeover: ${err.message}${rollback}` });
         }
@@ -192,6 +195,8 @@ function restoreOne(unit, deps) {
         case "launchd": {
             if (!unit.path)
                 throw new Error(`no plist path recorded for ${unit.name}`);
+            if (unit.definitionMissing)
+                throw new Error("the original LaunchAgent plist is missing; this unit cannot be restored");
             moveBack(unit, unit.path);
             must(deps.run, "launchctl", ["bootstrap", `gui/${deps.uid}`, unit.path]);
             return;
@@ -216,6 +221,16 @@ function restoreOne(unit, deps) {
             return;
     }
 }
+/** Retire the migratable legacy mesh job and emit the daemon's operator-facing result lines. */
+export function retireLegacyMeshUnits(units, options, deps, log) {
+    const selected = legacyMeshUnitsToRetire(units, options);
+    const result = adoptLegacyUnits(selected, deps);
+    for (const unit of result.adopted)
+        log("info", `retired legacy ${unit.unitId} unit ${unit.name}; hq daemon now owns mesh`);
+    for (const failure of result.failed)
+        log("warn", `could not retire legacy ${failure.unit.unitId} unit ${failure.unit.name}: ${failure.error}`);
+    return result;
+}
 function restoreFrom(record, deps, check, result) {
     const units = readAdoptedUnits(record);
     if (units.length === 0)

package/dist/lib/daemon/run.js

@@ -22,7 +22,7 @@ import { SUPERVISOR_HANDOFF_FLAG, readDaemonFlag } from "./flag.js";
 import { findLegacyUnits, legacyMeshUnitsToRetire, legacyOwnerLookup } from "./legacy.js";
 import { readLegacySyncEnv } from "./legacy-sync-env.js";
 import { acquireDaemonLock, isProcessAlive, processCommandLine, releaseDaemonLock } from "./lock.js";
-import { adoptLegacyUnits } from "./migrate.js";
+import { retireLegacyMeshUnits } from "./migrate.js";
 import { daemonDir as meshDaemonDir, daemonPidPath as meshDaemonPidPath } from "../mesh/live/daemon/paths.js";
 import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
 import { daemonRootRefusal } from "./install.js";
@@ -72,6 +72,17 @@ export function probeLegacyUnits(platform, home) {
         home,
         existsSync: fs.existsSync,
         listDir: (dir) => fs.readdirSync(dir),
+        launchdJobLoaded: (label) => {
+            if (platform !== "darwin")
+                return false;
+            const uid = process.getuid?.() ?? 0;
+            const result = spawnSync("launchctl", ["print", `gui/${uid}/${label}`], {
+                encoding: "utf8",
+                windowsHide: true,
+                timeout: 15_000,
+            });
+            return result.status === 0;
+        },
         windowsTaskExists,
     });
 }
@@ -344,7 +355,12 @@ export async function runDaemon(opts) {
     if (legacyMesh.length > 0) {
         try {
             const uid = process.getuid?.() ?? 0;
-            const result = adoptLegacyUnits(legacyMesh, {
+            retireLegacyMeshUnits(legacyMesh, {
+                platform,
+                managed: opts.managed === true,
+                hosted: opts.host !== undefined,
+                meshEnabled: enabledServices(machineType, initial).includes("mesh"),
+            }, {
                 run: (command, args) => {
                     const r = spawnSync(command, args, { encoding: "utf8", windowsHide: true, timeout: 15_000 });
                     return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
@@ -356,11 +372,7 @@ export async function runDaemon(opts) {
                 systemAdoptedDir: "/var/lib/hq/daemon/adopted",
                 systemRecordPath: "/var/lib/hq/daemon/adopted.json",
                 systemUnitDir: "/etc/systemd/system",
-            });
-            for (const unit of result.adopted)
-                log("info", `retired legacy ${unit.unitId} unit ${unit.name}; hq daemon now owns mesh`);
-            for (const failure of result.failed)
-                log("warn", `could not retire legacy ${failure.unit.unitId} unit ${failure.unit.name}: ${failure.error}`);
+            }, (level, message) => log(level, message));
         }
         catch (err) {
             log("error", `could not retire legacy mesh units: ${err.message}`);

package/dist/lib/daemon/supervisor.js

@@ -28,6 +28,7 @@ export const BACKOFF_MAX_MS = 60_000;
 export const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
 const MESH_OWNER_RECHECK_MS = 15_000;
+const MESH_OWNER_LOG_INTERVAL_MS = 10 * 60_000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
 export const HANDOFF_STAGGER_MS = 15_000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */
@@ -297,11 +298,18 @@ export function createSupervisor(deps) {
             }
             const meshOwnerReason = slot.plan.service === "mesh" ? deps.meshOwnerReason?.() : undefined;
             if (meshOwnerReason) {
+                let lastLoggedReason;
+                let lastLoggedAt = Number.NEGATIVE_INFINITY;
                 const waitForOwner = (reason) => {
                     slot.state.status = "waiting";
                     slot.state.reason = reason;
                     slot.state.nextRunAt = now() + MESH_OWNER_RECHECK_MS;
-                    deps.log("warn", `${reason}; retrying mesh ownership check in ${MESH_OWNER_RECHECK_MS}ms`);
+                    const at = now();
+                    if (reason !== lastLoggedReason || at - lastLoggedAt >= MESH_OWNER_LOG_INTERVAL_MS) {
+                        deps.log("warn", `${reason}; retrying mesh ownership check in ${MESH_OWNER_RECHECK_MS}ms`);
+                        lastLoggedReason = reason;
+                        lastLoggedAt = at;
+                    }
                     slot.timer = setT(() => {
                         slot.timer = undefined;
                         const current = deps.meshOwnerReason?.();

package/dist/lib/lanes/quota.d.ts

@@ -89,6 +89,25 @@ export declare function quotaSignalFromFields(fields: {
 }, model: string | undefined, now: Date): QuotaSignal | null;
 export declare function readQuotaSignal(runDir: string, model: string | undefined, now: Date, workerOutOffset?: number): QuotaSignal | null;
 export declare function recordAccountQuota(hqRoot: string, provider: LaneProvider, accountId: string, signal: QuotaSignal): QuotaState;
+export interface ClearedModelQuotaReset {
+    model: string;
+    quota_reset_at: string;
+}
+export interface AccountQuotaClearResult {
+    all_models_quota_reset_at: string | null;
+    model_quota_resets: ClearedModelQuotaReset[];
+}
+export interface ClearAccountQuotaOptions {
+    /** Clear only this model's reset instead of every per-model reset. */
+    model?: string;
+    /** Clear only marks whose reset time is still ahead of now. */
+    futureOnly?: boolean;
+    now?: Date;
+}
+/** Clear quota reset marks and persist them with the quota file's atomic writer. */
+export declare function clearAccountQuota(hqRoot: string, provider: LaneProvider, accountId: string, options?: ClearAccountQuotaOptions): AccountQuotaClearResult;
+export declare function clearAccountQuotaAfterSuccessfulTurn(hqRoot: string, provider: LaneProvider, accountId: string, model: string, now: Date): AccountQuotaClearResult;
+export declare function clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot: string, provider: LaneProvider, accountId: string, model: string, now: Date): void;
 export interface QuotaBlock {
     blocked: boolean;
     reason?: "account_quota_exhausted" | "account_model_unavailable";

package/dist/lib/lanes/quota.js

@@ -19,6 +19,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { withLaneRecordFileLock } from "./store.js";
 export const QUOTA_STATE_REL = path.join("personal", "lanes", "quota.json");
 export const QUOTA_SCHEMA_VERSION = "hq-lanes-quota.v1";
 /**
@@ -278,40 +279,116 @@ export function readQuotaSignal(runDir, model, now, workerOutOffset = 0) {
     return quotaSignalFromFields(fields, model, now);
 }
 export function recordAccountQuota(hqRoot, provider, accountId, signal) {
-    const state = loadQuotaState(hqRoot);
-    const accounts = state.providers[provider] ?? {};
-    const current = accounts[accountId] ?? { models: {} };
-    const models = { ...current.models };
-    if (signal.model) {
-        const prior = models[signal.model] ?? {};
-        const next = { ...prior };
-        if (signal.needs_credits) {
-            next.needs_credits = true;
-            next.marker = signal.marker ?? `needs credits for ${signal.model}`;
-            delete next.quota_reset_at;
+    return withLaneRecordFileLock(quotaStatePath(hqRoot), () => {
+        const state = loadQuotaState(hqRoot);
+        const accounts = state.providers[provider] ?? {};
+        const current = accounts[accountId] ?? { models: {} };
+        const models = { ...current.models };
+        if (signal.model) {
+            const prior = models[signal.model] ?? {};
+            const next = { ...prior };
+            if (signal.needs_credits) {
+                next.needs_credits = true;
+                next.marker = signal.marker ?? `needs credits for ${signal.model}`;
+                delete next.quota_reset_at;
+            }
+            if (signal.quota_reset_at &&
+                !signal.needs_credits &&
+                shouldReplaceReset(next.quota_reset_at, signal.quota_reset_at)) {
+                next.quota_reset_at = signal.quota_reset_at;
+            }
+            models[signal.model] = next;
         }
-        if (signal.quota_reset_at &&
-            !signal.needs_credits &&
-            shouldReplaceReset(next.quota_reset_at, signal.quota_reset_at)) {
-            next.quota_reset_at = signal.quota_reset_at;
+        const account = { ...current, models };
+        if (signal.account_wide && signal.quota_reset_at) {
+            if (shouldReplaceReset(current.all_models_quota_reset_at, signal.quota_reset_at)) {
+                account.all_models_quota_reset_at = signal.quota_reset_at;
+                account.reset_source = signal.reset_source ?? "provider";
+            }
+            else if (current.all_models_quota_reset_at) {
+                account.all_models_quota_reset_at = current.all_models_quota_reset_at;
+                account.reset_source = current.reset_source ?? "provider";
+            }
         }
-        models[signal.model] = next;
-    }
-    const account = { ...current, models };
-    if (signal.account_wide && signal.quota_reset_at) {
-        if (shouldReplaceReset(current.all_models_quota_reset_at, signal.quota_reset_at)) {
-            account.all_models_quota_reset_at = signal.quota_reset_at;
-            account.reset_source = signal.reset_source ?? "provider";
+        accounts[accountId] = account;
+        state.providers[provider] = accounts;
+        writeQuotaState(hqRoot, state);
+        return state;
+    });
+}
+/** Clear quota reset marks and persist them with the quota file's atomic writer. */
+export function clearAccountQuota(hqRoot, provider, accountId, options = {}) {
+    return withLaneRecordFileLock(quotaStatePath(hqRoot), () => {
+        const cleared = {
+            all_models_quota_reset_at: null,
+            model_quota_resets: [],
+        };
+        const state = loadQuotaState(hqRoot);
+        const account = state.providers[provider]?.[accountId];
+        if (!account)
+            return cleared;
+        const now = options.now ?? new Date();
+        const shouldClear = (reset) => reset !== undefined &&
+            (!options.futureOnly || resetStillAhead(reset, now));
+        let changed = false;
+        const accountWideReset = account.all_models_quota_reset_at;
+        if (shouldClear(accountWideReset)) {
+            cleared.all_models_quota_reset_at = accountWideReset;
+            delete account.all_models_quota_reset_at;
+            delete account.reset_source;
+            changed = true;
+        }
+        const modelNames = options.model === undefined
+            ? Object.keys(account.models).sort()
+            : [options.model];
+        for (const model of modelNames) {
+            const entry = account.models[model];
+            const modelReset = entry?.quota_reset_at;
+            if (!entry || !shouldClear(modelReset))
+                continue;
+            cleared.model_quota_resets.push({
+                model,
+                quota_reset_at: modelReset,
+            });
+            delete entry.quota_reset_at;
+            if (Object.keys(entry).length === 0)
+                delete account.models[model];
+            changed = true;
         }
-        else if (current.all_models_quota_reset_at) {
-            account.all_models_quota_reset_at = current.all_models_quota_reset_at;
-            account.reset_source = current.reset_source ?? "provider";
+        if (!changed)
+            return cleared;
+        if (account.all_models_quota_reset_at === undefined) {
+            delete account.reset_source;
         }
+        const accounts = state.providers[provider];
+        if (account.all_models_quota_reset_at === undefined &&
+            Object.keys(account.models).length === 0) {
+            delete accounts[accountId];
+            if (Object.keys(accounts).length === 0)
+                delete state.providers[provider];
+        }
+        else {
+            accounts[accountId] = account;
+        }
+        writeQuotaState(hqRoot, state);
+        return cleared;
+    });
+}
+export function clearAccountQuotaAfterSuccessfulTurn(hqRoot, provider, accountId, model, now) {
+    return clearAccountQuota(hqRoot, provider, accountId, {
+        model,
+        futureOnly: true,
+        now,
+    });
+}
+export function clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot, provider, accountId, model, now) {
+    try {
+        clearAccountQuotaAfterSuccessfulTurn(hqRoot, provider, accountId, model, now);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`hq lanes: quota cleanup after successful turn failed for provider=${provider} account=${accountId} model=${model}: ${detail}\n`);
     }
-    accounts[accountId] = account;
-    state.providers[provider] = accounts;
-    writeQuotaState(hqRoot, state);
-    return state;
 }
 function shouldReplaceReset(current, incoming) {
     if (!current)

package/dist/lib/lanes/reconcile.js

@@ -27,7 +27,7 @@ import { appendDropboxMessage } from "./dropbox.js";
 import { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG, listHostProcesses, runRunawayToolGuard, RUNAWAY_TOOL_GUARD_FLAG, } from "./runaway-tool-guard.js";
 import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
-import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
+import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { SILENCE_MS, appendWatcherEvent, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
@@ -1299,6 +1299,17 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     }
                     return next;
                 }, deps.dryRun);
+                if (!deps.dryRun &&
+                    result.changed &&
+                    result.record.state === "done" &&
+                    terminalClassification.state === "done" &&
+                    terminalEnvelope?.decision === "done" &&
+                    !quota &&
+                    !providerRejection &&
+                    result.record.account &&
+                    result.record.model) {
+                    clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot, result.record.provider, result.record.account, result.record.model, new Date(nowIso));
+                }
                 if (result.changed) {
                     summary.dead_host.push({
                         id: lane.lane_id,

package/dist/lib/lanes/store.d.ts

@@ -43,6 +43,8 @@ export declare function sanitizeHostComponent(hostname: string): string;
 export declare function mintLaneId(deps?: Pick<StoreDeps, "now" | "hostname"> & Partial<Pick<StoreDeps, "generateLaneUlid">>): string;
 export declare function mintQuestionId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
 export declare function appendCappedHistory<T>(history: readonly T[], entry: T, cap?: number): T[];
+/** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
+export declare function withLaneRecordFileLock<T>(recordPath: string, fn: () => T): T;
 export declare function parseLaneRecord(raw: unknown, filePath?: string): LaneRecord;
 export declare function parseQuestionRecord(raw: unknown, filePath?: string): QuestionRecord;
 /**

package/dist/lib/lanes/store.js

@@ -222,6 +222,10 @@ function withRecordLock(recordPath, deps, fn) {
         }
     }
 }
+/** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
+export function withLaneRecordFileLock(recordPath, fn) {
+    return withRecordLock(recordPath, defaultStoreDeps(), fn);
+}
 function readJsonFile(filePath, deps) {
     let text;
     try {

package/dist/lib/lanes/watcher.js

@@ -40,7 +40,7 @@ import { laneStories, terminalEnvelopeStoryStatus } from "./stories.js";
 import { appendCappedHistory, listQuestionIds, readLane, readQuestion, retryUpdateLane, withLaneHireLocks } from "./store.js";
 import { enforceRegistryApprovalGate } from "./approval-gate.js";
 import { readWorkerRunResult } from "./delivery.js";
-import { applyDefaultQuotaHold, quotaSignalFromFields, readQuotaSignal, recordAccountQuota, } from "./quota.js";
+import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, quotaSignalFromFields, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { PROVIDER_REJECTED_REASON, QUOTA_STATUS, isProviderLoginFailure, providerRejectionDetails, readProviderRejection, } from "./provider-rejection.js";
 import { appendDropboxMessageAtPath, dropboxInboxHasMessages, readToolActivity, toolActivityPath } from "./dropbox.js";
 import { loadLanesConfig, providerProgressEventMinIntervalMs, providerQuotaDefaultHoldMs } from "./config.js";
@@ -445,6 +445,15 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
         }
         return next;
     });
+    if (updated.state === "done" &&
+        effectiveClassification.state === "done" &&
+        effectiveEnvelope?.decision === "done" &&
+        opts.quota == null &&
+        opts.providerRejection == null &&
+        updated.account &&
+        updated.model) {
+        clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot, updated.provider, updated.account, updated.model, new Date(at));
+    }
     notifySlotFreed({
         hqRoot,
         provider: updated.provider,

package/dist/lib/mesh/live/daemon/install.d.ts

@@ -307,6 +307,9 @@ export declare function uninstallDaemonService(opts: {
     unlinkSync?: typeof fs.unlinkSync;
     existsSync?: typeof fs.existsSync;
     deactivate?: (platform: DaemonInstallPlatform, dest: string) => void;
+    /** Service-manager runner for uninstall deactivation (tests inject; never the real binary). */
+    run?: RunCommand;
+    uid?: number;
     /** Windows: schtasks.exe runner (tests inject; never the real binary). */
     schtasks?: SchtasksRunner;
     /** Windows: terminate the recorded daemon pid after `schtasks /End` (tests inject). */

package/dist/lib/mesh/live/daemon/install.js

@@ -22,7 +22,7 @@ import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, verifyHqR
 import { defaultPidLockDeps, pidLockStatus, readPidLock } from "./pid-lock.js";
 import { retireLegacyListen } from "./legacy-listen.js";
 import { readDaemonState } from "./state.js";
-import { activateLaunchd, launchdIsLoaded, launchdPlistProgramArguments, launchdProgramArgumentsDiffer, parseLaunchctlPrintArguments, } from "../../../service-manager/launchd.js";
+import { activateLaunchd, defaultRunCommand, launchdIsLoaded, launchdServiceTarget, launchdPlistProgramArguments, launchdProgramArgumentsDiffer, parseLaunchctlPrintArguments, } from "../../../service-manager/launchd.js";
 import { activateSystemd, systemdIsActive } from "../../../service-manager/systemd.js";
 import { nodeBinaryProblem, preferStableNodeBinary } from "../../../node-binary.js";
 /**
@@ -955,7 +955,18 @@ export function uninstallDaemonService(opts) {
     }
     if (platform === "darwin") {
         if (existsSync(paths.plistPath)) {
-            opts.deactivate?.(platform, paths.plistPath);
+            if (opts.deactivate) {
+                opts.deactivate(platform, paths.plistPath);
+            }
+            else {
+                const run = opts.run ?? defaultRunCommand;
+                const target = launchdServiceTarget(paths.plistPath, opts.uid);
+                const bootout = run("launchctl", ["bootout", target]);
+                if (bootout.status !== 0 && run("launchctl", ["print", target]).status === 0) {
+                    const detail = (bootout.stderr || bootout.stdout).trim();
+                    throw new Error(`launchctl bootout failed for ${target}${detail ? `: ${detail}` : ` (exit ${bootout.status})`}`);
+                }
+            }
             unlinkSync(paths.plistPath);
         }
         return {

package/dist/utils/self-update.js

@@ -131,6 +131,236 @@ function isPathInside(candidate, parent) {
     const relative = path.relative(path.resolve(parent), path.resolve(candidate));
     return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 }
+function readNpmBinMap(packageRoot) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        if (manifest.bin === undefined)
+            return {};
+        const entries = typeof manifest.bin === "string"
+            ? [["hq", manifest.bin]]
+            : manifest.bin && typeof manifest.bin === "object" && !Array.isArray(manifest.bin)
+                ? Object.entries(manifest.bin)
+                : null;
+        if (!entries)
+            return null;
+        const bins = {};
+        for (const [name, target] of entries) {
+            if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\") ||
+                typeof target !== "string" || target.length === 0 || path.isAbsolute(target) ||
+                !isPathInside(path.resolve(packageRoot, target), packageRoot)) {
+                return null;
+            }
+            bins[name] = target;
+        }
+        return bins;
+    }
+    catch {
+        return null;
+    }
+}
+function symlinkTargetIsInsidePackage(linkPath, target, packageRoot) {
+    return isPathInside(path.resolve(path.dirname(linkPath), target), packageRoot);
+}
+function snapshotNpmBinLinks(prefix, packageRoot) {
+    if (process.platform === "win32")
+        return [];
+    const binMap = readNpmBinMap(packageRoot);
+    if (!binMap)
+        return [];
+    const binDirectory = path.join(prefix, "bin");
+    const links = [];
+    for (const name of Object.keys(binMap)) {
+        const linkPath = path.join(binDirectory, name);
+        try {
+            if (!fs.lstatSync(linkPath).isSymbolicLink())
+                continue;
+            const target = fs.readlinkSync(linkPath);
+            const resolved = fs.realpathSync(linkPath);
+            if (!isPathInside(resolved, packageRoot))
+                continue;
+            links.push({ path: linkPath, target });
+        }
+        catch {
+            // A missing or dangling entry was not a working npm bin link to snapshot.
+        }
+    }
+    return links;
+}
+function restoreNpmBinLinks(snapshot) {
+    if (!snapshot.npmBinDirectory || !snapshot.npmBinPackageRoot || !snapshot.npmBinLinks?.length)
+        return true;
+    if (process.platform === "win32")
+        return true;
+    let restored = true;
+    for (const bin of snapshot.npmBinLinks) {
+        if (path.dirname(bin.path) !== snapshot.npmBinDirectory) {
+            reportBinLinkConflict(bin.path, "the saved path is outside the npm bin directory");
+            restored = false;
+            continue;
+        }
+        let existing;
+        let existingTarget;
+        try {
+            existing = fs.lstatSync(bin.path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                reportBinLinkConflict(bin.path, errorMessage(error));
+                restored = false;
+                continue;
+            }
+        }
+        if (existing) {
+            if (!existing.isSymbolicLink()) {
+                reportBinLinkConflict(bin.path, "a regular file owns this command name");
+                restored = false;
+                continue;
+            }
+            const currentTarget = fs.readlinkSync(bin.path);
+            existingTarget = currentTarget;
+            if (!symlinkTargetIsInsidePackage(bin.path, currentTarget, snapshot.npmBinPackageRoot)) {
+                reportBinLinkConflict(bin.path, "the existing symlink points outside hq-cli");
+                restored = false;
+                continue;
+            }
+            try {
+                if (currentTarget === bin.target &&
+                    isPathInside(fs.realpathSync(bin.path), snapshot.npmBinPackageRoot))
+                    continue;
+            }
+            catch {
+                // A dangling link into the package is safe to replace with the snapshot.
+            }
+        }
+        if (!symlinkTargetIsInsidePackage(bin.path, bin.target, snapshot.npmBinPackageRoot)) {
+            reportBinLinkConflict(bin.path, "the saved npm link target is outside the restored hq-cli package");
+            restored = false;
+            continue;
+        }
+        const temporary = `${bin.path}.hq-cli-restore-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            fs.mkdirSync(snapshot.npmBinDirectory, { recursive: true });
+            if (!existing) {
+                // Creating the link directly is deliberately no-clobber: if another
+                // tool claimed the command name after lstat, EEXIST preserves it.
+                fs.symlinkSync(bin.target, bin.path);
+            }
+            else {
+                fs.symlinkSync(bin.target, temporary);
+                const current = fs.lstatSync(bin.path);
+                if (!current.isSymbolicLink() || fs.readlinkSync(bin.path) !== existingTarget) {
+                    throw new Error("the bin entry changed while it was being restored");
+                }
+                fs.renameSync(temporary, bin.path);
+            }
+            try {
+                if (!isPathInside(fs.realpathSync(bin.path), snapshot.npmBinPackageRoot)) {
+                    throw new Error("restored link does not resolve into the restored hq-cli package");
+                }
+            }
+            catch (error) {
+                fs.rmSync(bin.path, { force: true });
+                throw error;
+            }
+        }
+        catch (error) {
+            fs.rmSync(temporary, { force: true });
+            reportBinLinkConflict(bin.path, errorMessage(error));
+            restored = false;
+        }
+    }
+    return restored;
+}
+function reportBinLinkConflict(linkPath, reason) {
+    console.error(chalk.yellow(`⚠ Could not restore hq-cli bin link at ${linkPath}; left it untouched (${reason}).`));
+}
+function reportForeignNpmBin(linkPath, reason) {
+    console.error(chalk.yellow(`⚠ Leaving hq-cli bin entry at ${linkPath} untouched; another tool owns it (${reason}).`));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function verifyOrRepairNpmBins(prefix, packageRoot) {
+    if (process.platform === "win32")
+        return { ok: true };
+    let livePackageRoot;
+    try {
+        livePackageRoot = fs.realpathSync(packageRoot);
+    }
+    catch (error) {
+        return { ok: false, detail: `the installed hq-cli package is missing: ${errorMessage(error)}` };
+    }
+    const bins = readNpmBinMap(livePackageRoot);
+    if (!bins || typeof bins.hq !== "string" || bins.hq.length === 0) {
+        return { ok: false, detail: "the installed hq-cli package does not declare a valid hq bin" };
+    }
+    const binDirectory = path.join(prefix, "bin");
+    for (const [name, target] of Object.entries(bins)) {
+        const linkPath = path.join(binDirectory, name);
+        const expected = path.resolve(livePackageRoot, target);
+        let existing;
+        let existingTarget;
+        try {
+            existing = fs.lstatSync(linkPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                return { ok: false, detail: `could not inspect ${linkPath}: ${errorMessage(error)}` };
+            }
+        }
+        if (existing) {
+            if (!existing.isSymbolicLink()) {
+                if (name === "hq") {
+                    return { ok: false, detail: `cannot repair ${linkPath}: a regular file owns this command name` };
+                }
+                reportForeignNpmBin(linkPath, "a regular file owns this command name");
+                continue;
+            }
+            const currentTarget = fs.readlinkSync(linkPath);
+            existingTarget = currentTarget;
+            if (!symlinkTargetIsInsidePackage(linkPath, currentTarget, livePackageRoot)) {
+                if (name === "hq") {
+                    return { ok: false, detail: `cannot repair ${linkPath}: the existing symlink points outside hq-cli` };
+                }
+                reportForeignNpmBin(linkPath, "the existing symlink points outside hq-cli");
+                continue;
+            }
+            try {
+                if (fs.realpathSync(linkPath) === expected && fs.statSync(linkPath).isFile())
+                    continue;
+            }
+            catch {
+                // Missing and dangling hq-cli links are repaired below.
+            }
+        }
+        const temporary = `${linkPath}.hq-cli-repair-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            fs.mkdirSync(binDirectory, { recursive: true });
+            const targetPath = path.relative(binDirectory, expected);
+            if (!existing) {
+                // A direct symlink create does not replace a file that appeared after
+                // lstat; EEXIST is surfaced as an update failure instead.
+                fs.symlinkSync(targetPath, linkPath);
+            }
+            else {
+                fs.symlinkSync(targetPath, temporary);
+                const current = fs.lstatSync(linkPath);
+                if (!current.isSymbolicLink() || fs.readlinkSync(linkPath) !== existingTarget) {
+                    throw new Error("the bin entry changed while it was being repaired");
+                }
+                fs.renameSync(temporary, linkPath);
+            }
+            if (fs.realpathSync(linkPath) !== expected || !fs.statSync(linkPath).isFile()) {
+                throw new Error("repaired link does not resolve to its declared package bin");
+            }
+        }
+        catch (error) {
+            fs.rmSync(temporary, { force: true });
+            return { ok: false, detail: `could not repair ${linkPath}: ${errorMessage(error)}` };
+        }
+    }
+    return { ok: true };
+}
 function isInsideNodeModules(candidate) {
     const segments = path.resolve(candidate).replace(/\\/g, "/").split("/").filter(Boolean);
     const index = process.platform === "win32"
@@ -159,8 +389,14 @@ function snapshotPathsAreSafe(snapshot) {
         snapshot.movedPath,
         snapshot.resolvedTarget,
         snapshot.publicLinkPath,
+        snapshot.npmBinPackageRoot,
     ].filter((value) => value !== undefined);
-    return paths.every(isInsideNodeModules);
+    if (!paths.every(isInsideNodeModules))
+        return false;
+    if (snapshot.npmBinLinks?.some((bin) => !snapshot.npmBinDirectory || path.dirname(bin.path) !== snapshot.npmBinDirectory ||
+        !isPathInside(bin.path, snapshot.npmBinDirectory)))
+        return false;
+    return true;
 }
 function snapshotInstall(install, renamePath = fs.renameSync) {
     const packageRoot = install.packageRoot;
@@ -200,6 +436,9 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
         const pnpmPublicLinkPath = publicLink?.path ?? (entry.isSymbolicLink() ? packageRoot : undefined);
         if (backupKind === "pnpm-public-link" && !pnpmPublicLinkPath)
             return null;
+        const npmBinLinks = backupKind === "package" && install.manager === "npm" && install.prefix
+            ? snapshotNpmBinLinks(install.prefix, sourcePath)
+            : undefined;
         movedPath = backupKind === "pnpm-public-link" ? pnpmPublicLinkPath : sourcePath;
         backupPath = path.join(path.dirname(movedPath), `.hq-cli-backup-${process.pid}-${randomBytes(8).toString("hex")}`);
         renamePath(movedPath, backupPath);
@@ -215,6 +454,9 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
             publicLinkTarget: backupKind === "pnpm-public-link"
                 ? publicLink?.target ?? symlinkTarget
                 : publicLink?.target,
+            npmBinDirectory: npmBinLinks ? path.join(install.prefix, "bin") : undefined,
+            npmBinPackageRoot: npmBinLinks ? sourcePath : undefined,
+            npmBinLinks,
         };
     }
     catch {
@@ -260,7 +502,7 @@ function restoreInstall(snapshot, renamePath = fs.renameSync) {
             fs.mkdirSync(path.dirname(snapshot.publicLinkPath), { recursive: true });
             fs.symlinkSync(snapshot.publicLinkTarget, snapshot.publicLinkPath, process.platform === "win32" ? "junction" : "dir");
         }
-        return true;
+        return restoreNpmBinLinks(snapshot);
     }
     catch {
         reportFailedRestore(snapshot);
@@ -458,6 +700,11 @@ async function updateAndReexec(argv, flavor, known, deps) {
         else {
             result = runner(plan.cmd, plan.args, updateEnv);
         }
+        if (result.ok && !staged && install.manager === "npm" && install.prefix && install.packageRoot) {
+            const bins = verifyOrRepairNpmBins(install.prefix, install.packageRoot);
+            if (!bins.ok)
+                result = bins;
+        }
         if (!result.ok && installSnapshot) {
             restoredAfterFailure = restoreInstall(installSnapshot, renamePath);
             if (restoredAfterFailure)

package/dist/utils/staged-install.js

@@ -89,7 +89,7 @@ export function stagedNpmInstall(install, version, deps = {}) {
             }
             return { ok: false, detail: `could not move hq-cli ${version} into place: ${message(error)}` };
         }
-        if (!linkBins(prefix, live, readBins(backup), tag)) {
+        if (!linkBins(prefix, live, readBins(backup), tag, rename)) {
             // `hq` does not reach the new package, so put the old one back.
             try {
                 rename(live, staged);
@@ -99,10 +99,10 @@ export function stagedNpmInstall(install, version, deps = {}) {
                 keepBackup = true;
                 return {
                     ok: false,
-                    detail: `could not link hq to hq-cli ${version} or restore the previous install from ${backup} (${message(error)})`,
+                    detail: `could not verify or relink every declared hq-cli bin for ${version}, or restore the previous install from ${backup} (${message(error)})`,
                 };
             }
-            return { ok: false, detail: `could not point ${path.join(prefix, "bin", "hq")} at hq-cli ${version}` };
+            return { ok: false, detail: `could not verify or relink every declared hq-cli bin for ${version}` };
         }
         try {
             postinstall(live);
@@ -136,11 +136,11 @@ export function stagedNpmInstall(install, version, deps = {}) {
  * links already point at the live path. A link into another package, or a
  * regular file (someone's wrapper), is left alone.
  *
- * `hq` is settled first. If it does not resolve to a file, its link is put
- * back as it was, no other bin is touched, and this returns false so the
- * caller can restore the old package.
+ * `hq` must resolve into the live package or the caller restores the old
+ * package. Other declared bins owned by another tool are left alone and warned
+ * about; bins we own or need to create must resolve into the live package.
  */
-function linkBins(prefix, live, previousBins, tag) {
+function linkBins(prefix, live, previousBins, tag, rename) {
     const binDir = path.join(prefix, "bin");
     const ownedByHqCli = (link) => {
         try {
@@ -156,7 +156,7 @@ function linkBins(prefix, live, previousBins, tag) {
         try {
             fs.mkdirSync(binDir, { recursive: true });
             fs.symlinkSync(want, temporary);
-            fs.renameSync(temporary, link);
+            rename(temporary, link);
         }
         catch {
             try {
@@ -185,30 +185,70 @@ function linkBins(prefix, live, previousBins, tag) {
         pointAt(link, want);
     };
     const bins = readBins(live);
-    const hqLink = path.join(binDir, "hq");
-    const hqBefore = symlinkTarget(hqLink);
-    if (bins.hq)
-        linkBin("hq", bins.hq);
-    if (!resolvesToFile(hqLink)) {
-        const hqAfter = symlinkTarget(hqLink);
-        if (hqAfter !== hqBefore) {
-            if (hqBefore === null) {
+    if (typeof bins.hq !== "string" || bins.hq.length === 0)
+        return false;
+    const foreignBins = new Set();
+    for (const [name, target] of Object.entries(bins)) {
+        if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\\"))
+            return false;
+        const targetPath = path.resolve(live, target);
+        if (!targetPath.startsWith(`${path.resolve(live)}${path.sep}`) || !resolvesToFile(targetPath))
+            return false;
+        const link = path.join(binDir, name);
+        try {
+            const existing = fs.lstatSync(link, { throwIfNoEntry: false });
+            if (existing && (!existing.isSymbolicLink() || !ownedByHqCli(link))) {
+                if (name === "hq")
+                    return false;
+                foreignBins.add(name);
+                console.error(`⚠ Leaving hq-cli bin entry at ${link} untouched; another tool owns it.`);
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    const changedBins = [];
+    const linkAndRecord = (name, target) => {
+        const link = path.join(binDir, name);
+        const before = symlinkTarget(link);
+        linkBin(name, target);
+        const after = symlinkTarget(link);
+        if (after !== before)
+            changedBins.push({ link, before });
+    };
+    const rollbackBinChanges = () => {
+        for (const change of changedBins.reverse()) {
+            const current = symlinkTarget(change.link);
+            if (current === null || !ownedByHqCli(change.link))
+                continue;
+            if (change.before === null) {
                 try {
-                    fs.unlinkSync(hqLink);
+                    fs.unlinkSync(change.link);
                 }
                 catch {
-                    // Nothing to undo.
+                    // The staged update still fails; preserve the best-effort rollback result.
                 }
             }
             else {
-                pointAt(hqLink, hqBefore);
+                pointAt(change.link, change.before);
             }
         }
+    };
+    const hqLink = path.join(binDir, "hq");
+    linkAndRecord("hq", bins.hq);
+    if (!resolvesToPackageBin(hqLink, live, bins.hq)) {
+        rollbackBinChanges();
         return false;
     }
     for (const [name, target] of Object.entries(bins)) {
-        if (name !== "hq")
-            linkBin(name, target);
+        if (name === "hq" || foreignBins.has(name))
+            continue;
+        linkAndRecord(name, target);
+        if (!resolvesToPackageBin(path.join(binDir, name), live, target)) {
+            rollbackBinChanges();
+            return false;
+        }
     }
     for (const name of Object.keys(previousBins)) {
         if (name in bins)
@@ -240,6 +280,16 @@ function resolvesToFile(link) {
         return false;
     }
 }
+function resolvesToPackageBin(link, packageRoot, target) {
+    try {
+        return fs.lstatSync(link).isSymbolicLink() &&
+            fs.realpathSync(link) === fs.realpathSync(path.resolve(packageRoot, target)) &&
+            fs.statSync(link).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 function readBins(packageRoot) {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.298.0",
+  "version": "5.299.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {