@indigoai-us/hq-cli 5.103.1 → 5.103.2

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.103.2] — 2026-08-19
+
 ## [5.103.1] — 2026-08-18
 
 ### Fixed

package/dist/commands/integrations-api.d.ts

@@ -206,6 +206,25 @@ export interface ConnectionAccess {
         grantedAt: string;
     }>;
 }
+export interface PendingApproval {
+    queueId: string;
+    connectionId: string;
+    provider: string;
+    /** Gateway tool (…mcp.tools.call). */
+    toolName: string;
+    /** Concrete app tool the caller named, when carried by the queued call. */
+    requestedTool?: string | null;
+    requestedBy: string;
+    requestedByName?: string | null;
+    createdAt: string;
+    expiresAt: string;
+}
+/**
+ * Live open-approval list, read from hq-pro's confirm-queue state (not the
+ * audit feed). Unlike the audit-derived reconstruction this replaces, a call
+ * that was approved/rejected/expired no longer appears here.
+ */
+export declare function fetchPendingApprovals(token: string, companyUid: string): Promise<PendingApproval[]>;
 export declare function getConnectionAccess(token: string, companyUid: string, connectionId: string): Promise<ConnectionAccess>;
 export declare function mutateConnectionAccess(token: string, companyUid: string, action: "grant" | "revoke", input: {
     connectionId: string;

package/dist/commands/integrations-api.js

@@ -110,6 +110,22 @@ export async function updateGovernance(token, companyUid, input) {
         await raiseForResponse(res, "Failed to update the app's settings");
     return (await res.json());
 }
+/**
+ * Live open-approval list, read from hq-pro's confirm-queue state (not the
+ * audit feed). Unlike the audit-derived reconstruction this replaces, a call
+ * that was approved/rejected/expired no longer appears here.
+ */
+export async function fetchPendingApprovals(token, companyUid) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/pending",
+        query: { companyUid },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to list pending approvals");
+    const body = (await res.json());
+    return body.pending ?? [];
+}
 export async function getConnectionAccess(token, companyUid, connectionId) {
     const res = await vaultApiFetch({
         token,

package/dist/commands/integrations-connect.js

@@ -25,6 +25,24 @@ import { completeOAuth, discoverDocs, installIntegration, listCatalog, pullBluep
 import { startLoopbackListener } from "./integrations-oauth.js";
 /** hq-pro's machine code for "this endpoint needs a browser sign-in". */
 const OAUTH_REQUIRED_CODE = "INTEGRATION_FACTORY_OAUTH_REQUIRED";
+/**
+ * A server-authoritative "this endpoint is OAuth-protected, run the browser
+ * sign-in instead" signal, in EITHER of the two shapes hq-pro emits it:
+ *
+ *   - the catalog/discovery install path returns the
+ *     `INTEGRATION_FACTORY_OAUTH_REQUIRED` code, and
+ *   - the direct-MCP install path returns `DIRECT_MCP_AUTH_REJECTED` with
+ *     `oauthProtected: true`.
+ *
+ * Keying off only the code left the direct-MCP path (e.g. `--mcp-url` against
+ * a sign-in server, or a bare-domain OAuth app) surfacing the raw
+ * "uses OAuth sign-in rather than a pasted access key" error instead of
+ * transparently switching to the sign-in flow.
+ */
+function isOAuthRequiredError(err) {
+    return (err instanceof IntegrationsCliError &&
+        (err.code === OAUTH_REQUIRED_CODE || err.oauthProtected === true));
+}
 /**
  * hq-pro will not take our loopback callback, for either of the two reasons it
  * can refuse one:
@@ -204,20 +222,40 @@ async function resolveTarget(token, companyUid, app, opts) {
         // authClass, both of which make the connect cleaner than a raw domain
         // lookup. Missing it is fine — the domain path still works.
         const match = await findCatalogEntry(token, companyUid, app);
-        if (match?.entryId) {
-            return {
-                ref: { catalogEntryId: match.entryId },
-                ...(match.authClass ? { authClass: match.authClass } : {}),
-                label: match.name || app,
-            };
-        }
+        return catalogEntryToTarget(match, { ref: { domain: app }, label: app });
+    }
+    // A bare name (`notion`, `atlassian`) is how the catalog reads to a person —
+    // the rows are titled `notion.com`, `atlassian.com`. Resolve it to that row
+    // (by its registrable label / provider / display name) so `connect notion`
+    // is `connect notion.com`. The match also carries the authClass, so an OAuth
+    // app routes to sign-in instead of a doomed key install. Ambiguous or
+    // unmatched → fall back to the server-side query resolver.
+    const named = await findCatalogEntryByName(token, companyUid, app);
+    if (named) {
+        return catalogEntryToTarget(named, { ref: { query: app }, label: app });
+    }
+    return { ref: { query: app }, label: app };
+}
+/**
+ * Turn a matched catalog entry into a connect target, preferring its opaque
+ * entryId (the cleanest handle) and otherwise its domain. `fallback` is used
+ * verbatim when there was no catalog match at all.
+ */
+function catalogEntryToTarget(match, fallback) {
+    if (!match)
+        return fallback;
+    if (match.entryId) {
         return {
-            ref: { domain: app },
-            ...(match?.authClass ? { authClass: match.authClass } : {}),
-            label: match?.name || app,
+            ref: { catalogEntryId: match.entryId },
+            ...(match.authClass ? { authClass: match.authClass } : {}),
+            label: match.name || fallback.label,
         };
     }
-    return { ref: { query: app }, label: app };
+    return {
+        ref: { domain: match.domain },
+        ...(match.authClass ? { authClass: match.authClass } : {}),
+        label: match.name || fallback.label,
+    };
 }
 /** Best-effort catalog lookup by domain; never fails the connect. */
 async function findCatalogEntry(token, companyUid, domain) {
@@ -232,6 +270,41 @@ async function findCatalogEntry(token, companyUid, domain) {
         return null;
     }
 }
+/**
+ * The registrable label of a domain — its first dot-separated segment
+ * (`notion.com` → `notion`, `linear.app` → `linear`). This is the short name a
+ * person types for a catalog app.
+ */
+function domainLabel(domain) {
+    return domain.trim().toLowerCase().split(".")[0] ?? "";
+}
+/**
+ * Best-effort resolution of a bare name to a single catalog entry. Matches the
+ * entry's registrable domain label (`notion` → `notion.com`) or an exact
+ * display-name. Returns null when nothing matches OR when more than one DISTINCT
+ * app matches — an ambiguous short name must not silently connect the wrong app,
+ * so it falls back to the server-side query resolver. Never throws: the catalog
+ * is an optimization, not the source of truth.
+ */
+async function findCatalogEntryByName(token, companyUid, name) {
+    try {
+        const want = name.trim().toLowerCase();
+        if (!want)
+            return null;
+        const entries = await listCatalog(token, companyUid, { query: name, limit: 20 });
+        const matches = entries.filter((entry) => domainLabel(entry.domain) === want ||
+            entry.name?.trim().toLowerCase() === want);
+        if (matches.length === 0)
+            return null;
+        // Collapse rows that point at the same app (same domain) before deciding
+        // ambiguity, so one app surfaced twice is still an unambiguous match.
+        const distinct = new Map(matches.map((m) => [m.domain.trim().toLowerCase(), m]));
+        return distinct.size === 1 ? [...distinct.values()][0] : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Run the browser sign-in and finish the install.
  *
@@ -507,7 +580,7 @@ export function registerConnectCommands(integrations) {
             // Server-authoritative detection: the endpoint turned out to be
             // OAuth-protected, so run the browser flow instead of making the
             // caller re-issue the command with --auth oauth.
-            if (err instanceof IntegrationsCliError && err.code === OAUTH_REQUIRED_CODE) {
+            if (isOAuthRequiredError(err)) {
                 const result = await connectViaOAuth(token, companyUid, target, opts);
                 if (result)
                     reportInstall(result, opts);
@@ -570,7 +643,7 @@ export function registerConnectCommands(integrations) {
             reportInstall(await completeCredentialIfNeeded(token, companyUid, target, opts, result), opts);
         }
         catch (err) {
-            if (err instanceof IntegrationsCliError && err.code === OAUTH_REQUIRED_CODE) {
+            if (isOAuthRequiredError(err)) {
                 const result = await connectViaOAuth(token, companyUid, target, opts);
                 if (result)
                     reportInstall(result, opts);

package/dist/commands/integrations-core.d.ts

@@ -120,10 +120,20 @@ export declare class IntegrationsCliError extends Error {
     readonly code?: string;
     /** HTTP status the failure came back with, when it came from a response. */
     readonly status?: number;
+    /**
+     * hq-pro's signal that the endpoint is OAuth-protected, carried on some
+     * auth-rejection bodies (e.g. `DIRECT_MCP_AUTH_REJECTED`). It is a SECOND,
+     * code-independent way to reach the sign-in flow: the direct-MCP install
+     * path reports OAuth via this flag rather than the `INTEGRATION_FACTORY_
+     * OAUTH_REQUIRED` code, so a connect that keys off only the code would
+     * surface the error instead of switching to the browser sign-in.
+     */
+    readonly oauthProtected?: boolean;
     constructor(message: string, opts?: {
         expected?: boolean;
         code?: string;
         status?: number;
+        oauthProtected?: boolean;
     });
 }
 /**
@@ -204,6 +214,15 @@ export declare function callGateway(token: string, params: Record<string, unknow
  * to the raw result when the shape differs.
  */
 export declare function unwrapGatewayResult(result: unknown): unknown;
+/**
+ * True when a tool result is an MCP *tool error* (`isError: true`). The flag
+ * lives on the OUTER gateway result alongside `content`, so it must be read
+ * from the raw `message.result` BEFORE `unwrapGatewayResult` strips the
+ * envelope down to the inner text. A failed tool call otherwise prints its
+ * error payload and still exits 0 — indistinguishable from success to any
+ * script (or agent) driving the gateway.
+ */
+export declare function gatewayResultIsError(result: unknown): boolean;
 interface QueuedOutcome {
     queuedForApproval: true;
     queueId: string;

package/dist/commands/integrations-core.js

@@ -28,6 +28,15 @@ export class IntegrationsCliError extends Error {
     code;
     /** HTTP status the failure came back with, when it came from a response. */
     status;
+    /**
+     * hq-pro's signal that the endpoint is OAuth-protected, carried on some
+     * auth-rejection bodies (e.g. `DIRECT_MCP_AUTH_REJECTED`). It is a SECOND,
+     * code-independent way to reach the sign-in flow: the direct-MCP install
+     * path reports OAuth via this flag rather than the `INTEGRATION_FACTORY_
+     * OAUTH_REQUIRED` code, so a connect that keys off only the code would
+     * surface the error instead of switching to the browser sign-in.
+     */
+    oauthProtected;
     constructor(message, opts = {}) {
         super(message);
         this.name = "IntegrationsCliError";
@@ -36,6 +45,8 @@ export class IntegrationsCliError extends Error {
             this.code = opts.code;
         if (opts.status !== undefined)
             this.status = opts.status;
+        if (opts.oauthProtected !== undefined)
+            this.oauthProtected = opts.oauthProtected;
     }
 }
 /**
@@ -161,6 +172,7 @@ export async function raiseForResponse(res, fallback) {
         expected: isClientError(res.status),
         status: res.status,
         ...(body.code ? { code: body.code } : {}),
+        ...(body.oauthProtected === true ? { oauthProtected: true } : {}),
     });
 }
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
@@ -305,6 +317,19 @@ export function unwrapGatewayResult(result) {
     }
     return result;
 }
+/**
+ * True when a tool result is an MCP *tool error* (`isError: true`). The flag
+ * lives on the OUTER gateway result alongside `content`, so it must be read
+ * from the raw `message.result` BEFORE `unwrapGatewayResult` strips the
+ * envelope down to the inner text. A failed tool call otherwise prints its
+ * error payload and still exits 0 — indistinguishable from success to any
+ * script (or agent) driving the gateway.
+ */
+export function gatewayResultIsError(result) {
+    return (!!result &&
+        typeof result === "object" &&
+        result.isError === true);
+}
 export function queuedOutcome(payload) {
     if (payload &&
         typeof payload === "object" &&

package/dist/commands/integrations-manage.js

@@ -17,7 +17,7 @@ import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
 import { IntegrationsCliError, bareProvider, fetchAdminSurface, printJson, resolveConnection, selectConnection, } from "./integrations-core.js";
-import { getConnectionAccess, mutateConnectionAccess, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
+import { fetchPendingApprovals, getConnectionAccess, mutateConnectionAccess, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
 const WRITE_POLICIES = ["auto-allow", "confirm", "deny"];
 const PERMISSIONS = ["read", "write", "admin"];
 /** Plain-English gloss for each write policy, used in every policy readout. */
@@ -99,7 +99,11 @@ function printAccess(access) {
     console.log(`${chalk.bold(access.provider)}  ${chalk.dim(`shared: ${mode}`)}`);
     console.log(chalk.dim(`  connected by ${access.creator.name ?? access.creator.uid}`));
     if (access.entries.length === 0) {
-        console.log(chalk.dim("  No individual grants."));
+        // "Individual shares" — not "grants" — so this never reads as contradicting
+        // `hq integrations grants`. This list is who the connection is SHARED with
+        // (who may use the app at all); `grants` is the separate per-tool
+        // authorization for change-making tools.
+        console.log(chalk.dim("  No individual shares (per-tool authorization is `hq integrations grants`)."));
     }
     for (const entry of access.entries) {
         console.log(`  ${describePrincipal(entry)}  ${chalk.dim(entry.permission)}`);
@@ -200,7 +204,7 @@ export function registerManageCommands(integrations) {
     });
     integrations
         .command("grants [app]")
-        .description("Show who may run an app's change-making tools without approval")
+        .description("Show who is authorized to run an app's change-making tools")
         .option("--company <slug>", "Company slug")
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
@@ -215,7 +219,7 @@ export function registerManageCommands(integrations) {
             return;
         }
         if (grants.length === 0) {
-            console.log("No per-tool exceptions — this app follows its overall approval setting.");
+            console.log("No per-tool authorization set — the app's overall sharing decides who may run its tools.");
             return;
         }
         for (const grant of grants) {
@@ -224,6 +228,15 @@ export function registerManageCommands(integrations) {
                 console.log(`  ${describePrincipal(entry)}  ${chalk.dim(entry.permission)}`);
             }
         }
+        // Authorization is not approval. A grant here says WHO may invoke the
+        // tool; whether that invocation runs immediately or waits for an owner is
+        // the connection's `policy` (confirm vs auto-allow). Saying so stops this
+        // list from reading as "these people bypass approval" — they don't unless
+        // the policy is auto-allow.
+        const policy = connection.writePolicy;
+        console.log(chalk.dim(policy === "auto-allow"
+            ? "\nApproval: this app is set to auto-allow, so authorized calls run immediately (`hq integrations policy`)."
+            : "\nApproval is separate: authorized change-making calls still follow this app's policy (`hq integrations policy`)."));
     });
     /*
      * grant / ungrant are read-modify-write: hq-pro's PATCH REPLACES the whole
@@ -231,11 +244,11 @@ export function registerManageCommands(integrations) {
      */
     integrations
         .command("grant [app]")
-        .description("Let someone run one of an app's change-making tools without approval")
+        .description("Authorize someone to run one of an app's change-making tools")
         .option("--company <slug>", "Company slug")
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
-        .requiredOption("--tool <name>", "The tool to allow")
+        .requiredOption("--tool <name>", "The tool to authorize")
         .requiredOption("--to <principal>", "Email, uid, or `everyone`")
         .option("--permission <level>", "read, write, or admin", "write")
         .option("--json", "Machine-readable output")
@@ -266,15 +279,15 @@ export function registerManageCommands(integrations) {
             printJson(result);
             return;
         }
-        console.log(chalk.green(`${describePrincipal({ ...principal, granteeId: principal.granteeId ?? "" })} can now run ${toolName} on ${connectionLabel(connection)} without approval.`));
+        console.log(chalk.green(`${describePrincipal({ ...principal, granteeId: principal.granteeId ?? "" })} is now authorized to run ${toolName} on ${connectionLabel(connection)}. Whether it needs approval still follows the app's policy.`));
     });
     integrations
         .command("ungrant [app]")
-        .description("Remove a per-tool exception, so the tool needs approval again")
+        .description("Remove a per-tool authorization, leaving only the app's default access")
         .option("--company <slug>", "Company slug")
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
-        .requiredOption("--tool <name>", "The tool to stop allowing")
+        .requiredOption("--tool <name>", "The tool to stop authorizing")
         .requiredOption("--from <principal>", "Email, uid, or `everyone`")
         .option("--json", "Machine-readable output")
         .action(async (app, opts) => {
@@ -289,14 +302,14 @@ export function registerManageCommands(integrations) {
         const current = connection.writeAllowlist ?? [];
         const merged = removeGrant(current, opts.tool.trim(), principal);
         if (merged === null) {
-            throw new IntegrationsCliError(`No exception for ${opts.from} on ${opts.tool} — nothing to remove.`, { expected: true });
+            throw new IntegrationsCliError(`No per-tool authorization for ${opts.from} on ${opts.tool} — nothing to remove.`, { expected: true });
         }
         const result = await patchAllowlistIfUnchanged(token, companyUid, connection.id, current, merged);
         if (opts.json) {
             printJson(result);
             return;
         }
-        console.log(chalk.green(`${opts.tool} on ${connectionLabel(connection)} needs approval again.`));
+        console.log(chalk.green(`${opts.tool} on ${connectionLabel(connection)} no longer has a per-tool authorization.`));
     });
     integrations
         .command("access [app]")
@@ -422,26 +435,36 @@ export function registerManageCommands(integrations) {
         .action(async (opts) => {
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
-        const surface = await fetchAdminSurface(token, companyUid);
-        const queued = surface.audit.filter((row) => row.outcome === "queued" && row.queueId);
+        // Live confirm-queue state — a call already approved, rejected, or expired
+        // is gone from this list, unlike the old audit-feed reconstruction which
+        // could only show that a call was once queued.
+        let pending;
+        try {
+            pending = await fetchPendingApprovals(token, companyUid);
+        }
+        catch (err) {
+            // This CLI can ship ahead of the hq-pro deploy that adds the pending
+            // route (the two land as separate PRs). A 404 means "backend too old",
+            // not a real failure — say so plainly instead of a stack trace.
+            if (err instanceof IntegrationsCliError && err.status === 404) {
+                throw new IntegrationsCliError("This HQ backend doesn't support the live pending list yet. Approvals still work — an owner gets the approve command when a call is queued.", { expected: true });
+            }
+            throw err;
+        }
         if (opts.json) {
-            printJson(queued);
+            printJson(pending);
             return;
         }
-        if (queued.length === 0) {
+        if (pending.length === 0) {
             console.log("Nothing is waiting for approval.");
             return;
         }
-        for (const row of queued) {
-            const who = row.memberOrAgentName ?? row.memberOrAgent;
-            console.log(`${chalk.bold(row.toolName)}  ${chalk.dim(`${who} · ${row.timestamp}`)}`);
+        for (const row of pending) {
+            const who = row.requestedByName ?? row.requestedBy;
+            const label = row.requestedTool ?? row.toolName;
+            console.log(`${chalk.bold(label)}  ${chalk.dim(`${who} · ${row.createdAt}`)}`);
             console.log(chalk.dim(`  hq integrations approve ${row.queueId}${row.provider ? ` --provider ${bareProvider(row.provider)}` : ""}`));
         }
-        // hq-pro exposes no "list open queue entries" route, so this is derived
-        // from the activity feed — and the feed records the QUEUING, never the
-        // later decision. Saying so is the difference between a useful list and
-        // a misleading one.
-        console.log(chalk.dim("\nDerived from recent activity — an entry already approved, rejected, or expired may still appear here."));
     });
     integrations
         .command("disconnect [app]")

package/dist/commands/integrations.d.ts

@@ -25,7 +25,7 @@
  *
  * Govern and remove:
  *   hq integrations policy [app] --set <m>   Approval setting for changes.
- *   hq integrations grants|grant|ungrant     Per-tool approval exceptions.
+ *   hq integrations grants|grant|ungrant     Per-tool authorization to run change-making tools.
  *   hq integrations access|share|unshare     Who may use the app.
  *   hq integrations audit                    Recent activity.
  *   hq integrations disconnect [app]         Remove it and its credentials.

package/dist/commands/integrations.js

@@ -25,7 +25,7 @@
  *
  * Govern and remove:
  *   hq integrations policy [app] --set <m>   Approval setting for changes.
- *   hq integrations grants|grant|ungrant     Per-tool approval exceptions.
+ *   hq integrations grants|grant|ungrant     Per-tool authorization to run change-making tools.
  *   hq integrations access|share|unshare     Who may use the app.
  *   hq integrations audit                    Recent activity.
  *   hq integrations disconnect [app]         Remove it and its credentials.
@@ -47,7 +47,7 @@ import { randomUUID } from "node:crypto";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, selectConnection, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
+import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
 import { registerConnectCommands } from "./integrations-connect.js";
 import { registerManageCommands } from "./integrations-manage.js";
 export { IntegrationsCliError, callGateway, fetchConnections, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
@@ -169,7 +169,15 @@ export function registerIntegrationsCommand(program) {
             }
             return;
         }
+        // A tool that ran but FAILED (`isError: true`) still has its payload
+        // printed — the error text is the useful part — but the command exits
+        // non-zero so a script or agent can tell failure from success without
+        // parsing output. The flag is on the raw gateway result, not the
+        // unwrapped payload.
         printJson(payload);
+        if (gatewayResultIsError(message.result)) {
+            process.exitCode = 1;
+        }
     });
     for (const decision of ["approve", "reject"]) {
         integrations

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

@@ -9,6 +9,8 @@
  *     performs the update and re-runs the command, and only warns when the
  *     update itself fails. Installs quietly (the package manager's stdout is
  *     captured, never forwarded) because `--json` consumers parse ours.
+ *     Attended callers wait for the install and get the re-exec; unattended
+ *     ones (hooks, scripts, agents, cron) do not update at all — see below.
  *
  *   - `selfUpdateAndReexec` — `hq rescue`. The rescue script ships inside this
  *     install's `@indigoai-us/hq-cloud` dependency, so a stale CLI runs a stale
@@ -28,6 +30,29 @@
  * command on the current version. Self-updating must never make a command less
  * available than it was before.
  *
+ * Surviving a killed parent — the reason this file spawns the way it does.
+ * A global install rewrites the one copy of the CLI on the machine and is NOT
+ * atomic: killed part-way through, it leaves a store the `hq` shim resolves
+ * into but cannot load, and every later invocation dies with MODULE_NOT_FOUND
+ * until a human reinstalls. Three properties prevent that:
+ *
+ *   1. Unattended callers do not update at all. They are the ones carrying
+ *      deadlines they cannot control, their own command may still need files
+ *      from the package an install would replace, and with no terminal to
+ *      return to the re-exec is pointless. `onlyWhenAttended` on the flavor.
+ *   2. Every install spawn is `detached`, so it runs in its own process group
+ *      and a signal aimed at the CLI's group — Ctrl-C, a hangup, a deadline
+ *      runner — cannot reach the package manager mid-write.
+ *   3. Install output goes to descriptors that outlive this process, never to
+ *      pipes we own, so a killed CLI cannot take the installer down by EPIPE.
+ *      `openInstallOutput` in version-gate.ts.
+ *
+ * (2) and (3) are separate holes and both must be closed: the process group
+ * governs signals, the descriptors govern I/O, and either one alone still
+ * leaves a way to kill an install half-applied.
+ *
+ * Covered by `self-update-kill-resistance.test.ts`.
+ *
  * Opt-outs: `HQ_NO_UPDATE_CHECK=1` (the shared knob that also silences
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
@@ -47,7 +72,13 @@ export type SelfUpdateAction =
 /** Updated, but the re-exec couldn't start; continue on the current (in-memory) version. */
  | "updated-no-reexec"
 /** Updated and the command re-ran on the new version; exit with `reexecStatus`. */
- | "reexec";
+ | "reexec"
+/**
+ * Unattended caller: replacing the CLI in place is unsafe here, so nothing
+ * was attempted and the command runs on the current version. An attended
+ * session, the desktop app's installer, or the hard version gate updates it.
+ */
+ | "deferred";
 export interface SelfUpdateOutcome {
     action: SelfUpdateAction;
     /** Exit status of the re-exec'd `hq …` (action === "reexec"). */
@@ -93,6 +124,12 @@ export interface SelfUpdateDeps {
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
     acquireLock?: () => (() => void) | null;
+    /**
+     * 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
+     * underneath themselves: hooks, scripts, agents, cron, CI.
+     */
+    interactive?: boolean;
 }
 /**
  * Startup path: the running CLI is behind npm `latest`, so update in place and

package/dist/utils/self-update.js

@@ -9,6 +9,8 @@
  *     performs the update and re-runs the command, and only warns when the
  *     update itself fails. Installs quietly (the package manager's stdout is
  *     captured, never forwarded) because `--json` consumers parse ours.
+ *     Attended callers wait for the install and get the re-exec; unattended
+ *     ones (hooks, scripts, agents, cron) do not update at all — see below.
  *
  *   - `selfUpdateAndReexec` — `hq rescue`. The rescue script ships inside this
  *     install's `@indigoai-us/hq-cloud` dependency, so a stale CLI runs a stale
@@ -28,6 +30,29 @@
  * command on the current version. Self-updating must never make a command less
  * available than it was before.
  *
+ * Surviving a killed parent — the reason this file spawns the way it does.
+ * A global install rewrites the one copy of the CLI on the machine and is NOT
+ * atomic: killed part-way through, it leaves a store the `hq` shim resolves
+ * into but cannot load, and every later invocation dies with MODULE_NOT_FOUND
+ * until a human reinstalls. Three properties prevent that:
+ *
+ *   1. Unattended callers do not update at all. They are the ones carrying
+ *      deadlines they cannot control, their own command may still need files
+ *      from the package an install would replace, and with no terminal to
+ *      return to the re-exec is pointless. `onlyWhenAttended` on the flavor.
+ *   2. Every install spawn is `detached`, so it runs in its own process group
+ *      and a signal aimed at the CLI's group — Ctrl-C, a hangup, a deadline
+ *      runner — cannot reach the package manager mid-write.
+ *   3. Install output goes to descriptors that outlive this process, never to
+ *      pipes we own, so a killed CLI cannot take the installer down by EPIPE.
+ *      `openInstallOutput` in version-gate.ts.
+ *
+ * (2) and (3) are separate holes and both must be closed: the process group
+ * governs signals, the descriptors govern I/O, and either one alone still
+ * leaves a way to kill an install half-applied.
+ *
+ * Covered by `self-update-kill-resistance.test.ts`.
+ *
  * Opt-outs: `HQ_NO_UPDATE_CHECK=1` (the shared knob that also silences
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
@@ -38,7 +63,7 @@ import * as path from "node:path";
 import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, inOwnProcessGroup, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
@@ -89,21 +114,24 @@ export function buildSelfUpdatePlan(install) {
  * stderr is kept only to explain a failure.
  */
 export function runUpdateQuiet(cmd, args, env) {
+    // File sinks rather than pipes: a pipe dies with this process and would take
+    // the installer down with it mid-write. See `openInstallOutput`.
+    const output = openInstallOutput(false);
     try {
         const plan = buildSpawnPlan(cmd, args);
-        const result = spawnSync(plan.cmd, plan.args, {
-            stdio: ["ignore", "pipe", "pipe"],
+        // `inOwnProcessGroup`: the install must survive a signal aimed at this
+        // process, or a killed `hq` leaves a corrupted global install behind.
+        const result = spawnSync(plan.cmd, plan.args, inOwnProcessGroup({
+            stdio: output.stdio,
             shell: plan.shell,
-            encoding: "utf-8",
             ...(env ? { env } : {}),
-        });
+        }));
         if (result.error) {
             const code = result.error.code;
             return { ok: false, code, detail: result.error.message };
         }
         if (result.status !== 0) {
-            const stderr = (result.stderr ?? "").trim();
-            const tail = stderr ? stderr.slice(-DETAIL_MAX_CHARS) : "";
+            const tail = output.stderrTail().slice(-DETAIL_MAX_CHARS);
             return {
                 ok: false,
                 detail: tail || `exit ${result.status ?? "signal"}`,
@@ -118,6 +146,9 @@ export function runUpdateQuiet(cmd, args, env) {
             detail: err instanceof Error ? err.message : String(err),
         };
     }
+    finally {
+        output.dispose();
+    }
 }
 function lockDir() {
     return path.join(os.homedir(), ".hq", "self-update.lock");
@@ -195,6 +226,32 @@ async function updateAndReexec(argv, flavor, known, deps) {
         return { action: "skipped" };
     if (!semver.gt(latestValid, current))
         return { action: "current", latest };
+    // Replacing the CLI in place is only safe when someone is at a terminal.
+    //
+    // A global install rewrites the very package this process is running from,
+    // and an unattended `hq` is the worst possible moment for that:
+    //
+    //   - It carries a deadline it does not control (a Claude Code hook capped at
+    //     `"timeout": 5`, a harness Bash deadline, cron), so waiting out a
+    //     tens-of-seconds install means being killed part-way through one.
+    //   - Its own command may still need files from the installed package.
+    //     `resolveBundledAsset` reads `assets/scaffold/**` from the package root
+    //     at call time, so an install overlapping the command can make it fail
+    //     with "Bundled asset is missing" or mix new assets with old in-memory
+    //     code. Running the install alongside the command is not an option, and
+    //     nothing here can know when the command will finish.
+    //   - Nobody benefits: with no terminal to return to, the re-exec is pointless
+    //     and the "Updating…" line is noise in output someone else is parsing.
+    //
+    // So an unattended caller does not update; it runs the command it was asked
+    // to run. Updates land from an attended session, from the desktop app's
+    // background installer (which owns this for unattended machines, retries, and
+    // can repair a CLI that no longer loads), or from the hq-pro hard gate when a
+    // version is genuinely not allowed to run.
+    const interactive = deps.interactive ?? process.stderr.isTTY === true;
+    if (!interactive && flavor.onlyWhenAttended) {
+        return { action: "deferred", latest };
+    }
     const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
     if (!releaseLock)
         return { action: "skipped", latest };
@@ -251,7 +308,7 @@ async function updateAndReexec(argv, flavor, known, deps) {
  * this resolve it from the registry.
  */
 export async function autoUpdateAndReexec(argv, latest, deps = {}) {
-    return updateAndReexec(argv, { noun: "command", verbose: false, lock: true }, latest, deps);
+    return updateAndReexec(argv, { noun: "command", verbose: false, lock: true, onlyWhenAttended: true }, latest, deps);
 }
 /**
  * Rescue path: update to npm latest and re-exec the rescue on the new version.
@@ -260,6 +317,6 @@ export async function autoUpdateAndReexec(argv, latest, deps = {}) {
  * are preserved.
  */
 export async function selfUpdateAndReexec(argv, deps = {}) {
-    return updateAndReexec(argv, { noun: "rescue", verbose: true, lock: true }, null, deps);
+    return updateAndReexec(argv, { noun: "rescue", verbose: true, lock: true, onlyWhenAttended: false }, null, deps);
 }
 //# sourceMappingURL=self-update.js.map

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

@@ -181,6 +181,57 @@ export type UpdateResult = {
 };
 type UpdateRunner = (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
 export { buildSpawnPlan, quoteForWindowsShell };
+/**
+ * Add `detached` to a **synchronous** spawn's options.
+ *
+ * Why a helper rather than the property inline: Node implements `detached` in
+ * its sync spawn path (`spawn_sync.cc` maps it onto libuv's
+ * `UV_PROCESS_DETACHED`, exactly as the async path does), but `@types/node`
+ * declares the flag only on the async `SpawnOptions`. This function is that
+ * one type gap, isolated and explained in a single place instead of a cast
+ * repeated at each call site.
+ *
+ * It is load-bearing rather than cosmetic. A global install rewrites the only
+ * copy of the CLI on the machine and is not atomic, so a package manager that
+ * shares the CLI's process group is destroyed mid-write whenever something
+ * signals that group — a Claude Code hook with `"timeout": 5`, a harness
+ * deadline, cron, or a plain Ctrl-C — leaving an install that resolves but
+ * cannot load (MODULE_NOT_FOUND) until a human reinstalls by hand.
+ *
+ * Because the guarantee rests on behaviour the types do not describe, it is
+ * pinned by a runtime test (`self-update-kill-resistance.test.ts`) that asserts
+ * the spawned child really is its own process-group leader. If a future Node
+ * stops honouring the flag here, that test fails loudly instead of the
+ * protection silently disappearing.
+ */
+export declare function inOwnProcessGroup<T extends object>(options: T): T;
+/**
+ * Where an install's output goes — the other half of surviving a killed parent.
+ *
+ * `inOwnProcessGroup` stops a signal from reaching the package manager, but it
+ * does nothing about file descriptors, and a PIPE is owned by this process. If
+ * we are killed mid-install the read ends close, and the package manager takes
+ * `EPIPE`/`SIGPIPE` on its next write — dying part-way through rewriting the
+ * global store, which is exactly the corruption the process group was meant to
+ * prevent. Pipe lifetime is not a process-group property, so both fixes are
+ * needed.
+ *
+ * A file descriptor onto a temp file has no such coupling: it stays valid after
+ * we are gone, and the installer runs to completion regardless.
+ *
+ * `inherit` is safe ONLY when our own streams are a terminal, because a
+ * terminal outlives us too. Inheriting a *pipe* (a hook, a captured harness
+ * invocation, cron) has the identical failure as a pipe we opened ourselves, so
+ * the verbose path takes the file sink there and gives up live output that
+ * nothing was reading anyway.
+ */
+export interface InstallOutput {
+    stdio: ("ignore" | "inherit" | number)[];
+    /** Captured stderr tail, or "" when output was inherited by a terminal. */
+    stderrTail: () => string;
+    dispose: () => void;
+}
+export declare function openInstallOutput(verbose: boolean, isTty?: boolean): InstallOutput;
 export declare function runUpdateCommand(cmd: string, args: string[], env?: NodeJS.ProcessEnv): UpdateResult;
 declare function performUpdateCommand(cmd: string, args: string[], runner?: UpdateRunner, env?: NodeJS.ProcessEnv): UpdateResult;
 declare function performUpdate(command: string, runner?: UpdateRunner): UpdateResult;

package/dist/utils/version-gate.js

@@ -29,7 +29,8 @@
  */
 import { spawnSync } from "node:child_process";
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
-import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { closeSync, existsSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
@@ -352,23 +353,95 @@ async function fetchVersionDecision() {
 // public surface (and the `__test__` block below) stable for existing callers
 // and tests.
 export { buildSpawnPlan, quoteForWindowsShell };
+/**
+ * Add `detached` to a **synchronous** spawn's options.
+ *
+ * Why a helper rather than the property inline: Node implements `detached` in
+ * its sync spawn path (`spawn_sync.cc` maps it onto libuv's
+ * `UV_PROCESS_DETACHED`, exactly as the async path does), but `@types/node`
+ * declares the flag only on the async `SpawnOptions`. This function is that
+ * one type gap, isolated and explained in a single place instead of a cast
+ * repeated at each call site.
+ *
+ * It is load-bearing rather than cosmetic. A global install rewrites the only
+ * copy of the CLI on the machine and is not atomic, so a package manager that
+ * shares the CLI's process group is destroyed mid-write whenever something
+ * signals that group — a Claude Code hook with `"timeout": 5`, a harness
+ * deadline, cron, or a plain Ctrl-C — leaving an install that resolves but
+ * cannot load (MODULE_NOT_FOUND) until a human reinstalls by hand.
+ *
+ * Because the guarantee rests on behaviour the types do not describe, it is
+ * pinned by a runtime test (`self-update-kill-resistance.test.ts`) that asserts
+ * the spawned child really is its own process-group leader. If a future Node
+ * stops honouring the flag here, that test fails loudly instead of the
+ * protection silently disappearing.
+ */
+export function inOwnProcessGroup(options) {
+    return { ...options, detached: true };
+}
+/** Tail of captured installer stderr kept to explain a failure. */
+const INSTALL_DETAIL_MAX_CHARS = 400;
+export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true && process.stderr.isTTY === true) {
+    if (verbose && isTty) {
+        return {
+            stdio: ["ignore", "inherit", "inherit"],
+            stderrTail: () => "",
+            dispose: () => { },
+        };
+    }
+    const dir = mkdtempSync(path.join(os.tmpdir(), "hq-cli-install-"));
+    const errPath = path.join(dir, "stderr.log");
+    const out = openSync(path.join(dir, "stdout.log"), "a");
+    const err = openSync(errPath, "a");
+    return {
+        stdio: ["ignore", out, err],
+        stderrTail: () => {
+            try {
+                return readFileSync(errPath, "utf-8").trim().slice(-INSTALL_DETAIL_MAX_CHARS);
+            }
+            catch {
+                return "";
+            }
+        },
+        dispose: () => {
+            for (const fd of [out, err]) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    // Already closed; nothing to recover.
+                }
+            }
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort cleanup of a temp dir.
+            }
+        },
+    };
+}
 export function runUpdateCommand(cmd, args, env) {
+    const output = openInstallOutput(true);
     try {
         const plan = buildSpawnPlan(cmd, args);
-        const result = spawnSync(plan.cmd, plan.args, {
-            stdio: "inherit",
+        const result = spawnSync(plan.cmd, plan.args, inOwnProcessGroup({
+            stdio: output.stdio,
             shell: plan.shell,
             ...(env ? { env } : {}),
-        });
+        }));
         // spawnSync reports a missing executable via `error`, not a throw.
         if (result.error) {
             const code = result.error.code;
             return { ok: false, code, detail: result.error.message };
         }
         if (result.status !== 0) {
+            // When output went to a file rather than the user's terminal, its tail is
+            // the only explanation anyone will ever see for this failure.
+            const captured = output.stderrTail();
             return {
                 ok: false,
-                detail: `exit ${result.status ?? "signal"}`,
+                detail: captured || `exit ${result.status ?? "signal"}`,
             };
         }
         return { ok: true };
@@ -380,6 +453,9 @@ export function runUpdateCommand(cmd, args, env) {
             detail: err instanceof Error ? err.message : String(err),
         };
     }
+    finally {
+        output.dispose();
+    }
 }
 function performUpdateCommand(cmd, args, runner = runUpdateCommand, env) {
     // Forward env only when there is one to forward, so the common path keeps the

package/package.json

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