@indigoai-us/hq-cli 5.345.45 → 5.345.47

package/dist/lib/install/codex-targets.js

@@ -155,6 +155,31 @@ export function removeCodexHooks(doc, hqRoot) {
         next.hooks = hooks;
     return next;
 }
+/**
+ * Codex trust keys (`<hooks.json>:<snake_event>:<group>:<hook>`) for the HQ
+ * entries in a hooks.json document. Foreign entries are left out so install
+ * never trusts a hook the user added themselves.
+ */
+export function codexHookTrustKeys(doc, hooksJsonPath, hqRoot) {
+    const hooks = doc.hooks;
+    if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+        return [];
+    const keys = [];
+    for (const [event, value] of Object.entries(hooks)) {
+        if (!Array.isArray(value))
+            continue;
+        const snake = event.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+        value.forEach((group, g) => {
+            if (!group || !Array.isArray(group.hooks))
+                return;
+            group.hooks.forEach((entry, h) => {
+                if (isAdapterEntry(entry, hqRoot))
+                    keys.push(`${hooksJsonPath}:${snake}:${g}:${h}`);
+            });
+        });
+    }
+    return keys;
+}
 export function hasAllCodexHooks(doc, hqRoot, target = 'master') {
     return addCodexHooks(doc, hqRoot, target) === doc;
 }

package/dist/lib/install/provider-wrappers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Throw if either wrapper target holds a non-HQ command. Callers run this before
+ * any install mutation so a collision cannot leave HQ half-installed.
+ */
+export declare function assertProviderWrappersInstallable(binDir: string): void;
+export declare function providerWrapperInstallPaths(home: string): string[];
+export declare function installProviderWrappers(binDir: string, home?: string): string[];
+export declare function removeProviderWrappers(binDir: string): string[];
+//# sourceMappingURL=provider-wrappers.d.ts.map

package/dist/lib/install/provider-wrappers.js

