@indigoai-us/hq-cli 5.345.202 → 5.345.204

package/dist/lib/daemon/run.js

@@ -36,6 +36,7 @@ import { createLanesReconcileWatcher } from "./lanes-reconcile-watcher.js";
 import { findLegacyUnits, legacyMeshUnitsToRetire, legacyOwnerLookup, } from "./legacy.js";
 import { readLegacySyncEnv } from "./legacy-sync-env.js";
 import { readVaultSyncSwitches, unreadableSwitchesWarning, writeVaultSyncSwitches } from "../vault-sync-switches.js";
+import { scheduleDaemonPlistRefresh } from "./plist-refresh.js";
 import { acquireDaemonLock, isProcessAlive, processCommandLine, releaseDaemonLock } from "./lock.js";
 import { retireLegacyMeshUnits } from "./migrate.js";
 import { daemonDir as meshDaemonDir, daemonPidPath as meshDaemonPidPath } from "../mesh/live/daemon/paths.js";
@@ -81,7 +82,7 @@ export function syncCoreVaultPlans(home, hqRoot, platform) {
             release: state.release,
             ...(vault.legacyOffSince ? { legacyOffSince: vault.legacyOffSince } : {}),
         }, platform);
-        const releaseHold = vault.phase === "full" ? fullModeHold(vault, state.release) : undefined;
+        const releaseHold = vault.phase === "full" ? fullModeHold(vault, state.release, platform) : undefined;
         return releaseHold ? { ...plan, blockedReason: releaseHold } : plan;
     });
 }
