@indigoai-us/hq-cli 5.345.168 → 5.345.169

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.345.169] — 2026-10-24
+- Sentry error reports now redact CloudFront signed-URL params (`Policy`, `Key-Pair-Id`) and the `AWSAccessKeyId` and `GoogleAccessId` ids when they appear as structured keys in event data, for example a parsed query under `extra`. The feedback diagnostics scrubber already redacted them (#2177); the Sentry scrubber caught them only inside strings. The shared structured-key cases now run against the Sentry scrubber too.
+- A debounced automatic checkpoint is now queued for the next checkpoint sibling. Before this, `hq core checkpoint` wrote the `-auto-` thread when the per-session debounce skipped the sibling, but it never queued the payload, so no sibling ever filled the thread in. The payload is now added to the pending queue once, and the next sibling run picks it up. The debounce still limits how many siblings start. When the pending queue goes over its cap of 50, a message on stderr now gives the number of oldest payloads dropped. Feedback a2a5c2c3-5ea0-4e1f-8155-1f39ce6ac750.
+
+- `hq feedback` now redacts presigned URL signatures, session tokens, bearer tokens and other credentials from the diagnostics it attaches. Before this fix, recent Sentry breadcrumbs were copied into diagnostics without scrubbing, so an S3 presigned URL's X-Amz-Security-Token could reach the stored feedback row. Diagnostics passed in by callers are scrubbed too, and the inline log tails and the S3 log bundle now also catch bare, URL-encoded, CloudFront, GCS and Azure signed URL parameters.
+- `hq doctor --fix` no longer starts a second background sync pull while a pull it stopped at its time limit is still shutting down. It takes the pull-start lock from another process only when that process has exited or its process id now belongs to a different process.
+- `hq doctor --fix` can now refresh sync journals on drives without hard links (exFAT, FAT, some network drives). `hq doctor` warns, naming the process, when a journal refresh lock has been held for more than 10 minutes.
+- `hq doctor --fix` no longer kills a slow sync journal pull after 90 seconds. A pull that is still running keeps going in the background for up to 10 minutes, one at a time, and `hq doctor` shows that journal as "refresh in progress" until it finishes. It never blocks your own `hq sync`, and it steps aside at once for `hq rescue` and other repairs, keeping what it already downloaded. A large company is no longer reported as stale every day.
+
 ## [5.345.168] — 2026-10-24
 - `hq dm` now picks the default audience from the recipient when no audience flag is passed. A 1:1 DM to a person (email, `prs_` uid, or a bare name that resolves to a person) sends `audience: "human"`. A 1:1 DM to an agent (`agt_` uid), a group DM and a channel post send `audience: "agent"`, so script and lane messages stay out of people's conversations. Scheduled sends (`--at`, `--in`) follow the same rule. Pass `--for-human` (alias for `--audience human`) to tag any message for people; an explicit `--audience human|agent|both` wins over `--for-human`, with a warning on stderr, and is validated on every path. `hq core delegate send` tags the pickup DM `audience: "both"`, `hq dm-bind post` keeps the channel default (`audience: "agent"`) for its automated status posts, and the agent MCP `hq_dm_send` tool, `hq agents message` and the `hq access` grant request apply the recipient rule. Reading commands (inbox, thread, channel) are unchanged, and `hq dm forward` does not set an audience.
 - `hq scan secrets` no longer exits 2 when a repo's `.gitleaks.toml` allowlist is rejected. In staged and file scans it now prints a fixed warning that quotes no part of the file and scans with no repo allowlist, so a real key is still reported (exit 1) and a commit that replaces a bad allowlist is not blocked. An unknown `--allowlist-rev` still exits 2.

package/dist/commands/core-checkpoint-native.js

@@ -1206,8 +1206,30 @@ function appendPending(pendingPath, payload) {
     // runs once the queue is already over cap, where newest-wins is the point.
     const kept = lines.slice(-MAX_PENDING_PAYLOADS);
     fs.writeFileSync(pendingPath, `${kept.join("\n")}\n`);
+    // Say so instead of dropping silently: a wedged sibling shows up here.
+    const dropped = lines.length - kept.length;
+    printError(`checkpoint: pending queue over cap (${MAX_PENDING_PAYLOADS}); dropped ${dropped} oldest payload(s)`);
     return kept.length;
 }
+/**
+ * Queue a payload for the next sibling run and record its ontology touches.
+ * Shared by the busy-sibling path and the debounced automatic path, so both
+ * hand their thread to the next run instead of leaving it unfilled.
+ */
+async function queuePayload(liveRoot, payload) {
+    const siblingRoot = path.join(liveRoot, "workspace", "checkpoints", "sibling");
+    fs.mkdirSync(siblingRoot, { recursive: true });
+    const depth = appendPending(path.join(siblingRoot, "pending.jsonl"), payload);
+    try {
+        const { recordQueuedTouches } = await import("../lib/checkpoint-ontology/queued-touches.js");
+        recordQueuedTouches(liveRoot, payload.company, payload.files, new Date());
+    }
+    catch {
+        // Queued touches only help a later ontology plan; they must never fail
+        // the checkpoint itself.
+    }
+    return depth;
+}
 /**
  * Take ownership of the queued payloads by renaming the queue aside.
  *
@@ -1369,15 +1391,7 @@ async function startSibling(liveRoot, input, threadPath, backend) {
     const activePid = existingSiblingPid(lockPath, Date.now());
     fs.mkdirSync(siblingRoot, { recursive: true });
     if (activePid !== null) {
-        const depth = appendPending(pendingPath, payload);
-        try {
-            const { recordQueuedTouches } = await import("../lib/checkpoint-ontology/queued-touches.js");
-            recordQueuedTouches(liveRoot, payload.company, payload.files, new Date());
-        }
-        catch {
-            // Queued touches only help a later ontology plan; they must never fail
-            // the checkpoint itself.
-        }
+        const depth = await queuePayload(liveRoot, payload);
         printResult(`checkpoint: sibling busy — payload queued (${depth} pending)`);
         return;
     }
@@ -1579,7 +1593,13 @@ async function runCheckpoint(options, command, group, preResolvedHqRoot) {
                 printResult(`checkpoint: sibling disabled (${SIBLING_SETTING})`);
             }
             else if (autoDebounced) {
-                printResult("checkpoint: sibling skipped (automatic checkpoint; one ran for this session recently)");
+                // feedback_a2a5c2c3: the debounce limits how many siblings start, but
+                // the thread still needs filling. Queue it once; the next sibling run
+                // claims it. The debounce stamp is not refreshed, so the window still
+                // closes on schedule and the next automatic checkpoint starts a run.
+                const depth = await queuePayload(liveRoot, siblingPayload(input, threadPath, "none"));
+                printResult("checkpoint: sibling skipped (automatic checkpoint; one ran for this session recently)" +
+                    ` — payload queued (${depth} pending)`);
             }
             else if (backend === "none") {
                 printResult("checkpoint: sibling disabled (backend none)");

package/dist/commands/feedback.js

@@ -3,6 +3,7 @@ import chalk from "chalk";
 import { ensureCognitoToken, loadCachedTokens } from "../utils/cognito-session.js";
 import { assertVaultApiRequestSupported, vaultApiFetch, } from "../utils/vault-api.js";
 import { collectDiagnostics } from "../utils/feedback-diagnostics.js";
+import { scrubDiagnosticsString, scrubDiagnosticsValue } from "../utils/scrub-diagnostics.js";
 import { MAX_SCREENSHOTS, uploadScreenshots } from "../utils/feedback-screenshots.js";
 import { FEEDBACK_LOGS_MAX_TOTAL_BYTES, FEEDBACK_LOGS_MIN_USEFUL_BYTES, collectFeedbackLogs, feedbackLogsEnabled, } from "../utils/feedback-logs.js";
 import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
@@ -79,8 +80,10 @@ export function resolveFeedbackReporter(env = process.env, isTTY = process.stdin
 function buildFeedbackRequestBody(opts) {
     const requestBody = {
         type: opts.type,
-        title: opts.title,
-        body: opts.body,
+        // Title and body are free text, and /hq-bug puts tool output in the body,
+        // so they get the same credential scrub as diagnostics.
+        title: scrubDiagnosticsString(opts.title),
+        body: scrubDiagnosticsString(opts.body),
         diagnostics: opts.diagnostics,
     };
     if (opts.reporterMark) {
@@ -157,7 +160,12 @@ export async function submitFeedback(opts) {
     // Keep submitFeedback safe for direct callers as well as the command path,
     // which invokes the same validator before uploading any attachments.
     validateFeedbackContent(opts.title, opts.body);
-    const diagnostics = opts.diagnostics ?? collectDiagnostics();
+    // Scrub here, at the one point every submission passes through. Callers may
+    // hand in their own diagnostics (the command path collects them before
+    // uploads, and adds latestVersion afterwards), and a caller-supplied blob
+    // previously skipped redaction entirely. The scrubbed copy is the object
+    // attachDebugLogs later mutates, so inline logs still land in the request.
+    const diagnostics = scrubDiagnosticsValue(opts.diagnostics ?? collectDiagnostics());
     const reporterMark = opts.type === "bug" && resolveProcessFlagGate(FEEDBACK_REPORTER_KIND_FLAG, { fallback: FEEDBACK_REPORTER_KIND_FLAG_FALLBACK }, () => FEEDBACK_REPORTER_KIND_FLAG_FALLBACK)
         ? resolveFeedbackReporter(process.env, process.stdin.isTTY === true, opts.reporterOverride)
         : undefined;

package/dist/lib/doctor/checks/sync-health.d.ts

@@ -116,6 +116,13 @@ export interface SyncHealthDeps {
      * since a re-upload would exit 0 without uploading.
      */
     manifestUploadsDisabled?: () => boolean;
+    /**
+     * Start time (epoch ms) of a live background `hq doctor --fix` pull for
+     * this refresh target (a company slug, or `personal`), or null. A journal
+     * whose refresh is still running is reported "refresh in progress" rather
+     * than stale (feedback cd56a501).
+     */
+    refreshInProgress?: (fixTarget: string) => number | null;
 }
 /**
  * True when `slug` is a filesystem-safe company folder name. Rejects empty
@@ -148,7 +155,6 @@ export declare function isPersonalJournalSlug(slug: string): boolean;
 export declare function journalSlugFromCheckId(checkId: string): string | null;
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export declare const syncHealthFamily: CheckFamily;
-/** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
 export declare function checkSyncHealth(context: CheckContext, rawDeps?: SyncHealthDeps): CheckResult[];
 /** True when `a` > `b` for plain X.Y.Z versions. Non-numeric parts compare 0. */
 export declare function semverGt(a: string, b: string): boolean;

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

