@indigoai-us/hq-cli 5.345.163 → 5.345.164

package/dist/lib/doctor/checks/sync-runtime.js

@@ -3,13 +3,27 @@
  * (realtime lag, receiver permission errors, restart loops, device-limit
  * backoff) plus the conflict counter the desktop app keeps in client health.
  *
- * Results carry only a closed reason code and counts. Log content (paths,
- * tenant ids, AWS error prose) never leaves this module.
+ * Results carry a closed reason code and counts. Log content (tenant ids, AWS
+ * error prose, queue URLs, absolute local paths) never leaves this module.
+ *
+ * Two exceptions, both bounded and both local-only (the client-health report
+ * forwards check ids, never `details`):
+ *   - `sync.runtime.receiver-permission` carries `details.byCall`, a count per
+ *     closed call class (which cloud call was refused), so a refusal on the
+ *     per-device queue credentials can be told apart from a refusal on the
+ *     object pull that follows a change event. Before this, 28 automated
+ *     client-health reports carried only the count (feedback_cd56a501).
+ *   - `sync.runtime.pull-access-denied` names the vault keys (never absolute
+ *     local paths) the receiver was refused on pull, with the runner's bounded
+ *     `reason` tag, capped at {@link PULL_DENIED_KEY_CAP} keys, so the stored
+ *     grant can be compared with the key the pull looked up (policy
+ *     hq-authorization-path-canonicalization).
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { currentSyncLogFamily, SYNC_LOG_GENERATIONS, syncLogBasePaths, syncLogGenerationPath, } from "../../../utils/sync-log-sources.js";
+import { readSessionCompanyLock } from "../../session-company-lock.js";
 export const SYNC_RUNTIME_WINDOW_MS = 60 * 60_000;
 /** Ignore timing and restart signals until a newly started receiver has settled. */
 export const SYNC_RUNTIME_RESTART_WARMUP_MS = 20 * 60_000;
@@ -18,9 +32,93 @@ const LAG_MIN_RECEIPTS = 3;
 const RESTART_MIN_STARTS = 4;
 const CONFLICT_MIN_COUNT = 5;
 const LOG_TAIL_BYTES = 8 * 1024 * 1024;
+/** Most refused vault keys named by `sync.runtime.pull-access-denied`. */
+export const PULL_DENIED_KEY_CAP = 10;
 const TIMESTAMP = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)\s/;
 const PERMISSION = /AccessDenied|not authorized to perform|\b403\b/;
 const DEVICE_LIMIT = /sync device limit exceeded|"sync_device_limit"/;
