@indigoai-us/hq-cli 5.183.0 → 5.185.0

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

package/dist/lib/doctor/fix/refresh-sync-outcome.js

@@ -0,0 +1,25 @@
+/** Classify process/HTTP results without retaining their free-text details. */
+export function classifyRefreshSyncOutcome(observation) {
+    const details = String(observation.stdout ?? "") + "\n" + String(observation.stderr ?? "");
+    const errorCode = observation.errorCode ??
+        /\b(ETIMEDOUT|ETIME|EAI_AGAIN|ENOTFOUND|ECONNRESET|ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|EPIPE|ECONNABORTED)\b/.exec(details)?.[1];
+    if (errorCode === "ETIMEDOUT" ||
+        errorCode === "ETIME" ||
+        observation.signal === "SIGTERM") {
+        return "pull-timeout";
+    }
+    if (!errorCode && observation.status === 0) {
+        return "pull-succeeded";
+    }
+    const httpStatus = /(?:HTTP(?:\/\d(?:\.\d)?)?\s+|status(?:\s+code)?\s*[=: ]\s*)([45]\d\d)\b/i.exec(details)?.[1] ?? "";
+    if (httpStatus.startsWith("4"))
+        return "pull-failed:4xx";
+    if (httpStatus.startsWith("5"))
+        return "pull-failed:5xx";
+    if (errorCode &&
+        /^(?:EAI_AGAIN|ENOTFOUND|ECONNRESET|ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|EPIPE|ECONNABORTED)$/.test(errorCode)) {
+        return "pull-failed:network";
+    }
+    return "pull-failed:other";
+}
+//# sourceMappingURL=refresh-sync-outcome.js.map

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

@@ -18,7 +18,7 @@
  * per-item result shape where both are optional.
  */
 import { type DoctorPlatform, type StatusCounts } from "./report.js";
-import type { DoctorStatus, FamilyRun } from "./types.js";
+import type { DoctorStatus, FamilyRun, SyncReasonCode } from "./types.js";
 /**
  * The `--json` schema version. Bump on any breaking change to the document
  * shape; the snapshot test in report.test.ts fails until the bump is
@@ -50,6 +50,10 @@ export interface DoctorJsonResult {
     family: string;
     /** Stable machine id for the check, e.g. `hooks.settings-present`. */
     checkId: string;
+    /** Stable classification for the sync family; contains no customer data. */
+    reasonCode?: SyncReasonCode;
+    /** Present only when this result's company opted in through hq-flags. */
+    clientHealthReasonCodesEnabled?: true;
     /** What was inspected. Present only when the result carries one. */
     target?: string;
     /** Human-readable explanation. */
@@ -92,6 +96,8 @@ export interface BuildDoctorJsonInput {
     platform?: DoctorPlatform;
     /** Families this run was restricted to. Omitted on a full run. */
     scope?: readonly string[];
+    /** Check ids whose own company enabled diagnostic reason codes in hq-flags. */
+    clientHealthReasonCodesEnabledCheckIds?: ReadonlySet<string>;
 }
 /** Assemble the machine-readable document from a completed run. */
 export declare function buildDoctorJson(input: BuildDoctorJsonInput): DoctorJsonDocument;

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

