@indigoai-us/hq-cli 5.109.8 → 5.109.11

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## [Unreleased]
 
+## [5.109.11] — 2026-09-12
+
+### Fixed
+
+- A torn-install recovery no longer gives up after 90 seconds while another hq
+  updater is still legitimately installing hq-cli. When a command starts just as
+  the desktop app (or the box's `hq-cli-update` timer, or another `hq`) is
+  rewriting the install, the recovery waits for that writer to finish — bounded by
+  the shared install lock's own 10-minute staleness window rather than the 90-second
+  settle deadline — and then re-runs once on the healed tree, so the common case
+  (an install that finishes within the window) no longer fails at all. A short
+  second line explains the pause while it waits. If a writer holds the lock past
+  that ceiling, the command still fails once, but with a "let the update finish,
+  then re-run — do not reinstall while it is running" remedy and a distinct
+  `lock-held` outcome, instead of advice to reinstall over a live installer
+  (Sentry HQ-CLI-1Y, HQ-CLI-23). The ceiling is overridable with
+  `HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS`.
+
+## [5.109.10] — 2026-09-12
+
+### Fixed
+
+- A global reinstall that tears the install tree out mid-startup now recovers
+  even when the module that vanished is a RELATIVE sibling (for example
+  `@babel/runtime`'s `./typeof.js`, reached through the mqtt → worker-timers
+  chain). The torn-install classifier reduced a relative CJS specifier to the
+  package name `.`, producing a readiness probe that could never turn true — so
+  an affected command burned the entire 90-second settle budget, never re-ran on
+  the settled tree, and reported an error instead of recovering. Relative
+  specifiers are now re-resolved the way Node's CJS resolver does — from the
+  importer's directory, trying the file, its `.js`/`.json`/`.node` forms, and the
+  directory forms — so the command waits only as long as the reinstall actually
+  takes and then re-execs once on the healed tree. A genuinely missing sibling
+  still surfaces exactly one error naming the resolved path (Sentry HQ-CLI-1R).
+
 ## [5.109.8] — 2026-09-11
 
 ### Fixed

package/dist/commands/agents.d.ts

@@ -37,6 +37,28 @@ export declare const VALID_PROVIDERS: Set<string>;
 export declare const VALID_AUTH_MODES: Set<string>;
 /** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
 export declare const VALID_AGENT_SIZE_KEYS: Set<string>;
+/**
+ * `hq agents create` exits with this distinct status when payment is required.
+ * Scripts can distinguish the expected upgrade state from an ordinary command
+ * failure without parsing human output.
+ */
+export declare const AGENT_CREATE_PAYMENT_REQUIRED_EXIT_CODE = 3;
+export type AgentCreatePlanLimit = Readonly<{
+    requiredPlan: "agents-500";
+    amountMinor: number;
+    currency: string;
+    checkoutUrl?: string;
+}>;
+/**
+ * Decode only the priced response defined by the agent-create contract. A
+ * lookalike 403 must stay an ordinary API error rather than opening a browser
+ * or guessing at a price.
+ */
+export declare function agentCreatePlanLimitFromPayload(status: number, body: unknown): AgentCreatePlanLimit | null;
+/** Print a server-priced plan block without minting or rewriting its URL. */
+export declare function surfaceAgentCreatePlanLimit(planLimit: AgentCreatePlanLimit, opts?: {
+    json?: boolean;
+}): Promise<void>;
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the
  * offending input and the legal set.
@@ -82,7 +104,9 @@ export declare class AgentsHttpError extends Error {
     code?: string;
     /** hq-pro's billing envelope on a `402 billing_required` provision block. */
     billing?: BillingErrorPayload;
-    constructor(status: number, message: string, code?: string, billing?: BillingErrorPayload);
+    /** Strictly decoded priced `403 AGENT_PLAN_LIMIT` create response. */
+    agentCreatePlanLimit?: AgentCreatePlanLimit;
+    constructor(status: number, message: string, code?: string, billing?: BillingErrorPayload, agentCreatePlanLimit?: AgentCreatePlanLimit);
 }
 /** Roster row from `GET /v1/agents` — a superset is returned; we keep what we render. */
 export interface CompanyAgentView {
@@ -194,7 +218,7 @@ export declare function formatAgentCreateSize(option: AgentCreateSizeOption): st
 /** Ask a TTY user to choose one of hq-pro's currently selectable quotes. */
 export declare function promptForAgentCreateSize(view: AgentCreateOptionsView): Promise<QuotedAgentCreateSizeOption>;
 /** Confirm creation using the server quote, preserving $0 as a real answer. */
-export declare function confirmAgentCreateQuoteOrExit(option: QuotedAgentCreateSizeOption, yes?: boolean): void;
+export declare function confirmAgentCreateQuoteOrExit(option: QuotedAgentCreateSizeOption, yes?: boolean, quiet?: boolean): void;
 export declare function provisionAgent(token: string, input: ProvisionAgentInput): Promise<{
     uid?: string;
     slug?: string;

package/dist/commands/agents.js

@@ -25,6 +25,7 @@
  * the caller's single active membership (same as `members.ts`).
  */
 import chalk from "chalk";
+import open from "open";
 import { randomUUID } from "node:crypto";
 import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
@@ -50,6 +51,96 @@ export const VALID_PROVIDERS = new Set(["codex", "grok", "claude", "agents-v2"])
 export const VALID_AUTH_MODES = new Set(["subscription", "apiKey"]);
 /** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
 export const VALID_AGENT_SIZE_KEYS = new Set(["basic", "power", "dev"]);
+/**
+ * `hq agents create` exits with this distinct status when payment is required.
+ * Scripts can distinguish the expected upgrade state from an ordinary command
+ * failure without parsing human output.
+ */
+export const AGENT_CREATE_PAYMENT_REQUIRED_EXIT_CODE = 3;
+function isCheckoutUrl(value) {
+    if (typeof value !== "string" || !value.trim())
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decode only the priced response defined by the agent-create contract. A
+ * lookalike 403 must stay an ordinary API error rather than opening a browser
+ * or guessing at a price.
+ */
+export function agentCreatePlanLimitFromPayload(status, body) {
+    if (status !== 403 || !body || typeof body !== "object")
+        return null;
+    const payload = body;
+    if (payload.code !== "AGENT_PLAN_LIMIT" ||
+        payload.reasonCode !== "plan_limit" ||
+        payload.requiredPlan !== "agents-500" ||
+        typeof payload.amountMinor !== "number" ||
+        !Number.isSafeInteger(payload.amountMinor) ||
+        payload.amountMinor < 0 ||
+        typeof payload.currency !== "string" ||
+        !/^[A-Za-z]{3}$/.test(payload.currency)) {
+        return null;
+    }
+    if (payload.checkoutUrl !== undefined && !isCheckoutUrl(payload.checkoutUrl)) {
+        return null;
+    }
+    return {
+        requiredPlan: "agents-500",
+        amountMinor: payload.amountMinor,
+        currency: payload.currency.toUpperCase(),
+        ...(typeof payload.checkoutUrl === "string"
+            ? { checkoutUrl: payload.checkoutUrl }
+            : {}),
+    };
+}
+function formatServerPrice(amountMinor, currency) {
+    return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency,
+    }).format(amountMinor / 100);
+}
+function canOfferAgentCheckout(json) {
+    return json !== true &&
+        process.stdin.isTTY === true &&
+        process.stdout.isTTY === true &&
+        !process.env.CI;
+}
+async function offerAgentCheckout(url) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => rl.question("Open the payment page now? [y/N] ", resolve));
+        if (!/^y(?:es)?$/i.test(answer.trim()))
+            return;
+    }
+    finally {
+        rl.close();
+    }
+    try {
+        await open(url);
+    }
+    catch {
+        console.error("Could not open the payment page automatically. Use the URL above.");
+    }
+}
+/** Print a server-priced plan block without minting or rewriting its URL. */
+export async function surfaceAgentCreatePlanLimit(planLimit, opts = {}) {
+    const price = `${formatServerPrice(planLimit.amountMinor, planLimit.currency)}/month`;
+    console.error(`Payment required: your plan does not include agents. Upgrade to ${planLimit.requiredPlan} costs ${price}.`);
+    if (!planLimit.checkoutUrl) {
+        console.error("Ask a company owner to upgrade before creating an agent.");
+        return;
+    }
+    // Deliberately plain and on its own line so terminals make this clickable.
+    console.log(planLimit.checkoutUrl);
+    if (canOfferAgentCheckout(opts.json))
+        await offerAgentCheckout(planLimit.checkoutUrl);
+}
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the
  * offending input and the legal set.
