@indigoai-us/hq-cli 5.345.43 → 5.345.45

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.43",
+  "version": "5.345.45",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {