@indigoai-us/hq-cli 5.345.44 → 5.345.45

package/dist/lib/lanes/story-ledger.d.ts

@@ -24,6 +24,20 @@ export interface StoryLedgerQuestionRef {
     project_id: string;
     story_id: string;
 }
+export interface ProjectFocusOverride {
+    reason: string;
+    by_lane: string;
+    at: string;
+    story: string;
+}
+export declare function readProjectStoryFocusData(hqRoot: string, projectId: string, companySlug?: string): {
+    path: string;
+    metadata: Record<string, unknown>;
+    userStories: Array<Record<string, unknown>>;
+    focusOverrides: ProjectFocusOverride[];
+};
+export declare function appendProjectFocusOverride(hqRoot: string, projectId: string, companySlug: string | undefined, override: ProjectFocusOverride): void;
+export declare function removeProjectFocusOverride(hqRoot: string, projectId: string, companySlug: string | undefined, override: ProjectFocusOverride): void;
 export interface LaneStatusSnapshot {
     schema_version: "hq-lanes-status.v1";
     project_id: string;

package/dist/lib/lanes/story-ledger.js

@@ -11,6 +11,52 @@ const LOCK_RETRY_MS = 10;
 const STORY_STATES = ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
 const MANAGER_OWNED_STATES = new Set(["review", "done", "dropped"]);
 const TERMINAL_STATES = new Set(["done", "failed", "interrupted", "cancelled", "killed"]);
+function projectFocusOverrides(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > 100) {
+        throw new LanesError("project_focus_overrides_invalid", "Project focus_overrides must be an array with at most 100 entries", {});
+    }
+    return value.map((item, index) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} must be an object`, {});
+        }
+        const entry = item;
+        if (["reason", "by_lane", "at", "story"].some((key) => typeof entry[key] !== "string" || !entry[key].trim())) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} is incomplete`, {});
+        }
+        if (!Number.isFinite(Date.parse(entry.at))) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} has an invalid timestamp`, {});
+        }
+        return entry;
+    });
+}
+export function readProjectStoryFocusData(hqRoot, projectId, companySlug) {
+    const ledger = resolveProjectStoryLedger(hqRoot, projectId, companySlug);
+    const parsed = readLedger(ledger);
+    const metadata = parsed.metadata;
+    return {
+        path: ledger.path,
+        metadata: metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)
+            ? metadata
+            : {},
+        userStories: parsed.userStories,
+        focusOverrides: projectFocusOverrides(parsed.focus_overrides),
+    };
+}
+export function appendProjectFocusOverride(hqRoot, projectId, companySlug, override) {
+    updateLedgerAtomically(resolveProjectStoryLedger(hqRoot, projectId, companySlug), (current) => {
+        const existing = projectFocusOverrides(current.focus_overrides);
+        return { ...current, focus_overrides: [...existing, override].slice(-100) };
+    });
+}
+export function removeProjectFocusOverride(hqRoot, projectId, companySlug, override) {
+    updateLedgerAtomically(resolveProjectStoryLedger(hqRoot, projectId, companySlug), (current) => {
+        const remaining = projectFocusOverrides(current.focus_overrides).filter((entry) => entry.reason !== override.reason || entry.by_lane !== override.by_lane ||
+            entry.at !== override.at || entry.story !== override.story);
+        return { ...current, focus_overrides: remaining };
+    });
+}
 export function laneStoryLedgerEnabled(companyUid) {
     return resolveProcessFlagGate(LANE_STORY_LEDGER_FLAG, { fallback: false }, () => false, companyUid);
 }

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

@@ -525,6 +525,13 @@ export interface LaneRecord {
     story_id: string;
     /** Explicit reason a lane was created without a project story. */
     no_story_reason?: string;
+    /** Human-authored focus guard overrides used to launch this lane onto a story. */
+    focus_overrides?: Array<{
+        reason: string;
+        by_lane: string;
+        at: string;
+        story: string;
+    }>;
     /** Last failed story-ledger synchronization, cleared after a successful retry. */
     ledger_sync_error?: string;
     /** Pending question ids owned by this lane. */
@@ -758,8 +765,9 @@ export interface LaneRecord {
     /** Last successful lane_progress mesh delivery, preserved across watcher restarts. */
     last_progress_event_at?: string;
 }
-/** The v1 fields that must exist on every durable lane record (spec §3). */
-export declare const REQUIRED_LANE_RECORD_FIELDS: readonly ["schema_version", "lane_id", "company", "project_id", "story_id", "depth", "senior", "senior_history", "state", "priority", "provider", "host", "version", "created_at", "updated_at", "attribution_history"];
+/** The v1 fields that must exist on every durable lane record (spec §3).
+ * `company` is normalized from absence for pre-attribution legacy records. */
+export declare const REQUIRED_LANE_RECORD_FIELDS: readonly ["schema_version", "lane_id", "project_id", "story_id", "depth", "senior", "senior_history", "state", "priority", "provider", "host", "version", "created_at", "updated_at", "attribution_history"];
 export declare const LANE_WRITERS: readonly ["creator", "command", "watcher", "reconcile", "spawn", "story-ledger"];
 export type LaneWriter = (typeof LANE_WRITERS)[number];
 /** Field ownership at the durable-record mutation boundary (spec §10.1). */

package/dist/lib/lanes/types.js

@@ -215,9 +215,10 @@ export function parseSeniorKind(value) {
         return value;
     throw new LanesError("unknown_senior_kind", `Unknown senior kind ${JSON.stringify(value)}. Accepted: ${SENIOR_KINDS.join(", ")}`, { accepted: [...SENIOR_KINDS], value });
 }
-/** The v1 fields that must exist on every durable lane record (spec §3). */
+/** The v1 fields that must exist on every durable lane record (spec §3).
+ * `company` is normalized from absence for pre-attribution legacy records. */
 export const REQUIRED_LANE_RECORD_FIELDS = [
-    "schema_version", "lane_id", "company", "project_id", "story_id", "depth",
+    "schema_version", "lane_id", "project_id", "story_id", "depth",
     "senior", "senior_history", "state", "priority", "provider", "host",
     "version", "created_at", "updated_at", "attribution_history",
 ];
@@ -225,7 +226,7 @@ export const LANE_WRITERS = ["creator", "command", "watcher", "reconcile", "spaw
 /** Field ownership at the durable-record mutation boundary (spec §10.1). */
 export const LANE_FIELD_WRITERS = {
     schema_version: ["creator"], lane_id: ["creator"], written_by_version: [], owner_written_by_version: [], company: ["creator", "command"], company_history: ["command"],
-    project_id: ["command"], story_id: ["command"], no_story_reason: ["creator", "command"], ledger_sync_error: ["story-ledger"], pending_question_ids: ["story-ledger"], stories: ["creator", "command", "watcher", "reconcile", "spawn"], thread_id: ["creator", "command", "spawn"], mesh_company: ["creator", "command"],
+    project_id: ["command"], story_id: ["command"], no_story_reason: ["creator", "command"], focus_overrides: ["command"], ledger_sync_error: ["story-ledger"], pending_question_ids: ["story-ledger"], stories: ["creator", "command", "watcher", "reconcile", "spawn"], thread_id: ["creator", "command", "spawn"], mesh_company: ["creator", "command"],
     depth: ["command"], senior: ["command"], senior_history: ["command"],
     hire_grant: ["creator", "command"],
     released_hire_grant: ["command"],

package/dist/utils/package-use-lease.d.ts

@@ -48,6 +48,7 @@ export declare function currentPackageUseUpdatePending(): boolean;
 export declare function currentPackageUseUpdateRequested(): boolean;
 export declare const __test__: {
     waitForUpdateRequest: typeof waitForUpdateRequest;
+    setPackageUseLeaseHeartbeatIntervalMs(intervalMs: number): void;
     setCurrentPackageUseLease(lease: PackageUseLease | null): void;
 };
 /**

package/dist/utils/package-use-lease.js

@@ -1,5 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { utimes } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,6 +9,8 @@ const CLI_NAME = "@indigoai-us/hq-cli";
 const UPDATE_REQUEST = "update.pending.json";
 export const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
 const HANDOFF_TIMEOUT_MS = 2_000;
+const PACKAGE_USE_LEASE_HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000;
+let packageUseLeaseHeartbeatIntervalMs = PACKAGE_USE_LEASE_HEARTBEAT_INTERVAL_MS;
 export const PACKAGE_USE_LEASE_PURPOSES = [
     "command",
     "resident-preload",
@@ -180,10 +183,32 @@ export function acquirePackageUseLease(prefix, hqVersion, stateDirectory, purpos
     const leasePath = path.join(directory, `${record.pid}-${record.start_time_ms}.json`);
     const tempPath = `${leasePath}.${Math.random().toString(36).slice(2)}.tmp`;
     let released = false;
+    let heartbeatInFlight = false;
+    let heartbeat = null;
+    const startHeartbeat = () => {
+        heartbeat = setInterval(() => {
+            if (released || heartbeatInFlight)
+                return;
+            heartbeatInFlight = true;
+            const now = new Date();
+            void utimes(leasePath, now, now)
+                .catch((error) => {
+                if (!released) {
+                    process.stderr.write(`hq-cli package-use lease heartbeat failed (${errorLabel(error)})\n`);
+                }
+            })
+                .finally(() => {
+                heartbeatInFlight = false;
+            });
+        }, packageUseLeaseHeartbeatIntervalMs);
+        heartbeat.unref();
+    };
     const release = () => {
         if (released)
             return;
         released = true;
+        if (heartbeat)
+            clearInterval(heartbeat);
         process.removeListener("exit", releaseOnExit);
         try {
             rmSync(leasePath, { force: true });
@@ -204,6 +229,7 @@ export function acquirePackageUseLease(prefix, hqVersion, stateDirectory, purpos
             throw new Error(`Unable to publish the HQ CLI package-use lease (${errorLabel(error)})`, { cause: error });
         }
         if (!exists(requestPath)) {
+            startHeartbeat();
             process.once("exit", releaseOnExit);
             return { leasePath, release };
         }
@@ -409,6 +435,9 @@ export function currentPackageUseUpdateRequested() {
 }
 export const __test__ = {
     waitForUpdateRequest,
+    setPackageUseLeaseHeartbeatIntervalMs(intervalMs) {
+        packageUseLeaseHeartbeatIntervalMs = intervalMs;
+    },
     setCurrentPackageUseLease(lease) {
         currentPackageUseLease = lease;
     },

package/dist/utils/self-update-backoff.d.ts

@@ -0,0 +1,17 @@
+export declare const SELF_UPDATE_FAILURE_BACKOFF_MS: number;
+export interface SelfUpdateFailureRecord {
+    /** Version the failed attempt tried to install. */
+    target: string;
+    /** Epoch milliseconds of the failed attempt. */
+    failedAt: number;
+}
+export interface SelfUpdateBackoff {
+    /** The recorded failure when it is still inside the backoff window, else null. */
+    active(now?: number): SelfUpdateFailureRecord | null;
+    record(target: string, now?: number): void;
+    clear(): void;
+}
+export declare function selfUpdateBackoffPath(homeDir?: string): string;
+/** File-backed backoff under `~/.hq`. Every operation is best-effort. */
+export declare function fileSelfUpdateBackoff(homeDir?: string): SelfUpdateBackoff;
+//# sourceMappingURL=self-update-backoff.d.ts.map

package/dist/utils/self-update-backoff.js

@@ -0,0 +1,73 @@
+/**
+ * Cross-target backoff for automatic CLI self-updates.
+ *
+ * The older loop guard in `version-check.ts` (`markLatestIneffective`) only
+ * suppresses the exact npm `latest` that failed, and only when the version
+ * cache file exists and still names that version. HQ publishes several
+ * releases a day, and the hq-pro "update recommended" path hands the updater a
+ * version that need not match the cache. Either way the next invocation saw a
+ * "new" target and ran the same failing install again, so a broken package
+ * manager made every `hq` command retry the update.
+ *
+ * This record is keyed on the failure itself, not on the target version: after
+ * any failed or ineffective automatic update, automatic updates pause for
+ * {@link SELF_UPDATE_FAILURE_BACKOFF_MS} whatever version is newest. An explicit
+ * `hq rescue` ignores the record and clears it when it succeeds.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const SELF_UPDATE_FAILURE_BACKOFF_MS = 24 * 60 * 60 * 1000;
+export function selfUpdateBackoffPath(homeDir = os.homedir()) {
+    return path.join(homeDir, ".hq", "self-update-backoff.json");
+}
+function readRecord(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof parsed.target !== "string" || typeof parsed.failedAt !== "number")
+            return null;
+        if (!Number.isFinite(parsed.failedAt))
+            return null;
+        return { target: parsed.target, failedAt: parsed.failedAt };
+    }
+    catch {
+        return null;
+    }
+}
+/** File-backed backoff under `~/.hq`. Every operation is best-effort. */
+export function fileSelfUpdateBackoff(homeDir) {
+    const file = selfUpdateBackoffPath(homeDir);
+    return {
+        active(now = Date.now()) {
+            const record = readRecord(file);
+            if (!record)
+                return null;
+            const age = now - record.failedAt;
+            // A record from the future (clock moved back) is treated as fresh only
+            // within one window, so a bad clock cannot disable updates forever.
+            if (age < -SELF_UPDATE_FAILURE_BACKOFF_MS)
+                return null;
+            return age <= SELF_UPDATE_FAILURE_BACKOFF_MS ? record : null;
+        },
+        record(target, now = Date.now()) {
+            try {
+                fs.mkdirSync(path.dirname(file), { recursive: true });
+                const tmp = `${file}.${process.pid}.tmp`;
+                fs.writeFileSync(tmp, `${JSON.stringify({ target, failedAt: now })}\n`);
+                fs.renameSync(tmp, file);
+            }
+            catch {
+                // A write failure only means the next invocation may retry once.
+            }
+        },
+        clear() {
+            try {
+                fs.rmSync(file, { force: true });
+            }
+            catch {
+                // Best-effort.
+            }
+        },
+    };
+}
+//# sourceMappingURL=self-update-backoff.js.map

package/dist/utils/self-update.d.ts

@@ -59,6 +59,7 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import { probePnpmVersion, type RunningInstall, type UpdateResult } from "./version-gate.js";
+import { type SelfUpdateBackoff } from "./self-update-backoff.js";
 import { type RestartDaemonResult } from "../lib/mesh/live/daemon/install.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
@@ -167,6 +168,12 @@ export interface SelfUpdateDeps {
      * stops auto-retrying it. Defaults to {@link markLatestIneffective}.
      */
     markIneffective?: (version: string) => void;
+    /**
+     * Cross-target failure backoff. After a failed or ineffective automatic
+     * update, automatic updates pause for 24 hours. Defaults to a record under
+     * `~/.hq` (see `self-update-backoff.ts`).
+     */
+    backoff?: SelfUpdateBackoff;
     /**
      * Whether a human is watching this invocation. Defaults to "stderr is a TTY",
      * which is false for exactly the callers that must not replace the CLI

package/dist/utils/self-update.js

@@ -69,6 +69,7 @@ import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, bu
 import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
+import { fileSelfUpdateBackoff } from "./self-update-backoff.js";
 import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
 import { createCurrentPackageUseLeaseHandoff, PACKAGE_USE_LEASE_HANDOFF_ENV, releaseCurrentPackageUseLease, } from "./package-use-lease.js";
 /**
@@ -847,9 +848,44 @@ function sleepForRetry(ms) {
 }
 async function updateAndReexec(argv, flavor, known, deps) {
     const env = deps.env ?? process.env;
+    // Recursion guard: a process started by an update (the re-exec'd command, a
+    // package-manager lifecycle script, or anything those spawn) carries this
+    // marker and must never start another update.
     if (env[REEXEC_GUARD_ENV] === "1" || env.HQ_NO_UPDATE_CHECK === "1") {
         return { action: "skipped" };
     }
+    // A failed automatic update pauses automatic updates for every target, not
+    // just the one that failed: HQ ships several releases a day, so a target-keyed
+    // guard let each new release re-run the same broken install on every
+    // command. `hq rescue` is an explicit request and ignores the backoff.
+    const backoff = deps.backoff ?? fileSelfUpdateBackoff(deps.homeDir);
+    const explicit = flavor.noun === "rescue";
+    if (!explicit && backoff.active()) {
+        return { action: "skipped" };
+    }
+    let outcome;
+    try {
+        outcome = await attemptUpdateAndReexec(argv, flavor, known, deps, env);
+    }
+    catch (error) {
+        if (known)
+            backoff.record(known);
+        else
+            backoff.record("unknown");
+        throw error;
+    }
+    if (outcome.action === "update-failed" || outcome.action === "update-ineffective") {
+        backoff.record(outcome.latest ?? known ?? "unknown");
+    }
+    else if (outcome.action === "updated" ||
+        outcome.action === "reexec" ||
+        outcome.action === "updated-no-reexec" ||
+        outcome.action === "current") {
+        backoff.clear();
+    }
+    return outcome;
+}
+async function attemptUpdateAndReexec(argv, flavor, known, deps, env) {
     const latest = known ?? (await (deps.fetchLatest ?? fetchLatestVersion)());
     if (!latest)
         return { action: "skipped" };

package/dist/utils/vault-api.d.ts

@@ -77,7 +77,39 @@ export declare function getCompanyUid(token: string, companySlug: string | undef
 baseUrl?: string, options?: {
     allowOfflineScopeFallback?: boolean;
 }): Promise<string>;
-export declare function resolveCallerPersonUid(token: string, baseUrl?: string): Promise<string>;
+/**
+ * The `agt_*` uid an agent machine token names, or null for any other token.
+ * An agent ID token carries `custom:entityType=agent` and
+ * `custom:entityUid=agt_*`; a person token carries neither. The claim is read
+ * without verification and only picks which identity the CLI resolves locally;
+ * hq-pro verifies the token and authorizes every request itself.
+ */
+export declare function agentUidFromToken(token: string): string | null;
+export type CallerIdentity = {
+    kind: 'person';
+    uid: string;
+} | {
+    kind: 'agent';
+    uid: string;
+};
+/**
+ * Resolve the caller's own principal uid. An agent machine token resolves to
+ * its `agt_*` uid with no network call (agents have no person entity); any
+ * other token resolves to its canonical `prs_*` uid exactly as
+ * {@link resolveCallerPersonUid} does. Use this where the server accepts an
+ * agent principal; use `resolveCallerPersonUid` where only a person can act.
+ */
+export declare function resolveCallerUid(token: string, baseUrl?: string): Promise<CallerIdentity>;
+/** Thrown when a person-only command runs under an agent machine identity. */
+export declare function agentIdentityUnsupportedError(agentUid: string, command?: string): Error;
+/**
+ * Resolve the caller's canonical `prs_*` uid for a person-only command. An
+ * agent machine token fails fast with a clear "not available to agent
+ * identities" error instead of the person lookup's "No person entity found".
+ */
+export declare function resolveCallerPersonUid(token: string, baseUrl?: string, opts?: {
+    command?: string;
+}): Promise<string>;
 export declare function getEntityUid(token: string, opts: {
     personal?: boolean;
     companySlug?: string;

package/dist/utils/vault-api.js

@@ -7,6 +7,7 @@ import { markExpectedUserError } from './expected-cli-error.js';
 import { redactErrorText } from './redact-error-text.js';
 import { isSecretLoadUnavailable, isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError } from './secret-load-availability.js';
 import { readCachedScopeUid, writeCachedScopeUid } from './secrets-cache.js';
+import { peekIdToken } from './id-token.js';
 /**
  * Identity / company resolution lookups must never hang forever. These small
  * GETs run BEFORE a command does its real work (e.g. `hq secrets env` resolves
@@ -679,9 +680,57 @@ baseUrl, options = {}) {
         return cachedUid;
     }
 }
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
+/**
+ * The `agt_*` uid an agent machine token names, or null for any other token.
+ * An agent ID token carries `custom:entityType=agent` and
+ * `custom:entityUid=agt_*`; a person token carries neither. The claim is read
+ * without verification and only picks which identity the CLI resolves locally;
+ * hq-pro verifies the token and authorizes every request itself.
+ */
+export function agentUidFromToken(token) {
+    const claims = peekIdToken(token);
+    const entityUid = claims['custom:entityUid'];
+    if (typeof entityUid !== 'string' || !AGENT_UID_PATTERN.test(entityUid))
+        return null;
+    const entityType = claims['custom:entityType'];
+    if (entityType !== undefined && entityType !== 'agent')
+        return null;
+    return entityUid;
+}
+/**
+ * Resolve the caller's own principal uid. An agent machine token resolves to
+ * its `agt_*` uid with no network call (agents have no person entity); any
+ * other token resolves to its canonical `prs_*` uid exactly as
+ * {@link resolveCallerPersonUid} does. Use this where the server accepts an
+ * agent principal; use `resolveCallerPersonUid` where only a person can act.
+ */
+export async function resolveCallerUid(token, baseUrl) {
+    const agentUid = agentUidFromToken(token);
+    if (agentUid)
+        return { kind: 'agent', uid: agentUid };
+    return { kind: 'person', uid: await lookupCallerPersonUid(token, baseUrl) };
+}
+/** Thrown when a person-only command runs under an agent machine identity. */
+export function agentIdentityUnsupportedError(agentUid, command) {
+    const what = command ? `\`${command}\`` : 'This command';
+    return markExpectedUserError(new Error(`${what} is not available to agent identities (signed in as agent ${agentUid}). ` +
+        'It acts for a person; run it from a person\'s HQ login.'));
+}
+/**
+ * Resolve the caller's canonical `prs_*` uid for a person-only command. An
+ * agent machine token fails fast with a clear "not available to agent
+ * identities" error instead of the person lookup's "No person entity found".
+ */
+export async function resolveCallerPersonUid(token, baseUrl, opts = {}) {
+    const agentUid = agentUidFromToken(token);
+    if (agentUid)
+        throw agentIdentityUnsupportedError(agentUid, opts.command);
+    return lookupCallerPersonUid(token, baseUrl);
+}
 // Same selection rule as the backend's `resolveCallerPersonUid`: ascending by
 // createdAt, tie-break by uid ascending. Returns the `prs_*` UID.
