@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/secrets-env-fast-path.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedSecretsEnvFastRequest } from "./fast-scaffold.js";
+import type { SecretsEnvFastResult } from "./secrets-env-fast-route.js";
+/** Run the shared secret action without importing the full CLI command graph. */
+export declare function runSecretsEnvFastPath(request: ParsedSecretsEnvFastRequest): Promise<SecretsEnvFastResult>;
+//# sourceMappingURL=secrets-env-fast-path.d.ts.map

package/dist/secrets-env-fast-path.js

@@ -0,0 +1,16 @@
+/** Run the shared secret action without importing the full CLI command graph. */
+export async function runSecretsEnvFastPath(request) {
+    if (process.env.HQ_AGENT_DIR?.trim()) {
+        const [os, { agentKitPaths }, { adoptAgentIdentityEnv }] = await Promise.all([
+            import("node:os"),
+            import("./lib/agent-kit/paths.js"),
+            import("./lib/agent-kit/adopt-identity.js"),
+        ]);
+        adoptAgentIdentityEnv(agentKitPaths(os.homedir(), process.env), process.env);
+    }
+    const { runSecretsEnvCommand } = await import("./commands/secrets.js");
+    return runSecretsEnvCommand(request.options, request.scope, {
+        fallbackOnAuthFailure: true,
+    });
+}
+//# sourceMappingURL=secrets-env-fast-path.js.map

package/dist/secrets-env-fast-route.d.ts

@@ -0,0 +1,18 @@
+/** Default-off hq-flags gate for the `secrets env` entry fast path. */
+import type { ParsedSecretsEnvFastRequest } from "./fast-scaffold.js";
+export declare const CLI_SECRETS_ENV_FAST_PATH_FLAG = "cli.secrets-env-fast-path";
+export type SecretsEnvFastResult = "handled" | "fallback";
+export interface SecretsEnvFastDispatchDeps {
+    isEnabled: () => Promise<boolean>;
+    runFast: () => Promise<SecretsEnvFastResult>;
+    runCurrent: () => Promise<void>;
+}
+/** Keep the existing command graph in control when the gate is off or declines. */
+export declare function dispatchSecretsEnvFastRequest(_request: ParsedSecretsEnvFastRequest, deps: SecretsEnvFastDispatchDeps): Promise<void>;
+/**
+ * Fast routes only use an explicit local override or the latest company flag
+ * snapshot. A missing company, stale snapshot, or unreadable cache leaves the
+ * current CLI path in control; it never performs a registry network request.
+ */
+export declare function secretsEnvFastRouteEnabled(request: ParsedSecretsEnvFastRequest, env?: NodeJS.ProcessEnv): Promise<boolean>;
+//# sourceMappingURL=secrets-env-fast-route.d.ts.map

package/dist/secrets-env-fast-route.js

