@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -0,0 +1,370 @@
+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 { LanesError } from "./errors.js";
+import { laneRunDir } from "./spawn.js";
+import { readAllLanes } from "./store.js";
+function readDoneClassifications(hqRoot, laneId) {
+    const root = fs.realpathSync(hqRoot);
+    const watcherLog = path.join(laneRunDir(root, laneId), "logs", "watcher.out");
+    if (!withinRoot(root, watcherLog)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher log path escapes the HQ root for ${laneId}`, { lane_id: laneId });
+    }
+    let text;
+    try {
+        const stat = fs.lstatSync(watcherLog);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane watcher log must be a regular file: ${watcherLog}`, { lane_id: laneId, path: watcherLog });
+        }
+        const realPath = fs.realpathSync(watcherLog);
+        if (!withinRoot(root, realPath)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher log escapes the HQ root for ${laneId}`, { lane_id: laneId, path: watcherLog });
+        }
+        text = fs.readFileSync(realPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const atTimes = [];
+    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")
+                continue;
+            const at = parseTime(value.at);
+            if (at !== undefined)
+                atTimes.push(at);
+        }
+        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);
+}
+const KEEP_ALIVE_ON_TIME_TOLERANCE_MS = 60_000;
+const KEEP_ALIVE_NOT_RESTARTED_GRACE_MS = 5 * 60_000;
+const LATE_KPI_THRESHOLD_MS = 10 * 60_000;
+const MAX_NEXT_CHECK_DELAY_MS = 24 * 60 * 60_000;
+const VERDICTS = [
+    "on_time",
+    "late",
+    "early_wake",
+    "message_wake",
+    "self_wake",
+    "early_by_keep_alive",
+    "not_restarted",
+    "waiting",
+];
+function parseTime(value) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function withinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function readStopEnvelopes(hqRoot, laneId) {
+    const root = fs.realpathSync(hqRoot);
+    const envelopeDir = path.join(laneRunDir(root, laneId), "envelopes");
+    if (!withinRoot(root, envelopeDir)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane envelope path escapes the HQ root for ${laneId}`, { lane_id: laneId });
+    }
+    let names;
+    try {
+        const realDir = fs.realpathSync(envelopeDir);
+        if (!withinRoot(root, realDir)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane envelope directory escapes the HQ root for ${laneId}`, { lane_id: laneId });
+        }
+        names = fs.readdirSync(realDir).filter((name) => /^\d+\.json$/.test(name)).sort();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { allMtimes: [], stops: [] };
+        throw err;
+    }
+    const allMtimes = [];
+    const stops = [];
+    for (const name of names) {
+        const file = path.join(envelopeDir, name);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_envelope_invalid", `Lane envelope must be a regular file: ${file}`, { lane_id: laneId, path: file });
+        }
+        allMtimes.push(stat.mtimeMs);
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            throw new LanesError("keep_alive_audit_envelope_invalid", `Cannot parse lane envelope ${file}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: laneId, path: file });
+        }
+        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)
+            continue;
+        stops.push({
+            mtimeMs: stat.mtimeMs,
+            ...(typeof raw.next_check_at === "string" ? { nextCheckAt: raw.next_check_at } : {}),
+        });
+    }
+    return { allMtimes: allMtimes.sort((a, b) => a - b), stops: stops.sort((a, b) => a.mtimeMs - b.mtimeMs) };
+}
+function readKeepAliveResumeEvents(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 = [];
+    const lines = text.split(/\r?\n/);
+    for (const [index, line] of lines.entries()) {
+        if (!line.trim())
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch (err) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Cannot parse lane watcher event ${eventsPath}:${index + 1}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
+        }
+        if (!isRecord(value) || value.event !== "keep_alive_resume")
+            continue;
+        const at = parseTime(value.at);
+        if (at === 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 nextEligibleAt = parseTime(value.next_eligible_at);
+        if (nextEligibleAt === undefined && value.resumed_from === "blocked")
+            continue;
+        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;
+        events.push({ at, nextEligibleAt, ...(reason === undefined ? {} : { reason }) });
+    }
+    return events.sort((a, b) => a.at - b.at);
+}
+function dueTime(stop, resumeEvents) {
+    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";
+    }
+    return { at: due, reason };
+}
+function hasDeliveredDropboxEvidence(hqRoot, laneId, stoppedAt, restartAt) {
+    const root = fs.realpathSync(hqRoot);
+    const delivered = path.join(laneRunDir(root, laneId), "dropbox", "delivered");
+    if (!withinRoot(root, delivered)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane delivered dropbox path escapes the HQ root for ${laneId}`, { lane_id: laneId, path: delivered });
+    }
+    let names;
+    try {
+        const stat = fs.lstatSync(delivered);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane delivered dropbox path must be a directory: ${delivered}`, { lane_id: laneId, path: delivered });
+        }
+        const realDir = fs.realpathSync(delivered);
+        if (!withinRoot(root, realDir)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane delivered dropbox path escapes the HQ root for ${laneId}`, { lane_id: laneId, path: delivered });
+        }
+        names = fs.readdirSync(realDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    return names.some((name) => {
+        const file = path.join(delivered, name);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return false;
+        const realFile = fs.realpathSync(file);
+        if (!withinRoot(root, realFile))
+            return false;
+        return stat.mtimeMs >= stoppedAt && stat.mtimeMs <= restartAt + 2 * 60_000;
+    });
+}
+function firstRestartAfter(lane, stop, nextEnvelopeMs) {
+    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")
+        .sort((a, b) => a.at - b.at)[0];
+    if (!restart || restart.at === undefined)
+        return null;
+    return {
+        at: iso(restart.at),
+        trigger: restart.entry.trigger,
+        caller: typeof restart.entry.caller === "string" ? restart.entry.caller : null,
+    };
+}
+function classifyVerdict(input) {
+    const { dueAt, restart, lane, nowMs } = input;
+    if (restart) {
+        const restartAt = Date.parse(restart.at);
+        if (restart.caller === lane.lane_id)
+            return "self_wake";
+        if (restart.trigger === "keep_alive") {
+            const event = input.resumeEvents
+                .filter((candidate) => candidate.at > input.stoppedAt && Math.abs(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";
+            if (event?.reason === undefined && hasDeliveredDropboxEvidence(input.hqRoot, lane.lane_id, input.stoppedAt, restartAt)) {
+                return "message_wake";
+            }
+            const nextCheckAt = parseTime(input.nextCheckAt);
+            if (nextCheckAt !== undefined && nextCheckAt > input.stoppedAt && restartAt < Math.min(nextCheckAt, input.stoppedAt + MAX_NEXT_CHECK_DELAY_MS)) {
+                return "early_by_keep_alive";
+            }
+            if (restartAt < dueAt - KEEP_ALIVE_ON_TIME_TOLERANCE_MS)
+                return "early_by_keep_alive";
+            if (restartAt <= dueAt + KEEP_ALIVE_ON_TIME_TOLERANCE_MS)
+                return "on_time";
+            return "late";
+        }
+        if (restartAt < dueAt)
+            return "early_wake";
+        return "late";
+    }
+    if (lane.state === "done" && nowMs > dueAt + KEEP_ALIVE_NOT_RESTARTED_GRACE_MS)
+        return "not_restarted";
+    return "waiting";
+}
+export function buildKeepAliveAudit(input) {
+    const nowMs = input.now.getTime();
+    const sinceMs = input.since === undefined
+        ? nowMs - 24 * 60 * 60_000
+        : parseTime(input.since);
+    if (sinceMs === undefined || !Number.isFinite(sinceMs)) {
+        throw new LanesError("invalid_since", "--since must be a valid ISO date-time", { since: input.since });
+    }
+    const lanes = readAllLanes(input.hqRoot).filter((lane) => (input.laneId === undefined || lane.lane_id === input.laneId) &&
+        typeof lane.hire_grant === "number" && Number.isFinite(lane.hire_grant) && lane.hire_grant > 0);
+    const rows = [];
+    const errors = [];
+    for (const lane of lanes) {
+        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);
+            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))
+                    continue;
+                const nextEnvelopeMs = allMtimes.find((mtime) => mtime > stop.mtimeMs);
+                const restart = firstRestartAfter(lane, stop, nextEnvelopeMs);
+                const due = dueTime(stop, keepAliveResumeEvents);
+                rows.push({
+                    lane: lane.lane_id,
+                    project: lane.project_id,
+                    profile: lane.worker_profile ?? lane.worker ?? null,
+                    stopped_at: iso(stop.mtimeMs),
+                    next_check_at: stop.nextCheckAt ?? null,
+                    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 }),
+                });
+            }
+        }
+        catch (err) {
+            const auditError = err instanceof LanesError
+                ? err
+                : new LanesError("keep_alive_audit_read_failed", `Unable to read keep-alive audit inputs for ${lane.lane_id}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: lane.lane_id, path: laneRunDir(input.hqRoot, lane.lane_id) });
+            errors.push({
+                lane: lane.lane_id,
+                error: auditError.error,
+                path: typeof auditError.details.path === "string" ? auditError.details.path : laneRunDir(input.hqRoot, lane.lane_id),
+                message: auditError.message,
+            });
+        }
+    }
+    rows.sort((a, b) => a.stopped_at.localeCompare(b.stopped_at) || a.lane.localeCompare(b.lane));
+    const byVerdict = Object.fromEntries(VERDICTS.map((verdict) => [verdict, 0]));
+    let lateOverTenMinutes = 0;
+    for (const row of rows) {
+        byVerdict[row.verdict] += 1;
+        if (row.verdict === "late" && row.restart && Date.parse(row.restart.at) - Date.parse(row.due_at) > LATE_KPI_THRESHOLD_MS) {
+            lateOverTenMinutes += 1;
+        }
+    }
+    return {
+        ok: true,
+        since: iso(sinceMs),
+        rows,
+        summary: {
+            by_verdict: byVerdict,
+            not_restarted: byVerdict.not_restarted,
+            late_over_10m: lateOverTenMinutes,
+            early_wake_by_others: byVerdict.early_wake,
+            self_wake: byVerdict.self_wake,
+            stopped_and_not_restarted_on_their_own: byVerdict.not_restarted + lateOverTenMinutes,
+        },
+        errors,
+    };
+}
+export function formatKeepAliveAuditText(result) {
+    const headings = ["LANE", "PROJECT", "PROFILE", "STOPPED", "NEXT_CHECK", "DUE", "RESTART", "VERDICT"];
+    const values = result.rows.map((row) => [
+        row.lane,
+        row.project,
+        row.profile ?? "—",
+        row.stopped_at,
+        row.next_check_at ?? "—",
+        row.due_at,
+        row.restart ? `${row.restart.at} ${row.restart.trigger}${row.restart.caller ? ` (${row.restart.caller})` : ""}` : "—",
+        row.verdict,
+    ]);
+    const widths = headings.map((heading, index) => Math.max(heading.length, ...values.map((row) => row[index].length)));
+    const tableLine = (row) => row.map((value, index) => value.padEnd(widths[index])).join("  ").trimEnd();
+    const counts = VERDICTS.map((verdict) => `${verdict}=${result.summary.by_verdict[verdict]}`).join(", ");
+    return [
+        tableLine(headings),
+        ...values.map(tableLine),
+        "",
+        `Since ${result.since}; ${counts}`,
+        `not_restarted=${result.summary.not_restarted}, late_over_10m=${result.summary.late_over_10m}, early_wake_by_others=${result.summary.early_wake_by_others}, self_wake=${result.summary.self_wake}`,
+        `Stopped and not restarted on their own: ${result.summary.stopped_and_not_restarted_on_their_own}`,
+        ...result.errors.map((error) => `Error ${error.lane} (${error.error}) at ${error.path}: ${error.message}`),
+    ].join("\n");
+}
+//# sourceMappingURL=keep-alive-audit.js.map

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

