@indigoai-us/hq-cli 5.342.11 → 5.342.13

package/dist/lib/lanes/keep-alive-audit.d.ts

@@ -1,8 +1,9 @@
-type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "keep_alive_off" | "waiting";
+type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "work_triggered" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "keep_alive_off" | "waiting";
 interface KeepAliveAuditRestart {
     at: string | null;
     trigger: string;
     caller: string | null;
+    workerEvent?: boolean;
 }
 interface KeepAliveAuditRow {
     lane: string;
@@ -13,6 +14,8 @@ interface KeepAliveAuditRow {
     due_at: string;
     due_reason: "next_check_at" | "backoff";
     restart: KeepAliveAuditRestart | null;
+    blocked_outcome?: "woken" | "skipped";
+    blocked_outcome_reason?: string;
     verdict: KeepAliveAuditVerdict;
 }
 interface KeepAliveAuditSummary {
@@ -41,6 +44,7 @@ export interface KeepAliveAuditResult {
 export interface StopEnvelope {
     name: string;
     mtimeMs: number;
+    decision: "done" | "blocked";
     nextCheckAt?: string;
 }
 export declare function readStopEnvelopes(hqRoot: string, laneId: string): {

package/dist/lib/lanes/keep-alive-audit.js

@@ -1,11 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS } from "./keep-alive.js";
+import { LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS, LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS } from "./keep-alive.js";
 import { LanesError } from "./errors.js";
 import { laneRunDir } from "./spawn.js";
 import { compareEnvelopeNames } from "./envelope-sequence.js";
 import { listQuestionIds, readAllLanes, tryReadQuestion } from "./store.js";
-function readDoneClassifications(hqRoot, laneId) {
+import { isIsoDateTime } from "./types.js";
+function readTerminalClassifications(hqRoot, laneId) {
     const root = fs.realpathSync(hqRoot);
     const watcherLog = path.join(laneRunDir(root, laneId), "logs", "watcher.out");
     if (!withinRoot(root, watcherLog)) {
@@ -28,23 +29,23 @@ function readDoneClassifications(hqRoot, laneId) {
             return [];
         throw err;
     }
-    const atTimes = [];
+    const classifications = [];
     for (const line of text.split(/\r?\n/)) {
         if (!line.includes('"classification"'))
             continue;
         try {
             const value = JSON.parse(line);
-            if (!isRecord(value) || value.state !== "done")
+            if (!isRecord(value) || (value.state !== "done" && value.state !== "blocked"))
                 continue;
             const at = parseTime(value.at);
             if (at !== undefined)
-                atTimes.push(at);
+                classifications.push({ at, state: value.state });
         }
         catch (err) {
             throw new LanesError("keep_alive_audit_event_invalid", `Cannot parse lane watcher classification in ${watcherLog}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: laneId, path: watcherLog });
         }
     }
-    return atTimes.sort((a, b) => a - b);
+    return classifications.sort((a, b) => a.at - b.at);
 }
 const KEEP_ALIVE_ON_TIME_TOLERANCE_MS = 60_000;
 const KEEP_ALIVE_NOT_RESTARTED_GRACE_MS = 5 * 60_000;
@@ -55,6 +56,7 @@ const VERDICTS = [
     "late",
     "early_wake",
     "message_wake",
+    "work_triggered",
     "self_wake",
     "early_by_keep_alive",
     "restarted_untimed",
@@ -68,6 +70,50 @@ function parseTime(value) {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+function readLaneWorkerResumeEvents(hqRoot, laneId) {
+    const root = fs.realpathSync(hqRoot);
+    const eventsPath = path.join(laneRunDir(root, laneId), "watcher", "events.jsonl");
+    if (!withinRoot(root, eventsPath)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher event path escapes the HQ root for ${laneId}`, { lane_id: laneId });
+    }
+    let text;
+    try {
+        const stat = fs.lstatSync(eventsPath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane watcher events must be a regular file: ${eventsPath}`, { lane_id: laneId, path: eventsPath });
+        }
+        const realPath = fs.realpathSync(eventsPath);
+        if (!withinRoot(root, realPath)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher event file escapes the HQ root for ${laneId}`, { lane_id: laneId, path: eventsPath });
+        }
+        text = fs.readFileSync(realPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const events = [];
+    for (const [index, line] of text.split(/\r?\n/).entries()) {
+        if (!line.trim())
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(value) || value.event !== "lane_worker_resumed")
+            continue;
+        const at = parseTime(value.resumed_at);
+        if (at === undefined || typeof value.reason !== "string" || !value.reason.trim()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane worker resume event has invalid timing or reason: ${eventsPath}:${index + 1}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
+        }
+        events.push({ at, reason: value.reason, caller: typeof value.caller === "string" ? value.caller : null });
+    }
+    return events.sort((a, b) => a.at - b.at);
+}
 function iso(ms) {
     return new Date(ms).toISOString();
 }
@@ -116,11 +162,15 @@ export function readStopEnvelopes(hqRoot, laneId) {
         if (!isRecord(raw) || raw.schema_version !== "hq-lane-envelope.v1") {
             throw new LanesError("keep_alive_audit_envelope_invalid", `Lane envelope is not hq-lane-envelope.v1: ${file}`, { lane_id: laneId, path: file });
         }
-        if (raw.decision !== "done" || raw.story_complete !== false)
+        const doneStop = raw.decision === "done" && raw.story_complete === false;
+        const blockedStop = raw.decision === "blocked" && typeof raw.next_check_at === "string" &&
+            isIsoDateTime(raw.next_check_at) && Date.parse(raw.next_check_at) > stat.mtimeMs;
+        if (!doneStop && !blockedStop)
             continue;
         stops.push({
             name,
             mtimeMs: stat.mtimeMs,
+            decision: blockedStop ? "blocked" : "done",
             ...(typeof raw.next_check_at === "string" ? { nextCheckAt: raw.next_check_at } : {}),
         });
     }
@@ -176,19 +226,20 @@ function readKeepAliveResumeEvents(hqRoot, laneId) {
         if (nextEligibleAt === undefined) {
             throw new LanesError("keep_alive_audit_event_invalid", `Keep-alive resume event has invalid timing fields: ${eventsPath}:${index + 1}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
         }
-        const reason = value.reason === "pending_work" || value.reason === "next_check_at_due" || value.reason === "backoff"
-            ? value.reason
-            : undefined;
+        const reason = typeof value.reason === "string" ? value.reason : undefined;
         events.push({ at, nextEligibleAt, ...(reason === undefined ? {} : { reason }) });
     }
     return events.sort((a, b) => a.at - b.at);
 }
 function dueTime(stop, resumeEvents) {
+    const nextCheck = parseTime(stop.nextCheckAt);
+    if (stop.decision === "blocked" && nextCheck !== undefined && nextCheck > stop.mtimeMs) {
+        return { at: Math.min(nextCheck, stop.mtimeMs + LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS), reason: "next_check_at" };
+    }
     const previousResume = resumeEvents.filter((event) => event.at <= stop.mtimeMs).at(-1);
     const terminalPlusBackoff = stop.mtimeMs + LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS;
     let due = Math.max(terminalPlusBackoff, previousResume?.nextEligibleAt ?? 0);
     let reason = "backoff";
-    const nextCheck = parseTime(stop.nextCheckAt);
     if (nextCheck !== undefined && nextCheck > stop.mtimeMs) {
         due = Math.max(due, Math.min(nextCheck, stop.mtimeMs + MAX_NEXT_CHECK_DELAY_MS));
         reason = "next_check_at";
@@ -286,7 +337,50 @@ function laneWasKeepAliveOffAtStop(lane, stoppedAt) {
     const optedInAt = parseTime(lane.keep_alive_opted_in_at);
     return optedInAt === undefined || optedInAt > stoppedAt;
 }
-function firstRestartAfter(lane, stop, nextEnvelopeMs) {
+function blockedKeepAliveOutcome(lane, stop, nextEnvelopeMs) {
+    const terminalAt = lane.last_envelope?.ref === `envelopes/${stop.name}`
+        ? parseTime(lane.last_envelope.at)
+        : undefined;
+    const candidates = (lane.status_gate_history ?? []).flatMap((entry) => {
+        if (entry.event !== "keep_alive_blocked_resumed" && entry.event !== "keep_alive_blocked_skipped")
+            return [];
+        const at = parseTime(entry.at);
+        const terminal = parseTime(entry.terminal_at);
+        if (at === undefined || terminal === undefined)
+            return [];
+        if (nextEnvelopeMs !== undefined && at >= nextEnvelopeMs)
+            return [];
+        const sameStop = terminalAt !== undefined
+            ? terminal === terminalAt
+            : Math.abs(terminal - stop.mtimeMs) <= 10 * 60_000;
+        if (!sameStop)
+            return [];
+        if (entry.event === "keep_alive_blocked_skipped" && entry.reason !== "flag_off")
+            return [];
+        return [{
+                status: entry.event === "keep_alive_blocked_resumed" ? "woken" : "skipped",
+                ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+                at: entry.at,
+                atMs: at,
+            }];
+    });
+    const latest = candidates.sort((left, right) => right.atMs - left.atMs)[0];
+    if (!latest)
+        return undefined;
+    return { status: latest.status, ...(latest.reason === undefined ? {} : { reason: latest.reason }), at: latest.at };
+}
+function firstRestartAfter(lane, stop, nextEnvelopeMs, workerResumeEvents) {
+    const recordedWorkerResume = workerResumeEvents
+        .filter((event) => event.at > stop.mtimeMs && (nextEnvelopeMs === undefined || event.at < nextEnvelopeMs))
+        .sort((a, b) => a.at - b.at)[0];
+    if (recordedWorkerResume !== undefined) {
+        return {
+            at: iso(recordedWorkerResume.at),
+            trigger: recordedWorkerResume.reason,
+            caller: recordedWorkerResume.caller,
+            workerEvent: true,
+        };
+    }
     const restart = (lane.resume_history ?? [])
         .map((entry) => ({ entry, at: parseTime(entry.at) }))
         .filter(({ entry, at }) => at !== undefined && at > stop.mtimeMs && (nextEnvelopeMs === undefined || at < nextEnvelopeMs) && typeof entry.trigger === "string")
@@ -329,6 +423,14 @@ function classifyVerdict(input) {
     if (restart?.trigger === "unknown" && laneWasKeepAliveOffAtStop(lane, input.stoppedAt))
         return "keep_alive_off";
     if (restart) {
+        if (restart.trigger === "pending_work" || restart.trigger === "watcher" || restart.trigger === "monitor_event")
+            return "work_triggered";
+        const workEvidenceEnd = input.nextEnvelopeAt ?? Number.POSITIVE_INFINITY;
+        const triggeredWork = restart.workerEvent !== true && input.resumeEvents
+            .filter((event) => event.at > input.stoppedAt && event.at < workEvidenceEnd && event.at <= (restart.at === null ? Number.POSITIVE_INFINITY : Date.parse(restart.at)))
+            .some((event) => event.reason === "pending_work" || event.reason === "watcher" || event.reason === "monitor_event");
+        if (triggeredWork)
+            return "work_triggered";
         if (restart.at === null)
             return "restarted_untimed";
         const restartAt = Date.parse(restart.at);
@@ -336,12 +438,14 @@ function classifyVerdict(input) {
             return "self_wake";
         if (restart.trigger === "message" || restart.trigger === "answered_questions")
             return "message_wake";
-        if (restart.trigger === "keep_alive") {
+        if (restart.trigger === "keep_alive" || restart.trigger === "next_check_at_due" || restart.trigger === "backoff") {
             const event = input.resumeEvents
                 .filter((candidate) => candidate.at > input.stoppedAt && candidate.at <= restartAt + 2 * 60_000)
                 .sort((left, right) => Math.abs(left.at - restartAt) - Math.abs(right.at - restartAt))[0];
             if (event?.reason === "pending_work")
-                return "message_wake";
+                return "work_triggered";
+            if (event?.reason === "watcher" || event?.reason === "monitor_event")
+                return "work_triggered";
             if (event?.reason === undefined &&
                 (hasDeliveredDropboxEvidence(input.hqRoot, lane.lane_id, input.stoppedAt, restartAt) ||
                     hasMessageResumeEvidence(lane, input.stoppedAt, restartAt) ||
@@ -384,15 +488,19 @@ export function buildKeepAliveAudit(input) {
         try {
             const { allMtimes, stops } = readStopEnvelopes(input.hqRoot, lane.lane_id);
             const keepAliveResumeEvents = readKeepAliveResumeEvents(input.hqRoot, lane.lane_id);
-            const doneClassifications = readDoneClassifications(input.hqRoot, lane.lane_id);
+            const laneWorkerResumeEvents = readLaneWorkerResumeEvents(input.hqRoot, lane.lane_id);
+            const terminalClassifications = readTerminalClassifications(input.hqRoot, lane.lane_id);
             for (const stop of stops) {
                 if (stop.mtimeMs < sinceMs || stop.mtimeMs > nowMs)
                     continue;
-                if (!doneClassifications.some((at) => at >= stop.mtimeMs && at - stop.mtimeMs <= 10 * 60_000))
+                if (!terminalClassifications.some((classification) => classification.state === stop.decision && classification.at >= stop.mtimeMs && classification.at - stop.mtimeMs <= 10 * 60_000))
                     continue;
                 const nextEnvelopeMs = allMtimes.find((mtime) => mtime > stop.mtimeMs);
-                const restart = firstRestartAfter(lane, stop, nextEnvelopeMs);
+                const blockedOutcome = stop.decision === "blocked" ? blockedKeepAliveOutcome(lane, stop, nextEnvelopeMs) : undefined;
+                const restart = firstRestartAfter(lane, stop, nextEnvelopeMs, laneWorkerResumeEvents);
                 const due = dueTime(stop, keepAliveResumeEvents);
+                const reportBlockedOutcome = blockedOutcome?.status === "woken" ||
+                    (blockedOutcome?.status === "skipped" && due.at <= nowMs);
                 rows.push({
                     lane: lane.lane_id,
                     project: lane.project_id,
@@ -402,7 +510,11 @@ export function buildKeepAliveAudit(input) {
                     due_at: iso(due.at),
                     due_reason: due.reason,
                     restart,
-                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, lane, nowMs, resumeEvents: keepAliveResumeEvents, hqRoot: input.hqRoot }),
+                    ...(reportBlockedOutcome && blockedOutcome ? {
+                        blocked_outcome: blockedOutcome.status,
+                        ...(blockedOutcome.reason === undefined ? {} : { blocked_outcome_reason: blockedOutcome.reason }),
+                    } : {}),
+                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, lane, nowMs, resumeEvents: keepAliveResumeEvents, ...(nextEnvelopeMs === undefined ? {} : { nextEnvelopeAt: nextEnvelopeMs }), hqRoot: input.hqRoot }),
                 });
             }
         }
@@ -449,7 +561,7 @@ export function buildKeepAliveAudit(input) {
     };
 }
 export function formatKeepAliveAuditText(result) {
-    const headings = ["LANE", "PROJECT", "PROFILE", "STOPPED", "NEXT_CHECK", "DUE", "RESTART", "VERDICT"];
+    const headings = ["LANE", "PROJECT", "PROFILE", "STOPPED", "NEXT_CHECK", "DUE", "RESTART", "OUTCOME", "VERDICT"];
     const values = result.rows.map((row) => [
         row.lane,
         row.project,
@@ -458,6 +570,7 @@ export function formatKeepAliveAuditText(result) {
         row.next_check_at ?? "—",
         row.due_at,
         row.restart ? `${row.restart.at ?? "untimed"} ${row.restart.trigger}${row.restart.caller ? ` (${row.restart.caller})` : ""}` : "—",
+        row.blocked_outcome === "woken" ? "woken" : row.blocked_outcome === "skipped" ? `due, not woken: ${(row.blocked_outcome_reason ?? "unknown").replaceAll("_", " ")}` : "—",
         row.verdict,
     ]);
     const widths = headings.map((heading, index) => Math.max(heading.length, ...values.map((row) => row[index].length)));

package/dist/lib/lanes/reconcile.js

@@ -27,8 +27,9 @@ import { checkLaneDiskSpace, configuredCodexRolloutHomes, lowDiskGuardEnabledFor
 import { laneCompanyUidSource, resolveLaneCompany } from "./lane-company.js";
 import { appendDropboxMessage } from "./dropbox.js";
 import { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG, listHostProcesses, runRunawayToolGuard, RUNAWAY_TOOL_GUARD_FLAG, } from "./runaway-tool-guard.js";
-import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS, LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
+import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS, LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveNextCheckAtMs, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
+import { isIsoDateTime } from "./types.js";
 import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { SILENCE_MS, appendWatcherEvent, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
@@ -2252,6 +2253,9 @@ async function resumeBlockedKeepAlive(hqRoot, lane, questions, summary, deps, no
     }
     const key = keepAliveCompanyKey(company);
     if (keepAliveFlags.get(key) !== true || blockedFlags.get(key) !== true) {
+        if (keepAliveFlags.get(key) === true && blockedFlags.get(key) !== true) {
+            recordBlockedKeepAliveFlagOff(hqRoot, lane, summary, deps);
+        }
         summary.skipped.push({ kind: "lane", id: lane.lane_id, why: "keep_alive_blocked" });
         return;
     }
@@ -2323,10 +2327,22 @@ async function resumeBlockedKeepAlive(hqRoot, lane, questions, summary, deps, no
         summary.skipped.push({ kind: "lane", id: lane.lane_id, why: "keep_alive_exhausted" });
         return;
     }
-    if (now.getTime() - terminalMs < LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS) {
+    const blockedEnvelope = readLatestEnvelopeRecord(hqRoot, lane.lane_id)?.envelope;
+    const nextCheckValue = blockedEnvelope?.decision === "blocked" ? blockedEnvelope.next_check_at : undefined;
+    const nextCheckValid = typeof nextCheckValue === "string" && isIsoDateTime(nextCheckValue) &&
+        Date.parse(nextCheckValue) > terminalMs;
+    const nextCheckMs = nextCheckValid
+        ? keepAliveNextCheckAtMs(nextCheckValue, now.getTime(), terminalMs)
+        : undefined;
+    if (nextCheckMs !== undefined && nextCheckMs > now.getTime()) {
+        appendBlockedKeepAliveHistory(hqRoot, lane, terminalAt, now.toISOString(), "blocked_grace", deps);
+        return;
+    }
+    if (!nextCheckValid && now.getTime() - terminalMs < LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS) {
         appendBlockedKeepAliveHistory(hqRoot, lane, terminalAt, now.toISOString(), "blocked_grace", deps);
         return;
     }
+    const resumeReason = nextCheckValid ? "next_check_at_due" : "backoff";
     const latest = deps.readKeepAliveRecheckLane?.(hqRoot, lane.lane_id) ?? readLane(hqRoot, lane.lane_id);
     if (latest.version !== lane.version || latest.state !== "blocked" || latest.last_envelope?.decision !== "blocked" || latest.last_envelope.at !== terminalAt)
         return;
@@ -2389,6 +2405,7 @@ async function resumeBlockedKeepAlive(hqRoot, lane, questions, summary, deps, no
             at: now.toISOString(),
             terminal_at: terminalAt,
             resume_queued: true,
+            reason: resumeReason,
         }),
     }), deps.dryRun);
     if (queued.changed) {
@@ -2399,7 +2416,7 @@ async function resumeBlockedKeepAlive(hqRoot, lane, questions, summary, deps, no
                 at: now.toISOString(),
                 attempt: (lane.keep_alive_resume_count ?? 0) + 1,
                 resumed_from: "blocked",
-                reason: "backoff",
+                reason: resumeReason,
                 ...(accountSelection !== undefined
                     ? { account_selection: keepAliveAccountSelectionEvidence(accountSelection) }
                     : {}),
@@ -2407,6 +2424,32 @@ async function resumeBlockedKeepAlive(hqRoot, lane, questions, summary, deps, no
         }
     }
 }
+function recordBlockedKeepAliveFlagOff(hqRoot, lane, summary, deps) {
+    const terminalAt = lane.last_envelope?.at;
+    if (deps.dryRun || lane.last_envelope?.decision !== "blocked" || terminalAt === undefined)
+        return;
+    const envelope = readLatestEnvelopeRecord(hqRoot, lane.lane_id)?.envelope;
+    const nextCheckAt = envelope?.decision === "blocked" ? envelope.next_check_at : undefined;
+    const terminalMs = Date.parse(lane.last_envelope.at);
+    if (typeof nextCheckAt !== "string" || !isIsoDateTime(nextCheckAt) || Date.parse(nextCheckAt) <= terminalMs)
+        return;
+    if (lane.status_gate_history?.some((entry) => entry.event === "keep_alive_blocked_skipped" && entry.terminal_at === terminalAt && entry.reason === "flag_off"))
+        return;
+    try {
+        casLaneIf(hqRoot, lane.lane_id, (current) => current.version === lane.version && current.state === "blocked" && current.last_envelope?.at === terminalAt, (current) => ({
+            ...current,
+            status_gate_history: appendCappedHistory(current.status_gate_history ?? [], {
+                event: "keep_alive_blocked_skipped",
+                at: deps.now().toISOString(),
+                terminal_at: terminalAt,
+                reason: "flag_off",
+            }),
+        }), false);
+    }
+    catch (err) {
+        markDirty(summary, { kind: "lane", id: lane.lane_id, why: `blocked keep-alive skip record failed: ${err instanceof Error ? err.message : String(err)}` });
+    }
+}
 function appendBlockedKeepAliveHistory(hqRoot, lane, terminalAt, at, reason, deps) {
     if (deps.dryRun || lane.status_gate_history?.some((entry) => entry.event === "keep_alive_blocked_grace" && entry.terminal_at === terminalAt && entry.resume_skipped_reason === reason))
         return;

package/dist/lib/lanes/spawn.js

@@ -56,6 +56,70 @@ const PROVIDER_COMMAND = {
     codex: "codex",
     grok: "grok",
 };
+function keepAliveResumeReason(runDir, pendingResume) {
+    if (pendingResume?.keep_alive !== true || typeof pendingResume.at !== "string")
+        return undefined;
+    const eventsPath = path.join(runDir, "watcher", "events.jsonl");
+    let content;
+    try {
+        content = fs.readFileSync(eventsPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "keep_alive";
+        throw err;
+    }
+    for (const line of content.split(/\r?\n/).reverse()) {
+        if (!line.trim())
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            const event = value;
+            if (event.event === "keep_alive_resume" && event.at === pendingResume.at && typeof event.reason === "string") {
+                return event.reason;
+            }
+        }
+    }
+    return "keep_alive";
+}
+function appendLaneWorkerResumeEvent(input) {
+    const eventsPath = path.join(laneRunDir(input.hqRoot, input.laneId), "watcher", "events.jsonl");
+    fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
+    let separator = "";
+    try {
+        const fd = fs.openSync(eventsPath, "r");
+        try {
+            const size = fs.fstatSync(fd).size;
+            if (size > 0) {
+                const lastByte = Buffer.alloc(1);
+                fs.readSync(fd, lastByte, 0, 1, size - 1);
+                if (lastByte[0] !== 0x0a)
+                    separator = "\n";
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    fs.appendFileSync(eventsPath, `${separator}${JSON.stringify({
+        event: "lane_worker_resumed",
+        lane_id: input.laneId,
+        resumed_at: input.resumedAt,
+        reason: input.reason,
+        ...(input.caller === undefined ? {} : { caller: input.caller }),
+        ...(input.turnId === undefined ? {} : { turn_id: input.turnId }),
+    })}\n`, "utf8");
+}
 export function providerCommandOnPath(command, pathEnv) {
     // Test and embedded callers can intentionally omit PATH and delegate lookup
     // to their spawn implementation. A present PATH is authoritative.
@@ -2081,6 +2145,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             trigger.kind === "resume" || trigger.kind === "message"
             ? "user"
             : undefined);
+    const resumeReason = keepAliveResumeReason(runDir, pendingResume) ?? resumeHistoryTrigger;
     let statusGateHeartbeat;
     try {
         statusGateHeartbeat = managerStatusGateHeartbeat(hqRoot, existing, laneTurnId, nowIso);
@@ -2356,6 +2421,14 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 ...(resumeHistoryCaller ? { caller: resumeHistoryCaller } : {}),
             }),
         }));
+        appendLaneWorkerResumeEvent({
+            hqRoot,
+            laneId: lane.lane_id,
+            resumedAt: nowIso,
+            reason: resumeReason,
+            ...(resumeHistoryCaller === undefined ? {} : { caller: resumeHistoryCaller }),
+            turnId: laneTurnId,
+        });
     }
     return laneLaunchResult(readLane(hqRoot, lane.lane_id));
 }
@@ -2670,6 +2743,12 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
             ...(callerLaneId ? { caller: callerLaneId } : {}),
         }),
     }));
+    appendLaneWorkerResumeEvent({
+        hqRoot,
+        laneId: lane.lane_id,
+        resumedAt: startedAt,
+        reason: "envelope_repair",
+    });
     return workerPid;
 }
 export { PROVIDER_HOME_ENV, PROVIDER_COMMAND };

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

@@ -445,10 +445,11 @@ export interface KrFreshnessState {
     stalled_fingerprint?: string;
 }
 export interface KeepAliveBlockedHistoryEntry {
-    event: "keep_alive_blocked_grace" | "keep_alive_blocked_resumed" | "keep_alive_blocked_escalated";
+    event: "keep_alive_blocked_grace" | "keep_alive_blocked_resumed" | "keep_alive_blocked_escalated" | "keep_alive_blocked_skipped";
     at: string;
     terminal_at: string;
     resume_skipped_reason?: "open_question" | "blocked_grace";
+    reason?: "flag_off" | "backoff" | "next_check_at_due";
     resume_queued?: boolean;
 }
 export interface KeepAliveResumeHistoryEntry {

package/dist/utils/package-use-lease.d.ts

@@ -1,3 +1,4 @@
+export declare const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
 export declare class PackageUseUpdatePendingError extends Error {
     constructor(message: string);
 }
@@ -10,11 +11,24 @@ export interface PackageUseLeaseRecord {
     start_time_ms: number;
     hq_version: string;
 }
+export interface PackageUseLeaseHandoff {
+    readonly envValue: string;
+    waitForChild(pid: number, childAlive: () => boolean): Promise<boolean>;
+    cleanup(): void;
+}
 export declare function npmPrefix(root: string, platform?: NodeJS.Platform): string | null;
 export declare function packageUseLeaseDirectory(prefix: string, stateDirectory?: string): string;
 export declare function packageUseUpdateRequestPath(prefix: string, stateDirectory?: string): string;
 declare function waitForUpdateRequest(requestPath: string, timeoutMs: number): void;
 export declare function acquirePackageUseLease(prefix: string, hqVersion: string, stateDirectory?: string): PackageUseLease;
+/**
+ * Create a bounded, per-reexec rendezvous in the current lease directory.
+ * The child confirms readiness only after publishing its own atomic lease.
+ */
+export declare function createPackageUseLeaseHandoff(lease: PackageUseLease, timeoutMs?: number): PackageUseLeaseHandoff;
+export declare function createCurrentPackageUseLeaseHandoff(timeoutMs?: number): PackageUseLeaseHandoff | null;
+/** Publish this process's lease identity to a parent waiting in the same prefix. */
+export declare function publishPackageUseLeaseHandoff(lease: PackageUseLease, env?: NodeJS.ProcessEnv): boolean;
 export declare function acquireCurrentPackageUseLease(): PackageUseLease | null;
 /** Release this process's package-use lease after a long-running command has loaded its package modules. */
 export declare function releaseCurrentPackageUseLease(): void;
@@ -30,6 +44,7 @@ export declare function currentPackageUseUpdatePending(): boolean;
 export declare function currentPackageUseUpdateRequested(): boolean;
 export declare const __test__: {
     waitForUpdateRequest: typeof waitForUpdateRequest;
+    setCurrentPackageUseLease(lease: PackageUseLease | null): void;
 };
 export {};
 //# sourceMappingURL=package-use-lease.d.ts.map