@@ -25,6 +25,8 @@
  */
 import { defaultSyncRuntimeResults } from "./sync-runtime.js";
 import * as fs from "node:fs";
+import { DEFAULT_OWNER_IDENTITY } from "../fix/process-identity.js";
+import { REFRESH_SPAWN_LOCK_WARN_MS, inspectRefreshSpawnLock, refreshHandoffStartedAt, } from "../fix/refresh-sync-handoff.js";
 import * as path from "node:path";
 // Namespace import, deliberately: hq-cloud is an ESM package, so a static
 // NAMED import of an export the installed version lacks is a link-time
@@ -63,6 +65,8 @@ function withDefaults(deps, hqRoot) {
         companySyncResolvable: deps.companySyncResolvable ??
             ((slug, lastSync) => !companyRecordedNotResolved(hqRoot, slug, deps.now().getTime(), lastSync)),
         manifestUploadsDisabled: deps.manifestUploadsDisabled ?? (() => manifestUploadsDisabled()),
+        refreshInProgress: deps.refreshInProgress ??
+            ((fixTarget) => refreshHandoffStartedAt(hqRoot, fixTarget, deps.now().getTime())),
     };
 }
 /**
@@ -294,6 +298,36 @@ export const syncHealthFamily = {
     run: (context) => Promise.resolve(checkSyncHealth(context)),
 };
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
+/**
+ * WARN when the `hq doctor --fix` spawn lock has been held for over
+ * {@link REFRESH_SPAWN_LOCK_WARN_MS}, naming the holder pid, so a stalled or
+ * suspended holder is visible. Report only: the lock is never removed here.
+ */
+function refreshSpawnLockResult(hqRoot, nowMs) {
+    let lock;
+    try {
+        lock = inspectRefreshSpawnLock(hqRoot, nowMs, DEFAULT_OWNER_IDENTITY);
+    }
+    catch {
+        return [];
+    }
+    if (!lock || lock.heldMs === null || lock.heldMs <= REFRESH_SPAWN_LOCK_WARN_MS)
+        return [];
+    // Left by a claimer that has exited: nothing to stop, and the next
+    // `hq doctor --fix` releases it.
+    if (lock.ownerGone)
+        return [];
+    const minutes = Math.floor(lock.heldMs / 60_000);
+    return [
+        {
+            status: "WARN",
+            checkId: "sync.refresh.spawn-lock",
+            reasonCode: "refresh-lock-held",
+            message: `The hq doctor --fix refresh lock has been held for ${minutes} minutes by process ${lock.pid}. No new journal refresh can start until it is released.`,
+            remediation: `If process ${lock.pid} is stuck or suspended, resume or stop it; the lock is released when it exits.`,
+        },
+    ];
+}
 export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
     const deps = withDefaults(rawDeps, context.hqRoot);
     try {
@@ -301,6 +335,7 @@ export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
             ...versionResults(context, deps),
             ...updateAvailabilityResult(context, deps),
             ...journalAndManifestResults(deps),
+            ...refreshSpawnLockResult(context.hqRoot, deps.now().getTime()),
             ...deps.runtime(deps.now()),
         ];
     }
