@indigoai-us/hq-cli 5.300.0 → 5.301.0

package/dist/commands/lanes.d.ts

@@ -31,6 +31,8 @@ export { emitLaneDecisionEvents };
 export interface LanesCommandDeps {
     /** Test seam for failures after a lane provider worker is started. */
     onLaneWorkerStarted?: (laneId: string, command: "message" | "resume") => void;
+    /** Test seam for failures after a message is durably queued. */
+    onLaneMessageQueued?: (laneId: string, path: "admission" | "account_move") => void;
     hqRoot?: () => string;
     /** Start HQ-root walk here instead of process.cwd(). Tests only. */
     cwd?: () => string;

package/dist/commands/lanes.js

@@ -7838,6 +7838,7 @@ export function registerLanesCommand(parent, deps = {}) {
     });
     const messageHandlerDeps = {
         onLaneWorkerStarted: deps.onLaneWorkerStarted,
+        onLaneMessageQueued: deps.onLaneMessageQueued,
         archiveResumeMessage,
         assertLaneRunsHereForAdmission,
         assertLaneRunsHereForOperatorMutation,

package/dist/commands/meetings.js

@@ -3,6 +3,25 @@ import { readFile } from "node:fs/promises";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid, resolveCallerPersonUid, } from "../utils/vault-api.js";
 import { isPlanGateError, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
+// Two minutes gives a large transcript time to arrive over a slow connection,
+// while keeping the interactive command from waiting indefinitely.
+const MEETING_DOCUMENT_DOWNLOAD_TIMEOUT_MS = 120_000;
+async function downloadMeetingDocument(url, readBody) {
+    const signal = AbortSignal.timeout(MEETING_DOCUMENT_DOWNLOAD_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, { signal });
+        if (!response.ok)
+            return { response, ok: false };
+        return { response, ok: true, body: await readBody(response) };
+    }
+    catch (err) {
+        if ((signal.aborted && signal.reason instanceof DOMException && signal.reason.name === "TimeoutError") ||
+            (err instanceof DOMException && err.name === "TimeoutError")) {
+            throw new Error(`Meeting document download timed out after ${MEETING_DOCUMENT_DOWNLOAD_TIMEOUT_MS / 1000} seconds. Check your network connection and try again.`);
+        }
+        throw err;
+    }
+}
 function formatDuration(seconds) {
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);
@@ -495,12 +514,12 @@ export function registerMeetingsCommand(program) {
                     console.error(chalk.red("No document available for this meeting."));
                     process.exit(1);
                 }
