@indigoai-us/hq-cli 5.183.0 → 5.184.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [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

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/doctor/checks/sync-health.js

@@ -223,6 +223,7 @@ function versionResults(context, deps) {
         results.push({
             status: "WARN",
             checkId: "sync.versions.core",
+            reasonCode: "core-version-unavailable",
             target: path.join(context.hqRoot, "core", "core.yaml"),
             message: "hq-core version could not be read from core/core.yaml — the scaffold may be missing or pre-v12.",
             remediation: "Run /update-hq to (re)install the hq-core scaffold.",
@@ -282,6 +283,7 @@ function updateAvailabilityResult(context, deps) {
             {
                 status: "WARN",
                 checkId: "sync.update.core",
+                reasonCode: "core-update-available",
                 message: `hq-core update available: local v${core}, latest v${latest}.`,
                 remediation: "Run /update-hq in a fresh session to upgrade.",
             },
@@ -373,6 +375,7 @@ function journalResults(deps, journals) {
                 return {
                     status: "NA",
                     checkId,
+                    reasonCode: "no-local-tree",
                     target: entry.path,
                     message: `Sync journal '${entry.slug}' is unused on this machine — there is no companies/${entry.slug} directory, so this journal is not a live sync target.`,
                 };
@@ -382,6 +385,7 @@ function journalResults(deps, journals) {
             return {
                 status: "WARN",
                 checkId,
+                reasonCode: "never-synced",
                 target: entry.path,
                 message: `Sync journal '${entry.slug}' exists but has never recorded a successful sync.`,
                 remediation: "Run /hq-sync (or `hq sync`) to complete a first sync.",
@@ -392,6 +396,7 @@ function journalResults(deps, journals) {
             return {
                 status: "UNKNOWN",
                 checkId,
+                reasonCode: "invalid-last-sync",
                 target: entry.path,
                 message: `Sync journal '${entry.slug}' has an unparseable lastSync (${lastSync}).`,
             };
@@ -402,6 +407,7 @@ function journalResults(deps, journals) {
             return {
                 status: "WARN",
                 checkId,
+                reasonCode: "stale-threshold",
                 target: entry.path,
                 message: `Sync journal '${entry.slug}' is stale: last successful sync ${days} day${days === 1 ? "" : "s"} ago (${lastSync}).`,
                 remediation: "Run /hq-sync (or `hq sync`) and check the sync runner.",
@@ -443,6 +449,7 @@ function manifestResults(deps, journals) {
             {
                 status: "NA",
                 checkId: "sync.manifest",
+                reasonCode: "manifest-unavailable",
                 message: `${MANIFEST_UNAVAILABLE_REASON} — upgrade hq-cloud to audit manifest uploads.`,
             },
         ];
@@ -456,6 +463,7 @@ function manifestResults(deps, journals) {
             {
                 status: "UNKNOWN",
                 checkId: "sync.manifest",
+                reasonCode: "manifest-state-unavailable",
                 message: `Manifest upload state could not be read: ${error instanceof Error ? error.message : String(error)}`,
                 remediation: "Check that the HQ state directory is readable, then re-run `hq doctor`.",
             },
@@ -469,6 +477,7 @@ function manifestResults(deps, journals) {
             {
                 status: "NA",
                 checkId: "sync.manifest",
+                reasonCode: "no-manifest-scopes",
                 message: "No manifest-auditable sync scopes on this machine — nothing to reconcile.",
             },
         ];
@@ -480,6 +489,7 @@ function manifestResults(deps, journals) {
             return {
                 status: "UNTESTED",
                 checkId,
+                reasonCode: "never-uploaded",
                 message: `Scope '${entry.scopeKey}' has never uploaded a sync manifest — expected until the first pass runs.`,
                 remediation: "Run `hq sync manifest` to upload one now.",
             };
@@ -489,6 +499,7 @@ function manifestResults(deps, journals) {
             return {
                 status: "UNKNOWN",
                 checkId,
+                reasonCode: "invalid-upload-time",
                 message: `Scope '${entry.scopeKey}' has an unparseable last manifest upload time (${entry.lastUploadAt}).`,
             };
         }
@@ -501,6 +512,7 @@ function manifestResults(deps, journals) {
             return {
                 status: "WARN",
                 checkId,
+                reasonCode: "stale-threshold",
                 message: `Scope '${entry.scopeKey}' last uploaded a sync manifest ${days} day${days === 1 ? "" : "s"} ago (${entry.lastUploadAt}) — the daily audit pass is not running.`,
                 remediation: "Run `hq sync manifest` and check HQ_SYNC_MANIFEST_DISABLED and the sync runner.",
             };
@@ -532,6 +544,7 @@ function unresolvedResults(deps, journals) {
     return slugs.map((slug) => ({
         status: "UNTESTED",
         checkId: `sync.manifest.unresolved.${slug}`,
+        reasonCode: "unresolved-company-uid",
         message: `Company scope '${slug}' has a sync journal but its companyUid could not be resolved locally — its manifest uploads were not checked.`,
         remediation: `Run \`hq sync manifest --scope ${slug}\` to audit it explicitly.`,
     }));

package/dist/lib/doctor/client-health-reason-codes-flag.d.ts

@@ -0,0 +1,26 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+export declare const CLIENT_HEALTH_REASON_CODES_FLAG = "client-health-sync-reason-codes";
+export declare const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
+export declare const CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS = 150;
+type ClientHealthFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface ClientHealthReasonCodesFlagDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => ClientHealthFlagClient;
+    getToken?: FlagClientOptions["getToken"];
+    fetch?: typeof fetch;
+    reportFailure?: (error: unknown) => void;
+}
+export interface ClientHealthReasonCodesCompany {
+    companyUid: string;
+    companySlug?: string;
+}
+/**
+ * Resolve the privacy gate from hq-flags with a bounded request. Missing
+ * identity, service configuration, and every lookup failure keep diagnostics
+ * off so a flag outage cannot delay the doctor's health result.
+ */
+export declare function clientHealthReasonCodesEnabled(dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+/** Resolve the same default-off gate for one explicitly identified company. */
+export declare function clientHealthReasonCodesEnabledForCompany(company: ClientHealthReasonCodesCompany, dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+export {};
+//# sourceMappingURL=client-health-reason-codes-flag.d.ts.map

package/dist/lib/doctor/client-health-reason-codes-flag.js

@@ -0,0 +1,94 @@
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+export const CLIENT_HEALTH_REASON_CODES_FLAG = "client-health-sync-reason-codes";
+export const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
+export const CLIENT_HEALTH_REASON_CODES_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 client-health reason-code flag lookup failed (${safeErrorClass(error)}); using default off.\n`);
+}
+function combineSignals(first, second) {
+    return first ? AbortSignal.any([first, second]) : second;
+}
+/**
+ * Resolve the privacy gate from hq-flags with a bounded request. Missing
+ * identity, service configuration, and every lookup failure keep diagnostics
+ * off so a flag outage cannot delay the doctor's health result.
+ */
+export async function clientHealthReasonCodesEnabled(dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const companyUid = env.HQ_COMPANY_UID?.trim() || "";
+    if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    }
+    return clientHealthReasonCodesEnabledForCompany({
+        companyUid,
+        companySlug: env.HQ_COMPANY_SLUG?.trim() || undefined,
+    }, dependencies, callerSignal);
+}
+/** Resolve the same default-off gate for one explicitly identified company. */
+export async function clientHealthReasonCodesEnabledForCompany(company, dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const endpoint = env.HQ_FLAGS_API_URL?.trim() || "";
+    const companyUid = company.companyUid.trim();
+    if (!endpoint || !/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    }
+    const companySlug = company.companySlug?.trim() || "";
+    const deadline = AbortSignal.timeout(CLIENT_HEALTH_REASON_CODES_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 = CLIENT_HEALTH_REASON_CODES_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: CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS,
+            onError: reportFailureOnce,
+        });
+        await client.ready();
+        if (!failed && !signal.aborted) {
+            enabled = client.isEnabled(CLIENT_HEALTH_REASON_CODES_FLAG, {
+                fallback: CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK,
+            });
+        }
+    }
+    catch (error) {
+        reportFailureOnce(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailureOnce(error);
+        }
+    }
+    return failed || signal.aborted
+        ? CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK
+        : enabled;
+}
+//# sourceMappingURL=client-health-reason-codes-flag.js.map

package/dist/lib/doctor/fix/apply.d.ts

@@ -31,6 +31,7 @@
 import type { CheckResult, DoctorStatus } from "../types.js";
 import { type GateProfile } from "../hook-gate-profiles.js";
 import { type FixClass } from "./remediation.js";
+import { type RefreshSyncOutcome } from "./refresh-sync-outcome.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export declare const HOOK_CONFIG_DIRS: readonly [".claude", ".codex", ".grok"];
 /** Options for {@link applyFixes}. Everything is injectable for hermetic tests. */
@@ -91,6 +92,8 @@ export interface RefreshSyncTarget {
 export interface RefreshSyncResult {
     /** Whether the pull exited 0. */
     ok: boolean;
+    /** Closed enum for machine-readable client-health diagnostics. */
+    outcome: RefreshSyncOutcome;
     /** One-line summary for the post-fix report. */
     message: string;
 }
@@ -108,6 +111,8 @@ export interface AppliedFix {
     summary: string;
     /** The status of the re-run check for this target, or null if not found. */
     postStatus: DoctorStatus | null;
+    /** Present for refresh-sync plans; contains no command output or path data. */
+    refreshSyncOutcome?: RefreshSyncOutcome;
 }
 /** The outcome of an {@link applyFixes} run. */
 export interface ApplyFixesResult {

package/dist/lib/doctor/fix/apply.js

@@ -40,6 +40,7 @@ import { deriveRemediation } from "./remediation.js";
 import { botDir } from "../../bot/paths.js";
 import { readBotConfig } from "../../bot/config.js";
 import { buildBotDaemonPaths, rewriteBotDaemonNodePath } from "../../bot/daemon.js";
+import { classifyRefreshSyncOutcome, } from "./refresh-sync-outcome.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
 /** Per-company bound for the default `hq sync pull` repair. */
@@ -130,6 +131,9 @@ export async function applyFixes(options) {
         target: plan.target,
         summary: plan.summary,
         postStatus: plan.postStatus(after),
+        ...(plan.refreshSyncOutcome?.()
+            ? { refreshSyncOutcome: plan.refreshSyncOutcome() }
+            : {}),
     }));
     write("\nPost-fix status:\n");
     for (const fix of applied) {
@@ -197,23 +201,41 @@ export function defaultRefreshSync(target) {
         cwd: target.hqRoot,
     });
     if (result.error) {
-        const timedOut = result.error.message.includes("ETIMEDOUT") || result.signal === "SIGTERM";
+        const spawnError = result.error;
+        const outcome = classifyRefreshSyncOutcome({
+            errorCode: spawnError.code,
+            ...(result.error.message.includes("ETIMEDOUT")
+                ? { errorCode: "ETIMEDOUT" }
+                : {}),
+            signal: result.signal,
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        });
         return Promise.resolve({
             ok: false,
-            message: timedOut
+            outcome,
+            message: outcome === "pull-timeout"
                 ? `timed out pulling '${target.slug}'`
                 : `could not start pull for '${target.slug}': ${result.error.message}`,
         });
     }
     if (result.status !== 0) {
+        const outcome = classifyRefreshSyncOutcome({
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        });
         const detail = (result.stderr || result.stdout || "").trim().split("\n").at(-1) ?? "";
         return Promise.resolve({
             ok: false,
+            outcome,
             message: `pull of '${target.slug}' exited ${result.status}${detail ? `: ${detail}` : ""}`,
         });
     }
     return Promise.resolve({
         ok: true,
+        outcome: "pull-succeeded",
         message: `pulled '${target.slug}'`,
     });
 }
@@ -287,6 +309,7 @@ function planRefreshSync(hqRoot, result, rem, refreshSync) {
     const slug = rem.fixTarget;
     if (!slug)
         return null;
+    let outcome;
     return {
         checkId: result.checkId,
         fixClass: "refresh-sync",
@@ -297,8 +320,10 @@ function planRefreshSync(hqRoot, result, rem, refreshSync) {
             `      refresh the stale sync journal (keeps local conflict copies)`,
         summary: `pull ${slug} to refresh its sync journal`,
         apply: async () => {
-            await refreshSync({ slug, hqRoot });
+            const result = await refreshSync({ slug, hqRoot });
+            outcome = result.outcome;
         },
+        refreshSyncOutcome: () => outcome,
         postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
     };
 }

package/dist/lib/doctor/fix/json-output.d.ts

@@ -0,0 +1,20 @@
+import type { AppliedFix, ApplyFixesResult } from "./apply.js";
+export declare const DOCTOR_FIX_JSON_SCHEMA_VERSION = 1;
+export interface DoctorFixJsonResult {
+    schemaVersion: number;
+    exitCode: number;
+    refused: ApplyFixesResult["refused"] | "outside-hq-tree";
+    refreshSync: {
+        checkId: string;
+        outcome: NonNullable<AppliedFix["refreshSyncOutcome"]>;
+        postStatus: AppliedFix["postStatus"];
+    }[];
+}
+/** Build the intentionally narrow JSON surface for `hq doctor --fix --json`. */
+export declare function buildDoctorFixJson(input: {
+    exitCode: number;
+    refused: ApplyFixesResult["refused"] | "outside-hq-tree";
+    applied: readonly AppliedFix[];
+}): DoctorFixJsonResult;
+export declare function renderDoctorFixJson(input: Parameters<typeof buildDoctorFixJson>[0]): string;
+//# sourceMappingURL=json-output.d.ts.map

package/dist/lib/doctor/fix/json-output.js

@@ -0,0 +1,22 @@
+export const DOCTOR_FIX_JSON_SCHEMA_VERSION = 1;
+/** Build the intentionally narrow JSON surface for `hq doctor --fix --json`. */
+export function buildDoctorFixJson(input) {
+    return {
+        schemaVersion: DOCTOR_FIX_JSON_SCHEMA_VERSION,
+        exitCode: input.exitCode,
+        refused: input.refused,
+        refreshSync: input.applied.flatMap((fix) => fix.fixClass === "refresh-sync" && fix.refreshSyncOutcome
+            ? [
+                {
+                    checkId: fix.checkId,
+                    outcome: fix.refreshSyncOutcome,
+                    postStatus: fix.postStatus,
+                },
+            ]
+            : []),
+    };
+}
+export function renderDoctorFixJson(input) {
+    return JSON.stringify(buildDoctorFixJson(input), null, 2) + "\n";
+}
+//# sourceMappingURL=json-output.js.map

package/dist/lib/doctor/fix/refresh-sync-outcome.d.ts

@@ -0,0 +1,12 @@
+/** Privacy-safe outcomes for a targeted refresh-sync attempt. */
+export type RefreshSyncOutcome = "pull-succeeded" | "pull-timeout" | "pull-failed:4xx" | "pull-failed:5xx" | "pull-failed:network" | "pull-failed:other";
+export interface RefreshSyncObservation {
+    errorCode?: string;
+    signal?: string | null;
+    status?: number | null;
+    stdout?: string;
+    stderr?: string;
+}
+/** Classify process/HTTP results without retaining their free-text details. */
+export declare function classifyRefreshSyncOutcome(observation: RefreshSyncObservation): RefreshSyncOutcome;
+//# sourceMappingURL=refresh-sync-outcome.d.ts.map