@@ -528,7 +563,7 @@ function journalResults(deps, journals) {
         if (entry.slug === PERSONAL_SCOPE_SLUG) {
             results.push(leftoverPersonalJournalResult(entry));
             if (!hasPersonalVaultJournal) {
-                results.push(journalFreshnessResult(entry, PERSONAL_VAULT_SCOPE_SLUG, nowMs));
+                results.push(withRefreshInProgress(deps, journalFreshnessResult(entry, PERSONAL_VAULT_SCOPE_SLUG, nowMs), "personal"));
             }
             continue;
         }
@@ -570,10 +605,40 @@ function journalResults(deps, journals) {
             results.push(notOnThisMachineResult(entry, checkId));
             continue;
         }
-        results.push(freshness);
+        results.push(withRefreshInProgress(deps, freshness, isPersonalJournalSlug(entry.slug) ? "personal" : entry.slug));
     }
     return results;
 }
+/**
+ * A stale or never-synced journal whose `hq doctor --fix` pull is still
+ * running in the background is UNTESTED "refresh in progress", not WARN.
+ * The pull records lastSync only when it finishes, so until then the journal
+ * looks stale even though the repair is under way. Once the process is gone
+ * the record no longer counts and the WARN comes back, so a pull that died is
+ * retried by the next `--fix`.
+ */
+function withRefreshInProgress(deps, result, fixTarget) {
+    if (result.status !== "WARN")
+        return result;
+    if (result.reasonCode !== "stale-threshold" && result.reasonCode !== "never-synced")
+        return result;
+    let startedAtMs;
+    try {
+        startedAtMs = deps.refreshInProgress(fixTarget);
+    }
+    catch {
+        return result;
+    }
+    if (startedAtMs === null)
+        return result;
+    return {
+        status: "UNTESTED",
+        checkId: result.checkId,
+        reasonCode: "refresh-in-progress",
+        ...(result.target ? { target: result.target } : {}),
+        message: `${result.message} hq doctor --fix is refreshing it in the background (started ${new Date(startedAtMs).toISOString()}); it passes when that pull finishes.`,
+    };
+}
 function companySyncResolvable(deps, slug, lastSync) {
     try {
         return deps.companySyncResolvable(slug, lastSync);

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

@@ -42,6 +42,8 @@ import type { CheckResult, DoctorStatus } from "../types.js";
 import { type GateProfile } from "../hook-gate-profiles.js";
 import { type FixClass } from "./remediation.js";
 import { type RemovePs1ShimsResult } from "../../windows/ps1-shims.js";
+import { processStartTime } from "./process-identity.js";
+import { type HarvestedRefreshRun, type OrphanPull, type RefreshOwnerIdentity } from "./refresh-sync-handoff.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"];
@@ -290,10 +292,45 @@ export declare function unresolvedSyncChecks(findings: readonly CheckResult[], a
 /**
  * Default `refresh-sync` repair: a bounded, pull-only, keep-conflicts
  * `hq sync pull --company <slug>` (or `--personal`) against the tree
- * `--fix` is repairing. Never a push, never interactive. A timeout or
- * non-zero exit is reported rather than thrown so later plans still run.
+ * `--fix` is repairing. Never a push, never interactive. A non-zero exit is
+ * reported rather than thrown so later plans still run.
+ *
+ * A pull still running after {@link REFRESH_SYNC_TIMEOUT_MS} is NOT killed
+ * (feedback cd56a501). A pull writes `lastSync` only when its pass finishes,
+ * so killing it at the deadline left a large vault, or a pull queued behind
+ * the sync runner's lock, stale on every run. It is left running detached and
+ * recorded in refresh-sync-handoff.ts; the journal check reports it as
+ * "refresh in progress" until it finishes.
+ */
+export declare function defaultRefreshSync(target: RefreshSyncTarget, deps?: RefreshSyncSpawnDeps): Promise<RefreshSyncResult>;
+/** Map a finished supervised pull to a {@link RefreshSyncResult}. */
+export declare function harvestedRefreshSyncResult(harvested: HarvestedRefreshRun): RefreshSyncResult;
+export { processStartTime };
+/**
+ * Kill an orphaned --fix pull past its cap, but only when the pid still names
+ * that pull: its process start time must match the one recorded when it
+ * started. A reused pid has a different start time and is left alone. On
+ * Windows no start time is recorded, so nothing is killed there.
+ */
+export declare function killOrphanPullIfSame(orphan: OrphanPull, _nowMs: number, probe?: (pid: number) => string | null): void;
+/** Test seams for {@link defaultRefreshSync}. */
+export interface RefreshSyncSpawnDeps {
+    command?: string;
+    args?: string[];
+    timeoutMs?: number;
+    maxBackgroundMs?: number;
+    nowMs?: () => number;
+    /** Directory holding hq-cloud's operation-lock files. */
+    locksDir?: string;
+    /** Process start-time probe for the spawn lock. */
+    identity?: RefreshOwnerIdentity;
+}
+/**
+ * How long a `--fix` pull waits for the operation lock. Unchanged from before
+ * the hand-off: a background pull must never queue on the lock longer than a
+ * foreground one did.
  */
-export declare function defaultRefreshSync(target: RefreshSyncTarget): Promise<RefreshSyncResult>;
+export declare const REFRESH_SYNC_LOCK_TIMEOUT_SEC = 30;
 /**
  * Default `refresh-manifest` repair: a bounded `hq sync manifest --scope <s>`
  * against the tree `--fix` is repairing. Exit 0 also covers throttled,
@@ -349,5 +386,4 @@ export declare function addHookIdToGateProfiles(source: string, hookId: string,
  * non-object `hooks` value — it is replaced rather than trusted.
  */
 export declare function registerHookInSettings(settings: unknown, event: string, command: string): Record<string, unknown>;
-export {};
 //# sourceMappingURL=apply.d.ts.map

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

@@ -37,9 +37,10 @@
  * (the command resolves it once), keeping this module decoupled from the CLI and
  * trivially testable against a fake tree.
  */
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { getStateDir } from "@indigoai-us/hq-cloud";
 import { isPersonalJournalSlug } from "../checks/sync-health.js";
 import { createDefaultRegistry } from "../registry.js";
 import { flattenFamilies } from "../report.js";
@@ -51,6 +52,8 @@ import { HQ_CLI_BINS, removeHqCliPs1Shims } from "../../windows/ps1-shims.js";
 import { botDir } from "../../bot/paths.js";
 import { readBotConfig } from "../../bot/config.js";
 import { buildBotDaemonPaths, installedDaemonHqBinary, repairBotDaemonIfStale, rewriteBotDaemonNodePath, } from "../../bot/daemon.js";
+import { DEFAULT_OWNER_IDENTITY, processStartTime } from "./process-identity.js";
+import { REFRESH_BACKGROUND_MAX_MS, REFRESH_SUPERVISOR_SOURCE, anyRefreshHandoffAlive, harvestRefreshHandoffs, releaseDeadRefreshSpawnLock, newRefreshRunPaths, readRefreshRunExit, readRefreshRunLog, claimRefreshRun, clearRefreshRecord, removeRefreshRun, } from "./refresh-sync-handoff.js";
 import { classifyRefreshSyncOutcome, } from "./refresh-sync-outcome.js";
 import { pullOutputShowsCompanyNotResolved, recordCompanyResolution, } from "../company-resolution-state.js";
 import { readRefreshManifestCursor, readRefreshSyncProgress, writeRefreshManifestCursor, writeRefreshSyncCursor, writeRefreshSyncLastRun, } from "./refresh-sync-progress.js";
@@ -184,6 +187,10 @@ export async function applyFixes(options) {
     };
     const refreshSync = async (target) => {
         const result = await performRefreshSync(target);
+        // Still running in the background: no evidence about the company yet.
+        // The next --fix harvests its real exit before it plans anything.
+        if (result.outcome === "pull-handed-off")
+            return result;
         if (target.personal)
             return result;
         noteCompanyOutcome(target.slug, result.ok, result.companyNotResolved === true);
@@ -205,6 +212,17 @@ export async function applyFixes(options) {
     // 2. Collect findings, then plan each newly unlocked allowlisted repair.
     //    Identity is deliberately the check id + target pair: an unsuccessful
     //    repair must not be applied repeatedly in one invocation.
+    // Background pulls from an earlier --fix: record how each really ended
+    // before planning, then drop the finished records (feedback cd56a501).
+    // A spawn lock left by a crashed claimer is released here when its owner is
+    // proven gone, even if no journal is stale this run.
+    releaseDeadRefreshSpawnLock(hqRoot, Date.now(), DEFAULT_OWNER_IDENTITY);
+    for (const harvested of harvestRefreshHandoffs(hqRoot, Date.now(), killOrphanPullIfSame)) {
+        const outcome = harvestedRefreshSyncResult(harvested);
+        if (harvested.slug === "personal" || isPersonalJournalSlug(harvested.slug))
+            continue;
+        noteCompanyOutcome(harvested.slug, outcome.ok, outcome.companyNotResolved === true);
+    }
     let findings = await collect(hqRoot);
     let lastAttemptedRefreshSyncSlug = readRefreshSyncProgress(hqRoot)?.lastAttemptedSlug ?? null;
     let refreshSyncAppliedThisRun = 0;
@@ -333,6 +351,11 @@ export async function applyFixes(options) {
             // left over and reported "not attempted" rather than as a failed repair.
             if (network && !networkBudgetLeft())
                 continue;
+            // One background pull per HQ root. While it runs it holds the operation
+            // lock, so another pull would only wait on it; leave the rest for the
+            // next run.
+            if (plan.fixClass === "refresh-sync" && anyRefreshHandoffAlive(hqRoot, Date.now()))
+                continue;
             if (plan.fixClass === "refresh-sync") {
                 // Persist before starting the bounded pull. If this process is killed,
                 // the next invocation resumes after this company instead of starving
@@ -540,85 +563,176 @@ async function defaultRunChecks(hqRoot) {
 /**
  * Default `refresh-sync` repair: a bounded, pull-only, keep-conflicts
  * `hq sync pull --company <slug>` (or `--personal`) against the tree
- * `--fix` is repairing. Never a push, never interactive. A timeout or
- * non-zero exit is reported rather than thrown so later plans still run.
+ * `--fix` is repairing. Never a push, never interactive. A non-zero exit is
+ * reported rather than thrown so later plans still run.
+ *
+ * A pull still running after {@link REFRESH_SYNC_TIMEOUT_MS} is NOT killed
+ * (feedback cd56a501). A pull writes `lastSync` only when its pass finishes,
+ * so killing it at the deadline left a large vault, or a pull queued behind
+ * the sync runner's lock, stale on every run. It is left running detached and
+ * recorded in refresh-sync-handoff.ts; the journal check reports it as
+ * "refresh in progress" until it finishes.
  */
-export function defaultRefreshSync(target) {
+export async function defaultRefreshSync(target, deps = {}) {
     const hqBin = process.argv[1];
     const selector = target.personal || isPersonalJournalSlug(target.slug)
         ? ["--personal"]
         : ["--company", target.slug];
-    const args = hqBin
-        ? [
-            hqBin,
-            "sync",
-            "pull",
-            ...selector,
-            "--hq-root",
-            target.hqRoot,
-            "--on-conflict",
-            "keep",
-            "--lock-timeout",
-            "30",
-        ]
-        : [
-            "sync",
-            "pull",
-            ...selector,
-            "--hq-root",
-            target.hqRoot,
-            "--on-conflict",
-            "keep",
-            "--lock-timeout",
-            "30",
-        ];
-    const result = spawnSync(hqBin ? process.execPath : "hq", args, {
-        encoding: "utf8",
-        timeout: REFRESH_SYNC_TIMEOUT_MS,
-        cwd: target.hqRoot,
-    });
-    if (result.error) {
-        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({
+    const pullArgs = [
+        "sync",
+        "pull",
+        ...selector,
+        "--hq-root",
+        target.hqRoot,
+        "--on-conflict",
+        "keep",
+        "--lock-timeout",
+        String(REFRESH_SYNC_LOCK_TIMEOUT_SEC),
+    ];
+    // Run the same CLI script under this node. Without a script path there is no
+    // safe way to start `hq` on Windows (it is a .cmd shim that needs a shell),
+    // so only POSIX falls back to `hq` on PATH.
+    if (!deps.command && !hqBin && process.platform === "win32") {
+        return {
             ok: false,
-            outcome,
-            message: outcome === "pull-timeout"
-                ? `timed out pulling '${target.slug}'`
-                : `could not start pull for '${target.slug}': ${result.error.message}`,
-        });
+            outcome: "pull-failed:other",
+            message: `could not start pull for '${target.slug}': the hq CLI script path is unknown`,
+        };
     }
-    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({
+    const command = deps.command ?? (hqBin ? process.execPath : "hq");
+    const args = deps.args ?? (hqBin ? [hqBin, ...pullArgs] : pullArgs);
+    const timeoutMs = deps.timeoutMs ?? REFRESH_SYNC_TIMEOUT_MS;
+    const maxBackgroundMs = deps.maxBackgroundMs ?? REFRESH_BACKGROUND_MAX_MS;
+    const nowMs = deps.nowMs ?? (() => Date.now());
+    // The pull runs under a supervisor that records its real exit status, so a
+    // pull left running past the deadline is still classified by the next run.
+    const run = newRefreshRunPaths(target.hqRoot, target.slug);
+    // One pull per HQ root: claim it (record written under the spawn lock)
+    // before spawning, so a concurrent --fix sees this pull and backs off.
+    if (!claimRefreshRun(target.hqRoot, target.slug, run, nowMs(), deps.identity ?? DEFAULT_OWNER_IDENTITY)) {
+        return {
             ok: false,
-            outcome,
-            message: `pull of '${target.slug}' exited ${result.status}${detail ? `: ${detail}` : ""}`,
-            companyNotResolved: !target.personal &&
-                !isPersonalJournalSlug(target.slug) &&
-                pullOutputShowsCompanyNotResolved(`${result.stdout ?? ""}\n${result.stderr ?? ""}`),
-        });
+            outcome: "pull-failed:lock-busy",
+            message: `another hq doctor --fix pull is already running; '${target.slug}' is left for the next run`,
+        };
+    }
+    let supervisor;
+    try {
+        fs.mkdirSync(path.dirname(run.log), { recursive: true });
+        supervisor = spawn(process.execPath, [
+            "-e",
+            REFRESH_SUPERVISOR_SOURCE,
+            run.log,
+            run.exit,
+            run.heartbeat,
+            run.pid,
+            run.cancel,
+            deps.locksDir ?? defaultLocksDir(),
+            String(maxBackgroundMs),
+            command,
+            ...args,
+        ], { cwd: target.hqRoot, detached: true, stdio: "ignore", windowsHide: true });
+    }
+    catch (error) {
+        clearRefreshRecord(target.hqRoot, target.slug, run);
+        removeRefreshRun(run);
+        return {
+            ok: false,
+            outcome: classifyRefreshSyncOutcome({ errorCode: error.code }),
+            message: `could not start pull for '${target.slug}': ${error.message}`,
+        };
     }
-    return Promise.resolve({
-        ok: true,
-        outcome: "pull-succeeded",
-        message: `pulled '${target.slug}'`,
+    const finished = await new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        supervisor.once("error", () => settle(true));
+        supervisor.once("exit", () => settle(true));
+        const timer = setTimeout(() => settle(false), timeoutMs);
     });
+    if (!finished) {
+        // Leave the pull running on its own. It records lastSync when it
+        // finishes; until then the journal check reports "refresh in progress".
+        supervisor.removeAllListeners();
+        supervisor.unref();
+        return {
+            ok: false,
+            outcome: "pull-handed-off",
+            message: `still pulling '${target.slug}' after ${timeoutMs / 1000}s; it keeps running in the background`,
+        };
+    }
+    const result = harvestedRefreshSyncResult({
+        slug: target.slug,
+        exit: readRefreshRunExit(run),
+        output: readRefreshRunLog(run),
+    });
+    clearRefreshRecord(target.hqRoot, target.slug, run);
+    removeRefreshRun(run);
+    return result;
+}
+/** Map a finished supervised pull to a {@link RefreshSyncResult}. */
+export function harvestedRefreshSyncResult(harvested) {
+    const { slug, exit, output } = harvested;
+    if (!exit) {
+        return { ok: false, outcome: "pull-failed:other", message: `pull of '${slug}' ended without a result` };
+    }
+    if (exit.capped) {
+        // Stopped at the background time cap. Completed downloads are kept.
+        return { ok: false, outcome: "pull-timeout-capped", message: `stopped pulling '${slug}' at the background time limit` };
+    }
+    if (exit.preempted) {
+        // Stopped so a sync the user or the runner started could take the lock.
+        // Completed downloads are kept; the next --fix resumes the journal.
+        return { ok: false, outcome: "pull-preempted", message: `paused pulling '${slug}' for another sync` };
+    }
+    if (exit.status === 0 && !exit.signal) {
+        return { ok: true, outcome: "pull-succeeded", message: `pulled '${slug}'` };
+    }
+    const outcome = classifyRefreshSyncOutcome({ status: exit.status, signal: exit.signal, stdout: output });
+    const detail = output.trim().split("\n").at(-1) ?? "";
+    const personal = slug === "personal" || isPersonalJournalSlug(slug);
+    return {
+        ok: false,
+        outcome,
+        message: `pull of '${slug}' exited ${exit.status ?? exit.signal}${detail ? `: ${detail}` : ""}`,
+        companyNotResolved: !personal && pullOutputShowsCompanyNotResolved(output),
+    };
 }
+export { processStartTime };
+/**
+ * Kill an orphaned --fix pull past its cap, but only when the pid still names
+ * that pull: its process start time must match the one recorded when it
+ * started. A reused pid has a different start time and is left alone. On
+ * Windows no start time is recorded, so nothing is killed there.
+ */
+export function killOrphanPullIfSame(orphan, _nowMs, probe = processStartTime) {
+    if (process.platform === "win32" || !orphan.recordedStart)
+        return;
+    const current = probe(orphan.pid);
+    if (!current || current !== orphan.recordedStart)
+        return;
+    try {
+        process.kill(-orphan.pid, "SIGKILL");
+    }
+    catch {
+        // gone
+    }
+}
+/** hq-cloud keeps operation locks in `<stateDir>/locks`. */
+function defaultLocksDir() {
+    return path.join(getStateDir(), "locks");
+}
+/**
+ * How long a `--fix` pull waits for the operation lock. Unchanged from before
+ * the hand-off: a background pull must never queue on the lock longer than a
+ * foreground one did.
+ */
+export const REFRESH_SYNC_LOCK_TIMEOUT_SEC = 30;
 /**
  * Default `refresh-manifest` repair: a bounded `hq sync manifest --scope <s>`
  * against the tree `--fix` is repairing. Exit 0 also covers throttled,

package/dist/lib/doctor/fix/process-identity.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Process start times, used to tell the owner of a pid from a later process
+ * that reused it (feedback cd56a501).
+ */
+import type { RefreshOwnerIdentity } from "./refresh-sync-handoff.js";
+/**
+ * A process's start time, or null if it cannot be read: `ps -o lstart=` on
+ * POSIX, the process StartTime from PowerShell on Windows.
+ */
+export declare function processStartTime(pid: number): string | null;
+/** Real process-table identity for the refresh spawn lock. */
+export declare const DEFAULT_OWNER_IDENTITY: RefreshOwnerIdentity;
+//# sourceMappingURL=process-identity.d.ts.map