@@ -34,7 +34,7 @@ export function buildDoctorJson(input) {
     const results = [];
     for (const run of input.families) {
         for (const result of run.results) {
-            results.push(toJsonResult(run.family.id, result));
+            results.push(toJsonResult(run.family.id, result, input.clientHealthReasonCodesEnabledCheckIds));
         }
     }
     return {
@@ -48,12 +48,16 @@ export function buildDoctorJson(input) {
     };
 }
 /** Convert one {@link CheckResult} into its JSON form, omitting empty optionals. */
-function toJsonResult(familyId, result) {
+function toJsonResult(familyId, result, clientHealthReasonCodesEnabledCheckIds) {
     const remediation = deriveRemediation(result);
     return {
         status: result.status,
         family: familyId,
         checkId: result.checkId,
+        ...(result.reasonCode !== undefined ? { reasonCode: result.reasonCode } : {}),
+        ...(clientHealthReasonCodesEnabledCheckIds?.has(result.checkId)
+            ? { clientHealthReasonCodesEnabled: true }
+            : {}),
         ...(result.target !== undefined ? { target: result.target } : {}),
         message: result.message,
         ...(result.remediation !== undefined

package/dist/lib/doctor/types.d.ts

@@ -18,6 +18,9 @@ export declare const DOCTOR_STATUSES: readonly ["PASS", "FAIL", "WARN", "UNTESTE
  * the type system rejects any other string at every call site.
  */
 export type DoctorStatus = (typeof DOCTOR_STATUSES)[number];
+/** Stable, privacy-safe diagnostics emitted by the sync health family. */
+export declare const SYNC_REASON_CODES: readonly ["core-version-unavailable", "core-update-available", "no-local-tree", "never-synced", "invalid-last-sync", "stale-threshold", "manifest-unavailable", "manifest-state-unavailable", "no-manifest-scopes", "never-uploaded", "invalid-upload-time", "unresolved-company-uid"];
+export type SyncReasonCode = (typeof SYNC_REASON_CODES)[number];
 /** Runtime type guard: true only for a member of the fixed vocabulary. */
 export declare function isDoctorStatus(value: unknown): value is DoctorStatus;
 /** A single per-item result produced by a check family. */
@@ -26,6 +29,8 @@ export interface CheckResult {
     status: DoctorStatus;
     /** Stable machine id for this item, e.g. `hooks.settings-present`. */
     checkId: string;
+    /** Closed diagnostic enum; never contains paths, company slugs, or prose. */
+    reasonCode?: SyncReasonCode;
     /** What was inspected — a path, hook id, etc. Optional. */
     target?: string;
     /** Human-readable one-line explanation of the result. */

package/dist/lib/doctor/types.js

@@ -21,6 +21,21 @@ export const DOCTOR_STATUSES = [
     "UNKNOWN",
     "KNOWN-DEFECT",
 ];
+/** Stable, privacy-safe diagnostics emitted by the sync health family. */
+export const SYNC_REASON_CODES = [
+    "core-version-unavailable",
+    "core-update-available",
+    "no-local-tree",
+    "never-synced",
+    "invalid-last-sync",
+    "stale-threshold",
+    "manifest-unavailable",
+    "manifest-state-unavailable",
+    "no-manifest-scopes",
+    "never-uploaded",
+    "invalid-upload-time",
+    "unresolved-company-uid",
+];
 /** Runtime type guard: true only for a member of the fixed vocabulary. */
 export function isDoctorStatus(value) {
     return (typeof value === "string" &&

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

@@ -22,6 +22,6 @@ export type { DaemonDoctorDeps, DaemonDoctorReport } from "./doctor.js";
 export { scopeBundleToAgentIdentity, } from "./credentials.js";
 export { FLUSH_INTERVAL_MS, DAEMON_VERSION_DRIFT_EXIT_CODE, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";
 export type { DaemonHandle, DaemonRunDeps } from "./run.js";
-export { TRANSCRIPT_ADAPTER_VERSION, TRANSCRIPT_EVENT_SOURCE, TRANSCRIPT_FRESH_MS, TRANSCRIPT_HOOK_COVER_MS, TRANSCRIPT_MARKER, TRANSCRIPT_SESSION_END_MS, TRANSCRIPT_TURN_QUIET_MS, TRANSCRIPT_WATCH_BACKOFF_DURATION_MS, TRANSCRIPT_WATCH_BACKOFF_ENTRIES, TRANSCRIPT_WATCH_ENTRY_CAP, TRANSCRIPT_WATCH_INTERVAL_MAX_MS, TRANSCRIPT_WATCH_INTERVAL_MS, TRANSCRIPT_WATCH_REVALIDATE_MS, TranscriptWatcher, createTranscriptDiscoverCache, decodeClaudeProjectDirName, defaultTranscriptFs, discoverTranscripts, discoverTranscriptsWithMeta, isTranscriptHookCovered, nextTranscriptWatchIntervalMs, noteHookSessionsFromSpoolFile, resolveTranscriptRegistration, sessionIdFromClaudeTranscriptPath, sessionIdFromCodexTranscriptPath, sortDiscoveries, } from "./transcript-watch.js";
+export { TRANSCRIPT_ADAPTER_VERSION, TRANSCRIPT_EVENT_SOURCE, TRANSCRIPT_FRESH_MS, TRANSCRIPT_HOOK_COVER_MS, TRANSCRIPT_MARKER, TRANSCRIPT_SESSION_END_MS, TRANSCRIPT_HOOK_QUIET_ADOPT_MS, TRANSCRIPT_TURN_QUIET_MS, TRANSCRIPT_WATCH_BACKOFF_DURATION_MS, TRANSCRIPT_WATCH_BACKOFF_ENTRIES, TRANSCRIPT_WATCH_ENTRY_CAP, TRANSCRIPT_WATCH_INTERVAL_MAX_MS, TRANSCRIPT_WATCH_INTERVAL_MS, TRANSCRIPT_WATCH_REVALIDATE_MS, TranscriptWatcher, createTranscriptDiscoverCache, decodeClaudeProjectDirName, defaultTranscriptFs, discoverTranscripts, discoverTranscriptsWithMeta, isTranscriptHookCovered, nextTranscriptWatchIntervalMs, noteHookSessionsFromSpoolFile, resolveTranscriptRegistration, sessionIdFromClaudeTranscriptPath, sessionIdFromCodexTranscriptPath, sortDiscoveries, } from "./transcript-watch.js";
 export type { DiscoveredTranscript, DiscoverScanMeta, DiscoverTranscriptsResult, TranscriptDiscoverCache, TranscriptFs, TranscriptKind, TranscriptWatchDeps, TranscriptWatchTickResult, } from "./transcript-watch.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/mesh/live/daemon/index.js

@@ -11,5 +11,5 @@ export { daemonConfigPath, findAncestorHqRoot, isInstallableHqRoot, readDaemonCo
 export { UNHEALTHY_SPOOL_AGE_MS, collectDaemonDoctor, formatCliIdentityLines, formatCliMismatchLine, formatDaemonDoctor, listHqBinariesOnPath, } from "./doctor.js";
 export { scopeBundleToAgentIdentity, } from "./credentials.js";
 export { FLUSH_INTERVAL_MS, DAEMON_VERSION_DRIFT_EXIT_CODE, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";
-export { TRANSCRIPT_ADAPTER_VERSION, TRANSCRIPT_EVENT_SOURCE, TRANSCRIPT_FRESH_MS, TRANSCRIPT_HOOK_COVER_MS, TRANSCRIPT_MARKER, TRANSCRIPT_SESSION_END_MS, TRANSCRIPT_TURN_QUIET_MS, TRANSCRIPT_WATCH_BACKOFF_DURATION_MS, TRANSCRIPT_WATCH_BACKOFF_ENTRIES, TRANSCRIPT_WATCH_ENTRY_CAP, TRANSCRIPT_WATCH_INTERVAL_MAX_MS, TRANSCRIPT_WATCH_INTERVAL_MS, TRANSCRIPT_WATCH_REVALIDATE_MS, TranscriptWatcher, createTranscriptDiscoverCache, decodeClaudeProjectDirName, defaultTranscriptFs, discoverTranscripts, discoverTranscriptsWithMeta, isTranscriptHookCovered, nextTranscriptWatchIntervalMs, noteHookSessionsFromSpoolFile, resolveTranscriptRegistration, sessionIdFromClaudeTranscriptPath, sessionIdFromCodexTranscriptPath, sortDiscoveries, } from "./transcript-watch.js";
+export { TRANSCRIPT_ADAPTER_VERSION, TRANSCRIPT_EVENT_SOURCE, TRANSCRIPT_FRESH_MS, TRANSCRIPT_HOOK_COVER_MS, TRANSCRIPT_MARKER, TRANSCRIPT_SESSION_END_MS, TRANSCRIPT_HOOK_QUIET_ADOPT_MS, TRANSCRIPT_TURN_QUIET_MS, TRANSCRIPT_WATCH_BACKOFF_DURATION_MS, TRANSCRIPT_WATCH_BACKOFF_ENTRIES, TRANSCRIPT_WATCH_ENTRY_CAP, TRANSCRIPT_WATCH_INTERVAL_MAX_MS, TRANSCRIPT_WATCH_INTERVAL_MS, TRANSCRIPT_WATCH_REVALIDATE_MS, TranscriptWatcher, createTranscriptDiscoverCache, decodeClaudeProjectDirName, defaultTranscriptFs, discoverTranscripts, discoverTranscriptsWithMeta, isTranscriptHookCovered, nextTranscriptWatchIntervalMs, noteHookSessionsFromSpoolFile, resolveTranscriptRegistration, sessionIdFromClaudeTranscriptPath, sessionIdFromCodexTranscriptPath, sortDiscoveries, } from "./transcript-watch.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/mesh/live/daemon/transcript-watch.d.ts

@@ -62,6 +62,13 @@ export declare const TRANSCRIPT_START_RETRY_BASE_MS = 30000;
 export declare const TRANSCRIPT_START_RETRY_MAX_MS = 120000;
 /** Ignore cold transcripts whose mtime is older than this on first sight. */
 export declare const TRANSCRIPT_FRESH_MS: number;
+/**
+ * Hook-covered sessions skipped as "stale" on first sight never got a quiet
+ * session_end (live: skippedHook=411, ended=0). Adopt them for this long after
+ * last activity so a 10–120 min quiet window still reports after a daemon
+ * restart or a missed track. Older than this stays silent (the 6h reaper).
+ */
+export declare const TRANSCRIPT_HOOK_QUIET_ADOPT_MS: number;
 export declare const TRANSCRIPT_MARKER: "from transcript";
 export declare const TRANSCRIPT_ADAPTER_VERSION: string;
 /** Network `source` stamped on every synthesized event (AMEND-001). */

package/dist/lib/mesh/live/daemon/transcript-watch.js

@@ -67,6 +67,13 @@ export const TRANSCRIPT_START_RETRY_BASE_MS = 30_000;
 export const TRANSCRIPT_START_RETRY_MAX_MS = 120_000;
 /** Ignore cold transcripts whose mtime is older than this on first sight. */
 export const TRANSCRIPT_FRESH_MS = TRANSCRIPT_SESSION_END_MS;
+/**
+ * Hook-covered sessions skipped as "stale" on first sight never got a quiet
+ * session_end (live: skippedHook=411, ended=0). Adopt them for this long after
+ * last activity so a 10–120 min quiet window still reports after a daemon
+ * restart or a missed track. Older than this stays silent (the 6h reaper).
+ */
+export const TRANSCRIPT_HOOK_QUIET_ADOPT_MS = 2 * 60 * 60 * 1000;
 export const TRANSCRIPT_MARKER = "from transcript";
 export const TRANSCRIPT_ADAPTER_VERSION = CLI_VERSION;
 /** Network `source` stamped on every synthesized event (AMEND-001). */
@@ -521,13 +528,24 @@ export function noteHookSessionsFromSpoolFile(spoolPath, lastHookEventAt, atMs,
         if (!line.trim())
             continue;
         try {
-            const ev = JSON.parse(line);
+            const raw = JSON.parse(line);
+            const ev = raw.event && typeof raw.event === "object" ? raw.event : raw;
             if (typeof ev.sessionId !== "string" || !ev.sessionId)
                 continue;
             // Synthesized transcript events carry source=transcript — not hooks.
             if (ev.source === TRANSCRIPT_EVENT_SOURCE)
                 continue;
-            lastHookEventAt.set(ev.sessionId, atMs);
+            let eventAt = atMs;
+            const atRaw = typeof ev.at === "string" ? ev.at : undefined;
+            if (atRaw) {
+                const parsed = Date.parse(atRaw);
+                if (Number.isFinite(parsed))
+                    eventAt = parsed;
+            }
+            const prev = lastHookEventAt.get(ev.sessionId);
+            if (prev === undefined || eventAt > prev) {
+                lastHookEventAt.set(ev.sessionId, eventAt);
+            }
             noted.push(ev.sessionId);
         }
         catch {
@@ -739,7 +757,10 @@ export class TranscriptWatcher {
         const lastActivity = Math.max(d.mtimeMs, hookAt ?? 0);
         let track = this.tracked.get(d.path);
         if (!track) {
-            if (nowMs - lastActivity > TRANSCRIPT_FRESH_MS)
+            // Cold transcripts stay silent. Hook-covered sessions that already sat
+            // quiet past TRANSCRIPT_SESSION_END_MS still need one session_end — the
+            // live skip path returned here and never tracked them (US-051).
+            if (nowMs - lastActivity > TRANSCRIPT_HOOK_QUIET_ADOPT_MS)
                 return;
             track = {
                 path: d.path,
@@ -857,6 +878,7 @@ export class TranscriptWatcher {
             root: this.deps.workMeshRoot,
             env: this.deps.env,
             now: () => new Date(nowMs),
+            ...(kind === "session_end" ? { transcriptPath: track.path } : {}),
         };
         this.enqueueFn(opts);
     }

package/dist/lib/mesh/live/emit-client.d.ts

@@ -74,6 +74,9 @@ export interface MeshEmitEvent {
     status?: "queued" | "in_progress" | "review" | "done";
     reason?: string;
     summary?: string;
+    repo?: string;
+    gitBranch?: string;
+    prUrls?: string[];
     evidence?: EmitEvidence;
 }
 export interface BuildMeshEmitEventInput {
@@ -90,6 +93,9 @@ export interface BuildMeshEmitEventInput {
     status?: "queued" | "in_progress" | "review" | "done";
     reason?: string;
     summary?: string;
+    repo?: string;
+    gitBranch?: string;
+    prUrls?: string[];
     evidence?: EmitEvidence;
 }
 /**

package/dist/lib/mesh/live/emit-client.js

@@ -192,6 +192,14 @@ export function buildMeshEmitEvent(input) {
     const summary = keep(input.summary);
     if (summary)
         event.summary = summary;
+    const repo = keep(input.repo);
+    if (repo)
+        event.repo = repo;
+    const gitBranch = keep(input.gitBranch);
+    if (gitBranch)
+        event.gitBranch = gitBranch;
+    if (input.prUrls && input.prUrls.length > 0)
+        event.prUrls = input.prUrls;
     if (input.evidence && Object.keys(input.evidence).length > 0) {
         event.evidence = input.evidence;
     }