+const SUBSCRIBE_ROUTE = /\/v1\/sync\/subscribe/;
+/** A vault key is relative; anything that looks like a local absolute path is dropped. */
+const ABSOLUTE_LOCAL_PATH = /^(?:\/|[A-Za-z]:[\\/]|\\\\)/;
+/**
+ * Vault keys this check will name. Printable, no control characters, no
+ * backslashes, no shell metacharacters other than space, `@`, `+`, `(`, `)`.
+ * The key is also single-quoted when embedded in the remediation command, so
+ * a `'` inside a key cannot end the quote. Keys outside this set are counted
+ * but not named.
+ */
+const NAMEABLE_VAULT_KEY = /^[A-Za-z0-9._\/ @()+'-]{1,512}$/;
+/** A key refused on at least this many pulls in the hour is a standing condition, not a one-off. */
+export const PULL_DENIED_MIN_REPEATS = 2;
+/** The runner's bounded machine tag on a `skip-access-denied` event. */
+const REASON_TAG = /^[A-Za-z0-9_-]{1,40}$/;
+/** Placeholder scope for a refusal whose runner event carried no usable company label. */
+const UNKNOWN_COMPANY = "unknown";
+const PERSONAL_VAULT_SLUGS = new Set(["personal", "__hq_personal_vault__"]);
+const COMPANY_SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
+const RECEIVER_EVENT_CALLS = {
+    "receiver.receive.failed": "sqs-receive",
+    "receiver.retry.failed": "sqs-visibility",
+    "receiver.lease.extend.failed": "sqs-visibility",
+    "receiver.release.failed": "sqs-visibility",
+    "receiver.delete.failed": "sqs-delete",
+    "receiver.metric.failed": "cloudwatch-metric",
+    "receiver.sync.failed": "targeted-pull",
+    "receiver.drain.failed": "targeted-pull",
+};
+function classifyRefusal(record, errText) {
+    const event = typeof record.event === "string" ? record.event : "";
+    if (SUBSCRIBE_ROUTE.test(errText))
+        return "subscribe";
+    const byEvent = RECEIVER_EVENT_CALLS[event];
+    if (byEvent)
+        return byEvent;
+    if (record.type === "error")
+        return "runner-error";
+    return "other";
+}
+const QUEUE_LEG = new Set([
+    "subscribe", "sqs-receive", "sqs-visibility", "sqs-delete", "cloudwatch-metric",
+]);
+function receiverPermissionRemediation(byCall) {
+    const classes = Object.keys(byCall);
+    const queueLeg = classes.some((call) => QUEUE_LEG.has(call));
+    const pullLeg = classes.includes("targeted-pull");
+    const parts = [];
+    if (queueLeg) {
+        parts.push("The queue credentials vended by POST /v1/sync/subscribe were refused on the per-device queue leg; " +
+            "restart the sync runner so it re-subscribes, then run `hq sync status`. If it repeats, the device roster entry for this machine needs attention (hq-pro device slots).");
+    }
+    if (pullLeg) {
+        parts.push("The object pull after a change event was refused; see sync.runtime.pull-access-denied for the refused keys and the grant to compare.");
+    }
+    if (parts.length === 0) {
+        parts.push("Run `hq sync status` and inspect the selected sync log under ~/.hq/logs/, ~/.hq/daemon/logs/, or the configured HQ_DAEMON_DIR/logs/.");
+    }
+    return parts.join(" ");
+}
+/** POSIX single-quote: safe to paste into a shell whatever the key holds. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function pullDeniedRemediation(latest) {
+    let lookup;
+    if (!latest) {
+        lookup = "Run `hq doctor` in a session locked to the company that owns the refused keys to see them named, then compare the stored grant with `hq files acl <key> --company <company>`. ";
+    }
+    else if (latest.company === UNKNOWN_COMPANY) {
+        lookup = "The runner did not record which company owns this key, so no lookup command is suggested; find the company that holds it and run `hq files acl <key> --company <company>`. ";
+    }
+    else {
+        const scope = latest.company === "personal" ? "" : ` --company ${latest.company}`;
+        lookup = `Compare the stored grant with the key the pull looked up: hq files acl ${shellQuote(latest.path)}${scope}. `;
+    }
+    return ("The receiver was addressed this change, so the publisher's grant evaluation allowed it, while the pull resolver refused it. " +
+        lookup +
+        "A read grant must cover the key via '*', the key itself, or an ancestor as 'A', 'A/' or 'A/*', naming you, one of your groups, or company-wide; " +
+        "the owner/admin bypass needs viewOthersFiles (viewOthersMeetings for meetings/, sources/, signals/ and knowledge/), and sessions/<other person> is creator-or-owner only. " +
+        "The key stays unjournaled and is retried each pass until the grant covers it.");
+}
 function parseRecord(rest) {
     const start = rest.indexOf("{");
     if (start < 0)
@@ -68,6 +166,9 @@ export function analyzeSyncRuntimeLog(lines, options) {
     const slowReceiptTimes = [];
     const receiverStartTimes = [];
     let denied = 0;
+    const deniedByCall = {};
+    let pullsDenied = 0;
+    const deniedKeys = new Map();
     let starts = 0;
     let deviceLimited = 0;
     for (const line of lines) {
@@ -84,6 +185,37 @@ export function analyzeSyncRuntimeLog(lines, options) {
         if (!record)
             continue;
         const event = record.event;
+        if (record.type === "skip-access-denied" && time >= since) {
+            // A deliberate per-object pull skip from the runner: the publisher
+            // addressed this device a change the pull resolver then refused. The
+            // event carries the vault key (relative by construction) and a bounded
+            // reason tag; the free-text `message` is never copied.
+            pullsDenied += 1;
+            const pathValue = typeof record.path === "string" ? record.path : "";
+            const rawCompany = typeof record.company === "string" ? record.company : "";
+            const company = PERSONAL_VAULT_SLUGS.has(rawCompany)
+                ? "personal"
+                : COMPANY_SLUG.test(rawCompany) ? rawCompany : UNKNOWN_COMPANY;
+            const reason = typeof record.reason === "string" && REASON_TAG.test(record.reason) ? record.reason : "denied";
+            // Refusals are grouped by (company, key) whatever the reason tag, and
+            // the latest tag is kept. A key that cannot be named (absolute or
+            // non-printable) is still grouped so it counts toward the repeat
+            // threshold, but it is never emitted.
+            const nameable = pathValue !== "" && !ABSOLUTE_LOCAL_PATH.test(pathValue) && NAMEABLE_VAULT_KEY.test(pathValue);
+            const key = `${company}\u0000${pathValue}`;
+            const existing = deniedKeys.get(key);
+            if (existing) {
+                existing.count += 1;
+                if (time >= existing.lastSeen) {
+                    existing.lastSeen = time;
+                    existing.reason = reason;
+                }
+            }
+            else {
+                deniedKeys.set(key, { company, path: pathValue, reason, count: 1, lastSeen: time, nameable });
+            }
+            continue;
+        }
         if (event === "receiver.start") {
             receiverStartTimes.push(time);
             const settledAt = time + SYNC_RUNTIME_RESTART_WARMUP_MS;
@@ -99,11 +231,36 @@ export function analyzeSyncRuntimeLog(lines, options) {
         }
         if (time >= since &&
             (record.type === "receiver" || record.type === "error" ||
-                (typeof event === "string" && event.startsWith("receiver."))) &&
-            PERMISSION.test(JSON.stringify(record.err ?? record.message ?? ""))) {
-            denied += 1;
+                (typeof event === "string" && event.startsWith("receiver.")))) {
+            const errText = JSON.stringify(record.err ?? record.message ?? "");
+            if (PERMISSION.test(errText)) {
+                denied += 1;
+                const call = classifyRefusal(record, errText);
+                deniedByCall[call] = (deniedByCall[call] ?? 0) + 1;
+            }
         }
     }
+    const byCallSummary = Object.entries(deniedByCall)
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([call, count]) => `${call} ${count}`)
+        .join(", ");
+    // The runner retries a refused key on every pass by design (the object
+    // stays unjournaled until the grant covers it). One refusal is a race with
+    // a share in flight; the same key refused again within the hour is a grant
+    // that does not cover what the publisher addressed. Only repeated keys are
+    // reported, named or counted.
+    const repeatedKeys = [...deniedKeys.values()]
+        .filter((key) => key.count >= PULL_DENIED_MIN_REPEATS)
+        .sort((a, b) => b.lastSeen - a.lastSeen || b.count - a.count);
+    const repeatedDenials = repeatedKeys.length > 0;
+    const nameableScopes = options.nameableCompanies === undefined ? null : new Set(options.nameableCompanies);
+    const namedKeys = repeatedKeys.filter((key) => key.nameable && (nameableScopes === null || nameableScopes.has(key.company)));
+    const unnamedRepeated = repeatedKeys.length - namedKeys.length;
+    const sortedDeniedKeys = namedKeys.slice(0, PULL_DENIED_KEY_CAP);
+    const latestDenied = sortedDeniedKeys[0];
+    const unnamedNote = unnamedRepeated > 0
+        ? ` ${unnamedRepeated} of them ${unnamedRepeated === 1 ? "is" : "are"} not named here (outside this session's companies, or not printable).`
+        : "";
     // Startup can temporarily expose queued receive latency and restart events
     // while the receiver is warming its backlog. Only judge receipts outside the
     // warm-up interval following the most recent preceding start.
@@ -111,7 +268,41 @@ export function analyzeSyncRuntimeLog(lines, options) {
     const conflicts = options.conflictCount ?? 0;
     const checks = [
         { id: "realtime-lag", reasonCode: "realtime-lag-stuck", failing: slowReceipts >= LAG_MIN_RECEIPTS, count: slowReceipts, label: "incoming changes delayed over 15 minutes" },
-        { id: "receiver-permission", reasonCode: "receiver-permission-denied", failing: denied > 0, count: denied, label: "cloud permission refusals" },
+        {
+            id: "receiver-permission",
+            reasonCode: "receiver-permission-denied",
+            failing: denied > 0,
+            count: denied,
+            label: "cloud permission refusals",
+            ...(denied > 0
+                ? {
+                    message: `${denied} cloud permission refusals in the last hour (${byCallSummary}).`,
+                    details: { byCall: deniedByCall },
+                    remediation: receiverPermissionRemediation(deniedByCall),
+                }
+                : {}),
+        },
+        {
+            id: "pull-access-denied",
+            reasonCode: "pull-access-denied",
+            failing: repeatedDenials,
+            count: pullsDenied,
+            label: "pulls refused",
+            ...(repeatedDenials
+                ? {
+                    message: `${pullsDenied} pulls refused in the last hour; ${repeatedKeys.length} vault keys refused ${PULL_DENIED_MIN_REPEATS} or more times` +
+                        (latestDenied ? `; most recent: ${latestDenied.company} ${latestDenied.path} (${latestDenied.reason}).` : ".") +
+                        unnamedNote,
+                    details: {
+                        count: pullsDenied,
+                        repeatedKeys: repeatedKeys.length,
+                        unnamedKeys: unnamedRepeated,
+                        keys: sortedDeniedKeys.map(({ company, path: keyPath, reason, count }) => ({ company, path: keyPath, reason, count })),
+                    },
+                    remediation: pullDeniedRemediation(latestDenied),
+                }
+                : {}),
+        },
         { id: "runner-restarts", reasonCode: "runner-restart-loop", failing: starts >= RESTART_MIN_STARTS, count: starts, label: "settled sync runner starts" },
         { id: "device-limit", reasonCode: "device-limit-backoff", failing: deviceLimited > 0, count: deviceLimited, label: "device-limit backoffs" },
         { id: "conflicts", reasonCode: "repeated-conflicts", failing: conflicts >= CONFLICT_MIN_COUNT, count: conflicts, label: "unresolved conflicts" },
@@ -121,8 +312,10 @@ export function analyzeSyncRuntimeLog(lines, options) {
             status: "WARN",
             checkId: `sync.runtime.${check.id}`,
             reasonCode: check.reasonCode,
-            message: `${check.count} ${check.label} in the last hour.`,
-            remediation: "Run `hq sync status` and inspect the selected sync log under ~/.hq/logs/, ~/.hq/daemon/logs/, or the configured HQ_DAEMON_DIR/logs/.",
+            message: check.message ?? `${check.count} ${check.label} in the last hour.`,
+            ...(check.details ? { details: check.details } : {}),
+            remediation: check.remediation ??
+                "Run `hq sync status` and inspect the selected sync log under ~/.hq/logs/, ~/.hq/daemon/logs/, or the configured HQ_DAEMON_DIR/logs/.",
         }
         : {
             status: "PASS",
@@ -185,11 +378,27 @@ function readConflictCount(file) {
         return 0;
     }
 }
+/**
+ * Company scopes this session may see named: `undefined` (all) when there is
+ * no session or no company lock; nothing when the lock cannot be verified.
+ */
+export function sessionNameableCompanies(env, readLock = readSessionCompanyLock) {
+    try {
+        const lock = readLock(env);
+        if (!lock || lock.companies.length === 0)
+            return undefined;
+        return lock.companies;
+    }
+    catch {
+        return [];
+    }
+}
 /** Read the machine's sync logs and client health file. */
 export function defaultSyncRuntimeResults(now, hqHome = path.join(os.homedir(), ".hq"), env = process.env) {
     const options = {
         now: now.getTime(),
         conflictCount: readConflictCount(path.join(hqHome, "client-health.json")),
+        nameableCompanies: sessionNameableCompanies(env),
     };
     const paths = syncLogBasePaths(hqHome, env);
     const familyModifiedMs = (family) => {

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

@@ -380,6 +380,7 @@ export async function applyFixes(options) {
         writeRefreshSyncLastRun(hqRoot, {
             lastAttemptedSlug: lastAttemptedRefreshSyncSlug ?? refreshSyncApplied.at(-1).target,
             lastRunAttemptedCheckIds: refreshSyncApplied.map((fix) => fix.checkId),
+            lastRunOutcomes: Object.fromEntries(refreshSyncApplied.flatMap((fix) => fix.refreshSyncOutcome ? [[fix.checkId, fix.refreshSyncOutcome]] : [])),
             lastRunAtMs: backupClock().getTime(),
         });
     }

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

@@ -1,5 +1,8 @@
 /** 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 declare const REFRESH_SYNC_OUTCOMES: readonly ["pull-succeeded", "pull-timeout", "pull-failed:4xx", "pull-failed:5xx", "pull-failed:network", "pull-failed:other"];
+export type RefreshSyncOutcome = (typeof REFRESH_SYNC_OUTCOMES)[number];
+/** Outcomes that say nothing about the journal itself: offline, timed out, or the service failed. */
+export declare const TRANSIENT_REFRESH_SYNC_OUTCOMES: ReadonlySet<RefreshSyncOutcome>;
 export interface RefreshSyncObservation {
     errorCode?: string;
     signal?: string | null;

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

@@ -1,3 +1,18 @@
+/** Privacy-safe outcomes for a targeted refresh-sync attempt. */
+export const REFRESH_SYNC_OUTCOMES = [
+    "pull-succeeded",
+    "pull-timeout",
+    "pull-failed:4xx",
+    "pull-failed:5xx",
+    "pull-failed:network",
+    "pull-failed:other",
+];
+/** Outcomes that say nothing about the journal itself: offline, timed out, or the service failed. */
+export const TRANSIENT_REFRESH_SYNC_OUTCOMES = new Set([
+    "pull-timeout",
+    "pull-failed:network",
+    "pull-failed:5xx",
+]);
 /** Classify process/HTTP results without retaining their free-text details. */
 export function classifyRefreshSyncOutcome(observation) {
     const details = String(observation.stdout ?? "") + "\n" + String(observation.stderr ?? "");

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

@@ -8,16 +8,45 @@
  * pass did not try — SessionStart hooks, including older ones that only
  * call `hq doctor --json`, otherwise file those leftover rows as unrepaired.
  */
+import { type RefreshSyncOutcome } from "./refresh-sync-outcome.js";
 import type { CheckResult } from "../types.js";
 export declare const REFRESH_SYNC_PROGRESS_RELATIVE_PATH: string;
 /** Hook re-verify runs immediately after `--fix`; 15 minutes covers a slow box. */
 export declare const CLIENT_HEALTH_REFRESH_SYNC_FRESH_MS: number;
 export interface RefreshSyncProgress {
+    /**
+     * Stays at 2. `lastRunOutcomes` and `transientSinceMs` are additive optional
+     * fields: an older CLI sharing this HQ root (desktop-bundled vs npm global,
+     * a pinned bot binary) accepts only versions 1 and 2 and throws on anything
+     * else from `--fix`'s own cursor read, so bumping the number would break its
+     * repair pass. Unknown fields are ignored by every reader.
+     */
     version: 1 | 2;
     lastAttemptedSlug: string;
     lastRunAttemptedCheckIds?: string[];
+    /**
+     * Per-check outcome of the last completed pass. Lets doctor JSON tell a
+     * pull that failed because the machine was offline or the service hiccuped
+     * (transient; retried next SessionStart) from one the service refused (4xx)
+     * or that failed for an unknown reason, so the client-health hook does not
+     * file an "unrepaired" report for a laptop that simply had no network at
+     * SessionStart (feedback_cd56a501 cluster: 19 of 28 reports were stale
+     * journals, most on installs whose pull did not complete).
+     */
+    lastRunOutcomes?: Record<string, RefreshSyncOutcome>;
+    /**
+     * When each check's current run of consecutive transient outcomes began.
+     * Cleared the moment a pass ends with any other outcome. Bounds the hiding:
+     * a journal transiently unrefreshed for longer than
+     * {@link TRANSIENT_REFRESH_SYNC_MAX_MS} is reported again, so a machine
+     * that can never reach the service (wrong endpoint, blocked network) still
+     * files a report instead of hiding forever.
+     */
+    transientSinceMs?: Record<string, number>;
     lastRunAtMs?: number;
 }
+/** A journal transiently unrefreshed for longer than this is reported again. */
+export declare const TRANSIENT_REFRESH_SYNC_MAX_MS: number;
 export declare function readRefreshSyncProgress(hqRoot: string): RefreshSyncProgress | null;
 /**
  * `--fix` manifest-upload cursor. Kept in its own file so the refresh-sync
@@ -39,8 +68,21 @@ export declare function writeRefreshSyncCursor(hqRoot: string, slug: string): vo
 export declare function writeRefreshSyncLastRun(hqRoot: string, input: {
     lastAttemptedSlug: string;
     lastRunAttemptedCheckIds: string[];
+    lastRunOutcomes?: Record<string, RefreshSyncOutcome>;
     lastRunAtMs: number;
 }): void;
+/**
+ * Journal check ids whose refresh pull in the last completed `--fix` pass, if
+ * that pass is still fresh, ended in a transient outcome (offline, timeout,
+ * service 5xx). Null when there is no fresh pass or no outcomes were recorded.
+ */
+export declare function freshTransientRefreshSyncCheckIds(hqRoot: string, nowMs: number): ReadonlySet<string> | null;
+/**
+ * True when doctor JSON should hide this stale journal because the fresh
+ * `--fix` pull for it failed transiently. Applies to company and personal
+ * journals alike: an offline laptop cannot refresh either.
+ */
+export declare function isTransientlyUnrefreshedJournalForClientHealth(result: CheckResult, transientCheckIds: ReadonlySet<string> | null): boolean;
 export declare function freshAttemptedCompanyJournalCheckIds(hqRoot: string, nowMs: number): ReadonlySet<string> | null;
 /** True when doctor JSON should hide this leftover company journal. */
 export declare function isUnreachedCompanyJournalForClientHealth(result: CheckResult, attemptedCheckIds: ReadonlySet<string> | null): boolean;

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

@@ -12,15 +12,41 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { isCompanyJournalSlug, journalSlugFromCheckId, } from "../checks/sync-health.js";
 import { deriveRemediation } from "./remediation.js";
+import { REFRESH_SYNC_OUTCOMES, TRANSIENT_REFRESH_SYNC_OUTCOMES, } from "./refresh-sync-outcome.js";
 export const REFRESH_SYNC_PROGRESS_RELATIVE_PATH = path.join("workspace", "doctor", "refresh-sync-progress.json");
 /** Hook re-verify runs immediately after `--fix`; 15 minutes covers a slow box. */
 export const CLIENT_HEALTH_REFRESH_SYNC_FRESH_MS = 15 * 60 * 1000;
+/** A journal transiently unrefreshed for longer than this is reported again. */
+export const TRANSIENT_REFRESH_SYNC_MAX_MS = 24 * 60 * 60 * 1000;
 function progressPath(hqRoot) {
     return path.join(hqRoot, REFRESH_SYNC_PROGRESS_RELATIVE_PATH);
 }
 function isCheckIdList(value) {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string");
 }
+/**
+ * Keep only outcome entries this CLI understands. A newer CLI may write an
+ * outcome this one does not know; dropping that entry (it then counts as
+ * "no recorded outcome") keeps `--fix` working instead of rejecting the
+ * whole cursor. Returns null when the value is not an object at all.
+ */
+function knownOutcomes(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const known = {};
+    for (const [checkId, outcome] of Object.entries(value)) {
+        if (typeof outcome === "string" && REFRESH_SYNC_OUTCOMES.includes(outcome)) {
+            known[checkId] = outcome;
+        }
+    }
+    return known;
+}
+function isTimestampMap(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((ms) => typeof ms === "number" && Number.isFinite(ms)));
+}
 export function readRefreshSyncProgress(hqRoot) {
     let contents;
     try {
@@ -47,6 +73,16 @@ export function readRefreshSyncProgress(hqRoot) {
     if (record.lastRunAtMs !== undefined && !Number.isFinite(record.lastRunAtMs)) {
         throw new Error(`Invalid refresh-sync progress cursor at ${REFRESH_SYNC_PROGRESS_RELATIVE_PATH}`);
     }
+    if (record.lastRunOutcomes !== undefined) {
+        const known = knownOutcomes(record.lastRunOutcomes);
+        if (known === null) {
+            throw new Error(`Invalid refresh-sync progress cursor at ${REFRESH_SYNC_PROGRESS_RELATIVE_PATH}`);
+        }
+        record.lastRunOutcomes = known;
+    }
+    if (record.transientSinceMs !== undefined && !isTimestampMap(record.transientSinceMs)) {
+        throw new Error(`Invalid refresh-sync progress cursor at ${REFRESH_SYNC_PROGRESS_RELATIVE_PATH}`);
+    }
     return record;
 }
 function writeProgressFile(hqRoot, progress, relativePath = REFRESH_SYNC_PROGRESS_RELATIVE_PATH) {
@@ -93,18 +129,82 @@ export function writeRefreshSyncCursor(hqRoot, slug) {
         ...(existing?.lastRunAttemptedCheckIds
             ? { lastRunAttemptedCheckIds: existing.lastRunAttemptedCheckIds }
             : {}),
+        ...(existing?.lastRunOutcomes ? { lastRunOutcomes: existing.lastRunOutcomes } : {}),
+        ...(existing?.transientSinceMs ? { transientSinceMs: existing.transientSinceMs } : {}),
         ...(existing?.lastRunAtMs !== undefined ? { lastRunAtMs: existing.lastRunAtMs } : {}),
     });
 }
 /** Record the check ids this completed `--fix` pass actually tried to refresh. */
 export function writeRefreshSyncLastRun(hqRoot, input) {
+    // Carry the start of each check's transient streak across runs; any other
+    // outcome (or no attempt this run) ends the streak.
+    let previous;
+    try {
+        previous = readRefreshSyncProgress(hqRoot);
+    }
+    catch {
+        previous = null;
+    }
+    const transientSinceMs = {};
+    for (const [checkId, outcome] of Object.entries(input.lastRunOutcomes ?? {})) {
+        if (!TRANSIENT_REFRESH_SYNC_OUTCOMES.has(outcome))
+            continue;
+        const since = previous?.transientSinceMs?.[checkId];
+        transientSinceMs[checkId] = typeof since === "number" ? Math.min(since, input.lastRunAtMs) : input.lastRunAtMs;
+    }
     writeProgressFile(hqRoot, {
         version: 2,
         lastAttemptedSlug: input.lastAttemptedSlug,
         lastRunAttemptedCheckIds: input.lastRunAttemptedCheckIds,
+        ...(input.lastRunOutcomes ? { lastRunOutcomes: input.lastRunOutcomes } : {}),
+        ...(Object.keys(transientSinceMs).length > 0 ? { transientSinceMs } : {}),
         lastRunAtMs: input.lastRunAtMs,
     });
 }
+/**
+ * Journal check ids whose refresh pull in the last completed `--fix` pass, if
+ * that pass is still fresh, ended in a transient outcome (offline, timeout,
+ * service 5xx). Null when there is no fresh pass or no outcomes were recorded.
+ */
+export function freshTransientRefreshSyncCheckIds(hqRoot, nowMs) {
+    let progress;
+    try {
+        progress = readRefreshSyncProgress(hqRoot);
+    }
+    catch {
+        return null;
+    }
+    if (!progress ||
+        progress.lastRunAtMs === undefined ||
+        !progress.lastRunOutcomes ||
+        nowMs - progress.lastRunAtMs < 0 ||
+        nowMs - progress.lastRunAtMs > CLIENT_HEALTH_REFRESH_SYNC_FRESH_MS) {
+        return null;
+    }
+    const outcomes = progress.lastRunOutcomes;
+    const since = progress.transientSinceMs ?? {};
+    return new Set(Object.entries(outcomes)
+        .filter(([checkId, outcome]) => TRANSIENT_REFRESH_SYNC_OUTCOMES.has(outcome) &&
+        // A streak older than the ceiling is no longer "just offline": report it.
+        nowMs - (since[checkId] ?? progress.lastRunAtMs) <= TRANSIENT_REFRESH_SYNC_MAX_MS)
+        .map(([checkId]) => checkId));
+}
+/**
+ * True when doctor JSON should hide this stale journal because the fresh
+ * `--fix` pull for it failed transiently. Applies to company and personal
+ * journals alike: an offline laptop cannot refresh either.
+ */
+export function isTransientlyUnrefreshedJournalForClientHealth(result, transientCheckIds) {
+    if (!transientCheckIds)
+        return false;
+    if (result.status !== "FAIL" && result.status !== "WARN")
+        return false;
+    if (!journalSlugFromCheckId(result.checkId))
+        return false;
+    if (!transientCheckIds.has(result.checkId))
+        return false;
+    return deriveRemediation(result)?.autoFixable === true;
+}
 export function freshAttemptedCompanyJournalCheckIds(hqRoot, nowMs) {
     let progress;
     try {

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

@@ -89,6 +89,13 @@ export interface DoctorJsonDocument {
     scope?: string[];
     /** The full, flattened result list in family/registration order. */
     results: DoctorJsonResult[];
+    /**
+     * Stale sync journals left out of `results` because the fresh `--fix` pull
+     * for them ended offline, timed out, or hit a service 5xx. They are retried
+     * at the next SessionStart; a client-health report must not count them as
+     * unrepaired. Absent when there are none.
+     */
+    transientRefreshSyncCheckIds?: string[];
 }
 /** Input to {@link buildDoctorJson}. */
 export interface BuildDoctorJsonInput {

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

@@ -19,7 +19,7 @@
  */
 import { computeExitCode, emptyStatusCounts, UNKNOWN_PLATFORM, } from "./report.js";
 import { deriveRemediation } from "./fix/remediation.js";
-import { freshAttemptedCompanyJournalCheckIds, isUnreachedCompanyJournalForClientHealth, } from "./fix/refresh-sync-progress.js";
+import { freshAttemptedCompanyJournalCheckIds, freshTransientRefreshSyncCheckIds, isTransientlyUnrefreshedJournalForClientHealth, isUnreachedCompanyJournalForClientHealth, } from "./fix/refresh-sync-progress.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
@@ -75,6 +75,8 @@ function summarizeJsonResults(results) {
 /** Assemble the machine-readable document from a completed run. */
 export function buildDoctorJson(input) {
     const attemptedRefreshSyncCheckIds = freshAttemptedCompanyJournalCheckIds(input.hqRoot, (input.now ?? (() => new Date()))().getTime());
+    const transientRefreshSyncCheckIds = freshTransientRefreshSyncCheckIds(input.hqRoot, (input.now ?? (() => new Date()))().getTime());
+    const transientHidden = [];
     const results = [];
     for (const run of input.families) {
         for (const result of run.results) {
@@ -84,6 +86,10 @@ export function buildDoctorJson(input) {
             if (isUnreachedCompanyJournalForClientHealth(result, attemptedRefreshSyncCheckIds)) {
                 continue;
             }
+            if (isTransientlyUnrefreshedJournalForClientHealth(result, transientRefreshSyncCheckIds)) {
+                transientHidden.push(result.checkId);
+                continue;
+            }
             results.push(toJsonResult(run.family.id, result, input.clientHealthReasonCodesEnabledCheckIds, input.clientHealthCheckStatusEnabledCheckIds));
         }
     }
@@ -95,6 +101,7 @@ export function buildDoctorJson(input) {
         exitCode: computeExitCode(input.families),
         ...(input.scope && input.scope.length > 0 ? { scope: [...input.scope] } : {}),
         results,
+        ...(transientHidden.length > 0 ? { transientRefreshSyncCheckIds: transientHidden } : {}),
     };
 }
 /** Convert one {@link CheckResult} into its JSON form, omitting empty optionals. */

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

@@ -19,7 +19,7 @@ export declare const DOCTOR_STATUSES: readonly ["PASS", "FAIL", "WARN", "UNTESTE
  */
 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", "company-not-resolved", "legacy-personal-journal", "never-synced", "invalid-last-sync", "stale-threshold", "manifest-unavailable", "manifest-state-unavailable", "no-manifest-scopes", "never-uploaded", "invalid-upload-time", "unresolved-company-uid", "realtime-lag-stuck", "receiver-permission-denied", "runner-restart-loop", "device-limit-backoff", "repeated-conflicts"];
+export declare const SYNC_REASON_CODES: readonly ["core-version-unavailable", "core-update-available", "no-local-tree", "company-not-resolved", "legacy-personal-journal", "never-synced", "invalid-last-sync", "stale-threshold", "manifest-unavailable", "manifest-state-unavailable", "no-manifest-scopes", "never-uploaded", "invalid-upload-time", "unresolved-company-uid", "realtime-lag-stuck", "receiver-permission-denied", "pull-access-denied", "runner-restart-loop", "device-limit-backoff", "repeated-conflicts"];
 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;

package/dist/lib/doctor/types.js

@@ -39,6 +39,7 @@ export const SYNC_REASON_CODES = [
     "unresolved-company-uid",
     "realtime-lag-stuck",
     "receiver-permission-denied",
+    "pull-access-denied",
     "runner-restart-loop",
     "device-limit-backoff",
     "repeated-conflicts",

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

@@ -14,7 +14,7 @@ export interface WorkCacheMqtt extends MeshMqttEventClient {
 export interface WorkCacheSubscriber {
     stop: () => Promise<void>;
 }
-export { AGENT_INBOX_PUSH_STATE_BASENAME } from "../paths.js";
+export { AGENT_INBOX_PUSH_STATE_BASENAME, SYNC_WAKE_STATE_BASENAME } from "../paths.js";
 export declare function startWorkCacheSubscriber(opts: {
     meshRoot: string;
     fetchCredentials?: PersonalCredentialsFetcher;