-export async function resolveCallerPersonUid(token, baseUrl) {
+async function lookupCallerPersonUid(token, baseUrl) {
     const res = await vaultApiFetch({
         token,
         path: '/entity/by-type/person',
@@ -708,16 +757,17 @@ export async function resolveCallerPersonUid(token, baseUrl) {
     });
     return persons[0].uid;
 }
-// Resolves the scope UID (cmp_* or prs_*) for a secrets command. Precedence:
-// `--personal` → caller's canonical person entity; else `--company <slug>` →
+// Resolves the scope UID (cmp_*, prs_* or agt_*) for a secrets command.
+// Precedence: `--personal` → caller's own scope (canonical person entity, or an
+// agent's own `agt_*` vault, which hq-pro treats as agent-self scope); else `--company <slug>` →
 // resolved company UID; else fallback to single active company membership.
 export async function getEntityUid(token, opts, options = {}) {
     if (opts.personal) {
         if (!options.allowOfflineScopeFallback)
-            return resolveCallerPersonUid(token);
+            return (await resolveCallerUid(token)).uid;
         const principalUid = cognitoCachePrincipalUid(token);
         try {
-            const uid = await resolveCallerPersonUid(token);
+            const { uid } = await resolveCallerUid(token);
             if (principalUid)
                 writeCachedScopeUid("personal", principalUid, uid);
             return uid;

package/dist/utils/version-gate.d.ts

@@ -47,6 +47,19 @@ export interface VersionCheckResponse {
     downloadUrl?: string;
     message?: string;
 }
+/**
+ * Environment for every package-manager child an update starts.
+ *
+ * - The recursion guard stops anything the install runs (lifecycle scripts,
+ *   a postinstall that calls `hq`) from starting a second update.
+ * - The Corepack settings keep an update from changing the user's package
+ *   manager setup. With `COREPACK_DEFAULT_TO_LATEST` unset, Corepack resolves a
+ *   missing default from the registry's newest release and writes it to its
+ *   global lastKnownGood file, which moved users from pnpm 10 to pnpm 12.
+ *   Project selection and auto-pinning are off so the caller's working
+ *   directory cannot pick, or be rewritten with, a package-manager version.
+ */
+export declare function packageManagerChildEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
 /**
  * Whether the running package lives inside a pnpm-managed **global** install.

package/dist/utils/version-gate.js

@@ -55,7 +55,30 @@ export function getVersionGatePhase() {
     return currentVersionGatePhase;
 }
 function isOptedOut() {
-    return process.env.HQ_NO_UPDATE_CHECK === "1";
+    // A process started by an update (re-exec, package-manager lifecycle script)
+    // carries the recursion guard and must never start another install.
+    return process.env.HQ_NO_UPDATE_CHECK === "1" || process.env[UPDATE_RECURSION_GUARD_ENV] === "1";
+}
+/**
+ * Environment for every package-manager child an update starts.
+ *
+ * - The recursion guard stops anything the install runs (lifecycle scripts,
+ *   a postinstall that calls `hq`) from starting a second update.
+ * - The Corepack settings keep an update from changing the user's package
+ *   manager setup. With `COREPACK_DEFAULT_TO_LATEST` unset, Corepack resolves a
+ *   missing default from the registry's newest release and writes it to its
+ *   global lastKnownGood file, which moved users from pnpm 10 to pnpm 12.
+ *   Project selection and auto-pinning are off so the caller's working
+ *   directory cannot pick, or be rewritten with, a package-manager version.
+ */
+export function packageManagerChildEnv(base = process.env) {
+    return {
+        ...base,
+        [UPDATE_RECURSION_GUARD_ENV]: "1",
+        COREPACK_DEFAULT_TO_LATEST: "0",
+        COREPACK_ENABLE_PROJECT_SPEC: "0",
+        COREPACK_ENABLE_AUTO_PIN: "0",
+    };
 }
 function findCliPackageRoot(startDir) {
     let dir = startDir;
@@ -608,6 +631,7 @@ export function pnpmUpdateEnv(install, base = process.env) {
         // project, which can silently switch the update subprocess to that version.
         COREPACK_ENABLE_PROJECT_SPEC: "0",
         COREPACK_DEFAULT_TO_LATEST: "0",
+        COREPACK_ENABLE_AUTO_PIN: "0",
     };
     if (!base.PNPM_HOME)
         result.PNPM_HOME = home;
@@ -723,10 +747,8 @@ export function probePnpmVersion(cmd, args, env, cwd) {
 export function performPnpmUpdate(install, runner = runUpdateCommand, env = process.env, probe = probePnpmVersion) {
     const cwd = mkdtempSync(path.join(os.tmpdir(), "hq-cli-pnpm-update-"));
     const updateEnv = {
-        ...env,
-        COREPACK_ENABLE_PROJECT_SPEC: "0",
+        ...packageManagerChildEnv(env),
         COREPACK_ENABLE_STRICT: "0",
-        COREPACK_DEFAULT_TO_LATEST: "0",
         npm_config_manage_package_manager_versions: "false",
     };
     try {
@@ -1125,6 +1147,14 @@ export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true
     };
 }
 export function runSupervisedUpdateCommand(cmd, args, output, env, cwd) {
+    // This process was itself started by an update. Starting another install
+    // from here is how one failed update turns into a process storm, so refuse.
+    if (process.env[UPDATE_RECURSION_GUARD_ENV] === "1") {
+        const detail = "refusing to start a package-manager install from inside another hq update " +
+            `(${UPDATE_RECURSION_GUARD_ENV}=1 is set)`;
+        console.error(chalk.yellow(`hq: ${detail}.`));
+        return { ok: false, code: "EHQUPDATERECURSION", detail };
+    }
     try {
         const plan = buildSpawnPlan(cmd, args);
         const timeoutMs = updateTimeoutMs(env);
@@ -1147,7 +1177,7 @@ export function runSupervisedUpdateCommand(cmd, args, output, env, cwd) {
             }),
         ], inOwnProcessGroup({
             stdio: output.stdio,
-            ...(env ? { env } : {}),
+            env: packageManagerChildEnv(env ?? process.env),
             ...(cwd ? { cwd } : {}),
         }));
         // spawnSync reports a missing executable via `error`, not a throw.

package/package.json

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