@@ -0,0 +1,190 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+const marker = '# hq-anywhere provider sign-in wrapper';
+const PROVIDER_PATH_RC_FILES = ['.bashrc', '.bash_profile', '.zshrc', '.zprofile', '.profile'];
+const wrapperHeader = (provider) => `#!/bin/sh\n${marker}: ${provider}\n`;
+/**
+ * Throw if either wrapper target holds a non-HQ command. Callers run this before
+ * any install mutation so a collision cannot leave HQ half-installed.
+ */
+export function assertProviderWrappersInstallable(binDir) {
+    for (const provider of ['claude', 'codex']) {
+        const file = path.join(binDir, provider);
+        let current;
+        try {
+            current = fs.readFileSync(file, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                continue;
+            throw e;
+        }
+        if (!current.startsWith(wrapperHeader(provider))) {
+            throw new Error(`Refusing to replace an existing ${provider} command at ${file}.`);
+        }
+    }
+}
+export function providerWrapperInstallPaths(home) {
+    const binDir = path.join(home, '.hq', 'bin');
+    const paths = ['claude', 'codex'].map((provider) => path.join(binDir, provider));
+    const pathSetupMarker = path.join(home, '.hq', 'provider-path-installed');
+    if (!fs.existsSync(pathSetupMarker)) {
+        paths.push(pathSetupMarker, ...PROVIDER_PATH_RC_FILES.map((rc) => path.join(home, rc)));
+    }
+    return paths;
+}
+function wrapperSource(provider) {
+    const pretty = provider === 'claude' ? 'Claude Code' : 'Codex';
+    const login = provider === 'claude' ? 'claude /login' : 'codex login';
+    const statusArgs = provider === 'claude' ? 'auth status' : 'login status';
+    const authFailure = provider === 'codex'
+        ? '401|unauthorized|not logged in|signed out|not authenticated|authentication required|unauthenticated|missing.*(bearer|credential|auth)|websocket.*auth'
+        : '401|unauthorized|not logged in|signed out|not authenticated|authentication required|unauthenticated|missing.*(bearer|credential|auth)';
+    const runAuthFailure = provider === 'codex'
+        ? 'HTTP error: *401|status 401|401 Unauthorized|websocket.*auth|not logged in|signed out|not authenticated|authentication required|unauthenticated'
+        : 'HTTP error: *401|status 401|401 Unauthorized|not logged in|signed out|not authenticated|authentication required|unauthenticated';
+    return [
+        '#!/bin/sh',
+        `${marker}: ${provider}`,
+        'set -u',
+        'umask 077',
+        `name=${provider}`,
+        `pretty='${pretty}'`,
+        `login='${login}'`,
+        `provider='${provider}'`,
+        '',
+        '# Skip this managed wrapper and locate the provider executable later in PATH.',
+        'self=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)/$(basename -- "$0")',
+        'real=',
+        'old_ifs=$IFS',
+        'IFS=:',
+        'for dir in $PATH; do',
+        '  [ -n "$dir" ] || dir=.',
+        '  candidate=$(CDPATH= cd -- "$dir" 2>/dev/null && pwd -P)/$name',
+        '  if [ -x "$candidate" ] && [ "$candidate" != "$self" ]; then real=$candidate; break; fi',
+        'done',
+        'IFS=$old_ifs',
+        'if [ -z "$real" ]; then printf \'%s CLI was not found on PATH.\\n\' "$pretty" >&2; exit 127; fi',
+        '',
+        '# The flag override is part of the existing hq-anywhere-runtime flag contract.',
+        'case "${HQ_FLAG_HQ_ANYWHERE_RUNTIME:-}" in false|0) exec "$real" "$@" ;; esac',
+        '',
+        '# Login, auth, and informational commands must remain reachable while signed out.',
+        'case "${1:-}" in',
+        '  --version|-v|--help|-h) exec "$real" "$@" ;;',
+        `  ${provider === 'claude' ? '/login|auth' : 'login'}) exec "$real" "$@" ;;`,
+        'esac',
+        '',
+        'log_dir="$HOME/.hq/logs"',
+        'mkdir -p "$log_dir" 2>/dev/null || :',
+        'log_file="$log_dir/provider-auth.log"',
+        'tmp=$(mktemp -d "${TMPDIR:-/tmp}/hq-provider.XXXXXX") || exit 1',
+        'trap \'rm -rf "$tmp"\' EXIT HUP INT TERM',
+        `if command -v timeout >/dev/null 2>&1; then timeout 5 "$real" ${statusArgs} >"$tmp/status" 2>&1; auth_status=$?; elif command -v perl >/dev/null 2>&1; then perl -e 'alarm 5; exec @ARGV' "$real" ${statusArgs} >"$tmp/status" 2>&1; auth_status=$?; else auth_status=124; fi`,
+        'case "$auth_status" in 124|142) : >"$tmp/status-timeout" ;; esac',
+        'if [ "$auth_status" -ne 0 ]; then cat "$tmp/status" >>"$log_file" 2>/dev/null || :; fi',
+        `if [ ! -e "$tmp/status-timeout" ] && grep -Eiq '${authFailure}' "$tmp/status"; then`,
+        '  cat "$tmp/status" >>"$log_file" 2>/dev/null || :',
+        '  printf \'%s\\n\' "[$(date -u +%FT%TZ)] $pretty sign-in check reported unauthenticated" >>"$log_file" 2>/dev/null || :',
+        '  printf \'%s is not signed in. Sign in to use HQ Anywhere:\\n  %s\\n\' "$pretty" "$login" >&2',
+        '  exit 1',
+        'fi',
+        'if [ -t 1 ] && { [ "$provider" = claude ] && [ "${1:-}" != -p ] && [ "${1:-}" != --print ] || [ "$provider" = codex ] && [ "${1:-}" != exec ]; }; then exec "$real" "$@"; fi',
+        '',
+        '# Leave provider stdout attached to the caller so streaming and TTY state survive.',
+        'mkfifo "$tmp/stderr.pipe"',
+        'filter_stderr() {',
+        '  trap - EXIT HUP INT TERM',
+        '  while :; do',
+        '    line=',
+        '    IFS= read -r line',
+        '    read_status=$?',
+        '    [ -n "$line" ] || [ "$read_status" -eq 0 ] || break',
+        '    if printf \'%s\\n\' "$line" | grep -Eiq "' + runAuthFailure + '"; then',
+        '      printf \'%s\\n\' "$line" >>"$tmp/auth-found"',
+        '    else',
+        '      printf \'%s\' "$line" >&2',
+        '      [ "$read_status" -eq 0 ] && printf \'\\n\' >&2',
+        '    fi',
+        '    [ "$read_status" -eq 0 ] || break',
+        '  done <"$tmp/stderr.pipe"',
+        '}',
+        'filter_stderr &',
+        'filter_pid=$!',
+        '"$real" "$@" 2>"$tmp/stderr.pipe"',
+        'status=$?',
+        'wait "$filter_pid"',
+        `if [ "$status" -ne 0 ] && [ -f "$tmp/auth-found" ]; then`,
+        '  # Only the matched authentication lines are logged; the run\'s other output can',
+        '  # carry prompts, source or downstream secrets and never reaches this file.',
+        '  { printf \'\\n[hq-anywhere] %s returned an authentication failure.\\n\' "$pretty"; cat "$tmp/auth-found"; } >>"$log_file" 2>/dev/null || :',
+        `  printf \'%s could not authenticate this run. Sign in to use HQ Anywhere:\\n  %s\\n\' "$pretty" "$login" >&2`,
+        '  exit "$status"',
+        'fi',
+        'exit "$status"',
+        '',
+    ].join('\n');
+}
+export function installProviderWrappers(binDir, home = path.dirname(path.dirname(binDir))) {
+    fs.mkdirSync(binDir, { recursive: true, mode: 0o755 });
+    const files = ['claude', 'codex'].map((provider) => path.join(binDir, provider));
+    // Both targets are checked before either is written, so a collision on codex
+    // cannot leave a freshly written claude wrapper behind.
+    assertProviderWrappersInstallable(binDir);
+    for (const provider of ['claude', 'codex']) {
+        const file = path.join(binDir, provider);
+        fs.writeFileSync(file, wrapperSource(provider), { mode: 0o755 });
+        fs.chmodSync(file, 0o755);
+    }
+    // Startup files are append-only. The marker avoids reading any shell startup file.
+    const pathSetupMarker = path.join(path.dirname(binDir), 'provider-path-installed');
+    if (!fs.existsSync(pathSetupMarker)) {
+        const pathLine = '\nexport PATH="$HOME/.hq/bin:$PATH" # hq-anywhere provider commands\n';
+        // Only startup files that already exist are edited. Creating .bash_profile or
+        // .zprofile would make the login shell select it and stop reading the user's
+        // existing .profile, silently dropping their environment setup.
+        const existing = PROVIDER_PATH_RC_FILES.filter((rc) => fs.existsSync(path.join(home, rc)));
+        const createdRcFiles = [];
+        if (existing.length === 0) {
+            // .profile shadows nothing: every POSIX login shell reads it, and no other
+            // startup file is present for it to take precedence over.
+            createdRcFiles.push('.profile');
+        }
+        for (const rc of [...existing, ...createdRcFiles]) {
+            fs.appendFileSync(path.join(home, rc), pathLine, { mode: 0o600 });
+        }
+        fs.writeFileSync(pathSetupMarker, `${createdRcFiles.join('\n')}\n`, { mode: 0o600 });
+    }
+    return files;
+}
+export function removeProviderWrappers(binDir) {
+    const removed = [];
+    for (const provider of ['claude', 'codex']) {
+        const file = path.join(binDir, provider);
+        if (!fs.existsSync(file))
+            continue;
+        const current = fs.readFileSync(file, 'utf8');
+        if (!current.startsWith(wrapperHeader(provider)))
+            continue;
+        fs.unlinkSync(file);
+        removed.push(file);
+    }
+    const home = path.dirname(path.dirname(binDir));
+    const pathSetupMarker = path.join(home, '.hq', 'provider-path-installed');
+    if (fs.existsSync(pathSetupMarker)) {
+        const createdRcFiles = new Set(fs.readFileSync(pathSetupMarker, 'utf8').split('\n').filter(Boolean));
+        const deletePathSetup = 's/\\nexport PATH="\\$HOME\\/\\.hq\\/bin:\\$PATH" # hq-anywhere provider commands\\n//';
+        for (const rc of PROVIDER_PATH_RC_FILES) {
+            const file = path.join(home, rc);
+            if (fs.existsSync(file)) {
+                execFileSync('perl', ['-0pi', '-e', deletePathSetup, file]);
+                if (createdRcFiles.has(rc))
+                    fs.unlinkSync(file);
+            }
+        }
+        fs.unlinkSync(pathSetupMarker);
+    }
+    return removed;
+}
+//# sourceMappingURL=provider-wrappers.js.map

package/dist/lib/lanes/provider-rejection.d.ts

@@ -6,13 +6,13 @@
  * output and no envelope. Without this module the watcher classifies that
  * `interrupted` with `exited_with_partial_output`, and the operator has to
  * read the raw log to learn why. Here the failure is named: the lane is
- * `failed` with `terminal_reason: provider_rejected` and the provider's own
- * message on `terminal_details`.
+ * terminalized with a named provider reason and the provider's own message on
+ * `terminal_details`; transient failures remain resumable.
  *
  * A 429 is parsed here like any other status so that a codex or grok 429,
- * which the claude-shaped quota reader cannot see, still reaches the quota
- * path: the watcher routes a `status === QUOTA_STATUS` failure to quota.ts
- * (reset time, account hold) and everything else to `provider_rejected`.
+ * which the claude-shaped quota reader cannot see, still reaches the watcher.
+ * Quota-specific messages become account holds; generic rate-limit responses
+ * remain retryable provider rejections.
  *
  * Only the fields named below are read out of the payload. The prompt, the
  * response body and everything else stay on disk. Nothing here logs.

package/dist/lib/lanes/provider-rejection.js

@@ -6,13 +6,13 @@
  * output and no envelope. Without this module the watcher classifies that
  * `interrupted` with `exited_with_partial_output`, and the operator has to
  * read the raw log to learn why. Here the failure is named: the lane is
- * `failed` with `terminal_reason: provider_rejected` and the provider's own
- * message on `terminal_details`.
+ * terminalized with a named provider reason and the provider's own message on
+ * `terminal_details`; transient failures remain resumable.
  *
  * A 429 is parsed here like any other status so that a codex or grok 429,
- * which the claude-shaped quota reader cannot see, still reaches the quota
- * path: the watcher routes a `status === QUOTA_STATUS` failure to quota.ts
- * (reset time, account hold) and everything else to `provider_rejected`.
+ * which the claude-shaped quota reader cannot see, still reaches the watcher.
+ * Quota-specific messages become account holds; generic rate-limit responses
+ * remain retryable provider rejections.
  *
  * Only the fields named below are read out of the payload. The prompt, the
  * response body and everything else stay on disk. Nothing here logs.
@@ -114,10 +114,14 @@ function capMessage(message) {
 export function retryableFromStatus(status) {
     if (status === null)
         return false;
-    if (status === 408 || status === 425)
+    if (status === 408 || status === 425 || status === 429)
         return true;
     return status >= 500 && status <= 599;
 }
+function retryableProviderFailure(status, message) {
+    return retryableFromStatus(status) ||
+        (status === null && /\b(?:rate limit|too many requests)\b/i.test(message));
+}
 /**
  * Codex `exec --json`: `{"type":"turn.failed","error":{"message":"<text>"}}`.
  * Measured 2026-09-22 (lane 01M34HCCP1ZDN3H68ESCRZE7RZ): the message is
@@ -151,7 +155,7 @@ export function parseCodexTurnFailed(text) {
             message: capMessage(message),
             status,
             error_type: errorType,
-            retryable: retryableFromStatus(status),
+            retryable: retryableProviderFailure(status, message),
             event: "codex.turn.failed",
         };
     });
@@ -175,15 +179,16 @@ export function parseClaudeResultRejection(text) {
         if (rec.is_error !== true && !loginFailure)
             return NOT_REJECTED;
         const status = statusOf(rec.api_error_status);
-        if (status === null && !loginFailure)
+        if (status === null && !loginFailure && !retryableProviderFailure(status, message)) {
             return NOT_REJECTED;
+        }
         return {
             reason: PROVIDER_REJECTED_REASON,
             provider: "claude",
             message: capMessage(message),
             status,
             error_type: typeof rec.subtype === "string" ? rec.subtype : null,
-            retryable: retryableFromStatus(status),
+            retryable: retryableProviderFailure(status, message),
             event: loginFailure && rec.is_error !== true
                 ? "claude.result.login_failure"
                 : "claude.result.is_error",
@@ -231,7 +236,7 @@ function grokRejectionFrom(rec) {
         message: capMessage(message),
         status,
         error_type: null,
-        retryable: retryableFromStatus(status),
+        retryable: retryableProviderFailure(status, message),
         event: "grok.error",
     };
 }

package/dist/lib/lanes/spawn.js

@@ -1621,11 +1621,16 @@ export function markSpawnFailure(hqRoot, laneId, reasonRaw, details, options = {
                 : []),
         ].filter((value) => typeof value === "string" && Number.isFinite(Date.parse(value)));
         const quotaResetAt = resetCandidates.sort((a, b) => Date.parse(a) - Date.parse(b))[0];
-        const resumableQuotaHold = current.keep_alive === true &&
-            (current.pending_resume !== undefined || options.resumeTrigger !== undefined) &&
-            (reason === "account_quota_exhausted" || reason === "account_model_unavailable") &&
+        // Initial queued lanes can be retried by reconcile without a session;
+        // ordinary resumes keep their existing failed-state behavior.
+        const initialQueuedSpawn = current.state === "queued" &&
+            current.pending_resume === undefined && options.resumeTrigger === undefined;
+        const keepAliveResume = current.keep_alive === true &&
+            (current.pending_resume !== undefined || options.resumeTrigger !== undefined);
+        const resumableQuotaHold = (reason === "account_quota_exhausted" || reason === "account_model_unavailable") &&
             typeof quotaResetAt === "string" &&
-            Number.isFinite(Date.parse(quotaResetAt));
+            Number.isFinite(Date.parse(quotaResetAt)) &&
+            (initialQueuedSpawn || keepAliveResume);
         if (current.state === "failed" && existing === reason && !resumableQuotaHold)
             return current;
         const operatorQuotaHold = resumableQuotaHold && options.resumeTrigger !== undefined;

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

@@ -76,6 +76,7 @@ export interface WatcherTickInput {
         errors: string[];
     } | null;
     providerRejection?: ProviderRejection | null;
+    hasProviderSession?: boolean;
 }
 export interface WatcherTickResult {
     emit?: WatcherSignal;
@@ -103,10 +104,13 @@ export declare function classifyLaneExit(input: {
     /**
      * Set when the worker's output stream carries a provider-level turn
      * failure (codex `turn.failed`, a Claude error result with an HTTP status,
-     * a grok error object). Failed, never interrupted: the provider refused
-     * the turn, so there is nothing to resume and no envelope to repair.
+     * a grok error object). A retryable refusal interrupts only when a provider
+     * session exists to resume; without one, the lane fails with the named
+     * provider reason. Neither path attempts envelope repair.
      */
     providerRejection?: ProviderRejection | null;
+    /** True only when the lane has a current or prior provider session id. */
+    hasProviderSession?: boolean;
 }): TerminalClassification;
 export declare function routeProviderFailure(failure: ProviderRejection | null, readQuota: () => QuotaSignal | null, model: string | undefined, now: Date): {
     quota: QuotaSignal | null;

package/dist/lib/lanes/watcher.js

@@ -106,11 +106,19 @@ export function classifyLaneExit(input) {
         throw new LanesError("unknown_envelope_decision", `Unknown envelope decision ${JSON.stringify(input.envelope.decision)}. Accepted: done, ask, blocked`, { accepted: ["done", "ask", "blocked"], value: input.envelope.decision });
     }
     if (input.providerRejection) {
+        const rejection = input.providerRejection;
+        const reason = isProviderLoginFailure(rejection)
+            ? "account_not_logged_in"
+            : rejection.status === 402
+                ? "provider_billing_required"
+                : rejection.status === 401 || rejection.status === 403
+                    ? "provider_auth_failed"
+                    : rejection.status === 429 || /\b(?:rate limit|too many requests)\b/i.test(rejection.message)
+                        ? "provider_rate_limited"
+                        : PROVIDER_REJECTED_REASON;
         return {
-            state: "failed",
-            reason: isProviderLoginFailure(input.providerRejection)
-                ? "account_not_logged_in"
-                : PROVIDER_REJECTED_REASON,
+            state: rejection.retryable && input.hasProviderSession === true ? "interrupted" : "failed",
+            reason,
         };
     }
     if (input.invalidEnvelope) {
@@ -129,15 +137,14 @@ export function classifyLaneExit(input) {
 }
 /**
  * One decision for an exited worker's output. An explicit provider status
- * wins over the quota text heuristics: a 429 from any provider (including
- * codex `turn.failed` and grok error objects, which the claude-shaped quota
- * reader never sees) becomes a quota signal; any other explicit status is a
- * rejection even when its text sounds like a quota message (a 402 "requires
- * usage credits" is a rejection, not a hold). A failure with no status at
- * all is matched against the quota text heuristics first: a status-less
- * "usage limit" / "rate limit" turn.failed still creates the account hold;
- * any other status-less message is a rejection. Only when the stream
- * carries no failure object does the quota reader's own read apply.
+ * wins over the quota text heuristics: a 429 with quota-specific text or a
+ * usage-limit error type becomes an account hold; a generic rate-limit
+ * response stays a retryable provider rejection. Any other explicit status
+ * is a rejection even when its text sounds like a quota message (a 402
+ * "requires usage credits" is a billing refusal, not a hold). A status-less
+ * usage-limit message can create an account hold, while a status-less
+ * rate-limit message remains a retryable provider rejection. Only when the
+ * stream carries no failure object does the quota reader's own read apply.
  */
 function validFailureOutputTime(value, fallback) {
     const parsed = new Date(value);
@@ -146,21 +153,31 @@ function validFailureOutputTime(value, fallback) {
         : fallback;
 }
 export function routeProviderFailure(failure, readQuota, model, now) {
-    if (failure && failure.status === QUOTA_STATUS) {
+    if (failure && failure.status === QUOTA_STATUS && isAccountQuotaFailure(failure)) {
         return {
             quota: quotaSignalFromFields({ api_error_status: QUOTA_STATUS, is_error: true, result: failure.message }, model, failure.output_at ? validFailureOutputTime(failure.output_at, now) : now),
             rejection: null,
         };
     }
-    if (failure && failure.status === null) {
+    if (failure && failure.status === null && isAccountQuotaFailure(failure)) {
         const quota = quotaSignalFromFields({ api_error_status: undefined, is_error: true, result: failure.message }, model, failure.output_at ? validFailureOutputTime(failure.output_at, now) : now);
         if (quota)
             return { quota, rejection: null };
     }
-    if (failure)
-        return { quota: null, rejection: failure };
+    if (failure) {
+        return {
+            quota: null,
+            rejection: failure.status === QUOTA_STATUS
+                ? { ...failure, retryable: true }
+                : failure,
+        };
+    }
     return { quota: readQuota(), rejection: null };
 }
+function isAccountQuotaFailure(failure) {
+    return failure.error_type === "usage_limit_reached" ||
+        /weekly limit|usage limit|quota|usage credits|hit your .+ limit/i.test(failure.message);
+}
 export function tickWatcher(input) {
     const silenceMs = input.silenceMs ?? SILENCE_MS;
     const at = new Date(input.nowMs).toISOString();
@@ -171,6 +188,7 @@ export function tickWatcher(input) {
             quota: input.quota,
             invalidEnvelope: input.invalidEnvelope,
             providerRejection: input.providerRejection,
+            hasProviderSession: input.hasProviderSession,
         });
         return {
             emit: { kind: "terminal", at, classification },
@@ -1578,6 +1596,8 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
             quota,
             invalidEnvelope,
             providerRejection,
+            hasProviderSession: typeof quotaLane?.provider_session_id === "string" &&
+                quotaLane.provider_session_id.trim().length > 0,
         });
         if (processAlive) {
             maybeHeartbeatLane(hqRoot, laneId, now());

package/dist/utils/hook-trust.d.ts

@@ -53,6 +53,13 @@ export interface RuntimeHookTrustResult {
 export declare function createCodexAppServerClient(cwd: string, executable?: string, args?: string[]): Promise<CodexRpcClient>;
 /** Trust only hooks declared by this HQ root's project `.codex/` layer. */
 export declare function trustCodexProjectHooks(hqRoot: string, deps?: HookTrustDependencies): Promise<RuntimeHookTrustResult>;
+/**
+ * Trust the user-scope hooks `hq install --global --runtime codex` registered
+ * in ~/.codex/hooks.json, named by their Codex keys (`<file>:<event>:<group>:<hook>`).
+ * Codex skips untrusted hooks, so without this HQ stays inert in every session
+ * outside the HQ folder. Other hooks in the same file are never trusted here.
+ */
+export declare function trustCodexUserHooks(cwd: string, keys: readonly string[], deps?: HookTrustDependencies): Promise<RuntimeHookTrustResult>;
 /**
  * Mark this HQ root as a trusted Claude Code workspace.
  *

package/dist/utils/hook-trust.js

@@ -181,10 +181,37 @@ export async function trustCodexProjectHooks(hqRoot, deps = DEFAULT_DEPS) {
     if (!fs.existsSync(path.join(hqRoot, '.codex'))) {
         return { runtime: 'codex', status: 'skipped', trusted: 0, reason: 'project .codex layer absent' };
     }
+    return trustCodexHooks(hqRoot, deps, (hooks) => {
+        const projectHooks = hqProjectHooks(hqRoot, hooks);
+        return projectHooks.length === 0
+            ? { skip: 'no HQ project hooks discovered' }
+            : { hooks: projectHooks };
+    });
+}
+/**
+ * Trust the user-scope hooks `hq install --global --runtime codex` registered
+ * in ~/.codex/hooks.json, named by their Codex keys (`<file>:<event>:<group>:<hook>`).
+ * Codex skips untrusted hooks, so without this HQ stays inert in every session
+ * outside the HQ folder. Other hooks in the same file are never trusted here.
+ */
+export async function trustCodexUserHooks(cwd, keys, deps = DEFAULT_DEPS) {
+    if (keys.length === 0) {
+        return { runtime: 'codex', status: 'skipped', trusted: 0, reason: 'no HQ user hooks registered' };
+    }
+    return trustCodexHooks(cwd, deps, (hooks) => {
+        const byKey = new Map(hooks.filter((hook) => hook.source === 'user' && !hook.isManaged).map((hook) => [hook.key, hook]));
+        const missing = keys.filter((key) => !byKey.has(key));
+        if (missing.length > 0)
+            return { fail: `Codex did not discover: ${missing.join(', ')}` };
+        return { hooks: keys.map((key) => byKey.get(key)) };
+    });
+}
+/** List hooks for `cwd`, trust and enable the selected ones, then verify. */
+async function trustCodexHooks(cwd, deps, select) {
     let client;
     try {
-        client = await deps.createCodexClient(hqRoot);
-        const discovered = hooksFromListResponse(await client.request('hooks/list', { cwds: [hqRoot] }));
+        client = await deps.createCodexClient(cwd);
+        const discovered = hooksFromListResponse(await client.request('hooks/list', { cwds: [cwd] }));
         if (discovered.errors.length > 0) {
             return {
                 runtime: 'codex',
@@ -193,19 +220,18 @@ export async function trustCodexProjectHooks(hqRoot, deps = DEFAULT_DEPS) {
                 reason: discovered.errors.join('; '),
             };
         }
-        const projectHooks = hqProjectHooks(hqRoot, discovered.hooks);
-        if (projectHooks.length === 0) {
-            return {
-                runtime: 'codex',
-                status: 'skipped',
-                trusted: 0,
-                reason: 'no HQ project hooks discovered',
-            };
+        const selection = select(discovered.hooks);
+        if ('skip' in selection) {
+            return { runtime: 'codex', status: 'skipped', trusted: 0, reason: selection.skip };
+        }
+        if ('fail' in selection) {
+            return { runtime: 'codex', status: 'failed', trusted: 0, reason: selection.fail };
         }
-        // Converge every HQ project hook to trusted AND enabled. A hook that is
+        const selected = selection.hooks;
+        // Converge every selected HQ hook to trusted AND enabled. A hook that is
         // already trusted but was toggled off would otherwise silently stay
-        // disabled forever — reindex is the convergence point, so it re-enables.
-        const pending = projectHooks.filter((hook) => hook.trustStatus === 'untrusted' || hook.trustStatus === 'modified' || !hook.enabled);
+        // disabled forever; reindex and install are the convergence points.
+        const pending = selected.filter((hook) => hook.trustStatus === 'untrusted' || hook.trustStatus === 'modified' || !hook.enabled);
         if (pending.length === 0) {
             return { runtime: 'codex', status: 'unchanged', trusted: 0 };
         }
@@ -220,7 +246,7 @@ export async function trustCodexProjectHooks(hqRoot, deps = DEFAULT_DEPS) {
             edits: [{ keyPath: 'hooks.state', value: state, mergeStrategy: 'upsert' }],
             reloadUserConfig: true,
         });
-        const verified = hooksFromListResponse(await client.request('hooks/list', { cwds: [hqRoot] }));
+        const verified = hooksFromListResponse(await client.request('hooks/list', { cwds: [cwd] }));
         const verifiedByKey = new Map(verified.hooks.map((hook) => [hook.key, hook]));
         const stillPending = pending
             .filter((hook) => {

package/dist/utils/self-update.js

@@ -65,7 +65,7 @@ import chalk from "chalk";
 import { Sentry } from "../sentry.js";
 import { isCliTelemetryDisabled } from "./cli-telemetry.js";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, canWriteNpmInstall, captureNonWritableNpmPrefixNotice, claimNonWritableNpmPrefixNotice, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, pnpmInstalledVersion, performPnpmUpdate, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, UPDATE_RECURSION_GUARD_ENV, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, canWriteNpmInstall, captureNonWritableNpmPrefixNotice, claimNonWritableNpmPrefixNotice, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, nonWritablePrefixNote, openInstallOutput, pnpmPathConflict, pnpmUpdateEnv, pnpmInstalledVersion, performPnpmUpdate, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, UPDATE_RECURSION_GUARD_ENV, } from "./version-gate.js";
 import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
@@ -931,6 +931,13 @@ async function attemptUpdateAndReexec(argv, flavor, known, deps, env) {
         console.error(chalk.dim(`hq-cli ${latest} is available, but this copy is a local dependency (${install.packageRoot}) — update the project that owns it.`));
         return { action: "skipped", latest };
     }
+    if (install.manager === "pnpm") {
+        const conflict = pnpmPathConflict(install);
+        if (conflict) {
+            console.error(chalk.yellow(`⚠ hq self-update refused: ${conflict}`));
+            return { action: "skipped", latest };
+        }
+    }
     const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
     if (!releaseLock)
         return { action: "skipped", latest };

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

@@ -430,6 +430,13 @@ declare function resolveHqOnPath(): string | null;
 export declare function parseReportedCliVersion(stdout: string): string | null;
 /** `<bin> --version` output (trimmed), or null on any failure/timeout. */
 declare function probeCliVersion(bin: string): string | null;
+/**
+ * Detect a second pnpm global install winning PATH before the updater mutates
+ * the running install. pnpm homes have independent global package trees and
+ * shims, so writing one home cannot change a different home that appears first
+ * on PATH.
+ */
+export declare function pnpmPathConflict(install: RunningInstall): string | null;
 /**
  * Read-your-writes convergence check, run after an install reports success.
  *