@indigoai-us/hq-cli 5.182.0 → 5.184.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.184.0] — 2026-09-25
+
+### Fixed
+
+- Work Mesh transcript-watch now emits `session_end` for hook-covered sessions that have already been quiet for 10 minutes when first seen (the live skip path that left `skippedHook=411 ended=0`). Held/spool rescans stamp last hook activity from each event's `at`, not the scan clock, so leftover `held.jsonl` lines cannot reset the quiet timer.
+- Quiet `session_end` (and SessionEnd flush) send an optional one-sentence summary of the last assistant reply (~140 chars, tokens and secrets-file paths redacted), plus git repo, branch, and PR URLs when cheap.
+
+### Added
+
+- `hq doctor --json` includes stable sync `reasonCode` enums. Client-health reports add `checkId: reasonCode` pairs only when the company-scoped `client-health-sync-reason-codes` hq-flags gate is enabled. `hq doctor --fix --json` reports refresh-sync outcomes without raw error details.
+
+## [5.183.0] — 2026-09-25
+
+### Added
+
+- `hq core sentry report` can attach bounded hook-timeout timing context to Sentry events when the company-scoped `hook-timeout-debug-context` flag is enabled. The flag defaults off.
+
 ## [5.182.0] — 2026-09-24
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -5495,6 +5495,9 @@ export declare const COMMAND_CATALOG: readonly [{
     }, {
         readonly flags: "--fix";
         readonly description: "Apply the allowlisted safe repairs (backs up first; read-only without this flag).";
+    }, {
+        readonly flags: "--client-health-report";
+        readonly description: "Resolve the opt-in hq-flags gate used by the client-health report hook.";
     }, {
         readonly flags: "--yes";
         readonly description: "Skip the interactive --fix confirmation (non-interactive use).";

package/dist/command-catalog.generated.js

@@ -7089,6 +7089,10 @@ export const COMMAND_CATALOG = [
                 "flags": "--fix",
                 "description": "Apply the allowlisted safe repairs (backs up first; read-only without this flag)."
             },
+            {
+                "flags": "--client-health-report",
+                "description": "Resolve the opt-in hq-flags gate used by the client-health report hook."
+            },
             {
                 "flags": "--yes",
                 "description": "Skip the interactive --fix confirmation (non-interactive use)."

package/dist/commands/doctor.d.ts

@@ -55,6 +55,8 @@ export interface RunDoctorOptions {
     stderr?: (chunk: string) => void;
     /** Emit the machine-readable JSON document instead of text. Default: false. */
     json?: boolean;
+    /** Resolve hq-flags independently for each company represented in sync results. */
+    resolveClientHealthReasonCodesForCompany?: (companySlug: string | null) => Promise<boolean>;
     /** In text mode, also print every PASS result. Default: false. */
     verbose?: boolean;
     /** In text mode, emit ANSI colour. Default: false (no escape sequences). */

package/dist/commands/doctor.js

@@ -23,6 +23,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { Option } from "commander";
 import { createDefaultRegistry, } from "../lib/doctor/registry.js";
 import { computeExitCode, renderText, UNKNOWN_PLATFORM, } from "../lib/doctor/report.js";
 import { buildDoctorJson, renderJson } from "../lib/doctor/json-output.js";
@@ -30,6 +31,10 @@ import { detectPlatform } from "../lib/doctor/platform.js";
 import { DEEP_FAMILY_ID, DEEP_FAMILY_TITLE, runDeepGuardTests, } from "../lib/doctor/deep/executor.js";
 import { PARITY_FAMILY_ID, PARITY_FAMILY_TITLE, runParityReplay, } from "../lib/doctor/deep/parity.js";
 import { applyFixes } from "../lib/doctor/fix/apply.js";
+import { renderDoctorFixJson } from "../lib/doctor/fix/json-output.js";
+import { clientHealthReasonCodesEnabled as isActiveCompanyClientHealthReasonCodesEnabled, clientHealthReasonCodesEnabledForCompany, } from "../lib/doctor/client-health-reason-codes-flag.js";
+import { isCompanyJournalSlug } from "../lib/doctor/checks/sync-health.js";
+import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
 import * as readline from "node:readline";
 import { runSideEffectTests } from "../lib/doctor/deep/sandbox.js";
 /**
@@ -157,7 +162,16 @@ export async function runDoctor(options = {}) {
         });
     }
     if (options.json) {
-        write(renderJson(buildDoctorJson({ hqRoot, families, platform, scope })));
+        const clientHealthReasonCodesEnabledCheckIds = options.resolveClientHealthReasonCodesForCompany
+            ? await resolveClientHealthReasonCodesCheckIds(families, options.resolveClientHealthReasonCodesForCompany)
+            : undefined;
+        write(renderJson(buildDoctorJson({
+            hqRoot,
+            families,
+            platform,
+            scope,
+            clientHealthReasonCodesEnabledCheckIds,
+        })));
     }
     else {
         write(renderText({
@@ -172,6 +186,61 @@ export async function runDoctor(options = {}) {
     // UNTESTED, NA, and KNOWN-DEFECT are reported but never fail the command.
     return { exitCode: computeExitCode(families), hqRoot, families };
 }
+async function resolveClientHealthReasonCodesCheckIds(families, resolveForCompany) {
+    const checksByCompany = new Map();
+    for (const run of families) {
+        if (run.family.id !== "sync")
+            continue;
+        for (const result of run.results) {
+            if (result.reasonCode === undefined ||
+                (result.status !== "FAIL" && result.status !== "WARN")) {
+                continue;
+            }
+            const scoped = /^sync\.(?:journal|manifest)\.(.+)$/.exec(result.checkId);
+            const companySlug = scoped && isCompanyJournalSlug(scoped[1]) ? scoped[1] : null;
+            const checkIds = checksByCompany.get(companySlug) ?? [];
+            checkIds.push(result.checkId);
+            checksByCompany.set(companySlug, checkIds);
+        }
+    }
+    const enabledChecks = new Set();
+    const decisions = await Promise.all([...checksByCompany.entries()].map(async ([companySlug, checkIds]) => ({
+        checkIds,
+        enabled: await resolveForCompany(companySlug),
+    })));
+    for (const decision of decisions) {
+        if (decision.enabled) {
+            for (const checkId of decision.checkIds)
+                enabledChecks.add(checkId);
+        }
+    }
+    return enabledChecks;
+}
+function createClientHealthReasonCodeCompanyResolver(hqRoot) {
+    const companies = readCompaniesManifestMap(hqRoot);
+    return async (companySlug) => {
+        if (companySlug === null) {
+            return isActiveCompanyClientHealthReasonCodesEnabled();
+        }
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(companySlug)) {
+            return false;
+        }
+        const manifestUid = companies?.[companySlug]?.cloud_uid;
+        const activeSlug = process.env.HQ_COMPANY_SLUG?.trim() || "";
+        const activeUid = process.env.HQ_COMPANY_UID?.trim() || "";
+        const companyUid = typeof manifestUid === "string" && manifestUid.trim()
+            ? manifestUid.trim()
+            : companySlug === activeSlug
+                ? activeUid
+                : "";
+        if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid))
+            return false;
+        return clientHealthReasonCodesEnabledForCompany({
+            companyUid,
+            companySlug,
+        });
+    };
+}
 /** Register the top-level `hq doctor` command so it appears in `hq --help`. */
 export function registerDoctorCommand(program) {
     program
@@ -186,6 +255,7 @@ export function registerDoctorCommand(program) {
         .option("--company <slug>", "Company slug for integrations checks (otherwise resolves your single active company).")
         .option("--only <families>", "Run only these comma-separated check families (e.g. hooks). Unknown names are rejected; --json then records the scope.")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
+        .addOption(new Option("--client-health-report", "Resolve the opt-in hq-flags gate used by the client-health report hook.").hideHelp())
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
         .action(async (opts) => {
@@ -208,8 +278,17 @@ export function registerDoctorCommand(program) {
         if (opts.fix === true) {
             const hqRoot = resolveHqRoot();
             if (!hqRoot) {
-                process.stderr.write(`hq doctor --fix: not inside an HQ tree.\n` +
-                    `  Looking for a directory containing all of: ${HQ_ROOT_MARKERS.join(", ")}\n`);
+                if (opts.json === true) {
+                    process.stdout.write(renderDoctorFixJson({
+                        exitCode: 1,
+                        refused: "outside-hq-tree",
+                        applied: [],
+                    }));
+                }
+                else {
+                    process.stderr.write(`hq doctor --fix: not inside an HQ tree.\n` +
+                        `  Looking for a directory containing all of: ${HQ_ROOT_MARKERS.join(", ")}\n`);
+                }
                 process.exitCode = 1;
                 return;
             }
@@ -217,8 +296,14 @@ export function registerDoctorCommand(program) {
                 hqRoot,
                 yes: opts.yes === true,
                 force: opts.force === true,
-                confirm: promptYesNo,
+                confirm: () => promptYesNo(opts.json === true ? process.stderr : process.stdout),
+                ...(opts.json === true
+                    ? { stdout: () => { }, stderr: () => { } }
+                    : {}),
             });
+            if (opts.json === true) {
+                process.stdout.write(renderDoctorFixJson(fixResult));
+            }
             process.exitCode = fixResult.exitCode;
             return;
         }
@@ -237,6 +322,14 @@ export function registerDoctorCommand(program) {
             id: detection.platform,
             evidence: detection.evidence,
         };
+        const clientHealthReasonCodesResolver = json && opts.clientHealthReport === true
+            ? (() => {
+                const hqRoot = resolveHqRoot();
+                return hqRoot
+                    ? createClientHealthReasonCodeCompanyResolver(hqRoot)
+                    : undefined;
+            })()
+            : undefined;
         const result = await runDoctor({
             json,
             verbose: opts.verbose === true,
@@ -247,6 +340,7 @@ export function registerDoctorCommand(program) {
             liveRuntimes: opts.liveRuntimes === true,
             company: opts.company,
             only: parseOnly(opts.only),
+            resolveClientHealthReasonCodesForCompany: clientHealthReasonCodesResolver,
         });
         // Set the exit code rather than calling process.exit, so the CLI's
         // normal shutdown (telemetry flush) still runs. Non-zero means either an
@@ -272,12 +366,12 @@ function parseOnly(value) {
  * (so a piped run without `--yes` writes nothing) and on anything other than an
  * explicit yes.
  */
-function promptYesNo() {
+function promptYesNo(output = process.stdout) {
     if (!process.stdin.isTTY)
         return Promise.resolve(false);
     const rl = readline.createInterface({
         input: process.stdin,
-        output: process.stdout,
+        output,
     });
     return new Promise((resolve) => {
         rl.question("Apply these repairs? [y/N] ", (answer) => {

package/dist/commands/mesh.js

@@ -29,6 +29,7 @@ const MEMBERSHIP_VALIDATION_TIMEOUT_MS = 5_000;
 import { buildEmitEvidence, machineEmitDisposition } from "../lib/mesh/live/emit-evidence.js";
 import { appendHeldLine } from "../lib/mesh/live/spool.js";
 import { createEmitPoster, buildMeshEmitEvent } from "../lib/mesh/live/emit-client.js";
+import { enrichSessionEndEvent } from "../lib/mesh/live/report-summary.js";
 import { emitEvents, formatEmitRejectionLines } from "../lib/mesh/live/emit.js";
 import { readEmitRetry, writeEmitRetry } from "../lib/mesh/live/emit-retry.js";
 import { generateUlid } from "../lib/mesh/live/ulid.js";
@@ -1533,6 +1534,14 @@ async function runSessionEnqueue(cliKind, opts) {
         task: opts.task,
         env: process.env,
     });
+    const reportFields = kind === "session_end"
+        ? enrichSessionEndEvent({
+            kind,
+            sessionId: sessionId,
+            cwd: opts.cwd,
+            summary: opts.summary,
+        })
+        : {};
     const event = buildMeshEmitEvent({
         eventId: opts.eventId?.trim() || generateUlid(Date.now()),
         kind: kind,
@@ -1546,7 +1555,15 @@ async function runSessionEnqueue(cliKind, opts) {
         taskId: opts.taskId,
         status: opts.status,
         reason: opts.reason,
-        summary: opts.summary,
+        summary: opts.summary ||
+            (typeof reportFields.summary === "string" ? reportFields.summary : undefined),
+        repo: typeof reportFields.repo === "string" ? reportFields.repo : undefined,
+        gitBranch: typeof reportFields.gitBranch === "string"
+            ? reportFields.gitBranch
+            : undefined,
+        prUrls: Array.isArray(reportFields.prUrls)
+            ? reportFields.prUrls
+            : undefined,
         evidence,
     });
     const meshRoot = workMeshHomeRoot();

package/dist/lib/core-utils/hook-timeout-debug-context-flag.d.ts

@@ -0,0 +1,20 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+export declare const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG = "hook-timeout-debug-context";
+export declare const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK = false;
+export declare const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_TIMEOUT_MS = 150;
+type DebugContextFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface HookTimeoutDebugContextFlagDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => DebugContextFlagClient;
+    getToken?: FlagClientOptions["getToken"];
+    fetch?: typeof fetch;
+    reportFailure?: (error: unknown) => void;
+}
+/**
+ * Read the optional diagnostic gate with a short, cancellable hq-flags request.
+ * Missing identity/configuration and every client failure use the default-off
+ * result so a flag outage cannot delay or suppress the underlying timeout.
+ */
+export declare function hookTimeoutDebugContextEnabled(dependencies?: HookTimeoutDebugContextFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+export {};
+//# sourceMappingURL=hook-timeout-debug-context-flag.d.ts.map

package/dist/lib/core-utils/hook-timeout-debug-context-flag.js

@@ -0,0 +1,80 @@
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+export const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG = "hook-timeout-debug-context";
+export const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK = false;
+export const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_TIMEOUT_MS = 150;
+function safeErrorClass(error) {
+    const name = error instanceof Error ? error.name : "UnknownError";
+    return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
+}
+function reportFlagFailure(error) {
+    process.stderr.write(`HQ hook timeout debug flag lookup failed (${safeErrorClass(error)}); using default off.\n`);
+}
+function combineSignals(first, second) {
+    return first ? AbortSignal.any([first, second]) : second;
+}
+/**
+ * Read the optional diagnostic gate with a short, cancellable hq-flags request.
+ * Missing identity/configuration and every client failure use the default-off
+ * result so a flag outage cannot delay or suppress the underlying timeout.
+ */
+export async function hookTimeoutDebugContextEnabled(dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const endpoint = env.HQ_FLAGS_API_URL?.trim() || "";
+    const companyUid = env.HQ_COMPANY_UID?.trim() || "";
+    if (!endpoint || !/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK;
+    }
+    const companySlug = env.HQ_COMPANY_SLUG?.trim() || "";
+    const deadline = AbortSignal.timeout(HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_TIMEOUT_MS);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    let client;
+    let failed = false;
+    let failureReported = false;
+    let enabled = HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK;
+    const reportFailureOnce = (error) => {
+        failed = true;
+        if (failureReported)
+            return;
+        failureReported = true;
+        (dependencies.reportFailure ?? reportFlagFailure)(error);
+    };
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint,
+            companyUid,
+            ...(companySlug && /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/.test(companySlug)
+                ? { companyIdentifiers: [companySlug] }
+                : {}),
+            env: {},
+            getToken: dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? ""),
+            fetch: (input, init) => doFetch(input, {
+                ...init,
+                signal: combineSignals(init?.signal ?? undefined, signal),
+            }),
+            refreshIntervalMs: 0,
+            requestTimeoutMs: HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_TIMEOUT_MS,
+            onError: reportFailureOnce,
+        });
+        await client.ready();
+        if (!failed && !signal.aborted) {
+            enabled = client.isEnabled(HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG, {
+                fallback: HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK,
+            });
+        }
+    }
+    catch (error) {
+        reportFailureOnce(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailureOnce(error);
+        }
+    }
+    return failed || signal.aborted ? HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK : enabled;
+}
+//# sourceMappingURL=hook-timeout-debug-context-flag.js.map

package/dist/lib/core-utils/sentry-report.d.ts

@@ -27,14 +27,32 @@ export declare const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
  * is owner-approved telemetry for the exact hook script and may include a
  * company directory; it is never a substitute for hook input or a transcript.
  */
-export declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["hook_name", "hook_path", "hook_event", "hook_script", "tool_name", "session_id", "declared_timeout_ms", "elapsed_ms", "remaining_ms", "watchdog_timeout_ms", "hook_timeout_ms", "hq_version", "platform", "load_average", "spawn_ms", "slow_child", "slow_child_ms", "exit_code", "final_elapsed_ms", "bash_env_set", "cwd_kind", "shell", "nproc", "hook_sequence"];
+export declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["hook_name", "hook_path", "hook_event", "hook_script", "tool_name", "session_id", "declared_timeout_ms", "elapsed_ms", "remaining_ms", "watchdog_timeout_ms", "hook_timeout_ms", "hq_version", "platform", "load_average", "spawn_ms", "slow_child", "slow_child_ms", "exit_code", "final_elapsed_ms", "bash_env_set", "cwd_kind", "shell", "nproc", "hook_sequence", "hook_timeout_debug_context"];
 export declare const MAX_SENTRY_REPORT_METADATA_KEYS: number;
 export type HookSequenceEntry = {
     script: string;
     event: string;
     ms: number;
 };
-export type SentryReportMetadataValue = string | number | boolean | HookSequenceEntry[];
+export type HookTimeoutDebugPhaseTiming = {
+    phase: string;
+    elapsed_ms: number;
+};
+export type HookTimeoutDebugContext = {
+    hook_name: string;
+    hook_event: string;
+    budget_ms: number;
+    elapsed_ms: number;
+    remaining_ms: number;
+    phase_timings: HookTimeoutDebugPhaseTiming[];
+    wait_point: string;
+    waiting_child_basename: string;
+    waiting_child_elapsed_ms: number;
+    load_average?: number | "unavailable";
+    spawn_ms?: number | "unavailable";
+    process_count?: number | "unavailable";
+};
+export type SentryReportMetadataValue = string | number | boolean | HookSequenceEntry[] | HookTimeoutDebugContext;
 export type SentryReportMetadata = Record<string, SentryReportMetadataValue>;
 export type SentryReportEvent = {
     type: string;
@@ -53,6 +71,8 @@ export type SentryReportOptions = {
     rateLimitDirectory?: string;
     /** Test seam for deterministic rate-limit windows. */
     rateLimitNow?: () => number;
+    /** Optional caller cancellation forwarded to the bounded flag lookup. */
+    signal?: AbortSignal;
 };
 export type SentryReportDependencies = {
     sentry: {
@@ -67,6 +87,8 @@ export type SentryReportDependencies = {
     rateLimitDirectory?: string;
     /** Test seam; production uses Date.now. */
     rateLimitNow?: () => number;
+    /** Test seam for the company-scoped, bounded debug-context gate. */
+    timeoutDebugContextEnabled?: (signal?: AbortSignal) => Promise<boolean>;
 };
 export type SentryReportResult = {
     code: 0 | 1;