@@ -0,0 +1,68 @@
+import { type LaneRecord, type ManagerStatusGateHistoryEntry, type QuestionRecord } from "./types.js";
+export declare const LEAD_LANE_KEEP_ALIVE_FLAG = "lanes.lead-keep-alive";
+export declare const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
+export declare const LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS: number;
+export declare const LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG = "lanes.keep-alive-resume-blocked";
+export declare const LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_DEFAULT_ENABLED = false;
+export declare const LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG = "lanes.keep-alive-immediate-first-resume";
+export declare const LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_DEFAULT_ENABLED = false;
+export declare const LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS = 30000;
+export declare const LEAD_LANE_KEEP_ALIVE_TERMINAL_TRIGGER_FLAG = "lanes.keep-alive-terminal-trigger";
+export declare const LEAD_LANE_KEEP_ALIVE_TERMINAL_TRIGGER_DEFAULT_ENABLED = false;
+export declare const LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS: number;
+/** Missing or unreadable registry values retain the legacy supersession behavior. */
+export declare const LANE_SUPERSESSION_LINEAGE_AWARE_FLAG = "lanes.supersession-lineage-aware";
+export declare const LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED = false;
+/** Missing or unreadable registry values keep rejecting superseded messages. */
+export declare const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG = "lanes.running-superseded-message-delivery";
+export declare const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_DEFAULT_ENABLED = false;
+export declare const LEAD_LANE_KEEP_ALIVE_MAX_RESUMES = 24;
+export declare const LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS: number;
+export declare const LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS: number;
+export type KeepAliveLane = Pick<LaneRecord, "lane_id" | "created_at" | "senior" | "company" | "project_id"> & Partial<Pick<LaneRecord, "mesh_company" | "worker_profile" | "hire_grant" | "provider_session_id" | "last_resume" | "state">>;
+export interface LaneTerminalResumeResult {
+    lane: LaneRecord;
+    resumeQueued: boolean;
+    resumeSkippedReason?: "open_question" | "blocked" | "miss_limit" | "no_provider_session";
+}
+/** Shared resume transition for terminal gate follow-ups. */
+export declare function queueLaneTerminalResume(current: LaneRecord, at: string, resumeText: string, options?: {
+    allowResume?: boolean;
+    mergeExisting?: boolean;
+    allowBlockedResume?: boolean;
+    trigger?: "resume" | "watcher";
+}): LaneTerminalResumeResult;
+/** Persist a manager status miss and queue its one bounded follow-up turn. */
+export declare function queueManagerStatusGateResume(hqRoot: string, laneId: string, entry: Omit<ManagerStatusGateHistoryEntry, "event" | "resume_queued" | "resume_skipped_reason">, resumeText: string): LaneRecord;
+export declare const LEAD_LANE_KEEP_ALIVE_RESUME_TEXT = "Automatic keep-alive resume: your last turn ended with decision done and story_complete false. Continue the open work from where you stopped. End with done only when story_complete is true; if you are waiting, use hq lanes ask or stay in the loop.";
+export declare const LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT = "You ended blocked with no pending question. Record the event you wait on in waiting_on, re-check each blocker, and continue the next unblocked story.";
+export declare const LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT = "Automatic keep-alive resume: your previous turn was interrupted by a provider process exit. Check your last state before continuing. Continue the open work from where you stopped. End with done only when story_complete is true; if you are waiting, use hq lanes ask or stay in the loop.";
+export type KeepAliveBlockedReason = NonNullable<LaneRecord["keep_alive_blocked_reason"]>;
+/** The latest terminal envelope fields used by both watch and reconcile. */
+export interface KeepAliveDoneEnvelope {
+    decision?: string;
+    story_complete?: boolean;
+    next_check_at?: string;
+}
+export type DoneKeepAliveVerdict = "eligible" | "standing_idle" | "story_complete" | "next_check_at";
+export declare function keepAliveNextCheckAtMs(value: unknown, nowMs: number, anchorMs?: number): number | undefined;
+/** Shared done-state policy used by watch, reconcile, and the show command. */
+export declare function doneKeepAliveVerdict(lane: Pick<LaneRecord, "keep_alive_standing">, envelope: KeepAliveDoneEnvelope, hasQueuedWork: boolean, options?: {
+    hasPendingWork?: boolean;
+    nowMs?: number;
+    nextCheckAnchorMs?: number;
+}): DoneKeepAliveVerdict | null;
+export declare function canResumeDoneKeepAliveLane(lane: Pick<LaneRecord, "keep_alive_standing">, envelope: KeepAliveDoneEnvelope, hasQueuedWork: boolean): boolean;
+/** Work signals already persisted for a lane that ended its turn. */
+export declare function hasPendingKeepAliveWork(hqRoot: string, lane: Pick<LaneRecord, "lane_id" | "company" | "pending_resume">, questionRecords?: readonly QuestionRecord[]): boolean;
+/** Undelivered answers that belong to this lane and company. */
+export declare function undeliveredAnsweredQuestions(lane: Pick<LaneRecord, "lane_id" | "company">, questions: readonly QuestionRecord[]): QuestionRecord[];
+export declare function retiredLaneRegistryPath(hqRoot: string): string;
+/** Missing registry means no retired lanes; every present invalid file fails closed. */
+export declare function loadRetiredLaneIds(hqRoot: string): ReadonlySet<string>;
+/** IDs may be stored bare or with an owner-host suffix after an underscore. */
+export declare function isRetiredLaneId(laneId: string, retiredLaneIds: ReadonlySet<string>): boolean;
+export declare function keepAliveSupersededBy<T extends KeepAliveLane>(lane: T, lanes: readonly T[], lineageAware?: boolean, companyForLane?: (lane: T) => T["company"]): T | undefined;
+export declare function keepAliveExclusion<T extends KeepAliveLane>(lane: T, lanes: readonly T[], retiredLaneIds: ReadonlySet<string>, lineageAware?: boolean, companyForLane?: (lane: T) => T["company"]): "retired" | "superseded" | undefined;
+export declare function leadLaneKeepAliveBackoffMs(attempt: number): number;
+//# sourceMappingURL=keep-alive.d.ts.map