@@ -114,7 +115,7 @@ export function planUnitsWithSyncCoreInterlock(services, context, supervisor) {
         let restorePersonal = false;
         const restoreCompanies = {};
         for (const vault of context.syncCoreVaults ?? []) {
-            if (vault.phase !== "full" || runningVaults.has(vault.uid) || !fullModeHold(vault, vault.release))
+            if (vault.phase !== "full" || runningVaults.has(vault.uid) || !fullModeHold(vault, vault.release, context.platform))
                 continue;
             if (vault.kind === "personal") {
                 restorePersonal = personalOff;
@@ -658,6 +659,21 @@ export async function runDaemon(opts) {
     }
     const hostNote = opts.host ? `, hosted by the ${opts.host} app` : "";
     log("info", `starting hq daemon (pid ${process.pid}) as ${machineType} (${detected.detail})${hostNote}`);
+    try {
+        scheduleDaemonPlistRefresh({
+            platform,
+            managedByLaunchd: opts.managed === true && opts.host === undefined,
+            home,
+            daemonRoot: paths.root,
+            nodeBinary: opts.nodeBinary,
+            hqBinary: opts.hqBinary,
+            env,
+            log,
+        });
+    }
+    catch (err) {
+        log("warn", `could not check the daemon LaunchAgent: ${err instanceof Error ? err.message : String(err)}`);
+    }
     // On Linux, services can outlive a daemon (KillMode=process). Adopt the ones
     // the previous daemon handed over and stop any others it left behind before
     // starting anything, so a service never runs twice.
@@ -1264,6 +1280,15 @@ export async function runDaemon(opts) {
             read: () => readUnitHolds(paths.holdsPath),
             write: (holds) => writeUnitHolds(paths.holdsPath, holds),
         },
+        pidAlive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (err) {
+                return err.code === "EPERM";
+            }
+        },
         exitOutputTail: (unitId) => {
             // An adopted unit was started by an earlier daemon; its output start is unknown.
             const offset = unitLogOffsets.get(unitId);

package/dist/lib/daemon/selfcheck.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The daemon's sync-engine self-check (`hq daemon service sync-core-selfcheck`).
+ *
+ * It reads the supervisor's state and holds and finds engine units
+ * (`sync-core:<vault>`) that have been held, or failing without a heartbeat,
+ * for more than ATTENTION_AFTER_MS. When there are any, it sends one DM to the
+ * person signed in on this machine, at most once a day per machine whichever
+ * units are affected, naming every affected vault in that one DM. The 16-hour outage of 2026-11-03 was
+ * found by hand; this makes the next one reach the owner.
+ */
+import type { DaemonState, PersistedHolds } from "./supervisor.js";
+/** An engine unit that has been held or failing this long needs a person. */
+export declare const ATTENTION_AFTER_MS: number;
+/** This machine sends at most one self-check DM per this long. */
+export declare const REPORT_INTERVAL_MS: number;
+export interface EngineUnitProblem {
+    unitId: string;
+    /** Epoch ms since when the unit has been held or failing. */
+    since: number;
+    /** One line for the DM. */
+    what: string;
+}
+/** Engine units held, or failing without a heartbeat, for more than ATTENTION_AFTER_MS at `now`. */
+export declare function engineUnitsNeedingAttention(state: DaemonState | null, holds: PersistedHolds, now: number, 
+/** False for a vault that is skipped on this machine or not on the rollout. */
+wanted?: (vaultUid: string) => boolean): EngineUnitProblem[];
+export interface SelfCheckRecord {
+    lastSentAt: number;
+    /** Sorted unit ids last reported (for the log; the rate limit ignores them). */
+    units: string[];
+}
+export declare function readSelfCheckRecord(file: string): SelfCheckRecord | null;
+export declare function writeSelfCheckRecord(file: string, record: SelfCheckRecord): void;
+/**
+ * Send now: something is wrong and this machine has not sent a self-check DM
+ * in the last day. Which units are affected does not matter, so units that
+ * take turns failing cannot send a DM on every change.
+ */
+export declare function shouldReport(problems: EngineUnitProblem[], last: SelfCheckRecord | null, now: number): boolean;
+/** The DM text for the owner. Plain, with the commands that fix each case. */
+export declare function selfCheckMessage(problems: EngineUnitProblem[], machine: string, 
+/** A name for a vault (company slug, "personal"), when known. */
+vaultName?: (vaultUid: string) => string | undefined): {
+    body: string;
+    details: string;
+};
+export interface SelfCheckDeps {
+    statePath: string;
+    holdsPath: string;
+    recordPath: string;
+    now: () => number;
+    machine: string;
+    readState: () => DaemonState | null;
+    readHolds: () => PersistedHolds;
+    /** False for a vault that is skipped here or not on the rollout. Default: every vault. */
+    wanted?: (vaultUid: string) => boolean;
+    /** A name for a vault, for the DM. */
+    vaultName?: (vaultUid: string) => string | undefined;
+    /**
+     * Send the DM to the person signed in on this machine; resolves to who it
+     * went to, or null when no person is signed in (an agent identity).
+     */
+    sendToOwner: (message: {
+        body: string;
+        details: string;
+    }) => Promise<string | null>;
+    log: (line: string) => void;
+}
+export type SelfCheckOutcome = "healthy" | "reported" | "already-reported" | "no-owner";
+export declare function runSelfCheck(deps: SelfCheckDeps): Promise<SelfCheckOutcome>;
+//# sourceMappingURL=selfcheck.d.ts.map

package/dist/lib/daemon/selfcheck.js

@@ -0,0 +1,150 @@
+/**
+ * The daemon's sync-engine self-check (`hq daemon service sync-core-selfcheck`).
+ *
+ * It reads the supervisor's state and holds and finds engine units
+ * (`sync-core:<vault>`) that have been held, or failing without a heartbeat,
+ * for more than ATTENTION_AFTER_MS. When there are any, it sends one DM to the
+ * person signed in on this machine, at most once a day per machine whichever
+ * units are affected, naming every affected vault in that one DM. The 16-hour outage of 2026-11-03 was
+ * found by hand; this makes the next one reach the owner.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { syncCoreUnitId } from "../sync-core/engine-home.js";
+import { ensurePrivateDir } from "./paths.js";
+/** An engine unit that has been held or failing this long needs a person. */
+export const ATTENTION_AFTER_MS = 30 * 60_000;
+/** This machine sends at most one self-check DM per this long. */
+export const REPORT_INTERVAL_MS = 24 * 60 * 60_000;
+const ENGINE_UNIT_PREFIX = syncCoreUnitId("");
+/** Engine units held, or failing without a heartbeat, for more than ATTENTION_AFTER_MS at `now`. */
+export function engineUnitsNeedingAttention(state, holds, now, 
+/** False for a vault that is skipped on this machine or not on the rollout. */
+wanted = () => true) {
+    const problems = [];
+    const units = state?.units ?? [];
+    const seen = new Set();
+    for (const unit of units) {
+        if (!unit.id.startsWith(ENGINE_UNIT_PREFIX))
+            continue;
+        if (!wanted(unit.id.slice(ENGINE_UNIT_PREFIX.length)))
+            continue;
+        seen.add(unit.id);
+        const problem = unitProblem(unit, holds[unit.id], state, now);
+        if (problem && now - problem.since > ATTENTION_AFTER_MS)
+            problems.push(problem);
+    }
+    // With no daemon state, the persisted holds are all there is to go on. With
+    // state, a hold for a unit the daemon does not supervise is left over from a
+    // vault that is no longer on the engine: it stops nothing, so it is not reported.
+    if (state)
+        return problems.sort((a, b) => a.unitId.localeCompare(b.unitId));
+    for (const [unitId, hold] of Object.entries(holds)) {
+        if (seen.has(unitId) || !unitId.startsWith(ENGINE_UNIT_PREFIX) || hold.retryStopped === true)
+            continue;
+        if (!wanted(unitId.slice(ENGINE_UNIT_PREFIX.length)))
+            continue;
+        if (now - hold.since > ATTENTION_AFTER_MS) {
+            problems.push({ unitId, since: hold.since, what: `held since ${iso(hold.since)}: ${hold.detail}` });
+        }
+    }
+    return problems.sort((a, b) => a.unitId.localeCompare(b.unitId));
+}
+function unitProblem(unit, hold, state, now) {
+    // Stopped on request (`hq daemon stop`, or a stopped recovery probe) is not failing.
+    if (unit.hold?.retryStopped === true || hold?.retryStopped === true)
+        return null;
+    if (unit.status === "held") {
+        const since = unit.hold?.since ?? hold?.since ?? now;
+        const detail = unit.hold?.detail ?? hold?.detail ?? unit.reason ?? "held";
+        return { unitId: unit.id, since, what: `held since ${iso(since)}: ${detail}` };
+    }
+    // Paused on purpose (sync paused, waiting for the legacy sync to hand over) is not failing.
+    if (unit.status !== "backoff" && unit.status !== "exited" && unit.status !== "running")
+        return null;
+    const last = unit.lastHeartbeatAt ? Date.parse(unit.lastHeartbeatAt) : Number.NaN;
+    // No heartbeat yet: count from when the daemon started supervising it.
+    const since = Number.isFinite(last) ? last : state.startedAt;
+    if (unit.status === "running" && unit.restarts === 0)
+        return null;
+    if (unit.status === "running" && Number.isFinite(last) && now - last <= ATTENTION_AFTER_MS)
+        return null;
+    const exit = unit.lastExit ? ` (last exit code ${unit.lastExit.code ?? "none"}${unit.lastExit.signal ? `, signal ${unit.lastExit.signal}` : ""})` : "";
+    return {
+        unitId: unit.id,
+        since,
+        what: `${unit.status === "running" ? "restarting" : "failing"} with no heartbeat since ${iso(since)}, restarted ${unit.restarts} times${exit}`,
+    };
+}
+function iso(ms) {
+    return new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function readSelfCheckRecord(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof parsed.lastSentAt !== "number" || !Array.isArray(parsed.units))
+            return null;
+        return { lastSentAt: parsed.lastSentAt, units: parsed.units.filter((u) => typeof u === "string") };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSelfCheckRecord(file, record) {
+    ensurePrivateDir(path.dirname(file));
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/**
+ * Send now: something is wrong and this machine has not sent a self-check DM
+ * in the last day. Which units are affected does not matter, so units that
+ * take turns failing cannot send a DM on every change.
+ */
+export function shouldReport(problems, last, now) {
+    if (problems.length === 0)
+        return false;
+    if (!last)
+        return true;
+    return now - last.lastSentAt >= REPORT_INTERVAL_MS;
+}
+/** The DM text for the owner. Plain, with the commands that fix each case. */
+export function selfCheckMessage(problems, machine, 
+/** A name for a vault (company slug, "personal"), when known. */
+vaultName = () => undefined) {
+    const named = (p) => {
+        const uid = p.unitId.slice(ENGINE_UNIT_PREFIX.length);
+        const name = vaultName(uid);
+        return name ? `${name} (${uid})` : uid;
+    };
+    const names = problems.map(named).join(", ");
+    const body = `HQ sync on ${machine}: the sync engine for ${names} has not synced for over ${ATTENTION_AFTER_MS / 60_000} minutes. ` +
+        "Run `hq daemon status` on that machine.";
+    const lines = problems.map((p) => `- ${named(p)}: ${p.what}. Retry with: hq daemon restart ${p.unitId}`);
+    lines.push("", "Logs: hq daemon logs <unit>. This check runs in hq daemon and sends at most one DM a day from this machine.");
+    return { body, details: lines.join("\n") };
+}
+export async function runSelfCheck(deps) {
+    const now = deps.now();
+    const problems = engineUnitsNeedingAttention(deps.readState(), deps.readHolds(), now, deps.wanted);
+    if (problems.length === 0) {
+        deps.log("sync engine self-check: every engine unit is healthy");
+        return "healthy";
+    }
+    for (const p of problems)
+        deps.log(`sync engine self-check: ${p.unitId} ${p.what}`);
+    const last = readSelfCheckRecord(deps.recordPath);
+    if (!shouldReport(problems, last, now)) {
+        deps.log(`sync engine self-check: already reported at ${iso(last.lastSentAt)}; next report after ${iso(last.lastSentAt + REPORT_INTERVAL_MS)}`);
+        return "already-reported";
+    }
+    const to = await deps.sendToOwner(selfCheckMessage(problems, deps.machine, deps.vaultName));
+    if (to === null) {
+        deps.log("sync engine self-check: this machine is signed in as an agent, so there is no owner to DM; nothing was sent");
+        return "no-owner";
+    }
+    writeSelfCheckRecord(deps.recordPath, { lastSentAt: now, units: problems.map((p) => p.unitId) });
+    deps.log(`sync engine self-check: sent a DM to ${to}`);
+    return "reported";
+}
+//# sourceMappingURL=selfcheck.js.map

package/dist/lib/daemon/supervisor.d.ts

@@ -46,6 +46,30 @@ export declare const CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS = 60000;
 export declare const HANDOFF_STAGGER_MS = 15000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */
 export declare const HANDOFF_DRAIN_MAX_MS: number;
+/** hq-syncd's exit code when another engine holds its engine lease or the HQ operation lock. */
+export declare const SYNC_CORE_LOCK_HELD_EXIT = 17;
+/**
+ * Heartbeat-timeout restarts of an engine that reported growing progress are
+ * not counted toward the hold, up to this many per failure episode. After
+ * that they count, so an engine that moves a few bytes each run and then hangs
+ * is still held (and reported by the self-check) instead of restarting forever.
+ */
+export declare const SYNC_CORE_PROGRESS_EXEMPT_MAX = 6;
+/** How often a unit held for exit 17 checks whether the lock holder is still alive. */
+export declare const LOCK_HOLDER_POLL_MS = 5000;
+/**
+ * The pid hq-syncd names when it exits 17: "local sync engine is already
+ * running (pid N)" or "HQ operation lock for ... is held by "cmd" (pid N)".
+ * Null when the output names no live-looking pid.
+ */
+export declare function lockHolderPidFromOutput(output: string | undefined): number | null;
+/**
+ * Bytes the engine reports having moved, from a protocol heartbeat that
+ * carries `progress` (see the engine contract in the hq-sync-core 0.1.24
+ * notes): `{"type":"heartbeat","progress":{"bytesReceived":N,"bytesSent":M}}`,
+ * both cumulative over the engine process. Null for a heartbeat without it.
+ */
+export declare function heartbeatProgressBytes(event: Record<string, unknown>): number | null;
 export interface SupervisedChild {
     pid?: number;
     stdout?: {
@@ -84,6 +108,11 @@ export interface UnitHold {
     probing?: boolean;
     /** Explicit stop of a recovering unit; only an explicit restart clears it. */
     retryStopped?: boolean;
+    /**
+     * Exit 17 holds: the pid hq-syncd said holds its lock. The hold is released
+     * as soon as that process is gone instead of waiting out the cooldown.
+     */
+    lockHolderPid?: number;
 }
 /** The holds file: unit id to hold. */
 export type PersistedHolds = Record<string, UnitHold>;
@@ -172,6 +201,8 @@ export interface SupervisorDeps {
         read(): PersistedHolds;
         write(holds: PersistedHolds): void;
     };
+    /** Whether a process is alive (signal 0). Enables releasing exit-17 holds when the lock holder exits. */
+    pidAlive?: (pid: number) => boolean;
 }
 export interface Supervisor {
     start(): void;

package/dist/lib/daemon/supervisor.js

@@ -51,6 +51,47 @@ const MESH_OWNER_LOG_INTERVAL_MS = 10 * 60_000;
 export const HANDOFF_STAGGER_MS = 15_000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */
 export const HANDOFF_DRAIN_MAX_MS = 15 * 60_000;
+/** hq-syncd's exit code when another engine holds its engine lease or the HQ operation lock. */
+export const SYNC_CORE_LOCK_HELD_EXIT = 17;
+/**
+ * Heartbeat-timeout restarts of an engine that reported growing progress are
+ * not counted toward the hold, up to this many per failure episode. After
+ * that they count, so an engine that moves a few bytes each run and then hangs
+ * is still held (and reported by the self-check) instead of restarting forever.
+ */
+export const SYNC_CORE_PROGRESS_EXEMPT_MAX = 6;
+/** How often a unit held for exit 17 checks whether the lock holder is still alive. */
+export const LOCK_HOLDER_POLL_MS = 5_000;
+/**
+ * The pid hq-syncd names when it exits 17: "local sync engine is already
+ * running (pid N)" or "HQ operation lock for ... is held by "cmd" (pid N)".
+ * Null when the output names no live-looking pid.
+ */
+export function lockHolderPidFromOutput(output) {
+    if (!output)
+        return null;
+    const matches = [...output.matchAll(/\(pid (\d+)\)/g)];
+    const pid = Number(matches.at(-1)?.[1]);
+    return Number.isSafeInteger(pid) && pid > 1 ? pid : null;
+}
+/**
+ * Bytes the engine reports having moved, from a protocol heartbeat that
+ * carries `progress` (see the engine contract in the hq-sync-core 0.1.24
+ * notes): `{"type":"heartbeat","progress":{"bytesReceived":N,"bytesSent":M}}`,
+ * both cumulative over the engine process. Null for a heartbeat without it.
+ */
+export function heartbeatProgressBytes(event) {
+    if (event.type !== "heartbeat")
+        return null;
+    const progress = event.progress;
+    if (!progress || typeof progress !== "object" || Array.isArray(progress))
+        return null;
+    const { bytesReceived, bytesSent } = progress;
+    const count = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
+    if (typeof bytesReceived !== "number" && typeof bytesSent !== "number")
+        return null;
+    return count(bytesReceived) + count(bytesSent);
+}
 const PASS_REQUEST_DIR_ENV = "HQ_SYNC_PASS_REQUEST_DIR";
 function passRequestDirOf(env) {
     const dir = env?.[PASS_REQUEST_DIR_ENV];
@@ -182,6 +223,9 @@ export function createSupervisor(deps) {
         if (slot.recoveryHealthyTimer !== undefined)
             clearT(slot.recoveryHealthyTimer);
         slot.recoveryHealthyTimer = undefined;
+        if (slot.lockHolderTimer !== undefined)
+            clearT(slot.lockHolderTimer);
+        slot.lockHolderTimer = undefined;
     };
     const clearTimer = (slot) => {
         clearRecoveryWindow(slot);
@@ -363,16 +407,60 @@ export function createSupervisor(deps) {
         if (deps.holds && recoverableHold(slot.plan, slot.state.hold)) {
             slot.state.hold.retryAt = now() + EPISODE_HEALTHY_RESET_MS;
         }
+        if (kind === "exhausted" && slot.plan.service === "sync-core"
+            && slot.state.lastExit?.code === SYNC_CORE_LOCK_HELD_EXIT && slot.lastLockHolderPid !== undefined) {
+            slot.state.hold.lockHolderPid = slot.lastLockHolderPid;
+            slot.state.hold.detail += `; the lock is held by pid ${slot.lastLockHolderPid}, released when it exits`;
+        }
         persistedHolds[slot.plan.id] = slot.state.hold;
         showHeld(slot);
         deps.log("error", `holding ${slot.plan.id}: ${slot.state.reason}`);
         writeHolds();
         armRecoveryProbe(slot);
+        armLockHolderWatch(slot);
+    };
+    /**
+     * A unit held because its lock was taken (exit 17) starts again as soon as
+     * the process holding the lock is gone, instead of after the cooldown.
+     */
+    const armLockHolderWatch = (slot) => {
+        const hold = slot.state.hold;
+        const pid = hold?.lockHolderPid;
+        if (!hold || pid === undefined || !deps.pidAlive || hold.retryStopped === true || stopped || slot.child)
+            return;
+        if (slot.lockHolderTimer !== undefined)
+            clearT(slot.lockHolderTimer);
+        const check = () => {
+            slot.lockHolderTimer = undefined;
+            if (stopped || slots.get(slot.plan.id) !== slot || slot.child || slot.state.hold !== hold || hold.retryStopped === true)
+                return;
+            let alive;
+            try {
+                alive = deps.pidAlive(pid);
+            }
+            catch {
+                alive = true;
+            }
+            if (alive) {
+                slot.lockHolderTimer = setT(check, LOCK_HOLDER_POLL_MS);
+                return;
+            }
+            deps.log("info", `releasing the hold on ${slot.plan.id}: pid ${pid}, which held its lock, has exited`);
+            clearTimer(slot);
+            clearHold(slot);
+            if (slot.plan.blocked)
+                setBlocked(slot);
+            else
+                startLong(slot);
+            emit();
+        };
+        slot.lockHolderTimer = setT(check, 0);
     };
     const clearHold = (slot) => {
         clearRecoveryWindow(slot);
         slot.attempts = 0;
         slot.failures = 0;
+        slot.progressExemptRestarts = 0;
         if (!slot.state.hold && !persistedHolds[slot.plan.id])
             return;
         delete slot.state.hold;
@@ -466,10 +554,11 @@ export function createSupervisor(deps) {
         escalateToKill();
         signalChild(slot, child, "SIGTERM");
     };
-    const scheduleRestart = (slot) => {
+    const scheduleRestart = (slot, countFailure = true) => {
         if (stopped)
             return;
-        slot.failures += 1;
+        if (countFailure)
+            slot.failures += 1;
         if (slot.failures >= EPISODE_MAX_FAILURES) {
             holdUnit(slot, "exhausted", "transient", `${slot.failures} failures without staying up for ${EPISODE_HEALTHY_RESET_MS / 60_000} min`);
             return;
@@ -502,8 +591,20 @@ export function createSupervisor(deps) {
                 slot.heartbeatTimer = undefined;
                 if (stopped || slot.child !== child || slot.expectingExit)
                     return;
-                deps.log("warn", `${slot.plan.id} emitted no sync protocol heartbeat for ${timeoutMs}ms; restarting it`);
-                terminate(slot, () => scheduleRestart(slot));
+                // An engine that reported bytes moving during this run is slow, not
+                // hung: restart it, but do not count it toward the exhausted hold.
+                // Bounded per episode: past SYNC_CORE_PROGRESS_EXEMPT_MAX these count again.
+                const grew = slot.plan.service === "sync-core" && slot.progressedThisRun === true;
+                const progressed = grew && (slot.progressExemptRestarts ?? 0) < SYNC_CORE_PROGRESS_EXEMPT_MAX;
+                if (progressed)
+                    slot.progressExemptRestarts = (slot.progressExemptRestarts ?? 0) + 1;
+                deps.log("warn", `${slot.plan.id} emitted no sync protocol heartbeat for ${timeoutMs}ms; restarting it` +
+                    (progressed
+                        ? ` (it reported transfer progress this run, so this does not count toward holding it; ${slot.progressExemptRestarts}/${SYNC_CORE_PROGRESS_EXEMPT_MAX})`
+                        : grew
+                            ? ` (it reported progress, but ${SYNC_CORE_PROGRESS_EXEMPT_MAX} such restarts already did not count, so this one does)`
+                            : ""));
+                terminate(slot, () => scheduleRestart(slot, !progressed));
                 emit();
             }, timeoutMs);
         };
@@ -543,6 +644,16 @@ export function createSupervisor(deps) {
                         runDeferredCliRestart();
                 }
             }
+            if (slot.plan.service === "sync-core") {
+                const bytes = heartbeatProgressBytes(event);
+                if (bytes !== null) {
+                    // The first progress heartbeat of a run is the baseline: counters are
+                    // cumulative per process, and a handshake alone moves some bytes.
+                    if (slot.progressBytes !== undefined && bytes > slot.progressBytes)
+                        slot.progressedThisRun = true;
+                    slot.progressBytes = Math.max(bytes, slot.progressBytes ?? 0);
+                }
+            }
             const at = now();
             slot.state.lastHeartbeatAt = new Date(at).toISOString();
             const pass = syncPassResult(event, slot.state.lastHeartbeatAt);
@@ -610,8 +721,10 @@ export function createSupervisor(deps) {
                 // run starts a new failure episode, as an unexpected exit would.
                 if (ranFor >= HEALTHY_RUN_MS)
                     slot.attempts = 0;
-                if (ranFor >= EPISODE_HEALTHY_RESET_MS)
+                if (ranFor >= EPISODE_HEALTHY_RESET_MS) {
                     slot.failures = 0;
+                    slot.progressExemptRestarts = 0;
+                }
                 const then = slot.afterExit;
                 slot.afterExit = undefined;
                 then?.();
@@ -688,8 +801,10 @@ export function createSupervisor(deps) {
             deps.log("warn", `${slot.plan.id} exited (code=${code ?? "null"} signal=${signal ?? "none"})`);
             if (ranFor >= HEALTHY_RUN_MS)
                 slot.attempts = 0;
-            if (ranFor >= EPISODE_HEALTHY_RESET_MS)
+            if (ranFor >= EPISODE_HEALTHY_RESET_MS) {
                 slot.failures = 0;
+                slot.progressExemptRestarts = 0;
+            }
             const stoppedFromOutside = signal === "SIGTERM" || signal === "SIGINT";
             if (slot.plan.restart === "on-failure" && (code === 0 || stoppedFromOutside)) {
                 slot.state.status = "exited";
@@ -702,6 +817,12 @@ export function createSupervisor(deps) {
                 const spawnError = slot.lastSpawnError;
                 delete slot.lastSpawnError;
                 const outputTail = spawnError === undefined ? readExitOutputTail(slot) : undefined;
+                delete slot.lastLockHolderPid;
+                if (slot.plan.service === "sync-core" && code === SYNC_CORE_LOCK_HELD_EXIT) {
+                    const holder = lockHolderPidFromOutput(outputTail);
+                    if (holder !== null)
+                        slot.lastLockHolderPid = holder;
+                }
                 if (!holdIfPermanent(slot, { code, signal, spawnError, outputTail }))
                     scheduleRestart(slot);
             }
@@ -740,6 +861,8 @@ export function createSupervisor(deps) {
         delete slot.lastProtocolLine;
         delete slot.lastProtocolStatus;
         delete slot.syncPassActive;
+        delete slot.progressBytes;
+        delete slot.progressedThisRun;
         let child;
         try {
             child = deps.spawn(slot.plan);
@@ -923,6 +1046,7 @@ export function createSupervisor(deps) {
         if (slot.state.hold) {
             showHeld(slot);
             armRecoveryProbe(slot);
+            armLockHolderWatch(slot);
             return;
         }
         startLong(slot);

package/dist/lib/daemon/unit-holds.js

@@ -20,7 +20,8 @@ function isHold(value) {
         && typeof h.detail === "string"
         && typeof h.since === "number"
         && typeof h.failures === "number"
-        && typeof h.keyHash === "string");
+        && typeof h.keyHash === "string"
+        && (h.lockHolderPid === undefined || (typeof h.lockHolderPid === "number" && Number.isSafeInteger(h.lockHolderPid) && h.lockHolderPid > 1)));
 }
 export function readUnitHolds(file) {
     let raw;

package/dist/lib/lanes/config.js

@@ -172,6 +172,14 @@ function optionalUnitInterval(value, field) {
     }
     return value;
 }
+function optionalPercent(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100) {
+        throw new LanesConfigError("invalid_config", `${field} must be a number in [0, 100]`, { field, value });
+    }
+    return value;
+}
 function parseAccount(provider, id, raw, deps) {
     if (!isPlainObject(raw)) {
         throw new LanesConfigError("invalid_config", `providers.${provider}.accounts.${id} must be an object`, { provider, account: id });
@@ -407,6 +415,11 @@ function parseThrottle(raw) {
         }
         result.min_available_mem_mb = obj.min_available_mem_mb;
     }
+    // darwin: a warn pressure level holds only at or below this free
+    // percentage. Unset means DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT (20).
+    const warnMinFree = optionalPercent(obj.memory_warn_min_free_percent, "throttle.memory_warn_min_free_percent");
+    if (warnMinFree !== undefined)
+        result.memory_warn_min_free_percent = warnMinFree;
     return result;
 }
 function parseLiveness(raw) {

package/dist/lib/lanes/throttle.d.ts

@@ -25,6 +25,17 @@ export declare const SYSCTL_BIN = "/usr/sbin/sysctl";
  * hw.memsize turns the percentage into MiB for min_available_mem_mb.
  */
 export declare const MEMORY_PRESSURE_SYSCTLS: readonly ["kern.memorystatus_level", "kern.memorystatus_vm_pressure_level", "hw.memsize"];
+/**
+ * Default for throttle.memory_warn_min_free_percent. On darwin a warn pressure
+ * level holds admission only while the free percentage is at or below this.
+ */
+export declare const DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT = 20;
+/**
+ * Whether a darwin memory_pressure level holds admission on its own. Critical
+ * always holds. Warn holds only at or below warnMinFreePercent free, or when
+ * the free percentage is unknown.
+ */
+export declare function pressureLevelHolds(signal: MemorySignal, warnMinFreePercent?: number): boolean;
 export declare const LANES_CPU_BUSY_OVERRIDE = "HQ_LANES_CPU_BUSY_OVERRIDE";
 export declare const LANES_CPU_CHECK = "HQ_LANES_CPU_CHECK";
 export interface CpuTimes {
@@ -129,7 +140,7 @@ export declare function readMemorySignal(deps?: ThrottleDeps): MemorySignal | nu
 /** Available memory in MiB from readMemorySignal; null skips the memory gate. */
 export declare function readAvailableMemMb(deps?: ThrottleDeps): number | null;
 /** Plain explanation of a memory hold: which signal, its value, and the threshold. */
-export declare function formatMemoryHoldMessage(signal: MemorySignal, thresholdMb: number): string;
+export declare function formatMemoryHoldMessage(signal: MemorySignal, thresholdMb: number, warnMinFreePercent?: number): string;
 export interface ThrottleState {
     consecutiveDeferrals: number;
     lastAdmissionAt: string | null;