@@ -0,0 +1,54 @@
+/** Default-off hq-flags gate for the `secrets env` entry fast path. */
+import { localOverrideEnvVar, readLocalOverride } from "@indigoai-us/hq-flags-client";
+export const CLI_SECRETS_ENV_FAST_PATH_FLAG = "cli.secrets-env-fast-path";
+/** Keep the existing command graph in control when the gate is off or declines. */
+export async function dispatchSecretsEnvFastRequest(_request, deps) {
+    if (!(await deps.isEnabled())) {
+        await deps.runCurrent();
+        return;
+    }
+    if ((await deps.runFast()) === "fallback") {
+        await deps.runCurrent();
+    }
+}
+/**
+ * Fast routes only use an explicit local override or the latest company flag
+ * snapshot. A missing company, stale snapshot, or unreadable cache leaves the
+ * current CLI path in control; it never performs a registry network request.
+ */
+export async function secretsEnvFastRouteEnabled(request, env = process.env) {
+    const override = readLocalOverride(CLI_SECRETS_ENV_FAST_PATH_FLAG, env);
+    if (override !== null)
+        return override;
+    const rawOverride = env[localOverrideEnvVar(CLI_SECRETS_ENV_FAST_PATH_FLAG)];
+    if (rawOverride === "1")
+        return true;
+    if (rawOverride === "0")
+        return false;
+    if (request.scope.personal)
+        return false;
+    try {
+        const scopedEnv = { ...env };
+        if (request.scope.company) {
+            // An explicit --company scope must override any ambient binding for the
+            // fast-path flag lookup, just as it overrides the secrets command scope.
+            delete scopedEnv.HQ_COMPANY_UID;
+            scopedEnv.HQ_COMPANY_SLUG = request.scope.company;
+        }
+        const [{ resolveProcessFlagCompanyContext }, { readFlagSnapshotFile }] = await Promise.all([
+            import("./lib/process-flag-company-context.js"),
+            import("./lib/flag-snapshot-file.js"),
+        ]);
+        const { companyUid } = resolveProcessFlagCompanyContext(scopedEnv);
+        if (!companyUid)
+            return false;
+        return readFlagSnapshotFile(companyUid, { env: scopedEnv })?.flags[CLI_SECRETS_ENV_FAST_PATH_FLAG] === true;
+    }
+    catch (error) {
+        // This is a performance rollout gate. Failure to read it preserves the
+        // existing full CLI behavior.
+        console.warn("[hq] secrets env fast-path flag lookup failed; using the full CLI path", error instanceof Error ? error.name : typeof error);
+        return false;
+    }
+}
+//# sourceMappingURL=secrets-env-fast-route.js.map

package/dist/sentry-before-send.js