@@ -112,12 +203,15 @@ export class AgentsHttpError extends Error {
     code;
     /** hq-pro's billing envelope on a `402 billing_required` provision block. */
     billing;
-    constructor(status, message, code, billing) {
+    /** Strictly decoded priced `403 AGENT_PLAN_LIMIT` create response. */
+    agentCreatePlanLimit;
+    constructor(status, message, code, billing, agentCreatePlanLimit) {
         super(message);
         this.name = "AgentsHttpError";
         this.status = status;
         this.code = code;
         this.billing = billing;
+        this.agentCreatePlanLimit = agentCreatePlanLimit;
     }
 }
 /**
@@ -134,7 +228,7 @@ export async function agentsRequest(opts) {
         // decline copy ("Your card was declined…") while `error` is the generic
         // "payment required" — error-first would feed surfaceBillingBlocked the
         // generic string and lose the decline reason (mirrors outpostRequest).
-        body.message ?? body.error ?? res.statusText, body.code, parseBillingPayload(body));
+        body.message ?? body.error ?? res.statusText, body.code, parseBillingPayload(body), agentCreatePlanLimitFromPayload(res.status, body) ?? undefined);
     }
     return (await res.json());
 }
@@ -242,7 +336,7 @@ export async function promptForAgentCreateSize(view) {
     }
 }
 /** Confirm creation using the server quote, preserving $0 as a real answer. */
-export function confirmAgentCreateQuoteOrExit(option, yes) {
+export function confirmAgentCreateQuoteOrExit(option, yes, quiet = false) {
     if (option.notBilled || option.netMonthlyCents === 0) {
         const message = `${option.productName} is ${formatUsd(0)}/month for this company — ` +
             "there is no per-agent charge.";
@@ -250,14 +344,26 @@ export function confirmAgentCreateQuoteOrExit(option, yes) {
             console.error(chalk.yellow(`${message}\nRe-run with --yes to confirm agent provisioning.`));
             process.exit(1);
         }
-        console.log(chalk.dim(`${message} Provisioning…`));
+        if (!quiet) {
+            console.log(chalk.dim(`${message} Provisioning…`));
+        }
         return;
     }
-    confirmChargeOrExit({
-        resource: "agent",
-        unitCents: option.netMonthlyCents,
-        yes,
-    });
+    if (!quiet) {
+        confirmChargeOrExit({
+            resource: "agent",
+            unitCents: option.netMonthlyCents,
+            yes,
+        });
+        return;
+    }
+    if (!yes) {
+        confirmChargeOrExit({
+            resource: "agent",
+            unitCents: option.netMonthlyCents,
+            yes,
+        });
+    }
 }
 export async function provisionAgent(token, input) {
     return agentsRequest({
@@ -764,7 +870,7 @@ export function registerAgentsCommand(program) {
     });
     agents
         .command("provision <name>")
-        .alias("new")
+        .aliases(["new", "create"])
         .description("Provision a new cloud agent (company-specific monthly price shown before creation)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
@@ -775,6 +881,7 @@ export function registerAgentsCommand(program) {
         .option("--description <text>", "Short description / bio")
         .option("--size <size>", "Agent box size: basic | power | dev (omitted keeps the current default)")
         .option("--yes", "Confirm the quoted monthly cost and provision the agent")
+        .option("--json", "Emit machine-readable output and never open a browser")
         .action(async function (name, opts) {
         try {
             // Both of these previously fell back to their default on an
@@ -818,12 +925,12 @@ export function registerAgentsCommand(program) {
                 : shouldChooseInteractively
                     ? await promptForAgentCreateSize(createOptions)
                     : requireDefaultAgentCreateSize(createOptions);
-            if (!shouldChooseInteractively) {
+            if (!shouldChooseInteractively && !opts.json) {
                 console.log(chalk.dim(formatAgentCreateSize(quotedSize)));
             }
             // Every path confirms hq-pro's company-specific quote. Omission still
             // leaves the POST size implicit, preserving the server-side default.
-            confirmAgentCreateQuoteOrExit(quotedSize, opts.yes);
+            confirmAgentCreateQuoteOrExit(quotedSize, opts.yes, opts.json);
             const slug = opts.slug ?? slugifyAgentName(name);
             try {
                 const result = await provisionAgent(token, {
@@ -849,10 +956,28 @@ export function registerAgentsCommand(program) {
                     surface: CLI_AGENT_CREATE_SURFACE,
                 });
                 const uid = typeof result.uid === "string" ? result.uid : slug;
-                console.log(chalk.green(`Provisioning started for agent "${name}".`));
-                console.log(chalk.dim(`Track setup: hq agents status ${uid} --company <slug>`));
+                if (opts.json) {
+                    console.log(JSON.stringify(result));
+                }
+                else {
+                    console.log(chalk.green(`Provisioning started for agent "${name}".`));
+                    console.log(chalk.dim(`Track setup: hq agents status ${uid} --company <slug>`));
+                }
             }
             catch (err) {
+                if (err instanceof AgentsHttpError &&
+                    err.status === 403 &&
+                    err.code === "AGENT_PLAN_LIMIT") {
+                    if (!err.agentCreatePlanLimit) {
+                        throw new Error("HQ Pro returned an unrecognized agent payment-required response.");
+                    }
+                    await surfaceAgentCreatePlanLimit(err.agentCreatePlanLimit, opts);
+                    // Keep the payment-required status through normal CLI teardown.
+                    // Unlike process.exit(), this is testable and cannot be caught by
+                    // this action's outer error boundary as a generic failure.
+                    process.exitCode = AGENT_CREATE_PAYMENT_REQUIRED_EXIT_CODE;
+                    return;
+                }
                 // No card on file → surface the shareable payment link instead of an
                 // opaque 402, then exit non-zero so scripts can react.
                 if (err instanceof AgentsHttpError &&

package/dist/lib/workers-registry/index.js

@@ -124,6 +124,32 @@ function registryText(now, entries) {
 function withoutTimestamp(content) {
     return content.split('\n').filter((line) => !line.startsWith('generated_at:')).join('\n');
 }
+/**
+ * Worker roots hold two kinds of `worker.yaml` that must never reach the
+ * registry.
+ *
+ * The `_template` company and any `_overrides` directory are scaffolding —
+ * copies kept so a new tenant or a pack override can be stamped out from them.
+ *
+ * A checkout nested under a tenant's `repos/` is a source repository that tenant
+ * happens to keep inside HQ, and when that repository is HQ itself, its own
+ * `core/workers` and template trees are full of worker.yaml files. Indexing them
+ * treats product source as deployed workers: they claim ids real workers already
+ * own, and because duplicates resolve by path order — a tenant path sorts before
+ * both `core` and `personal` — the checkout wins. The operator's actual worker
+ * then silently vanishes from the registry every skill reads.
+ */
+function isExcludedWorkerPath(relativeFile) {
+    const normalized = relativeFile.replaceAll('\\', '/');
+    const [root, tenant, nested] = normalized.split('/');
+    if (root !== 'companies')
+        return /(?:^|\/)_overrides(?:\/|$)/.test(normalized);
+    if (tenant === '_template')
+        return true;
+    if (nested === 'repos')
+        return true;
+    return /(?:^|\/)_overrides(?:\/|$)/.test(normalized);
+}
 /**
  * Generate core/workers/registry.yaml from worker.yaml files. Invalid workers
  * are quarantined but do not prevent all valid workers from being registered.
@@ -138,7 +164,7 @@ export function generateWorkersRegistry(hqRoot, options = {}) {
         ...workerYamlFiles(hqRoot, 'personal/workers'),
     ].sort();
     for (const relativeFile of files) {
-        if (relativeFile.startsWith('companies/_template/') || /(?:^|[/\\])_overrides(?:[/\\]|$)/.test(relativeFile))
+        if (isExcludedWorkerPath(relativeFile))
             continue;
         const fields = readWorkerFields(path.join(hqRoot, relativeFile));
         const missing = ['id', 'type', 'description'].filter((key) => !fields[key]);

package/dist/startup-registration.d.ts

@@ -35,6 +35,24 @@ export declare const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90000;
 export declare const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish\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;

package/dist/startup-registration.js

@@ -19,7 +19,7 @@
 import { spawnSync } from "node:child_process";
 import { resolveRunningInstall } from "./utils/version-gate.js";
 import { stringDerivedPackageRoot } from "./utils/hq-roots.js";
-import { updateLockPath } from "./utils/update-lock.js";
+import { updateLockPath, UPDATE_LOCK_STALE_MS } from "./utils/update-lock.js";
 import { classifyModuleNotFound, InstallTreeTornError, waitForInstallTreeSettled, } from "./utils/install-tree-torn.js";
 /**
  * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
@@ -46,6 +46,31 @@ export function resolveSettleTimeoutMs(env) {
         return DEFAULT_INSTALL_SETTLE_TIMEOUT_MS;
     return Number.parseInt(raw.trim(), 10);
 }
+/** Operator override for the settle wait's LOCK ceiling (time under a live writer). */
+export 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 const DEFAULT_INSTALL_SETTLE_LOCK_TIMEOUT_MS = UPDATE_LOCK_STALE_MS;
+/**
+ * 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 const INSTALL_TREE_LOCK_WAIT_NOTICE = "hq: another hq updater is still installing hq-cli; waiting for it to finish…";
+/** Resolve the lock ceiling from the environment (0 = do not extend; default on invalid). */
+export function resolveSettleLockTimeoutMs(env) {
+    const raw = env[INSTALL_SETTLE_LOCK_TIMEOUT_ENV];
+    if (typeof raw !== "string" || raw.trim() === "")
+        return DEFAULT_INSTALL_SETTLE_LOCK_TIMEOUT_MS;
+    if (!/^\d+$/.test(raw.trim()))
+        return DEFAULT_INSTALL_SETTLE_LOCK_TIMEOUT_MS;
+    return Number.parseInt(raw.trim(), 10);
+}
 /**
  * Register commands, recovering once from a torn-install module-resolution
  * failure. On a clean registration this returns `{}` and touches nothing else.
@@ -90,17 +115,27 @@ export async function registerCommandsWithRecovery(args) {
             packageRoot,
             lockPath,
             deadlineMs: resolveSettleTimeoutMs(env),
+            lockWaitMs: resolveSettleLockTimeoutMs(env),
+            onLockExtended: () => stderr.write(`${INSTALL_TREE_LOCK_WAIT_NOTICE}\n`),
         });
         if (!result.settled) {
             throw new InstallTreeTornError({
                 cause: err,
                 classified,
                 packageRoot,
-                outcome: "unsettled",
+                // A fresh foreign lock still held at the end means a live cooperating
+                // writer held the shared lock past its own ceiling — report 'lock-held'
+                // (its remedy tells the user to let the update finish, never to reinstall
+                // over it). Otherwise the tree genuinely never settled with no writer
+                // visible, which keeps meaning 'unsettled'.
+                outcome: result.lockHeldAtEnd ? "lock-held" : "unsettled",
                 attempt: 1,
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                lockHeldAtEnd: result.lockHeldAtEnd,
+                lockedMs: result.lockedMs,
+                lockTool: result.lockTool,
             });
         }
         const spawn = deps.spawn ?? spawnSync;

package/dist/utils/install-tree-torn.d.ts

@@ -46,19 +46,28 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "
  *                    '<abs>'` + `requireStack`.
  *   - `cjs-package`: CJS require of a bare specifier — `Cannot find module
  *                    '<name>'` + `requireStack`.
+ *   - `cjs-relative`: CJS require of a RELATIVE specifier — `Cannot find module
+ *                    './x'` (or `../x`) + `requireStack`. Node reports the RAW
+ *                    relative token, never a resolved path, so it is re-resolved
+ *                    from the importer's directory rather than reduced by
+ *                    packageNameOf (which would yield the un-probeable name `.`).
  *   - `esm-enoent`:  ESM loader ENOENT (HQ-CLI-1M) — a module present at RESOLVE
  *                    and gone at READ, so getSourceSync/openSync raises ENOENT
  *                    (not ERR_MODULE_NOT_FOUND). `err.path` is the vanished file.
  *   - `unknown`:     a module-not-found whose message did not parse; recovery
  *                    still waits on the lock / retired-dir / quiet signals.
  */
-export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "esm-enoent" | "unknown";
+export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "cjs-relative" | "esm-enoent" | "unknown";
 /**
  * The missing thing, re-resolvable by the readiness probe:
- *   - `path`:    an absolute filesystem path (a `.js` file, or a package dir).
- *   - `package`: a bare package `name` resolvable from directory `from` upward.
- *   - `unknown`: the message did not parse; treated as "present" by the probe so
- *                readiness turns only on the lock / retired-dir / quiet signals.
+ *   - `path`:     an absolute filesystem path (a `.js` file, or a package dir).
+ *   - `package`:  a bare package `name` resolvable from directory `from` upward.
+ *   - `relative`: a RELATIVE `specifier` (`./x`, `../x`) re-resolved the way
+ *                 Node's CJS resolver does from directory `from` —
+ *                 `path.resolve(from, specifier)` plus the `.js`/`.json`/`.node`
+ *                 and directory forms.
+ *   - `unknown`:  the message did not parse; treated as "present" by the probe so
+ *                 readiness turns only on the lock / retired-dir / quiet signals.
  */
 export type ModuleErrorTarget = {
     kind: "path";
@@ -67,6 +76,10 @@ export type ModuleErrorTarget = {
     kind: "package";
     name: string;
     from: string;
+} | {
+    kind: "relative";
+    specifier: string;
+    from: string;
 } | {
     kind: "unknown";
 };
@@ -115,10 +128,24 @@ export interface InstallTreeFs {
  *                exact ancestor walk `getPackageJSONURL` performs, done WITHOUT
  *                `createRequire` so an ESM-only / export-conditioned package
  *                cannot false-negative.
+ *   - `relative`: re-resolve `path.resolve(from, specifier)` as Node's CJS
+ *                require would — a real file (exact / `.js` / `.json` / `.node`),
+ *                or a directory whose package.json `main` (or that main's index)
+ *                or own `index.*` is a real file. A bare or partially-extracted
+ *                directory is NOT loadable and reads as not-present.
  *   - `unknown`: true (readiness turns on the other signals).
  * Any filesystem error reads as "not present" rather than throwing.
  */
 export declare function installTargetPresent(target: ModuleErrorTarget, fs?: InstallTreeFs): boolean;
+/**
+ * Default ceiling on the CUMULATIVE time the wait may spend observing a FRESH
+ * foreign lock held by a live pid. Equal to the shared update-lock contract's own
+ * staleness window ({@link UPDATE_LOCK_STALE_MS} — "no healthy npm install -g of
+ * this package runs 10 minutes"), so the wait trusts a live cooperating writer for
+ * exactly as long as the contract legitimises holding the lock, and never longer.
+ * Overridable by the seam (env HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS).
+ */
+export declare const DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS: number;
 export interface WaitForInstallTreeSettledArgs {
     target: ModuleErrorTarget;
     /** The running install's package dir (from resolveRunningInstall), or null. */
@@ -132,6 +159,22 @@ export interface WaitForInstallTreeSettledArgs {
     pollMs?: number;
     quietMs?: number;
     deadlineMs: number;
+    /**
+     * Ceiling on the CUMULATIVE time observed under a FRESH foreign lock held by a
+     * live pid. Locked time does NOT consume `deadlineMs` (the budget for the tree
+     * to settle once no cooperating writer is visible); it is bounded separately by
+     * this ceiling so the wait can never hang. Defaults to
+     * {@link DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS}.
+     */
+    lockWaitMs?: number;
+    /**
+     * Invoked exactly once — at the first poll where the total wait has reached
+     * `deadlineMs` while a fresh foreign lock is still held (the moment the
+     * pre-lock-aware wait would have given up). Lets the seam print a one-line
+     * notice that the pause is a live updater, not a hang. Never invoked when no
+     * lock is seen or the lock clears before the deadline.
+     */
+    onLockExtended?: () => void;
 }
 export interface WaitForInstallTreeSettledResult {
     settled: boolean;
@@ -140,20 +183,46 @@ export interface WaitForInstallTreeSettledResult {
     sawLock: boolean;
     /** An npm retired/staging sibling (`.hq-cli-<rand>`) was observed at least once. */
     sawRetired: boolean;
+    /** A fresh foreign lock was held on the FINAL poll of an unsettled wait. */
+    lockHeldAtEnd: boolean;
+    /** Cumulative wall time observed under a fresh foreign lock held by a live pid. */
+    lockedMs: number;
+    /** The bounded `tool` of the last fresh foreign lock seen, or "" if none. */
+    lockTool: string;
 }
 /**
  * Poll until the install tree has been continuously READY for `quietMs`, or the
- * `deadlineMs` passes. READY means: (i) no FRESH update lock held by another pid,
- * (ii) the missing target is present, and — when `packageRoot` is known —
- * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and
- * (iv) no `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem
- * error makes its condition "not ready" rather than throwing. `deadlineMs === 0`
- * evaluates readiness exactly once (no waiting); otherwise the whole wait is
- * bounded, so the caller can never hang.
+ * wait exhausts its bounds. READY means: (i) no FRESH update lock held by another
+ * pid, (ii) the missing target is present, and — when `packageRoot` is known —
+ * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and (iv) no
+ * `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem error makes
+ * its condition "not ready" rather than throwing.
+ *
+ * The wait is LOCK-AWARE and bounded on TWO independent axes, so a live
+ * cooperating writer (the desktop app, the box's update timer, another `hq`)
+ * cannot make a legitimately-in-progress reinstall look like a torn install:
+ *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
+ *     by `deadlineMs`. That is the budget for the TREE to settle once no writer is
+ *     visible; with no lock ever seen, unlocked time equals total wait time and
+ *     the behaviour is byte-for-byte the pre-lock-aware one (unsettled at exactly
+ *     `deadlineMs`, and `deadlineMs === 0` evaluates readiness exactly once).
+ *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
+ *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
+ *     10-minute staleness window) and does NOT consume the settle budget. When
+ *     that ceiling is reached with the lock still held, the result is unsettled
+ *     with `lockHeldAtEnd` true so the seam can report a distinct `lock-held`
+ *     outcome and remedy rather than telling the user to reinstall over a live
+ *     writer.
+ * Each poll's REAL elapsed interval (now() deltas) is attributed to the locked or
+ * unlocked bucket by whether a fresh foreign lock was held when the interval
+ * began, so a starved event loop only makes the wait coarser, never unbounded. A
+ * stale lock (dead pid, older than the staleness window, unparseable) or our own
+ * pid never extends anything. The whole wait is bounded (≤ `deadlineMs +
+ * lockWaitMs`), so the caller can never hang.
  */
 export declare function waitForInstallTreeSettled(args: WaitForInstallTreeSettledArgs): Promise<WaitForInstallTreeSettledResult>;
 /** The recovery OUTCOME, which — not the dialect — decides capture. */
-export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed";
+export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed" | "lock-held";
 export type InstallTreeTornDiagnostics = {
     dialect: ModuleErrorDialect;
     code: ModuleNotFoundCode;
@@ -165,6 +234,12 @@ export type InstallTreeTornDiagnostics = {
     waitedMs: number;
     sawLock: boolean;
     sawRetired: boolean;
+    /** A fresh foreign lock was still held when the wait gave up (→ 'lock-held'). */
+    lockHeldAtEnd: boolean;
+    /** Cumulative wall time the wait spent under a fresh foreign lock. */
+    lockedMs: number;
+    /** The bounded `tool` of the last fresh foreign lock seen, or "". */
+    lockTool: string;
     node: string;
 };
 export interface InstallTreeTornInit {
@@ -177,6 +252,12 @@ export interface InstallTreeTornInit {
     waitedMs: number;
     sawLock: boolean;
     sawRetired: boolean;
+    /** Whether a fresh foreign lock was held when the wait gave up (default false). */
+    lockHeldAtEnd?: boolean;
+    /** Cumulative time under a fresh foreign lock (default 0). */
+    lockedMs?: number;
+    /** The last fresh foreign lock's `tool`, bounded on construction (default ""). */
+    lockTool?: string;
 }
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
@@ -203,10 +284,20 @@ export declare function installTreeTornCaptureContext(err: InstallTreeTornError)
  * appended by {@link installTreeTornStderrLine}.
  */
 export declare const INSTALL_TREE_TORN_REMEDY: string;
+/**
+ * The fixed, input-free remedy for the 'lock-held' outcome: a cooperating writer
+ * held the shared update lock past its own staleness ceiling. Telling the user to
+ * `npm i -g` here would collide with a live installer mid-rename — the exact race
+ * update-lock.ts exists to prevent — so this remedy tells them to let the running
+ * update finish and NEVER to reinstall over it. Interpolates NOTHING.
+ */
+export declare const INSTALL_TREE_LOCK_HELD_REMEDY: string;
 /**
  * The single actionable stderr line for a captured torn-install failure: the
- * fixed remedy plus the bounded, hq-derived missing specifier — the only
- * interpolated value, never argv.
+ * outcome's fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv. A 'lock-held' outcome selects the "let the
+ * update finish" remedy (never the reinstall advice); every other outcome keeps
+ * {@link INSTALL_TREE_TORN_REMEDY} byte-for-byte.
  */
 export declare function installTreeTornStderrLine(err: InstallTreeTornError): string;
 //# sourceMappingURL=install-tree-torn.d.ts.map

package/dist/utils/install-tree-torn.js

@@ -34,11 +34,13 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { CLI_NAME } from "../cli-version.js";
 import { boundedDiagnosticValue } from "./package-root-diagnostics.js";
-import { isLockStale } from "./update-lock.js";
+import { isLockStale, UPDATE_LOCK_STALE_MS } from "./update-lock.js";
 /** Byte caps for the (hq-derived, path-shaped) diagnostic strings. */
 const SPECIFIER_BYTES = 256;
 const IMPORTER_BYTES = 256;
 const PACKAGE_ROOT_BYTES = 256;
+/** Byte cap for the lock holder's `tool` (the only foreign string this reads). */
+const LOCK_TOOL_BYTES = 64;
 const ESM_PACKAGE_RE = /^Cannot find package '([^']+)' imported from (.+)$/s;
 const CJS_MODULE_RE = /^Cannot find module '([^']+)'/s;
 const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)$/s;
@@ -52,6 +54,13 @@ const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)
  * the settle wait. `load\b` also excludes the sibling `esm/loader` module.
  */
 const ESM_LOADER_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]load\b/;
+/**
+ * A relative module specifier — `./x`, `../x`, `.\x`, `..\x`, or a bare `.`/`..`.
+ * Mirrors the shape src/utils/incomplete-install-error.ts uses, extended with the
+ * bare-`.`/`..` case so a token that packageNameOf would reduce to the
+ * un-probeable name `.` is caught here and re-resolved instead.
+ */
+const RELATIVE_CJS_SPECIFIER = /^\.\.?([\\/]|$)/;
 /**
  * Reduce a bare specifier to its PACKAGE name: `@scope/name/sub` → `@scope/name`,
  * `name/sub` → `name`, `name` → `name`. This is the unit the readiness probe
@@ -64,6 +73,20 @@ export function packageNameOf(specifier) {
         return parts.slice(0, 2).join("/");
     return parts[0] ?? specifier;
 }
+/**
+ * Build a `package` target from an already-reduced name, UNLESS that name is not
+ * a plausible bare package: empty, a relative token reduced to `.`/`..`, or a
+ * subpath-imports token (`#internal`). Each of those reduces to a name whose
+ * `node_modules/<name>/package.json` ancestor probe can NEVER be true, so it
+ * falls back to `unknown` — readiness then turns on the lock / retired-dir /
+ * quiet signals rather than a probe that stays permanently false.
+ */
+function barePackageTarget(name, from) {
+    if (name.length === 0 || name.startsWith(".") || name.startsWith("#")) {
+        return { kind: "unknown" };
+    }
+    return { kind: "package", name, from };
+}
 /**
  * Classify a thrown value as a module-resolution failure and extract the missing
  * target, or return `null` for anything that is not one. The decision is
@@ -128,7 +151,7 @@ export function classifyModuleNotFound(err) {
             dialect: "esm-package",
             specifier: spec,
             importer,
-            target: { kind: "package", name: spec, from: path.dirname(importer) },
+            target: barePackageTarget(spec, path.dirname(importer)),
         };
     }
     // (c) CJS `Cannot find module '<spec>'` (+ Require stack). Absolute → a path
@@ -142,12 +165,32 @@ export function classifyModuleNotFound(err) {
             if (path.isAbsolute(spec)) {
                 return { code, dialect: "cjs-path", specifier: spec, importer, target: { kind: "path", path: spec } };
             }
+            // Relative specifier (`./x`, `../x`): Node reports the RAW token, so
+            // packageNameOf would reduce it to `.`/`..` and build a package target
+            // whose ancestor probe can never be true. Re-resolve it from the importer's
+            // directory, and report the RESOLVED path as the diagnostic specifier
+            // (actionable — the missing sibling's real location), mirroring esm-path.
+            if (RELATIVE_CJS_SPECIFIER.test(spec)) {
+                if (importer && path.isAbsolute(importer)) {
+                    const from = path.dirname(importer);
+                    return {
+                        code,
+                        dialect: "cjs-relative",
+                        specifier: path.resolve(from, spec),
+                        importer,
+                        target: { kind: "relative", specifier: spec, from },
+                    };
+                }
+                // No usable (absolute) importer survived — fall back to the lock /
+                // retired-dir / quiet signals rather than a probe that cannot be true.
+                return { code, dialect: "cjs-relative", specifier: spec, importer, target: { kind: "unknown" } };
+            }
             return {
                 code,
                 dialect: "cjs-package",
                 specifier: spec,
                 importer,
-                target: { kind: "package", name: packageNameOf(spec), from: path.dirname(importer) },
+                target: barePackageTarget(packageNameOf(spec), path.dirname(importer)),
             };
         }
     }
@@ -179,6 +222,58 @@ function defaultIsPidAlive(pid) {
         return err.code === "EPERM";
     }
 }
+/** CJS extensions Node's LOAD_AS_FILE / LOAD_INDEX try, in order. */
+const CJS_FILE_EXTENSIONS = [".js", ".json", ".node"];
+/** Whether `p` exists AND is a regular file (not a directory); any fs error → false. */
+function isResolvableFile(p, fs) {
+    try {
+        return fs.existsSync(p) && !fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Node's LOAD_AS_FILE(X): X itself, then X + each CJS extension — each must be a file. */
+function loadAsFile(base, fs) {
+    if (isResolvableFile(base, fs))
+        return true;
+    return CJS_FILE_EXTENSIONS.some((ext) => isResolvableFile(base + ext, fs));
+}
+/** Node's LOAD_INDEX(X): X/index.{js,json,node} — each must be a file. */
+function loadIndex(dir, fs) {
+    return CJS_FILE_EXTENSIONS.some((ext) => isResolvableFile(path.join(dir, `index${ext}`), fs));
+}
+/**
+ * Whether a relative target's resolved `base` is loadable exactly as Node's CJS
+ * require would load it: LOAD_AS_FILE(base), else LOAD_AS_DIRECTORY(base) — its
+ * package.json `main` resolved as a file (or that main's index), else
+ * base/index.*. A bare or partially-extracted directory — one that holds neither
+ * a resolvable `main` nor an index file — is deliberately NOT loadable, so it
+ * reads as not-present and the single re-exec cannot fire on a still-torn tree
+ * (mirrors the MODULE_NOT_FOUND Node would still throw for that state).
+ */
+function relativeTargetResolvable(base, fs) {
+    if (loadAsFile(base, fs))
+        return true;
+    const manifest = path.join(base, "package.json");
+    if (isResolvableFile(manifest, fs)) {
+        let main = null;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+            if (typeof parsed.main === "string" && parsed.main.trim() !== "")
+                main = parsed.main;
+        }
+        catch {
+            main = null; // unreadable / unparseable manifest — fall back to index.*
+        }
+        if (main !== null) {
+            const mainBase = path.resolve(base, main);
+            if (loadAsFile(mainBase, fs) || loadIndex(mainBase, fs))
+                return true;
+        }
+    }
+    return loadIndex(base, fs);
+}
 /**
  * Whether the missing target is now present on disk — the readiness signal the
  * settle wait polls. It re-resolves the SAME step Node's resolver took:
@@ -189,6 +284,11 @@ function defaultIsPidAlive(pid) {
  *                exact ancestor walk `getPackageJSONURL` performs, done WITHOUT
  *                `createRequire` so an ESM-only / export-conditioned package
  *                cannot false-negative.
+ *   - `relative`: re-resolve `path.resolve(from, specifier)` as Node's CJS
+ *                require would — a real file (exact / `.js` / `.json` / `.node`),
+ *                or a directory whose package.json `main` (or that main's index)
+ *                or own `index.*` is a real file. A bare or partially-extracted
+ *                directory is NOT loadable and reads as not-present.
  *   - `unknown`: true (readiness turns on the other signals).
  * Any filesystem error reads as "not present" rather than throwing.
  */
@@ -209,6 +309,15 @@ export function installTargetPresent(target, fs = nodeInstallTreeFs) {
             }
             return true;
         }
+        if (target.kind === "relative") {
+            // Re-resolve exactly as Node's CJS require would from `from`, so the probe
+            // turns true only when the missing module is ACTUALLY loadable again — a
+            // bare or partially-extracted directory must not read as present, or the
+            // single re-exec would fire on a still-torn tree. The extensionless case
+            // matters — a production sibling shape (`./Base/TreeIterator`, HQ-CLI-1N)
+            // carries no extension, so an exact-path-only probe would stay false for it.
+            return relativeTargetResolvable(path.resolve(target.from, target.specifier), fs);
+        }
         // package: ancestor walk from `from`.
         let dir = path.resolve(target.from);
         for (;;) {
@@ -225,6 +334,15 @@ export function installTargetPresent(target, fs = nodeInstallTreeFs) {
         return false;
     }
 }
+/**
+ * Default ceiling on the CUMULATIVE time the wait may spend observing a FRESH
+ * foreign lock held by a live pid. Equal to the shared update-lock contract's own
+ * staleness window ({@link UPDATE_LOCK_STALE_MS} — "no healthy npm install -g of
+ * this package runs 10 minutes"), so the wait trusts a live cooperating writer for
+ * exactly as long as the contract legitimises holding the lock, and never longer.
+ * Overridable by the seam (env HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS).
+ */
+export const DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS = UPDATE_LOCK_STALE_MS;
 /** The scope/leaf split of CLI_NAME, e.g. `@indigoai-us` / `hq-cli`. */
 function cliNameParts() {
     const slash = CLI_NAME.indexOf("/");
@@ -232,26 +350,32 @@ function cliNameParts() {
         return { scope: null, leaf: CLI_NAME };
     return { scope: CLI_NAME.slice(0, slash), leaf: CLI_NAME.slice(slash + 1) };
 }
-/** Whether a FRESH update lock is held by a DIFFERENT live pid (blocks readiness). */
-function freshForeignLockHeld(lockPath, nowMs, isPidAlive, fs) {
+/**
+ * The FRESH update lock held by a DIFFERENT live pid, or null. A non-null result
+ * blocks readiness AND extends the wait under the lock ceiling; the lock file is
+ * only ever READ. Freshness is decided by {@link isLockStale} exactly as before
+ * (parseable, `startedAt` younger than {@link UPDATE_LOCK_STALE_MS}, pid alive),
+ * and our own pid never counts.
+ */
+function freshForeignLock(lockPath, nowMs, isPidAlive, fs) {
     let raw;
     try {
         raw = fs.readFileSync(lockPath, "utf-8");
     }
     catch {
-        return false; // no lock (ENOENT) or unreadable — not a fresh foreign holder
+        return null; // no lock (ENOENT) or unreadable — not a fresh foreign holder
     }
     if (isLockStale(raw, nowMs, isPidAlive))
-        return false;
+        return null;
     try {
         const info = JSON.parse(raw);
         if (info.pid === process.pid)
-            return false; // our own lock never blocks us
+            return null; // our own lock never blocks us
+        return info;
     }
     catch {
-        return false; // isLockStale already treats unparseable as stale, unreachable
+        return null; // isLockStale already treats unparseable as stale, unreachable
     }
-    return true;
 }
 /** Whether an npm retired/staging sibling (`.<leaf>-*`) sits beside packageRoot. */
 function retiredSiblingPresent(packageRoot, fs) {
@@ -268,13 +392,33 @@ function packageRootHealthy(packageRoot, fs) {
 }
 /**
  * Poll until the install tree has been continuously READY for `quietMs`, or the
- * `deadlineMs` passes. READY means: (i) no FRESH update lock held by another pid,
- * (ii) the missing target is present, and — when `packageRoot` is known —
- * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and
- * (iv) no `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem
- * error makes its condition "not ready" rather than throwing. `deadlineMs === 0`
- * evaluates readiness exactly once (no waiting); otherwise the whole wait is
- * bounded, so the caller can never hang.
+ * wait exhausts its bounds. READY means: (i) no FRESH update lock held by another
+ * pid, (ii) the missing target is present, and — when `packageRoot` is known —
+ * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and (iv) no
+ * `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem error makes
+ * its condition "not ready" rather than throwing.
+ *
+ * The wait is LOCK-AWARE and bounded on TWO independent axes, so a live
+ * cooperating writer (the desktop app, the box's update timer, another `hq`)
+ * cannot make a legitimately-in-progress reinstall look like a torn install:
+ *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
+ *     by `deadlineMs`. That is the budget for the TREE to settle once no writer is
+ *     visible; with no lock ever seen, unlocked time equals total wait time and
+ *     the behaviour is byte-for-byte the pre-lock-aware one (unsettled at exactly
+ *     `deadlineMs`, and `deadlineMs === 0` evaluates readiness exactly once).
+ *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
+ *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
+ *     10-minute staleness window) and does NOT consume the settle budget. When
+ *     that ceiling is reached with the lock still held, the result is unsettled
+ *     with `lockHeldAtEnd` true so the seam can report a distinct `lock-held`
+ *     outcome and remedy rather than telling the user to reinstall over a live
+ *     writer.
+ * Each poll's REAL elapsed interval (now() deltas) is attributed to the locked or
+ * unlocked bucket by whether a fresh foreign lock was held when the interval
+ * began, so a starved event loop only makes the wait coarser, never unbounded. A
+ * stale lock (dead pid, older than the staleness window, unparseable) or our own
+ * pid never extends anything. The whole wait is bounded (≤ `deadlineMs +
+ * lockWaitMs`), so the caller can never hang.
  */
 export async function waitForInstallTreeSettled(args) {
     const now = args.now ?? Date.now;
@@ -284,16 +428,32 @@ export async function waitForInstallTreeSettled(args) {
     const pollMs = args.pollMs ?? 250;
     const quietMs = args.quietMs ?? 1500;
     const deadlineMs = args.deadlineMs;
+    const lockWaitMs = args.lockWaitMs ?? DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS;
     const start = now();
     let readySince = null;
     let sawLock = false;
     let sawRetired = false;
+    let lockedMs = 0;
+    let unlockedMs = 0;
+    let lockTool = "";
+    let prevT = start;
+    let prevForeignLockHeld = false;
+    let lockExtendedFired = false;
     for (;;) {
         const t = now();
-        const foreignLock = freshForeignLockHeld(args.lockPath, t, isPidAlive, fs);
-        if (foreignLock)
+        // Attribute the interval that just elapsed [prevT, t) to the bucket for the
+        // lock state that held when it BEGAN (real now() deltas, never nominal pollMs).
+        if (prevForeignLockHeld)
+            lockedMs += t - prevT;
+        else
+            unlockedMs += t - prevT;
+        const lock = freshForeignLock(args.lockPath, t, isPidAlive, fs);
+        const foreignLockHeld = lock !== null;
+        if (foreignLockHeld) {
             sawLock = true;
-        let ready = !foreignLock && installTargetPresent(args.target, fs);
+            lockTool = boundedDiagnosticValue(lock.tool, LOCK_TOOL_BYTES);
+        }
+        let ready = !foreignLockHeld && installTargetPresent(args.target, fs);
         if (ready && args.packageRoot) {
             try {
                 if (!packageRootHealthy(args.packageRoot, fs))
@@ -323,11 +483,29 @@ export async function waitForInstallTreeSettled(args) {
         }
         const waitedMs = t - start;
         if (ready && (deadlineMs === 0 || t - readySince >= quietMs)) {
-            return { settled: true, waitedMs, sawLock, sawRetired };
+            // Settling requires no foreign lock, so it is never held at the end here.
+            return { settled: true, waitedMs, sawLock, sawRetired, lockHeldAtEnd: false, lockedMs, lockTool };
+        }
+        // Give up when the TREE has had a full unlocked budget with no writer visible,
+        // OR a writer is STILL holding the lock and has held it past its own staleness
+        // ceiling. The lock ceiling is gated on a lock being held RIGHT NOW so that a
+        // ceiling of 0 (HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS=0, "do not extend under a
+        // lock") disables only the extension and does not collapse the ordinary
+        // deadlineMs settle when no lock exists — `lockedMs` is 0 ≥ 0 on every poll.
+        // `deadlineMs` 0 makes the unlocked test fire on the first poll (evaluate-once),
+        // matching the pre-lock-aware contract; `lockHeldAtEnd` distinguishes the causes.
+        if (unlockedMs >= deadlineMs || (foreignLockHeld && lockedMs >= lockWaitMs)) {
+            return { settled: false, waitedMs, sawLock, sawRetired, lockHeldAtEnd: foreignLockHeld, lockedMs, lockTool };
         }
-        if (waitedMs >= deadlineMs) {
-            return { settled: false, waitedMs, sawLock, sawRetired };
+        // The first poll at which the wait has reached `deadlineMs` while a lock is
+        // still held is exactly where the pre-lock-aware wait gave up — announce the
+        // extension once, and only when we are genuinely going to keep waiting.
+        if (!lockExtendedFired && foreignLockHeld && waitedMs >= deadlineMs) {
+            lockExtendedFired = true;
+            args.onLockExtended?.();
         }
+        prevT = t;
+        prevForeignLockHeld = foreignLockHeld;
         await sleep(pollMs);
     }
 }
@@ -357,6 +535,9 @@ export class InstallTreeTornError extends Error {
             waitedMs: init.waitedMs,
             sawLock: init.sawLock,
             sawRetired: init.sawRetired,
+            lockHeldAtEnd: init.lockHeldAtEnd ?? false,
+            lockedMs: init.lockedMs ?? 0,
+            lockTool: boundedDiagnosticValue(init.lockTool ?? "", LOCK_TOOL_BYTES),
             node: process.version,
         };
         Object.setPrototypeOf(this, new.target.prototype);
@@ -379,15 +560,26 @@ export const INSTALL_TREE_TORN_REMEDY = "the hq-cli install was being updated by
     "timer, the desktop app, or another hq command) while this command started. " +
     "Re-run your command; if it keeps failing, reinstall with " +
     "`npm i -g @indigoai-us/hq-cli` (or `pnpm add -g @indigoai-us/hq-cli`).";
+/**
+ * The fixed, input-free remedy for the 'lock-held' outcome: a cooperating writer
+ * held the shared update lock past its own staleness ceiling. Telling the user to
+ * `npm i -g` here would collide with a live installer mid-rename — the exact race
+ * update-lock.ts exists to prevent — so this remedy tells them to let the running
+ * update finish and NEVER to reinstall over it. Interpolates NOTHING.
+ */
+export const INSTALL_TREE_LOCK_HELD_REMEDY = "another hq updater (the desktop app, the box's hq-cli-update timer, or another " +
+    "hq command) was still installing hq-cli when this command stopped waiting. Let " +
+    "that update finish, then re-run your command; do not reinstall while it is running.";
 /**
  * The single actionable stderr line for a captured torn-install failure: the
- * fixed remedy plus the bounded, hq-derived missing specifier — the only
- * interpolated value, never argv.
+ * outcome's fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv. A 'lock-held' outcome selects the "let the
+ * update finish" remedy (never the reinstall advice); every other outcome keeps
+ * {@link INSTALL_TREE_TORN_REMEDY} byte-for-byte.
  */
 export function installTreeTornStderrLine(err) {
+    const remedy = err.diagnostics.outcome === "lock-held" ? INSTALL_TREE_LOCK_HELD_REMEDY : INSTALL_TREE_TORN_REMEDY;
     const specifier = err.diagnostics.specifier;
-    return specifier
-        ? `${INSTALL_TREE_TORN_REMEDY} (missing: ${specifier})`
-        : INSTALL_TREE_TORN_REMEDY;
+    return specifier ? `${remedy} (missing: ${specifier})` : remedy;
 }
 //# sourceMappingURL=install-tree-torn.js.map

package/dist/utils/sentry-fingerprint.js

@@ -92,8 +92,8 @@ const KNOWN_ERROR_NAMES = new Set([
     // (HQ-CLI-1A).
     "QmdWorkdirMissingError",
     // A torn-install failure the bounded settle-wait + single re-exec could not
-    // recover (HQ-CLI-1G/1H/1J/1K). Fingerprinted on its own branch below by the
-    // bounded `diagnostics.outcome`, so the whole family groups into ≤3 issues.
+    // recover (HQ-CLI-1G/1H/1J/1K, HQ-CLI-1Y). Fingerprinted on its own branch below
+    // by the bounded `diagnostics.outcome`, so the whole family groups into ≤4 issues.
     "InstallTreeTornError",
 ]);
 /**
@@ -102,7 +102,7 @@ const KNOWN_ERROR_NAMES = new Set([
  * the carrier's message is fixed, so this outcome IS the only discriminator.
  */
 const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
-    "guarded", "unsettled", "reexec-failed",
+    "guarded", "unsettled", "reexec-failed", "lock-held",
 ]);
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";
@@ -214,8 +214,8 @@ export function sentryFingerprintFor(err) {
     }
     // A torn-install failure carries neither an rpcCode nor an HTTP status; its
     // only bounded discriminator is the recovery `diagnostics.outcome`. Keyed
-    // BEFORE the rpc/status branches so the family groups into ≤3 predictable
-    // issues (guarded / unsettled / reexec-failed) rather than one fungible bucket.
+    // BEFORE the rpc/status branches so the family groups into ≤4 predictable issues
+    // (guarded / unsettled / reexec-failed / lock-held) rather than one fungible bucket.
     if (rawName === "InstallTreeTornError") {
         const diagnostics = record.diagnostics;
         const outcome = diagnostics !== null && typeof diagnostics === "object"

package/package.json

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