-                const docRes = await fetch(documentUrl);
-                if (!docRes.ok) {
-                    console.error(chalk.red(`Failed to download meeting document (${docRes.status})`));
+                const download = await downloadMeetingDocument(documentUrl, (response) => response.text());
+                if (!download.ok) {
+                    console.error(chalk.red(`Failed to download meeting document (${download.response.status})`));
                     process.exit(1);
                 }
-                const markdown = await docRes.text();
+                const markdown = download.body;
                 if (meetings.opts().json) {
                     console.log(JSON.stringify({ meetingId: detail.meetingId, sourceShape: "markdown", markdown }, null, 2));
                     return;
@@ -513,12 +532,12 @@ export function registerMeetingsCommand(program) {
                 console.error(chalk.red("No document URL available for this meeting."));
                 process.exit(1);
             }
-            const docRes = await fetch(detail.documentUrl);
-            if (!docRes.ok) {
-                console.error(chalk.red(`Failed to download meeting document (${docRes.status})`));
+            const download = await downloadMeetingDocument(detail.documentUrl, (response) => response.json());
+            if (!download.ok) {
+                console.error(chalk.red(`Failed to download meeting document (${download.response.status})`));
                 process.exit(1);
             }
-            const doc = (await docRes.json());
+            const doc = download.body;
             if (meetings.opts().json) {
                 console.log(JSON.stringify(doc.transcript, null, 2));
                 return;
@@ -573,12 +592,12 @@ export function registerMeetingsCommand(program) {
                     console.log(chalk.yellow("No notes available for this meeting."));
                     return;
                 }
-                const docRes = await fetch(documentUrl);
-                if (!docRes.ok) {
-                    console.error(chalk.red(`Failed to download meeting document (${docRes.status})`));
+                const download = await downloadMeetingDocument(documentUrl, (response) => response.text());
+                if (!download.ok) {
+                    console.error(chalk.red(`Failed to download meeting document (${download.response.status})`));
                     process.exit(1);
                 }
-                const markdown = await docRes.text();
+                const markdown = download.body;
                 if (meetings.opts().json) {
                     console.log(JSON.stringify({ meetingId: detail.meetingId, sourceShape: "markdown", markdown }, null, 2));
                     return;
@@ -591,12 +610,12 @@ export function registerMeetingsCommand(program) {
                 console.error(chalk.red("No document URL available for this meeting."));
                 process.exit(1);
             }
-            const docRes = await fetch(detail.documentUrl);
-            if (!docRes.ok) {
-                console.error(chalk.red(`Failed to download meeting document (${docRes.status})`));
+            const download = await downloadMeetingDocument(detail.documentUrl, (response) => response.json());
+            if (!download.ok) {
+                console.error(chalk.red(`Failed to download meeting document (${download.response.status})`));
                 process.exit(1);
             }
-            const doc = (await docRes.json());
+            const doc = download.body;
             if (meetings.opts().json) {
                 console.log(JSON.stringify(doc.notes, null, 2));
                 return;

package/dist/commands/safe-extract.d.ts

@@ -111,10 +111,10 @@ export declare function assertLinkTargetContained(packDir: string, entryAbs: str
 /**
  * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
  * argv form, never a shell string, keeps hostile filenames out of shell syntax.
- * When the default-off compatibility flag is enabled, Windows drive paths use
- * a basename relative to the archive directory. GNU tar cannot parse `C:\\...`
- * as remote `host:path`, and Windows' bundled bsdtar accepts the same relative
- * argv without GNU-only `--force-local`.
+ * Windows drive paths use a basename relative to the archive directory by
+ * default. GNU tar cannot parse `C:\\...` as remote `host:path`, and Windows'
+ * bundled bsdtar accepts the same relative argv without GNU-only `--force-local`.
+ * Callers can still explicitly opt out with `useRelativeWindowsDrivePath: false`.
  */
 export declare function listTarball(tarballPath: string, opts?: Pick<SafeExtractOptions, 'platform' | 'useRelativeWindowsDrivePath' | 'execFileSync'>): TarEntry[];
 /**

package/dist/commands/safe-extract.js

@@ -35,7 +35,6 @@
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { installPathCompatibilityEnabled } from '../lib/install-path-compatibility-flag.js';
 export const DEFAULT_CAPS = {
     // A content pack is docs/skills/policies/small scripts. 256 MiB is already
     // generous; anything larger is almost certainly a bomb or a mistake.
@@ -218,14 +217,14 @@ function tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath)
 /**
  * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
  * argv form, never a shell string, keeps hostile filenames out of shell syntax.
- * When the default-off compatibility flag is enabled, Windows drive paths use
- * a basename relative to the archive directory. GNU tar cannot parse `C:\\...`
- * as remote `host:path`, and Windows' bundled bsdtar accepts the same relative
- * argv without GNU-only `--force-local`.
+ * Windows drive paths use a basename relative to the archive directory by
+ * default. GNU tar cannot parse `C:\\...` as remote `host:path`, and Windows'
+ * bundled bsdtar accepts the same relative argv without GNU-only `--force-local`.
+ * Callers can still explicitly opt out with `useRelativeWindowsDrivePath: false`.
  */
 export function listTarball(tarballPath, opts = {}) {
     const platform = opts.platform ?? process.platform;
-    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? installPathCompatibilityEnabled();
+    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? true;
     const location = tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath);
     const out = (opts.execFileSync ?? execFileSync)('tar', ['-tvf', location.archiveArg], {
         encoding: 'utf-8',
@@ -330,7 +329,7 @@ export function safeExtractTarball(tarballPath, finalDir, opts = {}) {
     }
     // Resolve once so listing and extraction use the same archive location.
     const platform = opts.platform ?? process.platform;
-    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? installPathCompatibilityEnabled();
+    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? true;
     const exec = opts.execFileSync ?? execFileSync;
     const location = tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath);
     // 1. Pre-flight against headers (no bytes written yet).

package/dist/lib/core-utils/token-usage-report.js

@@ -120,7 +120,7 @@ function comparison(projectDirs, before, after, minHours, json, stdout) {
 /** Print token usage totals from Claude session JSONL files. */
 export function tokenUsageReport(args = [], options = {}) {
     const { stdout, stderr } = ioFor(options);
-    let lastDays = 7, since = "", json = false, before = "", after = "", minHours = 0;
+    let lastDays = 7, since = "", json = false, before = "", after = "", minHours = 0, projectDir = options.projectDir, projectDirSeen = false;
     for (let index = 0; index < args.length;) {
         const arg = args[index];
         if (arg === "--last") {
@@ -149,8 +149,22 @@ export function tokenUsageReport(args = [], options = {}) {
             minHours = Number.parseFloat(args[index + 1] ?? "");
             index += 2;
         }
+        else if (arg === "--project-dir") {
+            const value = args[index + 1];
+            if (!value || value.startsWith("--")) {
+                line(stderr, "--project-dir requires a path");
+                return 1;
+            }
+            if (projectDirSeen) {
+                line(stderr, "--project-dir may be specified only once");
+                return 1;
+            }
+            projectDir = value;
+            projectDirSeen = true;
+            index += 2;
+        }
         else if (arg === "-h" || arg === "--help") {
-            stdout("token-usage-report.sh — Daily effective-token totals + top burners from Claude Code session JSONLs.\nUsage:\n  scripts/token-usage-report.sh                # last 7 days, table\n  scripts/token-usage-report.sh --last 14      # last 14 days\n  scripts/token-usage-report.sh --since 2026-05-01\n  scripts/token-usage-report.sh --json         # machine-readable\nEffective tokens weighting (matches weekly rate-limit volume):\n  input + 5×output + 1.25×cache_creation + 0.1×cache_read\n--- Compare-windows mode (US-011) ---\nFormat: --before YYYY-MM-DD:YYYY-MM-DD --after YYYY-MM-DD:YYYY-MM-DD\n");
+            stdout("token-usage-report.sh — Daily effective-token totals + top burners from Claude Code session JSONLs.\nUsage:\n  scripts/token-usage-report.sh                # last 7 days, table\n  scripts/token-usage-report.sh --last 14      # last 14 days\n  scripts/token-usage-report.sh --since 2026-05-01\n  scripts/token-usage-report.sh --json         # machine-readable\n  scripts/token-usage-report.sh --project-dir <path> # use one Claude activity folder\nEffective tokens weighting (matches weekly rate-limit volume):\n  input + 5×output + 1.25×cache_creation + 0.1×cache_read\n--- Compare-windows mode (US-011) ---\nFormat: --before YYYY-MM-DD:YYYY-MM-DD --after YYYY-MM-DD:YYYY-MM-DD\n");
             return 0;
         }
         else {
@@ -158,7 +172,7 @@ export function tokenUsageReport(args = [], options = {}) {
             return 1;
         }
     }
-    const projectDirs = resolveProjectDirs(options).filter((dir) => fs.existsSync(dir) && fs.statSync(dir).isDirectory());
+    const projectDirs = resolveProjectDirs({ ...options, projectDir }).filter((dir) => fs.existsSync(dir) && fs.statSync(dir).isDirectory());
     if (before && after) {
         comparison(projectDirs, before, after, minHours, json, stdout);
         return 0;

package/dist/lib/index-render/companies.d.ts

@@ -1,3 +1,6 @@
 import { RenderContext, RenderResult } from "./shared.js";
-export declare function renderCompanies(context: RenderContext): RenderResult;
+export declare class CompanyIndexUserError extends Error {
+    constructor(message: string);
+}
+export declare function renderCompanies(context: RenderContext, args?: string[]): RenderResult;
 //# sourceMappingURL=companies.d.ts.map

package/dist/lib/index-render/companies.js

@@ -1,6 +1,12 @@
 import * as fs from "fs";
 import * as path from "path";
 import { basename, countImmediate, date, exists, immediateEntries, isHidden, log, projectStatus, readJson, sanitize, titleize, truncate, write } from "./shared.js";
+export class CompanyIndexUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CompanyIndexUserError";
+    }
+}
 function description(root, company, name) {
     const base = `companies/${company}/${name}`;
     const nonHidden = (child) => !isHidden(child);
@@ -17,9 +23,66 @@ function description(root, company, name) {
         default: return "—";
     }
 }
-export function renderCompanies(context) {
+export function renderCompanies(context, args = []) {
+    if (args.some((arg) => arg === "--help" || arg === "-h")) {
+        (context.output ?? ((message) => process.stdout.write(message)))("Usage: hq core rebuild-index companies [--company <slug>]\n\n" +
+            "Regenerate company root INDEX.md files. Without --company, all companies are regenerated.\n" +
+            "--company <slug> regenerates only that company's index.\n" +
+            "Company-scoped writes require the cli.rebuild-index-company-scope flag.\n");
+        return { written: [] };
+    }
+    let selectedCompany;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--company") {
+            if (selectedCompany !== undefined)
+                throw new CompanyIndexUserError("rebuild-index companies: --company may be supplied once");
+            const value = args[index + 1];
+            if (!value || value.startsWith("--"))
+                throw new CompanyIndexUserError("rebuild-index companies: --company requires a company slug");
+            selectedCompany = value;
+            index += 1;
+        }
+        else if (arg.startsWith("--company=")) {
+            if (selectedCompany !== undefined)
+                throw new CompanyIndexUserError("rebuild-index companies: --company may be supplied once");
+            selectedCompany = arg.slice("--company=".length);
+            if (!selectedCompany)
+                throw new CompanyIndexUserError("rebuild-index companies: --company requires a company slug");
+        }
+        else {
+            throw new CompanyIndexUserError(`rebuild-index companies: unknown option ${arg}`);
+        }
+    }
     const written = [];
-    for (const directory of immediateEntries(context.root, "companies", "dir")) {
+    let scopedDirectories;
+    if (selectedCompany === undefined) {
+        scopedDirectories = immediateEntries(context.root, "companies", "dir");
+    }
+    else {
+        if (selectedCompany === "." || selectedCompany === ".." ||
+            selectedCompany.includes("/") || selectedCompany.includes("\\") ||
+            path.basename(selectedCompany) !== selectedCompany ||
+            selectedCompany.startsWith("_") || isHidden(selectedCompany)) {
+            throw new CompanyIndexUserError(`rebuild-index companies: invalid company slug "${selectedCompany}"`);
+        }
+        const companiesRoot = path.resolve(context.root, "companies");
+        const selectedDirectory = path.resolve(companiesRoot, selectedCompany);
+        let selectedStat;
+        try {
+            selectedStat = fs.lstatSync(selectedDirectory);
+        }
+        catch (cause) {
+            if (cause.code !== "ENOENT")
+                throw cause;
+            throw new CompanyIndexUserError(`rebuild-index companies: no company directory named "${selectedCompany}"`);
+        }
+        if (!selectedStat.isDirectory()) {
+            throw new CompanyIndexUserError(`rebuild-index companies: no company directory named "${selectedCompany}"`);
+        }
+        scopedDirectories = [selectedDirectory];
+    }
+    for (const directory of scopedDirectories) {
         const company = basename(directory);
         if (company.startsWith("_") || isHidden(company))
             continue;
@@ -40,7 +103,7 @@ export function renderCompanies(context) {
                 const parsed = readJson(prd);
                 let text = typeof parsed?.description === "string" ? parsed.description : "";
                 text = truncate(sanitize(text), 110) || "—";
-                lines.push(`| \`${project}\` | ${projectStatus(context.root, project, prd, "active")} | ${text} |`);
+                lines.push(`| \`${project}\` | ${projectStatus(context.root, project, prd, "active", prd)} | ${text} |`);
             }
         }
         else

package/dist/lib/index-render/index.d.ts

@@ -2,4 +2,5 @@ import { RenderContext, RenderResult } from "./shared.js";
 export type IndexTarget = "all" | "companies" | "company-knowledge" | "orchestrator" | "projects" | "public-knowledge" | "reports" | "social-drafts" | "threads" | "workers";
 export declare function renderIndexTarget(target: IndexTarget, context: RenderContext, args?: string[]): RenderResult;
 export { atomicWrite, comparePath, immediateEntries, type RenderContext, type RenderResult } from "./shared.js";
+export { CompanyIndexUserError } from "./companies.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index-render/index.js

@@ -10,7 +10,7 @@ import { renderWorkers } from "./workers.js";
 const allOrder = ["threads", "orchestrator", "companies", "projects", "company-knowledge", "public-knowledge", "workers", "reports", "social-drafts"];
 export function renderIndexTarget(target, context, args = []) {
     switch (target) {
-        case "companies": return renderCompanies(context);
+        case "companies": return renderCompanies(context, args);
         case "company-knowledge": return renderCompanyKnowledge(context);
         case "orchestrator": return renderOrchestrator(context);
         case "projects": return renderProjects(context);
@@ -40,4 +40,5 @@ export function renderIndexTarget(target, context, args = []) {
     }
 }
 export { atomicWrite, comparePath, immediateEntries } from "./shared.js";
+export { CompanyIndexUserError } from "./companies.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/index-render/shared.d.ts

@@ -39,7 +39,7 @@ export declare function hasUnclosedKeepMarker(content: string): boolean;
 export declare function looksAutoGenerated(content: string): boolean;
 export declare function generatedStamp(content: string): string | undefined;
 export declare function log(context: RenderContext, message: string): void;
-export declare function projectStatus(root: string, project: string, prdPath: string, fallback: string): string;
+export declare function projectStatus(root: string, project: string, prdPath: string, fallback: string, expectedStatePrdPath?: string): string;
 export declare function basename(file: string): string;
 export declare function isHidden(name: string): boolean;
 export declare function mtime(file: string): number;

package/dist/lib/index-render/shared.js

@@ -134,9 +134,11 @@ export function generatedStamp(content) {
     return content.match(/^<!-- hq-generated-sha256: ([a-f0-9]{64}) -->/m)?.[1];
 }
 export function log(context, message) { context.log?.(message); }
-export function projectStatus(root, project, prdPath, fallback) {
+export function projectStatus(root, project, prdPath, fallback, expectedStatePrdPath) {
     const state = readJson(at(root, `workspace/orchestrator/${project}/state.json`));
-    if (state) {
+    const stateMatchesPrd = expectedStatePrdPath === undefined || (typeof state?.prd_path === "string" &&
+        path.resolve(root, state.prd_path) === path.resolve(root, expectedStatePrdPath));
+    if (state && stateMatchesPrd) {
         const raw = typeof state.status === "string" ? state.status : "active";
         if (["completed", "complete"].includes(raw))
             return "complete";

package/dist/lib/mesh/live/daemon/mqtt-events.d.ts

@@ -0,0 +1,7 @@
+import type { MqttClientEventCallbacks } from "mqtt";
+/** Event callbacks shared by the daemon's two MQTT client seams. */
+export type MeshMqttEventMap = Pick<MqttClientEventCallbacks, "connect" | "error" | "close" | "message">;
+export interface MeshMqttEventClient {
+    on<Event extends keyof MeshMqttEventMap>(event: Event, handler: MeshMqttEventMap[Event]): unknown;
+}
+//# sourceMappingURL=mqtt-events.d.ts.map

package/dist/lib/mesh/live/daemon/mqtt-events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mqtt-events.js.map

package/dist/lib/mesh/live/daemon/mqtt-events.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mqtt-events.test-d.d.ts.map

package/dist/lib/mesh/live/daemon/mqtt-events.test-d.js

@@ -0,0 +1,10 @@
+// @ts-expect-error unsupported event names are not part of mqtt's event map
+presence.on("conect", () => { });
+// @ts-expect-error MQTT message handlers receive a string topic
+presence.on("message", (topic) => void topic);
+// @ts-expect-error unsupported event names are not part of mqtt's event map
+workCache.on("conect", () => { });
+// @ts-expect-error MQTT message handlers receive a string topic
+workCache.on("message", (topic) => void topic);
+export {};
+//# sourceMappingURL=mqtt-events.test-d.js.map

package/dist/lib/mesh/live/daemon/presence.d.ts

@@ -12,6 +12,7 @@
  * - Server credential refusals use a long retry (default 10m ±20%)
  */
 import { type IClientOptions, type MqttClient } from "mqtt";
+import type { MeshMqttEventClient } from "./mqtt-events.js";
 import { type Contract3Bundle, type CredentialsFetcher, type TimerHost } from "./credentials.js";
 export type MqttConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
 /**
@@ -49,8 +50,7 @@ export interface PresencePayload {
     at: string;
 }
 /** Structural mqtt client surface used by PresenceClient (test seam). */
-export interface MeshMqttClientLike {
-    on(event: string, handler: (...args: any[]) => void): unknown;
+export interface MeshMqttClientLike extends MeshMqttEventClient {
     publish(topic: string, message: string | Buffer, opts: {
         qos: 0 | 1 | 2;
         retain?: boolean;

package/dist/lib/mesh/live/daemon/work-subscribe.d.ts

@@ -3,9 +3,9 @@
  * Owns live-cache.json writes. Presence publish stays on PresenceClient.
  */
 import type { IClientOptions } from "mqtt";
+import type { MeshMqttEventClient } from "./mqtt-events.js";
 import { type PersonalCredentialsFetcher } from "./credentials.js";
-export interface WorkCacheMqtt {
-    on(event: string, handler: (...args: any[]) => void): unknown;
+export interface WorkCacheMqtt extends MeshMqttEventClient {
     subscribe(topic: string, opts: {
         qos: 0 | 1;
     }, cb?: (err?: Error | null) => void): unknown;

package/dist/utils/self-update.js

@@ -748,7 +748,7 @@ async function updateAndReexec(argv, flavor, known, deps) {
             console.error(chalk.dim(`  Or repair the install: hq rescue`));
         }
         console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
-        await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result.code, env, flavor.noun === "rescue");
+        await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result, env, flavor.noun === "rescue");
         return { action: "update-failed", latest };
     }
     if (installSnapshot)
@@ -801,10 +801,52 @@ async function updateAndReexec(argv, flavor, known, deps) {
     console.error(chalk.dim(`✓ hq-cli updated to ${latest}.`));
     return { action: "reexec", reexecStatus: status, latest };
 }
-const SELF_UPDATE_ERROR_CLASSES = new Set(["MODULE_NOT_FOUND", "EACCES", "EEXIST"]);
-async function captureSelfUpdateOutcome(action, fromVersion, targetVersion, installFlavor, code, env, flushBeforeExit) {
+const SELF_UPDATE_ERROR_CLASSES = new Set([
+    "MODULE_NOT_FOUND",
+    "ENOENT",
+    "EACCES",
+    "EEXIST",
+    "E404",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "EPERM",
+    "ETARGET",
+    "ETIMEDOUT",
+]);
+function selfUpdateErrorReason(code, failureKind) {
+    switch (code) {
+        case "MODULE_NOT_FOUND":
+            return "module_missing";
+        case "ENOENT":
+            return "program_not_found";
+        case "EACCES":
+        case "EPERM":
+            return "permission_denied";
+        case "EEXIST":
+            return "file_collision";
+        case "E404":
+            return "npm_package_not_found";
+        case "ETARGET":
+            return "npm_target_unavailable";
+        case "EAI_AGAIN":
+        case "ECONNREFUSED":
+        case "ECONNRESET":
+        case "ENOTFOUND":
+            return "registry_network_error";
+        case "ETIMEDOUT":
+            return "timed_out";
+        default:
+            if (failureKind === "package_manager_exit")
+                return "package_manager_exit";
+            return code ? "other_error" : "unknown";
+    }
+}
+async function captureSelfUpdateOutcome(action, fromVersion, targetVersion, installFlavor, failure, env, flushBeforeExit) {
     if (isCliTelemetryDisabled(env))
         return;
+    const code = failure?.diagnosticCode ?? failure?.code;
     const error = new Error(action === "update-failed" ? "Self-update failed" : "Self-update ineffective");
     // This event needs no stack: frames would expose the machine's install path.
     error.stack = undefined;
@@ -814,7 +856,12 @@ async function captureSelfUpdateOutcome(action, fromVersion, targetVersion, inst
             from_version: fromVersion,
             target_version: targetVersion,
             install_flavor: installFlavor,
-            error_class: code && SELF_UPDATE_ERROR_CLASSES.has(code) ? code : "other",
+            error_class: code && SELF_UPDATE_ERROR_CLASSES.has(code)
+                ? code
+                : failure?.failureKind === "package_manager_exit"
+                    ? "package_manager_exit"
+                    : "other",
+            error_reason: selfUpdateErrorReason(code, failure?.failureKind),
         },
     });
     if (flushBeforeExit) {

package/dist/utils/staged-npm-install.d.ts

@@ -0,0 +1,16 @@
+export type StagedInstallResult = {
+    ok: boolean;
+    detail?: string;
+    code?: string;
+};
+export type StagedInstallRunner = (command: string, args: string[], env?: NodeJS.ProcessEnv) => StagedInstallResult;
+/**
+ * Build hq-cli in a space-free temporary npm prefix, then replace the package
+ * and its executable links under the real prefix only after npm succeeds.
+ * Existing files are held beside their destinations until activation completes,
+ * so failed installs and failed activation restore the prior working tree.
+ */
+export declare function installNpmPackageStaged(prefix: string, packageSpec: string, runner: StagedInstallRunner, platform?: NodeJS.Platform, activate?: typeof activateStagedNpmPackage): StagedInstallResult;
+/** Atomically replace a package already built under a temporary npm prefix. */
+export declare function activateStagedNpmPackage(prefix: string, stagePrefix: string, platform?: NodeJS.Platform): StagedInstallResult;
+//# sourceMappingURL=staged-npm-install.d.ts.map