@indigoai-us/hq-cli 5.282.0 → 5.284.0

package/dist/lib/lanes/outpost-hire-cache.js

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 export const OUTPOST_HIRE_SUMMARY_CACHE_TTL_MS = 60_000;
+export const LANE_OUTPOST_SNAPSHOT_CACHE_FLAG = "lanes.outpost-snapshot-cache";
 const CACHE_RELATIVE_PATH = path.join("workspace", "lanes-runs", ".cache", "outpost-hire-summaries.json");
 export function outpostHireSummaryCachePath(hqRoot) {
     return path.join(hqRoot, CACHE_RELATIVE_PATH);
@@ -10,6 +11,13 @@ export function outpostHireSummaryCacheKey(outpostId, laneId) {
     return JSON.stringify([outpostId, laneId]);
 }
 export function readOutpostHireSummaryCache(hqRoot, nowMs) {
+    return readCache(hqRoot, nowMs, false);
+}
+/** Reads the last validated summaries even after their freshness window expires. */
+export function readOutpostHireSummaryCacheIncludingStale(hqRoot, nowMs) {
+    return readCache(hqRoot, nowMs, true);
+}
+function readCache(hqRoot, nowMs, includeStale) {
     const filePath = outpostHireSummaryCachePath(hqRoot);
     let contents;
     try {
@@ -36,7 +44,7 @@ export function readOutpostHireSummaryCache(hqRoot, nowMs) {
     const entries = new Map();
     const duplicates = new Set();
     for (const value of parsed) {
-        const entry = parseCacheEntry(value, nowMs);
+        const entry = parseCacheEntry(value, nowMs, includeStale);
         if (!entry)
             continue;
         const key = outpostHireSummaryCacheKey(entry.outpost_id, entry.lane_id);
@@ -94,7 +102,7 @@ export function writeOutpostHireSummaryCache(hqRoot, updates, nowMs, existingEnt
         console.warn(`Could not write Outpost hire summary cache at ${filePath}: ${errorText(err)}`);
     }
 }
-function parseCacheEntry(value, nowMs) {
+function parseCacheEntry(value, nowMs, includeStale = false) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return undefined;
     const entry = value;
@@ -120,7 +128,7 @@ function parseCacheEntry(value, nowMs) {
     const cachedAt = Date.parse(entry.cached_at);
     if (!Number.isFinite(cachedAt) ||
         cachedAt > nowMs ||
-        nowMs - cachedAt > OUTPOST_HIRE_SUMMARY_CACHE_TTL_MS) {
+        (!includeStale && nowMs - cachedAt > OUTPOST_HIRE_SUMMARY_CACHE_TTL_MS)) {
         return undefined;
     }
     const hire = `${entry.hire_alive_children}/${entry.hire_grant}`;

package/dist/lib/lanes/outpost-snapshot-cache.d.ts

@@ -0,0 +1,26 @@
+export declare const OUTPOST_SNAPSHOT_CACHE_TTL_MS = 3000;
+export declare const OUTPOST_SNAPSHOT_CACHE_STALE_LOCK_MS = 45000;
+export interface OutpostSnapshotCachePolicy {
+    ttlMs?: number;
+    staleLockMs?: number;
+    lockWaitMs?: number;
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    acquireLock?: (lockPath: string, token: string, nowMs: number) => void;
+}
+/** Deduplicates identical remote snapshot queries within one command invocation. */
+export declare class OutpostSnapshotInvocationMemo {
+    private readonly requests;
+    getOrCreate<T>(outpostId: string, query: unknown, fetch: () => Promise<T>): Promise<T>;
+}
+export declare function outpostLaneListSnapshotKey(outpostId: string, normalizedQuery: unknown): string;
+export declare function outpostSnapshotCachePath(hqRoot: string, key: string): string;
+export declare function getOrFetchOutpostSnapshot<T>(input: {
+    hqRoot: string;
+    key: string;
+    isValue: (value: unknown) => value is T;
+    fetch: () => Promise<T>;
+    policy?: OutpostSnapshotCachePolicy;
+}): Promise<T>;
+//# sourceMappingURL=outpost-snapshot-cache.d.ts.map

package/dist/lib/lanes/outpost-snapshot-cache.js

@@ -0,0 +1,215 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+export const OUTPOST_SNAPSHOT_CACHE_TTL_MS = 3_000;
+export const OUTPOST_SNAPSHOT_CACHE_STALE_LOCK_MS = 45_000;
+const CACHE_RELATIVE_PATH = path.join("workspace", "lanes-runs", ".cache", "outpost-snapshots");
+const CACHE_SCHEMA_VERSION = "hq-lanes-outpost-snapshot-cache.v1";
+const LOCK_POLL_MS = 20;
+const LOCK_WAIT_MS = 60_000;
+/** Deduplicates identical remote snapshot queries within one command invocation. */
+export class OutpostSnapshotInvocationMemo {
+    requests = new Map();
+    getOrCreate(outpostId, query, fetch) {
+        const key = JSON.stringify([outpostId, query]);
+        const existing = this.requests.get(key);
+        if (existing)
+            return existing;
+        const request = fetch();
+        this.requests.set(key, request);
+        return request;
+    }
+}
+export function outpostLaneListSnapshotKey(outpostId, normalizedQuery) {
+    return JSON.stringify(["lane-list", outpostId, normalizedQuery]);
+}
+export function outpostSnapshotCachePath(hqRoot, key) {
+    const digest = createKeyDigest(key);
+    return path.join(hqRoot, CACHE_RELATIVE_PATH, `${digest}.json`);
+}
+export async function getOrFetchOutpostSnapshot(input) {
+    const policy = input.policy ?? {};
+    const now = policy.now ?? Date.now;
+    const ttlMs = policy.ttlMs ?? OUTPOST_SNAPSHOT_CACHE_TTL_MS;
+    const staleLockMs = policy.staleLockMs ?? OUTPOST_SNAPSHOT_CACHE_STALE_LOCK_MS;
+    const lockWaitMs = policy.lockWaitMs ?? LOCK_WAIT_MS;
+    const pollMs = policy.pollMs ?? LOCK_POLL_MS;
+    const sleep = policy.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const filePath = outpostSnapshotCachePath(input.hqRoot, input.key);
+    const cached = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
+    if (cached !== undefined)
+        return cached;
+    const lockPath = `${filePath}.lock`;
+    const token = `${process.pid}:${randomBytes(12).toString("hex")}`;
+    const startedAt = now();
+    const acquireLock = policy.acquireLock ?? createCacheLock;
+    while (true) {
+        try {
+            acquireLock(lockPath, token, now());
+            break;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST") {
+                process.stderr.write(`${JSON.stringify({
+                    event: "lanes.outpost_snapshot_cache_lock_unavailable",
+                    error: typeof code === "string" ? code : "UnknownError",
+                    fallback: "uncached",
+                })}\n`);
+                const value = await input.fetch();
+                if (!input.isValue(value)) {
+                    throw new LanesError("outpost_snapshot_cache_value_invalid", "Outpost snapshot fetch returned an invalid value", { key: input.key });
+                }
+                return value;
+            }
+            if (recoverStaleLock(lockPath, staleLockMs, now()))
+                continue;
+            const afterWait = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
+            if (afterWait !== undefined)
+                return afterWait;
+            if (now() - startedAt >= lockWaitMs) {
+                throw new LanesError("outpost_snapshot_cache_lock_timeout", "Timed out waiting for an Outpost snapshot refresh", { path: lockPath });
+            }
+            await sleep(pollMs);
+        }
+    }
+    try {
+        const afterLock = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
+        if (afterLock !== undefined)
+            return afterLock;
+        const value = await input.fetch();
+        if (!input.isValue(value)) {
+            throw new LanesError("outpost_snapshot_cache_value_invalid", "Outpost snapshot fetch returned an invalid value", { key: input.key });
+        }
+        writeCache(filePath, input.key, value, now());
+        return value;
+    }
+    finally {
+        releaseLock(lockPath, token);
+    }
+}
+function createCacheLock(lockPath, token, nowMs) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const lockFd = fs.openSync(lockPath, "wx", 0o600);
+    try {
+        fs.writeSync(lockFd, `${token}\n${nowMs}\n`);
+    }
+    catch (err) {
+        try {
+            fs.closeSync(lockFd);
+        }
+        catch (closeErr) {
+            process.stderr.write(`lanes snapshot cache: lock close failed: ${errorText(closeErr)}\n`);
+        }
+        releaseLock(lockPath, token);
+        throw err;
+    }
+    fs.closeSync(lockFd);
+}
+function createKeyDigest(key) {
+    // A lane-list query can contain lane ids. Keep raw ids out of cache filenames.
+    return createHash("sha256").update(key).digest("hex");
+}
+function readFreshCache(filePath, key, nowMs, ttlMs, isValue) {
+    let contents;
+    try {
+        contents = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        process.stderr.write(`lanes snapshot cache: read failed: ${errorText(err)}\n`);
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(contents);
+    }
+    catch (err) {
+        process.stderr.write(`lanes snapshot cache: ignoring malformed cache: ${errorText(err)}\n`);
+        return undefined;
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const entry = raw;
+    if (Object.keys(entry).length !== 4 ||
+        entry.schema_version !== CACHE_SCHEMA_VERSION ||
+        entry.key !== key ||
+        !Number.isSafeInteger(entry.cached_at) ||
+        entry.cached_at > nowMs ||
+        nowMs - entry.cached_at >= ttlMs ||
+        !isValue(entry.value))
+        return undefined;
+    return entry.value;
+}
+function writeCache(filePath, key, value, nowMs) {
+    const temporaryPath = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        const fd = fs.openSync(temporaryPath, "wx", 0o600);
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify({
+                schema_version: CACHE_SCHEMA_VERSION,
+                key,
+                cached_at: nowMs,
+                value,
+            })}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporaryPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temporaryPath);
+        }
+        catch (cleanupErr) {
+            if (cleanupErr.code !== "ENOENT") {
+                process.stderr.write(`lanes snapshot cache: temp cleanup failed: ${errorText(cleanupErr)}\n`);
+            }
+        }
+        // The cache is an optimization; a successful, validated remote result stays usable.
+        process.stderr.write(`lanes snapshot cache: write failed: ${errorText(err)}\n`);
+    }
+}
+function recoverStaleLock(lockPath, staleLockMs, nowMs) {
+    let stat;
+    try {
+        stat = fs.statSync(lockPath);
+    }
+    catch (err) {
+        return err.code === "ENOENT";
+    }
+    if (nowMs - stat.mtimeMs <= staleLockMs)
+        return false;
+    const stalePath = `${lockPath}.stale.${process.pid}.${randomBytes(6).toString("hex")}`;
+    try {
+        fs.renameSync(lockPath, stalePath);
+        fs.unlinkSync(stalePath);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return true;
+        throw new LanesError("outpost_snapshot_cache_lock_recovery_failed", `Could not recover a stale Outpost snapshot lock: ${errorText(err)}`, { path: lockPath });
+    }
+}
+function releaseLock(lockPath, token) {
+    try {
+        const contents = fs.readFileSync(lockPath, "utf8");
+        if (contents.split("\n", 1)[0] === token)
+            fs.unlinkSync(lockPath);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            process.stderr.write(`lanes snapshot cache: lock release failed: ${errorText(err)}\n`);
+        }
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=outpost-snapshot-cache.js.map

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

@@ -22,6 +22,8 @@ export interface StoreDeps {
     unlinkSync: typeof fs.unlinkSync;
     existsSync: typeof fs.existsSync;
     readdirSync: typeof fs.readdirSync;
+    /** Bulk readers may provide a pre-indexed conflict-sidecar lookup. */
+    conflictSidecarPathsFor?: (recordPath: string) => readonly string[];
     openSync: typeof fs.openSync;
     closeSync: typeof fs.closeSync;
     fsyncSync: typeof fs.fsyncSync;
@@ -50,6 +52,8 @@ export declare function mergeLaneRecords(live: LaneRecord, sidecars: readonly La
 export declare function mergeQuestionRecords(live: QuestionRecord, sidecars: readonly QuestionRecord[]): QuestionRecord;
 export declare function tryReadLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord | null;
 export declare function readLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord;
+/** Reads every lane while scanning the lane directory for conflict sidecars once. */
+export declare function readAllLanes(hqRoot: string, deps?: StoreDeps): LaneRecord[];
 export declare function tryReadQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord | null;
 export declare function readQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord;
 /** Semver precedence includes prerelease identifiers (for example, rc.2 > rc.1). */

package/dist/lib/lanes/store.js

@@ -954,6 +954,9 @@ export function isConflictSidecarName(recordBasename, name) {
     return name.startsWith(`${recordBasename}.conflict-`);
 }
 function sidecarPathsFor(recordPath, deps) {
+    if (deps.conflictSidecarPathsFor) {
+        return [...deps.conflictSidecarPathsFor(recordPath)];
+    }
     const dir = path.dirname(recordPath);
     const base = path.basename(recordPath);
     if (!deps.existsSync(dir))
@@ -1157,6 +1160,42 @@ export function readLane(hqRoot, laneId, deps = defaultStoreDeps()) {
         throw new LaneNotFoundError("lane", laneId);
     return record;
 }
+/** Reads every lane while scanning the lane directory for conflict sidecars once. */
+export function readAllLanes(hqRoot, deps = defaultStoreDeps()) {
+    const laneIds = listLaneIds(hqRoot, deps);
+    if (laneIds.length === 0)
+        return [];
+    const laneDir = path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR);
+    let names;
+    try {
+        names = deps.readdirSync(laneDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            names = [];
+        else
+            throw err;
+    }
+    const sidecarsByRecord = new Map();
+    for (const name of names) {
+        if (typeof name !== "string")
+            continue;
+        const marker = name.indexOf(".json.conflict-");
+        if (marker < 0 || name.startsWith("."))
+            continue;
+        const recordBasename = name.slice(0, marker + ".json".length);
+        if (!isConflictSidecarName(recordBasename, name))
+            continue;
+        const sidecars = sidecarsByRecord.get(recordBasename) ?? [];
+        sidecars.push(path.join(laneDir, name));
+        sidecarsByRecord.set(recordBasename, sidecars);
+    }
+    const indexedDeps = {
+        ...deps,
+        conflictSidecarPathsFor: (recordPath) => sidecarsByRecord.get(path.basename(recordPath)) ?? [],
+    };
+    return laneIds.map((laneId) => readLane(hqRoot, laneId, indexedDeps));
+}
 export function tryReadQuestion(hqRoot, questionId, deps = defaultStoreDeps()) {
     const filePath = questionRecordPath(hqRoot, questionId);
     return readMergedRecord(filePath, parseQuestionRecord, mergeQuestionRecords, deps);

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

@@ -562,13 +562,21 @@ export function normalizePersonalRealtimeBundle(raw) {
     }
     if (!topics.dm && typeof r.topic === "string")
         topics.dm = r.topic;
+    const agentInboxTopic = typeof r.agentInboxTopic === "string" ? r.agentInboxTopic.trim() : "";
     const actorUid = (typeof r.principalUid === "string" && /^(?:prs|agt)_[A-Za-z0-9]+$/.test(r.principalUid)
         ? r.principalUid
         : undefined) ||
         actorUidFromPersonalTopic(topics.dm) ||
+        actorUidFromPersonalTopic(agentInboxTopic) ||
         "";
     if (!actorUid)
         throw new Error("contract-2 vend could not derive actorUid");
+    // hq-pro advertises the agent's own inbox topic as a top-level capability.
+    // Keep it only for the exact actor-owned topic; it reuses this personal MQTT
+    // session and never grants the subscriber a topic supplied by another actor.
+    if (actorUid.startsWith("agt_") && agentInboxTopic === `hq/${actorUid}/inbox`) {
+        topics.inbox = agentInboxTopic;
+    }
     // Only keep topics that belong to the vended principal.
     for (const [k, v] of Object.entries(topics)) {
         if (actorUidFromPersonalTopic(v) !== actorUid)

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

@@ -14,6 +14,7 @@ export interface WorkCacheMqtt {
 export interface WorkCacheSubscriber {
     stop: () => Promise<void>;
 }
+export declare const AGENT_INBOX_PUSH_STATE_BASENAME = "agent-inbox-push.json";
 export declare function startWorkCacheSubscriber(opts: {
     meshRoot: string;
     fetchCredentials?: PersonalCredentialsFetcher;

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

@@ -2,10 +2,57 @@
  * Contract-2 subscriber for the personal work topic.
  * Owns live-cache.json writes. Presence publish stays on PresenceClient.
  */
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { createPersonalRealtimeFetcher, } from "./credentials.js";
 import { presignIotWssUrl } from "./presign.js";
 import { applyProjectViewPush, parseProjectViewPush } from "./live-cache.js";
 import { backoffDelayMs, RECONNECT_MIN_DELAY_MS } from "./presence.js";
+export const AGENT_INBOX_PUSH_STATE_BASENAME = "agent-inbox-push.json";
+const INBOX_PUSH_HEARTBEAT_MS = 5_000;
+function readInboxWakeSequence(meshRoot, onInfo) {
+    const target = path.join(meshRoot, AGENT_INBOX_PUSH_STATE_BASENAME);
+    try {
+        const info = fs.lstatSync(target);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            onInfo?.("agent inbox push state read ignored (not a regular file)");
+            return 0;
+        }
+        const parsed = JSON.parse(fs.readFileSync(target, "utf8"));
+        if (Number.isSafeInteger(parsed.wakeSequence) && Number(parsed.wakeSequence) >= 0) {
+            return Number(parsed.wakeSequence);
+        }
+        onInfo?.("agent inbox push state read ignored (invalid wake sequence)");
+        return 0;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            const name = error instanceof Error ? error.name : "UnknownError";
+            onInfo?.(`agent inbox push state read failed (${name})`);
+        }
+        return 0;
+    }
+}
+function writeInboxPushState(meshRoot, state) {
+    fs.mkdirSync(meshRoot, { recursive: true, mode: 0o700 });
+    const target = path.join(meshRoot, AGENT_INBOX_PUSH_STATE_BASENAME);
+    const temporary = `${target}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+        fs.chmodSync(temporary, 0o600);
+        fs.renameSync(temporary, target);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (cleanupError) {
+            if (cleanupError.code !== "ENOENT")
+                throw cleanupError;
+        }
+        throw error;
+    }
+}
 export async function startWorkCacheSubscriber(opts) {
     const fetchCredentials = opts.fetchCredentials ??
         (opts.token
@@ -28,10 +75,48 @@ export async function startWorkCacheSubscriber(opts) {
     let reconnectLogged = false;
     let attempt = 0;
     let timer = null;
+    let heartbeatTimer = null;
     let generation = 0;
+    let inboxSubscribed = false;
+    // Carry the sequence forward from the last state marker so a daemon restart
+    // cannot reuse a value the watcher has already consumed.
+    let wakeSequence = readInboxWakeSequence(opts.meshRoot, opts.onInfo);
+    const clearInboxHeartbeat = () => {
+        if (heartbeatTimer !== null)
+            timers.clearTimeout(heartbeatTimer);
+        heartbeatTimer = null;
+    };
+    const persistInboxState = (connected) => {
+        try {
+            writeInboxPushState(opts.meshRoot, {
+                connected,
+                heartbeatAtMs: now().getTime(),
+                wakeSequence,
+            });
+        }
+        catch (error) {
+            const name = error instanceof Error ? error.name : "UnknownError";
+            opts.onInfo?.(`agent inbox push state write failed (${name})`);
+        }
+    };
+    const scheduleInboxHeartbeat = () => {
+        if (stopped || !inboxSubscribed)
+            return;
+        clearInboxHeartbeat();
+        heartbeatTimer = timers.setTimeout(() => {
+            heartbeatTimer = null;
+            if (!stopped && inboxSubscribed) {
+                persistInboxState(true);
+                scheduleInboxHeartbeat();
+            }
+        }, INBOX_PUSH_HEARTBEAT_MS);
+    };
     const connect = async () => {
         if (stopped)
             return;
+        inboxSubscribed = false;
+        clearInboxHeartbeat();
+        persistInboxState(false);
         const gen = ++generation;
         let bundle;
         try {
@@ -44,8 +129,12 @@ export async function startWorkCacheSubscriber(opts) {
         if (stopped || gen !== generation)
             return;
         const topic = bundle.topics.work;
-        if (!topic) {
-            opts.onInfo?.("work cache subscribe skipped: credentials have no work topic");
+        const inboxTopic = bundle.actorUid.startsWith("agt_") &&
+            bundle.topics.inbox === `hq/${bundle.actorUid}/inbox`
+            ? bundle.topics.inbox
+            : undefined;
+        if (!topic && !inboxTopic) {
+            opts.onInfo?.("work cache subscribe skipped: credentials have no supported topic");
             return;
         }
         const url = presignIotWssUrl(bundle.credentials, bundle.iotEndpoint, bundle.region, now());
@@ -60,12 +149,55 @@ export async function startWorkCacheSubscriber(opts) {
             if (stopped || gen !== generation)
                 return;
             reconnectLogged = false;
-            attempt = 0;
-            next.subscribe(topic, { qos: 1 }, () => undefined);
+            let pendingSubscriptions = Number(Boolean(topic)) + Number(Boolean(inboxTopic));
+            let subscriptionFailed = false;
+            const finishSubscription = (err) => {
+                if (err) {
+                    if (subscriptionFailed)
+                        return;
+                    subscriptionFailed = true;
+                    schedule(err);
+                    next.end(true);
+                    return;
+                }
+                if (subscriptionFailed)
+                    return;
+                pendingSubscriptions -= 1;
+                if (pendingSubscriptions === 0)
+                    attempt = 0;
+            };
+            if (topic) {
+                next.subscribe(topic, { qos: 1 }, (err) => finishSubscription(err));
+            }
+            if (inboxTopic) {
+                next.subscribe(inboxTopic, { qos: 1 }, (err) => {
+                    if (stopped || gen !== generation)
+                        return;
+                    if (err) {
+                        inboxSubscribed = false;
+                        clearInboxHeartbeat();
+                        persistInboxState(false);
+                        opts.onInfo?.("agent inbox push subscribe failed");
+                        finishSubscription(err);
+                        return;
+                    }
+                    inboxSubscribed = true;
+                    persistInboxState(true);
+                    scheduleInboxHeartbeat();
+                    finishSubscription();
+                });
+            }
         });
         next.on("message", (_topic, payload) => {
             if (stopped || gen !== generation)
                 return;
+            if (inboxTopic && _topic === inboxTopic && inboxSubscribed) {
+                // A topic message is a doorbell only. Never parse, persist, or log its
+                // content; the authenticated inbox GET remains the source of truth.
+                wakeSequence += 1;
+                persistInboxState(true);
+                return;
+            }
             if (_topic !== topic)
                 return;
             const push = parseProjectViewPush(payload);
@@ -79,11 +211,14 @@ export async function startWorkCacheSubscriber(opts) {
         next.on("close", () => {
             if (stopped || gen !== generation)
                 return;
+            inboxSubscribed = false;
+            clearInboxHeartbeat();
+            persistInboxState(false);
             schedule();
         });
     };
     const schedule = (err) => {
-        if (stopped)
+        if (stopped || timer !== null)
             return;
         if (!reconnectLogged) {
             reconnectLogged = true;
@@ -106,6 +241,9 @@ export async function startWorkCacheSubscriber(opts) {
             generation += 1;
             if (timer !== null)
                 timers.clearTimeout(timer);
+            clearInboxHeartbeat();
+            inboxSubscribed = false;
+            persistInboxState(false);
             const current = client;
             client = null;
             if (!current)

package/dist/lib/policy-validator.d.ts

@@ -0,0 +1,2 @@
+export declare function policyValidatorDiagnostic(content: string, filePath: string, env: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=policy-validator.d.ts.map