@indigoai-us/hq-cli 5.345.175 → 5.345.177

package/dist/lib/lanes/loop.js

@@ -2,6 +2,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { isPidRecordAlive, readProcStarttime } from "./spawn.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 export const LOOP_SCHEMA = "hq-lane-loop.v1";
 export const PHASE_ENVELOPE_SCHEMA = "hq-phase-envelope/v1";
@@ -362,7 +363,9 @@ function nextQueueSequence(runDir) {
     atomicJson(sequenceFile, { sequence });
     return sequence;
 }
-function acquireRunnerLease(runDir) {
+function acquireRunnerLease(runDir, identity) {
+    const readStarttime = identity?.readStarttime ?? readProcStarttime;
+    const starttime = readStarttime(process.pid) ?? undefined;
     const lock = path.join(runDir, "loop", "runner.lock");
     fs.mkdirSync(path.dirname(lock), { recursive: true });
     try {
@@ -372,27 +375,34 @@ function acquireRunnerLease(runDir) {
         if (error.code !== "EEXIST")
             throw error;
         let pid;
+        let recordedStarttime;
         try {
             const owner = readJson(path.join(lock, "owner.json"));
-            if (isRecord(owner) && typeof owner.pid === "number")
+            if (isRecord(owner) && typeof owner.pid === "number") {
                 pid = owner.pid;
+                recordedStarttime = typeof owner.starttime === "number" ? owner.starttime : undefined;
+            }
         }
         catch (readError) {
             if (readError.code !== "ENOENT" && !(readError instanceof SyntaxError))
                 throw readError;
         }
-        let alive = false;
-        if (pid !== undefined && Number.isSafeInteger(pid) && pid > 0) {
-            try {
-                process.kill(pid, 0);
-                alive = true;
-            }
-            catch (probeError) {
-                alive = probeError.code === "EPERM";
-                if (!alive && probeError.code !== "ESRCH")
-                    throw probeError;
-            }
-        }
+        const alive = pid !== undefined && Number.isSafeInteger(pid) && pid > 0 &&
+            isPidRecordAlive({ pid, starttime: recordedStarttime }, identity?.isAlive ?? ((candidate) => {
+                try {
+                    process.kill(candidate, 0);
+                    return true;
+                }
+                catch (error) {
+                    if (error.code === "EPERM")
+                        return true;
+                    if (error.code === "ESRCH")
+                        return false;
+                    throw error;
+                }
+            }), readStarttime);
+        if (pid === undefined || !Number.isSafeInteger(pid) || pid <= 0)
+            throw new Error("Loop runner lease ownership is unknown; explicit recovery required");
         const age = Date.now() - fs.statSync(lock).mtimeMs;
         if (alive || age <= 60_000)
             throw new Error(`Loop runner is already active${pid ? ` (pid ${pid})` : ""}`);
@@ -423,9 +433,12 @@ function acquireRunnerLease(runDir) {
         if (released)
             return;
         released = true;
+        process.removeListener("exit", release);
         clearInterval(heartbeat);
         try {
-            fs.rmSync(lock, { recursive: true, force: true });
+            const owner = readJson(ownerFile);
+            if (isRecord(owner) && owner.pid === process.pid && owner.starttime === starttime)
+                fs.rmSync(lock, { recursive: true, force: true });
         }
         catch (error) {
             if (error.code !== "ENOENT")
@@ -434,27 +447,35 @@ function acquireRunnerLease(runDir) {
     };
     const heartbeat = setInterval(() => {
         try {
-            atomicJson(ownerFile, { pid: process.pid, heartbeat_at: new Date().toISOString() });
+            atomicJson(ownerFile, { pid: process.pid, starttime, heartbeat_at: new Date().toISOString() });
         }
         catch (error) {
             process.stderr.write(`hq lanes: loop lease heartbeat failed: ${error instanceof Error ? error.message : String(error)}\n`);
         }
     }, 15_000);
-    atomicJson(ownerFile, { pid: process.pid, heartbeat_at: new Date().toISOString() });
+    atomicJson(ownerFile, { pid: process.pid, starttime, heartbeat_at: new Date().toISOString() });
     process.once("exit", release);
-    fs.mkdirSync(pendingDir(runDir), { recursive: true });
-    for (const active of envelopeFiles(activeDir(runDir))) {
-        const recovered = path.join(pendingDir(runDir), `0000000000000-recovered-${path.basename(active)}`);
-        try {
-            fs.renameSync(active, recovered);
-        }
-        catch (recoveryError) {
-            if (recoveryError.code !== "ENOENT") {
-                release();
-                throw recoveryError;
-            }
+    // A dead controller may have performed external effects before it died.
+    // Replaying an active envelope cannot be justified by reclaiming its lease.
+    if (inspectLoopRecovery(runDir).kind === "hold") {
+        release();
+        throw new Error("Loop recovery requires an explicit disposition of interrupted work");
+    }
+    try {
+        // Only this lease owner may finalize the proven local completion window.
+        // Never execute it again; a failure leaves the original active file intact.
+        for (const file of completedActiveRecovery(runDir).files) {
+            const destination = path.join(claimedDir(runDir), path.basename(file));
+            if (fs.existsSync(destination))
+                throw new Error("Completed loop archive already exists; explicit recovery required");
+            fs.mkdirSync(claimedDir(runDir), { recursive: true });
+            fs.renameSync(file, destination);
         }
     }
+    catch (error) {
+        release();
+        throw error;
+    }
     return release;
 }
 function envelopeFiles(dir) {
@@ -806,8 +827,8 @@ export function commitIdleLoopStop(runDir, laneId, now = () => new Date()) {
     persistStatus(runDir, laneId, { state: "stopped", queue_depth: listLoopQueue(runDir).length, active_envelope_id: null, active_phase: null });
     return true;
 }
-export function setLoopControllerPid(runDir, laneId, pid) {
-    persistStatus(runDir, laneId, { pid });
+export function setLoopControllerPid(runDir, laneId, pid, starttime) {
+    persistStatus(runDir, laneId, { pid, starttime });
 }
 export function clearLoopControllerPid(runDir, laneId, pid) {
     let currentPid;
@@ -821,51 +842,129 @@ export function clearLoopControllerPid(runDir, laneId, pid) {
             throw error;
     }
     if (currentPid === pid)
-        persistStatus(runDir, laneId, { pid: undefined });
+        persistStatus(runDir, laneId, { pid: undefined, starttime: undefined });
 }
 /**
  * True when a loop lane's controller is alive with no phase active: the lane
  * finished its last phase and is waiting for the next envelope.
  */
-export function loopLaneIsIdle(runDir, laneId) {
+export function loopLaneIsIdle(runDir, laneId, isAlive, readStarttime) {
     const status = loopStatus(runDir, laneId);
-    return status.state === "waiting" && status.active_envelope_id === null && loopControllerIsAlive(runDir);
+    return status.state === "waiting" && status.active_envelope_id === null && loopControllerIsAlive(runDir, isAlive, readStarttime);
 }
-export function loopControllerIsAlive(runDir) {
-    let pid;
-    try {
-        const status = readJson(loopPath(runDir));
-        if (isRecord(status))
-            pid = status.pid;
+export function loopControllerIsAlive(runDir, isAlive, readStarttime = readProcStarttime) {
+    const records = [];
+    for (const file of [loopPath(runDir), path.join(runDir, "loop", "runner.lock", "owner.json")]) {
+        try {
+            const value = readJson(file);
+            if (isRecord(value) && typeof value.pid === "number" && Number.isSafeInteger(value.pid) && value.pid > 0) {
+                records.push({ pid: value.pid, starttime: typeof value.starttime === "number" ? value.starttime : undefined });
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+                throw error;
+        }
     }
-    catch (error) {
-        if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+    const probe = isAlive ?? ((candidate) => {
+        try {
+            process.kill(candidate, 0);
+            return true;
+        }
+        catch (error) {
+            if (error.code === "EPERM")
+                return true;
+            if (error.code === "ESRCH")
+                return false;
             throw error;
-    }
-    if (typeof pid !== "number") {
+        }
+    });
+    // A failed second launch may overwrite loop.json before its lease fails.
+    // The live lease owner still protects the first controller.
+    return records.some(record => isPidRecordAlive(record, probe, readStarttime));
+}
+/** A local terminal result is enough only when no external handoff was promised. */
+function completedActiveRecovery(runDir) {
+    const files = [];
+    for (const file of envelopeFiles(activeDir(runDir))) {
+        const record = fileEnvelope(file);
+        if (record.envelope.kind === "stop")
+            return { files: [], stopped: true };
+        let result;
         try {
-            const owner = readJson(path.join(runDir, "loop", "runner.lock", "owner.json"));
-            if (isRecord(owner))
-                pid = owner.pid;
+            result = readJson(path.join(resultsDir(runDir), resultName(record.envelope_id)));
         }
         catch (error) {
             if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
                 throw error;
         }
+        if (!isRecord(result) || result.schema_version !== LOOP_SCHEMA || result.envelope_id !== record.envelope_id ||
+            !["done", "failed"].includes(String(result.status)) ||
+            typeof result.started_at !== "string" || !Number.isFinite(Date.parse(result.started_at)) ||
+            typeof result.finished_at !== "string" || !Number.isFinite(Date.parse(result.finished_at)) ||
+            Date.parse(result.finished_at) < Date.parse(result.started_at)) {
+            return { files: [], reason: "active_phase_outcome_unknown" };
+        }
+        if (typeof record.envelope.result_path === "string") {
+            // Local write happens before the optional external handoff. Do not read
+            // arbitrary paths or assume a local result proves that handoff finished.
+            return { files: [], reason: "external_completion_unverified" };
+        }
+        files.push(file);
     }
-    if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
+    return { files };
+}
+/** Read durable work without changing queue files or assuming effects are replayable. */
+export function inspectLoopRecovery(runDir) {
+    const status = loopStatus(runDir, path.basename(runDir));
+    if (["parked", "stopped", "failed"].includes(status.state))
+        return { kind: "protected" };
+    const lease = path.join(runDir, "loop", "runner.lock");
+    if (fs.existsSync(lease)) {
+        let owner;
+        try {
+            owner = readJson(path.join(lease, "owner.json"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+                throw error;
+        }
+        if (!isRecord(owner) || !Number.isSafeInteger(owner.pid) || Number(owner.pid) <= 0) {
+            return { kind: "hold", reason: "runner_lease_identity_unknown" };
+        }
     }
-    catch (error) {
-        if (error.code === "EPERM")
-            return true;
-        if (error.code === "ESRCH")
-            return false;
-        throw error;
+    const completed = completedActiveRecovery(runDir);
+    if (completed.reason)
+        return { kind: "hold", reason: completed.reason };
+    if (completed.stopped)
+        return { kind: "protected" };
+    for (const file of envelopeFiles(claimedDir(runDir))) {
+        const record = fileEnvelope(file);
+        if (record.envelope.kind === "stop")
+            return { kind: "protected" };
+        let result;
+        try {
+            result = readJson(path.join(resultsDir(runDir), resultName(record.envelope_id)));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+                throw error;
+        }
+        if (!isRecord(result) || result.schema_version !== LOOP_SCHEMA || result.envelope_id !== record.envelope_id ||
+            !["done", "failed", "stopped"].includes(String(result.status))) {
+            return { kind: "hold", reason: "claimed_phase_outcome_unknown" };
+        }
+        if (result.status === "stopped")
+            return { kind: "protected" };
     }
+    const pending = listLoopQueue(runDir);
+    // A completed phase still needs lease-owned archiving before an idle stop.
+    if (completed.files.length > 0)
+        return { kind: "pending" };
+    // A queued intentional stop remains owned by the ordinary stop path.
+    if (pending[0]?.envelope?.kind === "stop")
+        return { kind: "protected" };
+    return { kind: pending.length > 0 ? "pending" : "empty" };
 }
 function phaseName(envelope, fallback) {
     const value = envelope;
@@ -911,6 +1010,14 @@ function persistStatus(runDir, laneId, patch) {
         updated_at: new Date().toISOString(),
     });
 }
+/** Reset only after an explicit, durable disposition; this never starts work. */
+export function resetLoopAfterDisposition(runDir, laneId, decision, hasPending) {
+    persistStatus(runDir, laneId, {
+        state: hasPending ? "waiting" : "failed", active_envelope_id: null, active_phase: null,
+        pid: undefined, starttime: undefined, queue_depth: listLoopQueue(runDir).length,
+        recovery_decision: decision,
+    });
+}
 function abortAfter(ms, parent) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(new Error("phase deadline exceeded")), Math.min(Math.max(ms, 1), 2_147_483_647));
@@ -947,12 +1054,12 @@ export async function runLoopLane(options) {
     const stalls = new Map();
     let completed = 0;
     fs.mkdirSync(options.runDir, { recursive: true });
-    let releaseRunner = acquireRunnerLease(options.runDir);
+    let releaseRunner = acquireRunnerLease(options.runDir, options.processIdentity);
     if (readHandoffHold(options.runDir)) {
         releaseRunner();
         return { state: loopStatus(options.runDir, options.lane.lane_id).state === "stopped" ? "stopped" : "parked", completed: 0 };
     }
-    persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid });
+    persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid, starttime: (options.processIdentity?.readStarttime ?? readProcStarttime)(process.pid) ?? undefined });
     try {
         const previous = readJson(loopPath(options.runDir));
         if (isRecord(previous) && isRecord(previous.stall_counts)) {
@@ -1206,7 +1313,7 @@ export async function runLoopLane(options) {
             const answeredRetryIsPending = envelopeFiles(pendingDir(options.runDir)).some((pendingFile) => path.basename(pendingFile).startsWith("0000000000000-answer-") && fileEnvelope(pendingFile).envelope_id === record.envelope_id);
             if (answeredRetryIsPending) {
                 try {
-                    releaseRunner = acquireRunnerLease(options.runDir);
+                    releaseRunner = acquireRunnerLease(options.runDir, options.processIdentity);
                     persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid, state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                     continue;
                 }

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

@@ -102,6 +102,11 @@ export interface ReconcileDeps {
     throttleDeps?: ThrottleDeps;
     livenessDeps?: LivenessDeps;
     isAlive?: (pid: number) => boolean;
+    /** Controller identity is independent of worker/watcher liveness. */
+    controllerProcessIdentity?: {
+        isAlive(pid: number): boolean;
+        readStarttime(pid: number): number | null;
+    };
     readSessionSenior?: (sessionId: string) => SeniorRef;
     presenceConnected?: boolean;
     env?: NodeJS.ProcessEnv;

package/dist/lib/lanes/reconcile.js

@@ -13,7 +13,7 @@ import { compareLaneQueueOrder, compareLaneQueueOrderWithLeads, leadLaneIds, has
 import { accountStatus, isCredentialProven, resolveAccount } from "./accounts.js";
 import { effectiveAccountHome } from "./account-home.js";
 import { enforceRegistryApprovalGate } from "./approval-gate.js";
-import { loopLaneIsIdle, loopStatus } from "./loop.js";
+import { inspectLoopRecovery, loopControllerIsAlive, loopLaneIsIdle, loopStatus } from "./loop.js";
 import { loadLanesConfig, providerQuotaDefaultHoldMs } from "./config.js";
 import { MAX_LANE_DEPTH } from "./constants.js";
 import { laneDepthCap } from "./depth-cap.js";
@@ -1499,7 +1499,8 @@ export async function runPassBody(hqRoot, deps) {
     }));
     const admissionThrottleDeps = startDeps.throttleDeps ?? defaultThrottleDeps(startDeps.env ?? process.env);
     const hasAdmissionCandidates = lanes.some((lane) => laneRunsHere(lane, startDeps.host) &&
-        (lane.state === "queued" || lane.state === "awaiting_input")) || [...keepAliveFlagByCompany.values()].some(Boolean);
+        (lane.state === "queued" || lane.state === "awaiting_input")) || summary.dead_host.some((entry) => entry.reason === "loop_controller_lost" && entry.to === "queued") ||
+        [...keepAliveFlagByCompany.values()].some(Boolean);
     const priorThrottleState = readThrottleState(throttleStatePath(hqRoot), admissionThrottleDeps);
     const priorThrottleSnapshot = priorThrottleState === "missing" || priorThrottleState === "unreadable"
         ? undefined
@@ -1597,6 +1598,8 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
     const nowIso = now.toISOString();
     const isAlive = deps.isAlive ?? isPidAlive;
     for (const lane of lanes) {
+        // Historical done lanes require explicit recovery; leftover files alone
+        // do not prove that their work should run again.
         if (lane.state !== "running")
             continue;
         // No HQ process backs a subagent lane, so a missing pid is not a dead
@@ -1658,7 +1661,7 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                 // Watcher owns terminal classification of a process that has just exited.
                 continue;
             }
-            if (lane.loop_mode === true && loopLaneIsIdle(runDir, lane.lane_id)) {
+            if (lane.loop_mode === true && loopLaneIsIdle(runDir, lane.lane_id, deps.controllerProcessIdentity?.isAlive, deps.controllerProcessIdentity?.readStarttime)) {
                 // An idle loop lane has no worker between phases. Its controller is
                 // alive and waiting for the next envelope, so the lane is not finished.
                 try {
@@ -1675,6 +1678,44 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                 }
                 continue;
             }
+            if (lane.loop_mode === true) {
+                try {
+                    // A controller can be alive while a phase starts; never use a stale
+                    // phase envelope to terminalize or admit behind that controller.
+                    if (loopControllerIsAlive(runDir, deps.controllerProcessIdentity?.isAlive, deps.controllerProcessIdentity?.readStarttime))
+                        continue;
+                    const recovery = inspectLoopRecovery(runDir);
+                    if (recovery.kind === "protected")
+                        continue;
+                    if (recovery.kind === "hold" || recovery.kind === "pending") {
+                        const hasQuestion = loadQuestionRecords(hqRoot, summary).some(question => question.lane_id === lane.lane_id && question.status === "pending");
+                        if (hasQuestion)
+                            continue;
+                        const hold = recovery.kind === "hold" || deps.spawn === undefined;
+                        const reason = hold ? "loop_recovery_required" : "loop_controller_lost";
+                        const result = casLaneIf(hqRoot, lane.lane_id, current => current.state === "running" && current.loop_mode === true &&
+                            laneRunsHere(current, deps.host) && !current.terminal_reason?.startsWith("operator_") &&
+                            !["loop_stopped", "story_closed"].includes(current.terminal_reason ?? ""), current => ({ ...current, state: hold ? "interrupted" : "queued",
+                            queued_reason: undefined, queued_details: undefined,
+                            admission_reserved_at: undefined,
+                            terminal_reason: hold ? reason : undefined,
+                            terminal_details: hold ? { reason: recovery.reason ?? "controller_admission_unavailable", automatic_replay: false } : { loop_recovery: true },
+                            interrupted_at: hold ? nowIso : undefined,
+                            last_host_report_at: nowIso,
+                        }), deps.dryRun);
+                        if (result.changed)
+                            summary.dead_host.push({ id: lane.lane_id, from: lane.state, to: result.record.state, reason });
+                        continue;
+                    }
+                }
+                catch (err) {
+                    markDirty(summary, { kind: "lane", id: lane.lane_id,
+                        why: `loop recovery inspection failed: ${err instanceof Error ? err.message : String(err)}` });
+                    continue;
+                }
+            }
+            if (lane.state !== "running")
+                continue;
             const hadPids = workerPid !== null || watcherPid !== null;
             if (!hadPids && nowMs - lastHostReportMs(lane) < DEAD_HOST_MS) {
                 try {
@@ -2175,9 +2216,40 @@ async function admitQueued(hqRoot, lanes, summary, deps, now, onlyLaneIds, exclu
         }
         const projected = [...running, ...spawned];
         const alternateAccount = availableBalancedAccount(hqRoot, lane, projected, config, deps.host, profileMaxConcurrent, now.getTime());
-        const admittedLane = alternateAccount !== undefined
+        let admittedLane = alternateAccount !== undefined
             ? writeAdmissionAccount(hqRoot, lane, alternateAccount, deps.dryRun)
             : lane;
+        if (admittedLane.terminal_details?.loop_recovery === true) {
+            const accounts = config.providers[admittedLane.provider].accounts;
+            const company = resolveLaneCompany(hqRoot, admittedLane).company;
+            let account;
+            try {
+                account = resolveAccount(admittedLane.provider, admittedLane.account, config, {
+                    hqRoot, hostname: deps.host.hostname,
+                    allowedAccounts: Object.keys(accounts).filter((id) => accountMatchesCompany(accounts[id], company, accounts)),
+                }).id;
+            }
+            catch (error) {
+                if (!(error instanceof AccountResolutionError))
+                    throw error;
+                writeQueueReason(hqRoot, admittedLane, "account_retry", deps.dryRun);
+                continue;
+            }
+            if (!accountMatchesCompany(accounts[account], company, accounts) && accounts[account]?.company !== undefined) {
+                writeQueueReason(hqRoot, admittedLane, "account_retry", deps.dryRun);
+                continue;
+            }
+            if (admittedLane.account !== account)
+                admittedLane = writeAdmissionAccount(hqRoot, admittedLane, account, deps.dryRun);
+            const status = accountStatus(admittedLane.provider, account, config, {
+                hostname: deps.host.hostname,
+                existsSync: (file) => fs.existsSync(file),
+            });
+            if (!status?.enabled || !isCredentialProven(status)) {
+                writeQueueReason(hqRoot, admittedLane, "account_retry", deps.dryRun);
+                continue;
+            }
+        }
         const baseCap = laneAdmissionCapReason(running, admittedLane, config, deps.host, profileMaxConcurrent, now.getTime());
         const currentCap = laneAdmissionCapReason([...running, ...spawned], admittedLane, config, deps.host, profileMaxConcurrent, now.getTime());
         let blockedBy;
@@ -2832,6 +2904,9 @@ async function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, fla
         await admitDueCandidates(new Set(queuedDueCandidateIds));
     };
     for (let originalLane of candidates) {
+        // Recovery requires an explicit effects disposition, even for keep-alive leads.
+        if (originalLane.terminal_reason === "loop_recovery_required")
+            continue;
         if (admitDueCandidates !== undefined && dueCandidateIds.size > 0 && !dueCandidateIds.has(originalLane.lane_id)) {
             await admitQueuedDueCandidates();
         }

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

@@ -15,6 +15,9 @@ export interface WorkCacheSubscriber {
     stop: () => Promise<void>;
 }
 export { AGENT_INBOX_PUSH_STATE_BASENAME, SYNC_WAKE_STATE_BASENAME } from "../paths.js";
+export type SyncWakeVaults = Record<string, {
+    wakeSequence: number;
+}>;
 export declare function startWorkCacheSubscriber(opts: {
     meshRoot: string;
     fetchCredentials?: PersonalCredentialsFetcher;

package/dist/lib/mesh/live/daemon/work-subscribe.js

@@ -15,22 +15,22 @@ const INBOX_PUSH_HEARTBEAT_MS = 5_000;
 const SYNC_WAKE_KEYS = new Set(["v", "type", "vault", "head", "rootId"]);
 const SYNC_WAKE_VAULT = /^(?:prs|cmp|agt)_[0-9A-Za-z]+$/;
 const SYNC_WAKE_ROOT = /^[0-9a-f]{64}$/i;
-function isSyncWakeEnvelope(payload) {
+function parseSyncWakeEnvelope(payload) {
     let parsed;
     try {
         parsed = JSON.parse(Buffer.isBuffer(payload) ? payload.toString("utf8") : payload);
     }
     catch {
-        return false;
+        return null;
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-        return false;
+        return null;
     const message = parsed;
     const keys = Object.keys(message);
     if (keys.length !== SYNC_WAKE_KEYS.size || keys.some((key) => !SYNC_WAKE_KEYS.has(key))) {
-        return false;
+        return null;
     }
-    return message.v === 1 &&
+    const valid = message.v === 1 &&
         message.type === "vault.head" &&
         typeof message.vault === "string" &&
         SYNC_WAKE_VAULT.test(message.vault) &&
@@ -38,6 +38,21 @@ function isSyncWakeEnvelope(payload) {
         Number(message.head) > 0 &&
         (message.rootId === null ||
             (typeof message.rootId === "string" && SYNC_WAKE_ROOT.test(message.rootId)));
+    return valid ? { vault: message.vault } : null;
+}
+function readVaultSequences(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const vaults = {};
+    for (const [vault, entry] of Object.entries(raw)) {
+        if (!SYNC_WAKE_VAULT.test(vault) || !entry || typeof entry !== "object")
+            continue;
+        const sequence = entry.wakeSequence;
+        if (Number.isSafeInteger(sequence) && Number(sequence) >= 0) {
+            vaults[vault] = { wakeSequence: Number(sequence) };
+        }
+    }
+    return vaults;
 }
 function readWakeSequence(meshRoot, basename, label, onInfo) {
     const target = path.join(meshRoot, basename);
@@ -45,21 +60,29 @@ function readWakeSequence(meshRoot, basename, label, onInfo) {
         const info = fs.lstatSync(target);
         if (!info.isFile() || info.isSymbolicLink()) {
             onInfo?.(`${label} state read ignored (not a regular file)`);
-            return { sequence: 0, writable: false };
+            return { sequence: 0, writable: false, vaults: {} };
         }
         const parsed = JSON.parse(fs.readFileSync(target, "utf8"));
         if (Number.isSafeInteger(parsed.wakeSequence) && Number(parsed.wakeSequence) >= 0) {
-            return { sequence: Number(parsed.wakeSequence), writable: true };
+            return {
+                sequence: Number(parsed.wakeSequence),
+                writable: true,
+                vaults: readVaultSequences(parsed.vaults),
+            };
         }
         onInfo?.(`${label} state read ignored (invalid wake sequence)`);
-        return { sequence: 0, writable: false };
+        return { sequence: 0, writable: false, vaults: {} };
     }
     catch (error) {
         if (error.code !== "ENOENT") {
             const name = error instanceof Error ? error.name : "UnknownError";
             onInfo?.(`${label} state read failed (${name})`);
         }
-        return { sequence: 0, writable: error.code === "ENOENT" };
+        return {
+            sequence: 0,
+            writable: error.code === "ENOENT",
+            vaults: {},
+        };
     }
 }
 function writeWakeState(meshRoot, basename, state, durable) {
@@ -132,19 +155,21 @@ export async function startWorkCacheSubscriber(opts) {
     let inboxWakeSequence = readWakeSequence(opts.meshRoot, AGENT_INBOX_PUSH_STATE_BASENAME, "agent inbox push", opts.onInfo).sequence;
     const syncWakeState = readWakeSequence(opts.meshRoot, SYNC_WAKE_STATE_BASENAME, "sync wake", opts.onInfo);
     let syncWakeSequence = syncWakeState.sequence;
+    const syncWakeVaults = { ...syncWakeState.vaults };
     const syncStateWritable = syncWakeState.writable;
     const clearInboxHeartbeat = () => {
         if (heartbeatTimer !== null)
             timers.clearTimeout(heartbeatTimer);
         heartbeatTimer = null;
     };
-    const persistState = (basename, label, connected, wakeSequence, identity, durable = true) => {
+    const persistState = (basename, label, connected, wakeSequence, identity, durable = true, vaults) => {
         try {
             writeWakeState(opts.meshRoot, basename, {
                 connected,
                 heartbeatAtMs: now().getTime(),
                 wakeSequence,
                 ...(connected && actorUid && identity ? { [identity]: actorUid } : {}),
+                ...(vaults ? { vaults } : {}),
             }, durable);
         }
         catch (error) {
@@ -154,7 +179,7 @@ export async function startWorkCacheSubscriber(opts) {
     };
     const persistInboxState = (connected, durable = true) => persistState(AGENT_INBOX_PUSH_STATE_BASENAME, "agent inbox push", connected, inboxWakeSequence, "agentUid", durable);
     const persistSyncState = (connected, durable = true) => syncStateWritable
-        ? persistState(SYNC_WAKE_STATE_BASENAME, "sync wake", connected, syncWakeSequence, undefined, durable)
+        ? persistState(SYNC_WAKE_STATE_BASENAME, "sync wake", connected, syncWakeSequence, undefined, durable, syncWakeVaults)
         : undefined;
     const scheduleInboxHeartbeat = () => {
         if (stopped || (!inboxSubscribed && !syncSubscribed))
@@ -287,11 +312,15 @@ export async function startWorkCacheSubscriber(opts) {
                 return;
             }
             if (syncTopic && _topic === syncTopic && syncSubscribed) {
-                if (!isSyncWakeEnvelope(payload)) {
+                const envelope = parseSyncWakeEnvelope(payload);
+                if (!envelope) {
                     opts.onInfo?.("sync wake ignored (invalid envelope)");
                     return;
                 }
                 syncWakeSequence += 1;
+                syncWakeVaults[envelope.vault] = {
+                    wakeSequence: (syncWakeVaults[envelope.vault]?.wakeSequence ?? 0) + 1,
+                };
                 persistSyncState(true);
                 return;
             }

package/dist/lib/sync-core/engine-home.d.ts

@@ -29,16 +29,23 @@ export declare function writeEngineHome(opts: WriteEngineHomeOptions): {
     engineHome: string;
     changed: boolean;
 };
-export interface SyncCorePlanFigures {
+export interface SyncCoreFirstCycle {
     at: string;
+    planned: number;
+    completed: number;
+    pending: number;
+    held: number;
+    notApplied: number;
     uploads: number;
     downloads: number;
     deletes: number;
     conflicts: number;
-    remoteRows: number;
-    localFiles: number;
+    deferred: number;
+    listed: number;
+    truncated: boolean;
 }
-export declare function engineReadOnlyPlan(engineHome: string, vaultUid: string): SyncCorePlanFigures | null;
+export declare const SYNC_CORE_STATUS_WORK_LIMIT = 20;
+export declare function engineFirstCycle(engineHome: string, vaultUid: string, since: string): SyncCoreFirstCycle | null;
 export declare function clearEngineStatus(home: string, vaultUid: string): void;
 export declare function removeEngineOwnership(home: string, vaultUid: string): void;
 export declare function inspectEngineHome(home: string, hqRoot: string | undefined, plan: SyncCoreVaultPlan, platform: NodeJS.Platform): SyncCoreVaultPlan;