@@ -175,6 +175,86 @@ function scrubFields(value, memo = new Map()) {
     return out;
 }
 export function beforeSend(event, _hint) {
+    if (event.tags?.sentry_event_type === "client_health") {
+        const sourceTags = (event.tags ?? {});
+        const checkClasses = new Set([
+            "sync.update.core",
+            "sync.journal.personal",
+            "sync.journal.personal_vault",
+            "sync.journal.company",
+            "sync.manifest.personal",
+            "sync.manifest.personal_vault",
+            "sync.manifest.company",
+            "other",
+        ]);
+        const reasonCodes = new Set([
+            "none",
+            "core-version-unavailable",
+            "core-update-available",
+            "no-local-tree",
+            "never-synced",
+            "invalid-last-sync",
+            "stale-threshold",
+            "manifest-unavailable",
+            "manifest-state-unavailable",
+            "no-manifest-scopes",
+            "never-uploaded",
+            "invalid-upload-time",
+            "unresolved-company-uid",
+        ]);
+        const platforms = new Set([
+            "aix", "android", "darwin", "freebsd", "haiku", "linux", "openbsd",
+            "sunos", "win32", "cygwin",
+        ]);
+        const architectures = new Set([
+            "arm", "arm64", "ia32", "loong64", "mips", "mipsel", "ppc", "ppc64",
+            "riscv64", "s390x", "x64",
+        ]);
+        const versionPattern = /^(?:unknown|\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?)$/;
+        const id = typeof event.user?.id === "string" &&
+            /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(event.user.id)
+            ? event.user.id
+            : undefined;
+        const checkClass = typeof sourceTags.check_class === "string" && checkClasses.has(sourceTags.check_class)
+            ? sourceTags.check_class
+            : "other";
+        const reasonCode = typeof sourceTags.reason_code === "string" && reasonCodes.has(sourceTags.reason_code)
+            ? sourceTags.reason_code
+            : "none";
+        const fixOutcome = ["not_auto_fixable", "fix_failed", "fix_timed_out"].includes(String(sourceTags.fix_outcome)) ? String(sourceTags.fix_outcome) : "not_auto_fixable";
+        const status = sourceTags.status === "WARN" ? "WARN" : "FAIL";
+        const count = typeof sourceTags.failing_check_count === "string" &&
+            /^[1-9]\d{0,2}$/.test(sourceTags.failing_check_count) &&
+            Number(sourceTags.failing_check_count) <= 250
+            ? sourceTags.failing_check_count
+            : "1";
+        const safeVersion = (value) => typeof value === "string" && versionPattern.test(value) ? value : "unknown";
+        const safePlatform = (value) => typeof value === "string" && platforms.has(value) ? value : "unknown";
+        const safeArchitecture = (value) => typeof value === "string" && architectures.has(value) ? value : "unknown";
+        return {
+            type: undefined,
+            ...(typeof event.event_id === "string" ? { event_id: event.event_id } : {}),
+            ...(typeof event.timestamp === "number" ? { timestamp: event.timestamp } : {}),
+            platform: "node",
+            level: "warning",
+            message: `Client health: ${checkClass} unresolved after hq doctor --fix`,
+            fingerprint: ["client-health", checkClass, reasonCode],
+            tags: {
+                sentry_event_type: "client_health",
+                check_class: checkClass,
+                reason_code: reasonCode,
+                fix_outcome: fixOutcome,
+                status,
+                failing_check_count: count,
+                cli_version: safeVersion(sourceTags.cli_version),
+                core_version: safeVersion(sourceTags.core_version),
+                sync_version: safeVersion(sourceTags.sync_version),
+                platform: safePlatform(sourceTags.platform),
+                arch: safeArchitecture(sourceTags.arch),
+            },
+            user: { ...(id ? { id } : {}), ip_address: null },
+        };
+    }
     if (event.request) {
         const req = event.request;
         event.request = {

package/dist/sentry.d.ts

@@ -1,5 +1,11 @@
-import * as Sentry from "@sentry/node";
-import type { ErrorEvent, EventHint } from "@sentry/node";
+import type { ErrorEvent, EventHint, NodeOptions } from "@sentry/node";
+type SentryModule = typeof import("@sentry/node");
+/**
+ * The command graph touches the Sentry facade on normal startup for a
+ * breadcrumb and a final flush. Keep those operations inert until the SDK
+ * module is loaded; the first capture that needs it loads the SDK synchronously.
+ */
+export declare const Sentry: SentryModule;
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -11,6 +17,12 @@ import type { ErrorEvent, EventHint } from "@sentry/node";
  * Consistent with the swallow-EPIPE posture established in #138.
  */
 export declare function epipeAwareBeforeSend(event: ErrorEvent, hint: EventHint): ErrorEvent | null;
-export declare function initSentry(): void;
-export { Sentry };
+/**
+ * Tests substitute only the transport so the real SDK lifecycle can be
+ * exercised without an ingest request. Production callers pass nothing.
+ */
+export declare function initSentry(overrides?: Partial<Pick<NodeOptions, "transport">>): void;
+/** Finish HQ's one per-invocation release-health session. */
+export declare function finishSentrySession(): void;
+export {};
 //# sourceMappingURL=sentry.d.ts.map

package/dist/sentry.js

@@ -1,13 +1,68 @@
-import * as Sentry from "@sentry/node";
+import { createRequire } from "node:module";
 import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
 import { beforeSend } from "./sentry-before-send.js";
 import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
 import { isEpipe } from "./utils/epipe.js";
+import { companySkillWrapperSentryTagsFor } from "./lib/company-skill-wrapper.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { incompleteInstallCaptureContext, incompleteInstallMessage, } from "./utils/incomplete-install-error.js";
-import { sentryFingerprintFor } from "./utils/sentry-fingerprint.js";
+import { installTreeTornSentryTagsFor, sentryFingerprintFor, sentryMcpCollisionContextFor, } from "./utils/sentry-fingerprint.js";
+const inertSentryScope = {
+    setTag: () => inertSentryScope,
+    setUser: () => inertSentryScope,
+    addBreadcrumb: () => inertSentryScope,
+    clearBreadcrumbs: () => inertSentryScope,
+    setLevel: () => inertSentryScope,
+    setFingerprint: () => inertSentryScope,
+};
+const requireSentry = createRequire(import.meta.url);
+let sentryModule;
+let pendingSentryBreadcrumbs = [];
+function loadSentryModule() {
+    sentryModule ??= requireSentry("@sentry/node");
+    return sentryModule;
+}
+/**
+ * The command graph touches the Sentry facade on normal startup for a
+ * breadcrumb and a final flush. Keep those operations inert until the SDK
+ * module is loaded; the first capture that needs it loads the SDK synchronously.
+ */
+export const Sentry = new Proxy({}, {
+    get(_target, property) {
+        if (property === Symbol.toStringTag)
+            return "Module";
+        if (property === "addBreadcrumb") {
+            return (breadcrumb) => {
+                if (sentryModule) {
+                    sentryModule.addBreadcrumb(breadcrumb);
+                    return;
+                }
+                if (pendingSentryBreadcrumbs.length >= 100)
+                    pendingSentryBreadcrumbs.shift();
+                pendingSentryBreadcrumbs.push(breadcrumb);
+            };
+        }
+        if (property === "withScope") {
+            return (callback) => {
+                if (sentryModule)
+                    return sentryModule.withScope(callback);
+                return callback(inertSentryScope);
+            };
+        }
+        if (property === "flush") {
+            return (timeout) => {
+                if (!sentryModule)
+                    return Promise.resolve(true);
+                return sentryModule.flush(timeout);
+            };
+        }
+        const sdk = loadSentryModule();
+        const value = Reflect.get(sdk, property);
+        return typeof value === "function" ? value.bind(sdk) : value;
+    },
+});
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -19,7 +74,17 @@ import { sentryFingerprintFor } from "./utils/sentry-fingerprint.js";
  * Consistent with the swallow-EPIPE posture established in #138.
  */
 export function epipeAwareBeforeSend(event, hint) {
-    if (isEpipe(hint?.originalException))
+    const flagRegistryWorkerEvent = isFlagRegistryWorkerEvent(event);
+    if (flagRegistryWorkerEvent) {
+        if (isExpectedFlagRegistryWorkerStartupFailure(hint?.originalException))
+            return null;
+        event.level = "warning";
+        event.tags = { ...event.tags, worker: "flag-registry" };
+        const missingFile = flagRegistryWorkerMissingFileTags(hint?.originalException, event);
+        if (missingFile)
+            event.tags = { ...event.tags, ...missingFile };
+    }
+    if (!flagRegistryWorkerEvent && isEpipe(hint?.originalException))
         return null;
     // Path-independent belt for environmental filesystem failures (ENOSPC /
     // EDQUOT / EROFS — a full disk, exhausted quota, or read-only mount, e.g.
@@ -30,14 +95,16 @@ export function epipeAwareBeforeSend(event, hint) {
     // either. handleTopLevelError already prints an actionable message for the
     // boundary route; dropping the event here suppresses the fatal regardless of
     // route, while the CLI still exits non-zero. HQ-CLI-R (Sentry 7671416365).
-    if (environmentalFsErrorMessage(hint?.originalException))
+    if (!flagRegistryWorkerEvent && environmentalFsErrorMessage(hint?.originalException))
         return null;
     // Path-independent belt for an IN-PROCESS incomplete-install module-load
     // failure — hq-cli's own globally installed tree is not intact at load time
     // (HQ-CLI-1N, a CJS relative-sibling MODULE_NOT_FOUND under its bundled
     // node_modules; HQ-CLI-1Q, a CJS BARE-specifier MODULE_NOT_FOUND the requiring
     // third-party package's own manifest declares; HQ-CLI-1M, an esm-loader ENOENT
-    // for a file present at resolve and gone at read). handleTopLevelError already
+    // for a file present at resolve and gone at read; HQ-CLI-20, its CJS loader-read
+    // twin — a bundled CJS dep gone between resolve and the loader's source read).
+    // handleTopLevelError already
     // prints the reinstall remedy for the top-level route; dropping the event here
     // suppresses the fatal regardless of route — the unhandled-rejection boundary,
     // the command-level captureException sites, and bin/hq-auth-refresh —
@@ -47,10 +114,10 @@ export function epipeAwareBeforeSend(event, hint) {
     // node_modules, so an hq-cli packaging fault (a dist/ miss, or a bare miss the
     // requirer does NOT declare — a possible undeclared/peer dependency) and the
     // path-less unattributable shape are NOT dropped here and stay captured.
-    if (incompleteInstallMessage(hint?.originalException))
+    if (!flagRegistryWorkerEvent && incompleteInstallMessage(hint?.originalException))
         return null;
     // An incomplete-install shape that is NOT suppressed (a bare miss the requirer
-    // does not declare, or a path-less esm-loader ENOENT) should still arrive
+    // does not declare, or a path-less loader/resolver ENOENT) should still arrive
     // ATTRIBUTABLE on every capture route, not only the top-level boundary:
     // handleTopLevelError in main.ts is the ONLY caller of
     // incompleteInstallCaptureContext, so events reaching this hook directly — the
@@ -68,20 +135,104 @@ export function epipeAwareBeforeSend(event, hint) {
     // before the fleet scrubber — so it covers EVERY capture route (the top-level
     // boundary, the command-level captureException sites, bin/hq-auth-refresh,
     // any uncaughtException), mirroring the EPIPE and environmental-fs drops
-    // above. The classifier reads only a closed allowlist (never message/argv),
-    // and returns null for anything it cannot bound, in which case Sentry's
-    // default grouping is left untouched.
-    const fingerprint = sentryFingerprintFor(hint?.originalException);
-    if (fingerprint)
-        event.fingerprint = fingerprint;
+    // above. The typed error classifiers use closed allowlists. The Codex
+    // collision branch uses one fixed bucket and adds the validated server name
+    // only as a tag; it sends no config values or paths. Unclassifiable
+    // events retain Sentry's default grouping.
+    const mcpCollision = sentryMcpCollisionContextFor(hint?.originalException);
+    if (mcpCollision) {
+        event.tags = { ...event.tags, ...mcpCollision.tags };
+        event.fingerprint = mcpCollision.fingerprint;
+    }
+    else {
+        const fingerprint = sentryFingerprintFor(hint?.originalException);
+        if (fingerprint)
+            event.fingerprint = fingerprint;
+    }
+    const skillWrapperTags = companySkillWrapperSentryTagsFor(hint?.originalException);
+    if (skillWrapperTags) {
+        event.tags = { ...event.tags, ...skillWrapperTags };
+    }
+    const installTreeTags = installTreeTornSentryTagsFor(hint?.originalException);
+    if (installTreeTags) {
+        event.tags = { ...event.tags, ...installTreeTags };
+    }
     return beforeSend(event, hint);
 }
-export function initSentry() {
+function isFlagRegistryWorkerEvent(event) {
+    return event.tags?.worker === "flag-registry" && Boolean(event.exception?.values?.some((value) => value.mechanism?.type === "auto.child_process.worker_thread"));
+}
+function isExpectedFlagRegistryWorkerStartupFailure(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const details = error;
+    if (details.code === "ENOENT" && details.syscall === "uv_cwd") {
+        const stack = typeof details.stack === "string" ? details.stack : "";
+        return stack.includes("node:internal/main/worker_thread") && /\bat process\.cwd \(/.test(stack);
+    }
+    if (details.code !== "MODULE_NOT_FOUND" && details.code !== "ERR_MODULE_NOT_FOUND") {
+        return false;
+    }
+    const message = typeof details.message === "string" ? details.message : "";
+    const missingModule = /Cannot find module\s+['"]([^'"]+)['"]/.exec(message)?.[1];
+    if (!missingModule)
+        return false;
+    return missingModule.replaceAll("\\", "/").endsWith("/flag-registry-worker.js") ||
+        missingModule === "flag-registry-worker.js";
+}
+function flagRegistryWorkerMissingFileTags(error, event) {
+    if (typeof error !== "object" || error === null)
+        return null;
+    const details = error;
+    if (details.code !== "ENOENT" || !["open", "lstat"].includes(String(details.syscall))) {
+        return null;
+    }
+    let missingPath = typeof details.path === "string" ? details.path : "";
+    if (!missingPath && typeof details.message === "string") {
+        missingPath = /\b(?:open|lstat)\s+['"]([^'"]+)['"]/.exec(details.message)?.[1] ?? "";
+    }
+    const basename = missingPath.replaceAll("\\", "/").split("/").at(-1) ?? "";
+    if (!basename)
+        return null;
+    const normalizedPath = missingPath.replaceAll("\\", "/");
+    const role = basename === "flag-registry-worker.js"
+        ? "worker_entry"
+        : normalizedPath.includes("/node_modules/")
+            ? "dependency"
+            : "other";
+    const eventText = [
+        event.message,
+        ...(event.exception?.values?.map((value) => value.value) ?? []),
+    ].filter((value) => typeof value === "string").join("\n");
+    const pathVisibility = eventText.includes(missingPath)
+        ? "full_path"
+        : eventText.includes(basename)
+            ? "basename_only"
+            : "omitted";
+    return {
+        flag_worker_load_failure: "1",
+        flag_worker_missing_basename: basename,
+        flag_worker_missing_file_role: role,
+        flag_worker_path_in_event: pathVisibility,
+        // The HQ beforeSend scrubber redacts credentials but does not strip paths.
+        flag_worker_path_scrubbed_by_hq_cli: "no",
+    };
+}
+/**
+ * Tests substitute only the transport so the real SDK lifecycle can be
+ * exercised without an ingest request. Production callers pass nothing.
+ */
+export function initSentry(overrides = {}) {
     const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
     if (!dsn)
         return;
-    Sentry.init({
+    const sdk = loadSentryModule();
+    sdk.init({
         dsn,
+        // import-in-the-middle's async ESM loader makes every later CLI import
+        // substantially slower. Keep HQ's explicit breadcrumbs, but give up
+        // automatic ESM third-party instrumentation (its spans/breadcrumbs).
+        registerEsmLoaderHooks: false,
         // CLI_VERSION reads package.json at runtime; npm_package_version is only
         // set under `npm run`, so an installed `hq` binary would always report
         // 0.0.0 and never match the uploaded source maps.
@@ -92,16 +243,26 @@ export function initSentry() {
         },
         beforeSend: epipeAwareBeforeSend,
         beforeBreadcrumb,
+        // HQ owns this short-lived CLI session explicitly below and closes it from
+        // main.ts. Leaving the SDK default enabled starts a competing session.
+        integrations: (defaults) => defaults.filter((integration) => integration.name !== "ProcessSession"),
+        ...overrides,
     });
     // Attribute events to the logged-in HQ identity (best-effort; null when not
     // logged in). A CLI process is one user, so global setUser is correct here.
     const user = getCachedSentryUser();
     if (user)
-        Sentry.setUser(user);
+        sdk.setUser(user);
+    for (const breadcrumb of pendingSentryBreadcrumbs)
+        sdk.addBreadcrumb(breadcrumb);
+    pendingSentryBreadcrumbs = [];
     // Release health: one session per CLI run. Ended + flushed in index.ts's
     // finally (covers every exit path). A captured error auto-marks the session
     // "errored", so crash-free numbers per release stay accurate.
-    Sentry.startSession();
+    sdk.startSession();
+}
+/** Finish HQ's one per-invocation release-health session. */
+export function finishSentrySession() {
+    sentryModule?.endSession();
 }
-export { Sentry };
 //# sourceMappingURL=sentry.js.map

package/dist/startup-registration.d.ts

@@ -16,13 +16,15 @@
  * style of handleTopLevelError so the whole seam is unit-testable without real
  * spawns, waits, or a real install tree.
  */
-import { type WaitForInstallTreeSettledArgs, type WaitForInstallTreeSettledResult } from "./utils/install-tree-torn.js";
+import { type InstallRewriteSignalArgs, type WaitForInstallTreeSettledArgs, type WaitForInstallTreeSettledResult } from "./utils/install-tree-torn.js";
 /**
  * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
  * from self-update's HQ_RESCUE_SELF_UPDATED so the two recovery paths cannot
  * shadow each other.
  */
 export declare const INSTALL_TREE_RECOVERY_GUARD_ENV = "HQ_INSTALL_TREE_RECOVERED";
+/** Carries the writer-state observed by the parent into the guarded re-exec. */
+export declare const INSTALL_TREE_RECOVERY_TREE_STATE_ENV = "HQ_INSTALL_TREE_RECOVERY_TREE_STATE";
 /** Operator override for the settle wait's deadline. */
 export declare const INSTALL_SETTLE_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_TIMEOUT_MS";
 /** Default settle deadline (ms). Overridable by {@link INSTALL_SETTLE_TIMEOUT_ENV}. */
@@ -32,9 +34,27 @@ export declare const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90000;
  * actually happens. It tells a human why the command paused and is the e2e's
  * synchronization point; it is never a remedy and never sets an error exit code.
  */
-export declare const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish\u2026";
+export declare const INSTALL_TREE_WAIT_NOTICE = "hq: checking whether the hq-cli install tree is still changing before retrying\u2026";
 /** Resolve the settle deadline from the environment (0 = evaluate once; default on invalid). */
 export declare function resolveSettleTimeoutMs(env: NodeJS.ProcessEnv): number;
+/** Operator override for the settle wait's LOCK ceiling (time under a live writer). */
+export declare const INSTALL_SETTLE_LOCK_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS";
+/**
+ * Default ceiling (ms) on the time the settle wait spends under a fresh foreign
+ * lock held by a live cooperating writer — the update-lock contract's own
+ * staleness window. Overridable by {@link INSTALL_SETTLE_LOCK_TIMEOUT_ENV}.
+ */
+export declare const DEFAULT_INSTALL_SETTLE_LOCK_TIMEOUT_MS: number;
+/**
+ * The single dim line emitted once when the wait continues PAST the settle
+ * deadline because a live updater still holds the shared install lock — so a human
+ * knows the pause is a running update, not a hang. Never a remedy, never an exit
+ * code; worded distinctly from {@link INSTALL_TREE_WAIT_NOTICE} so the e2e can
+ * synchronize on it.
+ */
+export declare const INSTALL_TREE_LOCK_WAIT_NOTICE = "hq: another hq updater is still installing hq-cli; waiting for it to finish\u2026";
+/** Resolve the lock ceiling from the environment (0 = do not extend; default on invalid). */
+export declare function resolveSettleLockTimeoutMs(env: NodeJS.ProcessEnv): number;
 /** Minimal view of a `spawnSync` result the seam relies on. */
 export interface RecoverySpawnResult {
     status: number | null;
@@ -48,8 +68,12 @@ export interface RegisterRecoveryDeps {
     resolveInstall?: () => {
         packageRoot: string | null;
     };
+    /** Filesystem-free fallback root for the torn window (defaults to stringDerivedPackageRoot). */
+    deriveInstallRoot?: () => string | null;
     lockPath?: () => string;
     waitForSettled?: (args: WaitForInstallTreeSettledArgs) => Promise<WaitForInstallTreeSettledResult>;
+    /** Positive writer-signal probe for the eval-throw gate (defaults to installRewriteInProgress). */
+    rewriteInProgress?: (args: InstallRewriteSignalArgs) => boolean;
     /** node flags to forward to the re-exec child (defaults to process.execArgv). */
     execArgv?: readonly string[];
 }