@indigoai-us/hq-cli 5.313.0 → 5.314.0

package/dist/lib/lanes/watch.js

@@ -1,249 +0,0 @@
-import { listQuestionIds, readLane, readQuestion, } from "./store.js";
-import { LaneNotFoundError, LanesError } from "./errors.js";
-import { providerSupportsSessionResume } from "./delivery.js";
-import { canResumeDoneKeepAliveLane, hasPendingKeepAliveWork, keepAliveNextCheckAtMs, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, } from "./keep-alive.js";
-import { isTerminalLaneState, } from "./types.js";
-export const DEFAULT_LANE_WATCH_INTERVAL_MS = 5_000;
-export const MAX_LANE_WATCH_INTERVAL_MS = 30_000;
-export const MAX_WATCHED_LANES = 64;
-export const MAX_WATCH_OUTPUT_LINES = 512;
-function defaultSleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function readableError(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-function boundedInterval(intervalMs) {
-    const value = intervalMs ?? DEFAULT_LANE_WATCH_INTERVAL_MS;
-    if (!Number.isFinite(value))
-        return DEFAULT_LANE_WATCH_INTERVAL_MS;
-    return Math.min(MAX_LANE_WATCH_INTERVAL_MS, Math.max(100, Math.floor(value)));
-}
-function validateLaneIds(laneIds) {
-    const unique = [...new Set(laneIds.map((laneId) => laneId.trim()))];
-    if (unique.some((laneId) => laneId.length === 0)) {
-        throw new LanesError("watch_invalid_lane_id", "Lane ids must not be empty");
-    }
-    if (unique.length === 0) {
-        throw new LanesError("watch_no_lanes", "hq lanes watch requires at least one lane id");
-    }
-    if (unique.length > MAX_WATCHED_LANES) {
-        throw new LanesError("watch_too_many_lanes", `hq lanes watch accepts at most ${MAX_WATCHED_LANES} lane ids`, { max: MAX_WATCHED_LANES });
-    }
-    return unique;
-}
-function canResumeKeepAliveLane(hqRoot, lane, nowMs = Date.now()) {
-    if (lane.keep_alive !== true ||
-        lane.keep_alive_opted_in_at === undefined ||
-        !Number.isFinite(Date.parse(lane.keep_alive_opted_in_at)) ||
-        lane.keep_alive_exhausted_at !== undefined ||
-        (lane.keep_alive_resume_count ?? 0) >= LEAD_LANE_KEEP_ALIVE_MAX_RESUMES ||
-        lane.keep_alive_blocked_reason === "retired" ||
-        lane.keep_alive_blocked_reason === "superseded" ||
-        lane.keep_alive_blocked_reason === "retired_list_invalid" ||
-        lane.keep_alive_blocked_reason === "terminal_state" ||
-        !providerSupportsSessionResume(lane.provider) ||
-        !(lane.provider_session_id ?? lane.last_resume?.session_id))
-        return false;
-    if (lane.state === "interrupted") {
-        return lane.terminal_reason === "exited_with_partial_output";
-    }
-    if (lane.state === "done") {
-        const hasPendingWork = hasPendingKeepAliveWork(hqRoot, lane);
-        const nextCheckAtMs = !hasPendingWork
-            ? keepAliveNextCheckAtMs(lane.last_envelope?.next_check_at, nowMs, Date.parse(lane.last_envelope?.at ?? lane.updated_at))
-            : undefined;
-        if (nextCheckAtMs !== undefined && nowMs < nextCheckAtMs)
-            return false;
-        return canResumeDoneKeepAliveLane(lane, { decision: lane.last_envelope?.decision, story_complete: lane.story_complete, next_check_at: lane.last_envelope?.next_check_at }, lane.keep_alive_standing === true && hasPendingWork) &&
-            lane.terminal_reason !== "provider_rejected" &&
-            lane.terminal_reason !== "account_not_logged_in";
-    }
-    return false;
-}
-export async function runLaneWatch(hqRoot, laneIds, deps = {}) {
-    const watchedIds = validateLaneIds(laneIds);
-    const readLaneRecord = deps.readLane ?? readLane;
-    const listQuestions = deps.listQuestionIds ?? listQuestionIds;
-    const readQuestionRecord = deps.readQuestion ?? readQuestion;
-    const sleep = deps.sleep ?? defaultSleep;
-    const writeLine = deps.writeLine ?? ((line) => console.log(line));
-    const writeAccountEvent = deps.writeAccountEvent ?? ((event) => {
-        writeLine(`account_logged_out provider=${event.provider} account=${event.account} host=${event.host.kind}:${event.host.id} lane_ids=${event.lane_ids.join(",")}`);
-    });
-    const writeError = deps.writeError ?? ((line) => process.stderr.write(`${line}\n`));
-    const maxOutputLines = Math.max(1, Math.floor(deps.maxOutputLines ?? MAX_WATCH_OUTPUT_LINES));
-    const intervalMs = boundedInterval(deps.intervalMs);
-    const previousStates = new Map();
-    const previousQuestionStatuses = new Map();
-    const previousAccountLogin = new Map();
-    let polls = 0;
-    let lines = 0;
-    let suppressed = false;
-    const emit = (line) => {
-        if (lines < maxOutputLines - 1) {
-            writeLine(line);
-            lines += 1;
-            return;
-        }
-        if (!suppressed) {
-            writeLine("lane watch: output limit reached; further events suppressed");
-            lines = maxOutputLines;
-            suppressed = true;
-        }
-    };
-    const emitAccountEvent = (event) => {
-        if (lines < maxOutputLines - 1) {
-            writeAccountEvent(event);
-            lines += 1;
-            return;
-        }
-        if (!suppressed) {
-            writeLine("lane watch: output limit reached; further events suppressed");
-            lines = maxOutputLines;
-            suppressed = true;
-        }
-    };
-    const unreadable = (kind, id, err) => {
-        const message = `${kind} ${id}: unreadable record (${readableError(err)})`;
-        writeError(`lane watch: ${message}`);
-        throw new LanesError("watch_record_unreadable", message, {
-            kind,
-            id,
-            cause: readableError(err),
-        });
-    };
-    while (true) {
-        polls += 1;
-        const records = [];
-        for (const laneId of watchedIds) {
-            let record = null;
-            try {
-                record = readLaneRecord(hqRoot, laneId);
-            }
-            catch (err) {
-                unreadable("lane", laneId, err);
-            }
-            if (!record) {
-                unreadable("lane", laneId, new LaneNotFoundError("lane", laneId));
-                continue;
-            }
-            records.push(record);
-            if (previousStates.get(laneId) !== record.state) {
-                emit(`lane ${laneId}: state=${record.state}${isTerminalLaneState(record.state) ? " (terminal)" : ""}`);
-                previousStates.set(laneId, record.state);
-            }
-        }
-        const keepAliveWaiting = new Set();
-        if (deps.keepAliveEnabled !== undefined) {
-            for (const record of records) {
-                if (!isTerminalLaneState(record.state) || !canResumeKeepAliveLane(hqRoot, record))
-                    continue;
-                if (!await deps.keepAliveEnabled(record))
-                    continue;
-                if (canResumeKeepAliveLane(hqRoot, record))
-                    keepAliveWaiting.add(record.lane_id);
-            }
-        }
-        let questionIds = [];
-        try {
-            questionIds = listQuestions(hqRoot);
-        }
-        catch (err) {
-            unreadable("question", "<index>", err);
-        }
-        const watchedSet = new Set(watchedIds);
-        for (const questionId of questionIds) {
-            let record = null;
-            try {
-                record = readQuestionRecord(hqRoot, questionId);
-            }
-            catch (err) {
-                unreadable("question", questionId, err);
-            }
-            if (!record) {
-                unreadable("question", questionId, new LaneNotFoundError("question", questionId));
-                continue;
-            }
-            if (watchedSet.has(record.lane_id) &&
-                previousQuestionStatuses.get(questionId) !== record.status) {
-                emit(`lane ${record.lane_id}: question=${record.question_id} status=${record.status}`);
-            }
-            previousQuestionStatuses.set(questionId, record.status);
-        }
-        if (deps.readAccountStatuses !== undefined) {
-            const accountLanes = records.filter((record) => record.account !== undefined &&
-                (!isTerminalLaneState(record.state) || keepAliveWaiting.has(record.lane_id)));
-            let statuses;
-            try {
-                statuses = await deps.readAccountStatuses(accountLanes);
-            }
-            catch (err) {
-                const message = `account login status: ${readableError(err)}`;
-                writeError(`lane watch: ${message}`);
-                throw new LanesError("watch_account_status_unavailable", message, {
-                    cause: readableError(err),
-                });
-            }
-            const statusLanes = new Map(accountLanes.map((record) => [record.lane_id, record]));
-            const grouped = new Map();
-            const seenLaneIds = new Set();
-            for (const status of statuses) {
-                const lane = statusLanes.get(status.lane_id);
-                if (!lane || lane.provider !== status.provider || lane.account !== status.account ||
-                    lane.host.kind !== status.host.kind || lane.host.id !== status.host.id ||
-                    (status.logged_in !== true && status.logged_in !== false && status.logged_in !== null) ||
-                    seenLaneIds.has(status.lane_id)) {
-                    const message = `malformed account login status for lane ${JSON.stringify(status.lane_id)}`;
-                    writeError(`lane watch: ${message}`);
-                    throw new LanesError("watch_account_status_invalid", message, {
-                        lane_id: status.lane_id,
-                    });
-                }
-                seenLaneIds.add(status.lane_id);
-                const key = JSON.stringify([status.provider, status.account, status.host.kind, status.host.id]);
-                const existing = grouped.get(key);
-                if (existing && existing.status.logged_in !== status.logged_in) {
-                    const message = `conflicting account login statuses for ${status.provider} account ${status.account} on ${status.host.kind}:${status.host.id}`;
-                    writeError(`lane watch: ${message}`);
-                    throw new LanesError("watch_account_status_invalid", message, {
-                        provider: status.provider,
-                        account: status.account,
-                        host: status.host,
-                    });
-                }
-                const group = existing ?? { status, laneIds: new Set() };
-                group.laneIds.add(status.lane_id);
-                grouped.set(key, group);
-            }
-            const missingLane = accountLanes.find((lane) => !seenLaneIds.has(lane.lane_id));
-            if (missingLane) {
-                const message = `account login status is missing for lane ${missingLane.lane_id}`;
-                writeError(`lane watch: ${message}`);
-                throw new LanesError("watch_account_status_invalid", message, {
-                    lane_id: missingLane.lane_id,
-                });
-            }
-            for (const [key, group] of grouped) {
-                const { status } = group;
-                const prior = previousAccountLogin.get(key);
-                if (prior === true && status.logged_in === false) {
-                    emitAccountEvent({
-                        event: "account_logged_out",
-                        provider: status.provider,
-                        account: status.account,
-                        host: status.host,
-                        lane_ids: [...group.laneIds].sort(),
-                    });
-                }
-                if (status.logged_in !== null)
-                    previousAccountLogin.set(key, status.logged_in);
-            }
-        }
-        if (records.every((record) => isTerminalLaneState(record.state) && !keepAliveWaiting.has(record.lane_id))) {
-            return { polls, lines, suppressed };
-        }
-        await sleep(intervalMs);
-    }
-}
-//# sourceMappingURL=watch.js.map

package/dist/lib/lanes/watcher-main.d.ts

@@ -1,11 +0,0 @@
-/**
- * Detached entry for the per-lane watcher. Spawned with
- * `detached: true` from `spawnLaneWorker`; not a session job.
- *
- * Usage: node watcher-main.js <lane-id>
- * Requires HQ_ROOT in the environment.
- */
-import { type EnvelopeRepairDispatchDeps } from "./envelope-repair-dispatch.js";
-import type { WatcherLoopDeps } from "./watcher.js";
-export declare function watcherMainDeps(hqRoot: string, laneId: string, env?: NodeJS.ProcessEnv, repairDispatchDeps?: Pick<EnvelopeRepairDispatchDeps, "spawnSync">): WatcherLoopDeps;
-//# sourceMappingURL=watcher-main.d.ts.map

package/dist/lib/lanes/watcher-main.js

@@ -1,108 +0,0 @@
-/**
- * Detached entry for the per-lane watcher. Spawned with
- * `detached: true` from `spawnLaneWorker`; not a session job.
- *
- * Usage: node watcher-main.js <lane-id>
- * Requires HQ_ROOT in the environment.
- */
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync, realpathSync } from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { runWatcherLoop } from "./watcher.js";
-import { spawnEnvelopeRepairViaCurrentCli, } from "./envelope-repair-dispatch.js";
-import { LanesError } from "./errors.js";
-import { openMeshTransport } from "../mesh/client.js";
-import { CompanySelectionError } from "../../utils/company-selection-error.js";
-export function watcherMainDeps(hqRoot, laneId, env = process.env, repairDispatchDeps = {}) {
-    const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../index.js");
-    return {
-        resolveQuestionActiveCompany,
-        spawnRepair: (root, lane, input) => spawnEnvelopeRepairViaCurrentCli(root, lane, input, { ...repairDispatchDeps, env }),
-        deliverLaneSeniorMessage: async (seniorLaneId, text) => deliverLaneSeniorMessage(cliEntry, seniorLaneId, text),
-        recoverQueuedMessages: async () => {
-            const result = spawnSync(process.execPath, [cliEntry, "lanes", "_recover-queued-messages", laneId], {
-                env,
-                encoding: "utf8",
-                timeout: 120_000,
-            });
-            if (result.error)
-                throw result.error;
-            if (result.status !== 0) {
-                throw new Error(`recovery command exited ${result.status ?? result.signal ?? "without status"}: ${(result.stderr ?? "").trim()}`);
-            }
-        },
-        scheduleTerminalKeepAlive: async ({ laneId: scheduledLaneId, version, dueAt }) => {
-            await new Promise((resolve, reject) => {
-                const child = spawn(process.execPath, [
-                    cliEntry,
-                    "lanes",
-                    "_keep-alive-terminal-trigger",
-                    scheduledLaneId,
-                    String(version),
-                    dueAt,
-                ], {
-                    env,
-                    detached: true,
-                    stdio: "ignore",
-                });
-                child.once("error", reject);
-                child.once("spawn", resolve);
-                child.unref();
-            });
-        },
-    };
-}
-function deliverLaneSeniorMessage(cliEntry, laneId, text) {
-    const result = spawnSync(process.execPath, [cliEntry, "lanes", "message", laneId, "--text", text], {
-        env: process.env,
-        encoding: "utf8",
-        timeout: 120_000,
-    });
-    if (result.error)
-        throw result.error;
-    if (result.status !== 0) {
-        throw new Error(`senior lane message command exited ${result.status ?? result.signal ?? "without status"}`);
-    }
-    let response;
-    try {
-        response = JSON.parse((result.stdout ?? "").trim());
-    }
-    catch {
-        throw new Error("senior lane message command returned invalid JSON");
-    }
-    if (response === null || typeof response !== "object" || Array.isArray(response) ||
-        response.accepted !== true ||
-        response.lane_id !== laneId) {
-        throw new Error("senior lane message command did not confirm acceptance");
-    }
-}
-async function resolveQuestionActiveCompany() {
-    try {
-        const { company } = await openMeshTransport({});
-        return { slug: company.companySlug, uid: company.companyUid };
-    }
-    catch (err) {
-        if (!(err instanceof CompanySelectionError))
-            throw err;
-        throw new LanesError("question_company_unavailable", "Cannot raise a lane question because the active HQ company could not be resolved", {});
-    }
-}
-function main() {
-    const laneId = process.argv[2]?.trim();
-    const hqRoot = process.env.HQ_ROOT?.trim();
-    if (!laneId || !hqRoot) {
-        process.stderr.write("hq lanes watcher: requires lane id argv and HQ_ROOT in the environment\n");
-        process.exit(1);
-    }
-    void runWatcherLoop(hqRoot, laneId, watcherMainDeps(hqRoot, laneId, process.env)).catch((err) => {
-        process.stderr.write(`hq lanes watcher: ${err instanceof Error ? err.message : String(err)}${err instanceof Error && err.stack ? `\n${err.stack}` : ""}\n`);
-        process.exit(1);
-    });
-}
-const invokedEntryPath = process.argv[1] ? path.resolve(process.argv[1]) : undefined;
-const currentModule = realpathSync(fileURLToPath(import.meta.url));
-if (invokedEntryPath && existsSync(invokedEntryPath) && realpathSync(invokedEntryPath) === currentModule) {
-    main();
-}
-//# sourceMappingURL=watcher-main.js.map

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

@@ -1,287 +0,0 @@
-/**
- * Per-lane watcher (spec §5.7).
- *
- * Armed at spawn, detached from the caller. Emits on progress, terminal, and
- * silence (20 minutes with the process still alive). Terminal classification
- * follows spec §5: an envelope decides done/ask/blocked; a process that exits
- * with partial output and no envelope is `interrupted`; silence is never
- * success.
- *
- * Progress has two sources. Output files (worker.out, worker.err,
- * last-message.txt) cover codex and grok, which stream as they work. They do
- * not cover Claude: `claude -p --output-format json` writes nothing until it
- * exits, so a healthy Claude lane used to hit the silence deadline at exactly
- * 20 minutes every time, and a hung one looked identical. The second source
- * is logs/tool-activity.json, which the drain hook rewrites on every
- * PreToolUse call (dropbox.ts). A worker that is working calls tools; a
- * worker that has not called a tool or written output for the whole window
- * is `stalled`, and the watcher says so on the lane record.
- *
- * What this cannot tell apart: a worker hung inside one tool call from a
- * worker running one legitimately long tool call (a 25-minute build); a
- * worker looping on tool calls without making progress from a working one;
- * a model stuck mid-generation with no tool call from one that is writing a
- * long answer. It also depends on the drain hook being registered in the
- * provider home (hooks-install.ts): with no hook there is no touch, and the
- * lane reads as stalled every window, which is the pre-existing behaviour.
- * Distinguishing a hung tool from a slow one needs the provider to report
- * per-call state, which none of the three CLIs expose today. `stalled` is
- * therefore a flag for the senior to look at, never a kill.
- *
- * Queue admission of the next lane when a slot frees is owned by the
- * periodic reconcile pass and is out of scope here.
- */
-import { ENVELOPE_INVALID_REASON, type LaneEnvelope, type LaneCompanyRef, type LaneRecord, type LaneState } from "./types.js";
-import { type QuotaSignal } from "./quota.js";
-import { type ProviderRejection } from "./provider-rejection.js";
-import type { AdmissionHost } from "./admission.js";
-import { type LaneMesh } from "./mesh-events.js";
-import { readLanesRegistryFlag } from "./registry-flag.js";
-import { type EnvelopeRepairSpawnInput, type SpawnLaneDeps } from "./spawn.js";
-/** Spec §5.7: no signal for 20 minutes while the process is still alive. */
-export declare const SILENCE_MS: number;
-export declare const WATCHER_POLL_MS = 5000;
-export declare const ENVELOPE_REPAIR_CONTINUE_TEXT = "continue the task; the previous turn ended without an envelope.";
-/** Synced last_host_report_at cadence. Reconcile dead-host TTL is 20 minutes. */
-export declare const WATCHER_HEARTBEAT_MS: number;
-/**
- * Cap on logs/watcher.out. A decision line is typically under 300 bytes, so
- * 256 KiB holds hundreds of transitions. A stuck lane cannot fill the disk:
- * once the file would exceed this, the oldest complete lines are dropped.
- */
-export declare const WATCHER_OUT_MAX_BYTES: number;
-export declare const WATCHER_DECISION_EVENTS: readonly ["liveness_transition", "silence_deadline", "envelope_observed", "envelope_invalid", "envelope_repair", "envelope_repair_continue", "classification", "terminal_write", "message_recovery", "message_recovery_failed", "message_undeliverable", "mesh_event", "mesh_event_failed"];
-/** Terminal reason when the envelope failed to parse after the repair turn (spec §4). */
-export { ENVELOPE_INVALID_REASON };
-export type WatcherDecisionEvent = (typeof WATCHER_DECISION_EVENTS)[number];
-export declare const WATCHER_SIGNAL_KINDS: readonly ["progress", "terminal", "silence"];
-export type WatcherSignalKind = (typeof WATCHER_SIGNAL_KINDS)[number];
-export interface TerminalClassification {
-    state: Extract<LaneState, "done" | "awaiting_input" | "blocked" | "interrupted" | "failed">;
-    reason?: string;
-}
-export interface WatcherSignal {
-    kind: WatcherSignalKind;
-    at: string;
-    classification?: TerminalClassification;
-}
-export interface WatcherTickInput {
-    nowMs: number;
-    processAlive: boolean;
-    progressed: boolean;
-    lastSignalMs: number;
-    envelope: LaneEnvelope | null;
-    hasPartialOutput: boolean;
-    silenceMs?: number;
-    quota?: QuotaSignal | null;
-    invalidEnvelope?: {
-        errors: string[];
-    } | null;
-    providerRejection?: ProviderRejection | null;
-}
-export interface WatcherTickResult {
-    emit?: WatcherSignal;
-    nextLastSignalMs: number;
-    done: boolean;
-}
-export declare function parseWatcherSignalKind(value: unknown): WatcherSignalKind;
-export declare function classifyLaneExit(input: {
-    envelope: LaneEnvelope | null;
-    hasPartialOutput: boolean;
-    /**
-     * Set when the worker's own result is a 429 or a usage-limit error.
-     * Distinct from a crash: the reason is account_quota_exhausted or
-     * account_model_unavailable, not exited_with_partial_output.
-     */
-    quota?: QuotaSignal | null;
-    /**
-     * Set when the run's envelope file exists but does not parse and no
-     * repair turn remains. Failed, regardless of partial output: the worker
-     * did finish, it just did not honour the contract.
-     */
-    invalidEnvelope?: {
-        errors: string[];
-    } | null;
-    /**
-     * Set when the worker's output stream carries a provider-level turn
-     * failure (codex `turn.failed`, a Claude error result with an HTTP status,
-     * a grok error object). Failed, never interrupted: the provider refused
-     * the turn, so there is nothing to resume and no envelope to repair.
-     */
-    providerRejection?: ProviderRejection | null;
-}): TerminalClassification;
-/**
- * One decision for an exited worker's output. An explicit provider status
- * wins over the quota text heuristics: a 429 from any provider (including
- * codex `turn.failed` and grok error objects, which the claude-shaped quota
- * reader never sees) becomes a quota signal; any other explicit status is a
- * rejection even when its text sounds like a quota message (a 402 "requires
- * usage credits" is a rejection, not a hold). A failure with no status at
- * all is matched against the quota text heuristics first: a status-less
- * "usage limit" / "rate limit" turn.failed still creates the account hold;
- * any other status-less message is a rejection. Only when the stream
- * carries no failure object does the quota reader's own read apply.
- */
-export declare function routeProviderFailure(failure: ProviderRejection | null, readQuota: () => QuotaSignal | null, model: string | undefined, now: Date): {
-    quota: QuotaSignal | null;
-    rejection: ProviderRejection | null;
-};
-export declare function tickWatcher(input: WatcherTickInput): WatcherTickResult;
-export declare function watcherEventsPath(hqRoot: string, laneId: string): string;
-export declare function watcherOutLogPath(hqRoot: string, laneId: string): string;
-export declare function appendCappedLog(filePath: string, line: string, maxBytes?: number): void;
-export declare function writeWatcherDecision(filePath: string, record: Record<string, unknown>, maxBytes?: number): void;
-/** Append a decision to the shared event stream without a read-modify-write. */
-export declare function appendWatcherEvent(filePath: string, record: Record<string, unknown>, appendLine?: (target: string, line: string) => void): void;
-export declare function watcherLastSignalPath(hqRoot: string, laneId: string): string;
-export declare function appendWatcherSignal(hqRoot: string, laneId: string, signal: WatcherSignal): void;
-/**
- * Slot-free notification. The periodic reconcile pass admits the next queued
- * lane; this watcher must not do it. Intentionally empty.
- */
-export declare function notifySlotFreed(_input: {
-    hqRoot: string;
-    provider: LaneRecord["provider"];
-    account?: string;
-}): void;
-export interface ApplyTerminalOpts {
-    envelope?: LaneEnvelope | null;
-    envelopeRef?: string;
-    envelopeValidationErrors?: string[];
-    questionIndexes?: readonly number[];
-    activeCompany?: LaneCompanyRef | null;
-    at?: string;
-    quota?: QuotaSignal | null;
-    /** Written to `terminal_details` with the model and account the run used. */
-    providerRejection?: ProviderRejection | null;
-}
-export declare function stalledReason(silenceMs: number): string;
-/**
- * The consumer of the silence signal. A silence emit on a running lane sets
- * `stalled` on the record so `hq lanes list` and `show` surface it; the next
- * progress emit clears it. Nothing here changes `state`.
- */
-export declare function markLaneStalled(hqRoot: string, laneId: string, at: string, reason: string): LaneRecord;
-export declare function clearLaneStalled(hqRoot: string, laneId: string): LaneRecord;
-export declare function applyTerminalToLane(hqRoot: string, laneId: string, classification: TerminalClassification, opts?: ApplyTerminalOpts): LaneRecord;
-/** Terminal write outcome for emitters: only the CAS winner may publish mesh effects. */
-export declare function applyTerminalToLaneWithResult(hqRoot: string, laneId: string, classification: TerminalClassification, opts?: ApplyTerminalOpts): {
-    record: LaneRecord;
-    changed: boolean;
-    envelope?: LaneEnvelope;
-    classification: TerminalClassification;
-};
-export declare function isPidAlive(pid: number): boolean;
-export interface LatestEnvelope {
-    envelope: LaneEnvelope;
-    ref: string;
-}
-/** The newest envelope file of this run, parsed or not. */
-export interface LatestEnvelopeFile {
-    ref: string;
-    /** Absolute path of the file. */
-    path: string;
-    text: string;
-    envelope: LaneEnvelope | null;
-    /** Parser message, or the missing-slot reason, when `envelope` is null. */
-    error: string | null;
-    /** True when the manifest's expected envelope slot was never created. */
-    missing?: boolean;
-}
-export declare function readLatestEnvelope(hqRoot: string, laneId: string, minName?: string): LaneEnvelope | null;
-/** Valid-only view over `readLatestEnvelopeFile`; an unparseable file reads as absent. */
-export declare function readLatestEnvelopeRecord(hqRoot: string, laneId: string, minName?: string): LatestEnvelope | null;
-/**
- * `minName` is this run's envelope slot (basename from spawn.json). Envelopes
- * that sort before it belong to an earlier run of the same lane and must not
- * classify this exit: a resumed run that dies before writing its own envelope
- * would otherwise be marked done again from the previous one.
- */
-export declare function readLatestEnvelopeFile(hqRoot: string, laneId: string, minName?: string): LatestEnvelopeFile | null;
-/** A descriptor for this run's manifest slot when no envelope file was written. */
-export declare function missingExpectedEnvelopeFile(hqRoot: string, laneId: string, envelopePath: string | undefined): LatestEnvelopeFile | null;
-export interface WatcherLoopDeps {
-    sleep?: (ms: number) => Promise<void>;
-    now?: () => number;
-    isAlive?: (pid: number) => boolean;
-    readStarttime?: (pid: number) => number | null;
-    pollMs?: number;
-    silenceMs?: number;
-    watcherOutPath?: string;
-    watcherOutMaxBytes?: number;
-    /**
-     * Mesh seam (spec §8). Default: `createLaneMesh({ interactive: false })`.
-     * `null` disables emission entirely (tests that are not about mesh).
-     */
-    mesh?: LaneMesh | null;
-    /** Override for `providers.<provider>.progress_event_min_interval_ms`. */
-    progressEventMinIntervalMs?: number;
-    /** Bound a hung mesh request so watcher liveness polling continues. */
-    meshRequestTimeoutMs?: number;
-    /** Spec §4 repair spawn. Default: `spawnEnvelopeRepair`. */
-    spawnRepair?: (hqRoot: string, lane: LaneRecord, input: EnvelopeRepairSpawnInput) => number;
-    /** Rebind and respawn after a provider quota or authentication refusal. */
-    retryAccount?: (hqRoot: string, lane: LaneRecord, reason: "usage_limit" | "account_unavailable") => LaneRecord | Promise<LaneRecord>;
-    /** Shared process/Outpost identity used by command admission and watcher retries. */
-    resolveAdmissionHost?: () => AdmissionHost;
-    /** Spawn seams for account retry; host scope is supplied by the resolver above. */
-    retrySpawnDeps?: Omit<SpawnLaneDeps, "admissionHost">;
-    /** Active-company fallback when an unscoped lane asks from its envelope. */
-    resolveQuestionActiveCompany?: () => Promise<LaneCompanyRef>;
-    /** Resume an atomically queued inbox after this watcher wins terminal CAS. */
-    recoverQueuedMessages?: (lane: LaneRecord) => Promise<void>;
-    /** Deliver a lane-senior escalation through the normal lane-message router. */
-    deliverLaneSeniorMessage?: (seniorLaneId: string, text: string) => Promise<void>;
-    /** Test seam; production reads the company-scoped hq-flags row. */
-    readBlockerFreshnessFlag?: typeof readLanesRegistryFlag;
-    /** Test seam; production reads the company-scoped hq-flags row. */
-    readKrFreshnessFlag?: typeof readLanesRegistryFlag;
-    /** Test seam; production reads the company-scoped hq-flags row. */
-    readEnvelopeRepairContinueFlag?: typeof readLanesRegistryFlag;
-    /** Test seam; production reads the company-scoped hq-flags row. */
-    readTerminalKeepAliveFlag?: typeof readLanesRegistryFlag;
-    /** Schedule an immediate reconcile check for the terminal lane version. */
-    scheduleTerminalKeepAlive?: (input: {
-        laneId: string;
-        version: number;
-        terminalAt: string;
-        dueAt: string;
-    }) => Promise<void>;
-}
-/**
- * Wrap one mesh call. A failed emit is logged as `mesh_event_failed` with
- * the event name and the error message, and never propagates: the lane's
- * state is decided by the envelope and the process, not by the network.
- */
-export declare function emitMeshSoft(event: string, logDecision: (record: Record<string, unknown>) => void, at: string, fn: (signal: AbortSignal) => Promise<void>, timeoutMs?: number): Promise<boolean>;
-/** Question ids an ask envelope raised, as `raiseEnvelopeQuestions` mints them. */
-export declare function envelopeQuestionIds(laneId: string, envelopeRef: string, envelope: LaneEnvelope, questionIndexes?: readonly number[]): string[];
-/** Detached and synchronous classifiers share one process-identity claim. */
-export declare function runWatcherLoop(hqRoot: string, laneId: string, deps?: WatcherLoopDeps): Promise<void>;
-export type EnvelopeRepairDecision = {
-    action: "spawned";
-} | {
-    action: "give_up";
-    errors: string[];
-};
-/**
- * Spec §4 repair decision for an exited worker whose expected envelope is
- * invalid or missing. First failure on a resumable provider with a recorded
- * session id: record `envelope_repair` on the lane and spawn the repair turn.
- * A provider with no session resume gets the same single attempt as a fresh
- * turn for invalid files. Anything else (already attempted, no session id on a
- * resumable provider, non-running lane, spawn failure): give up with every
- * error collected. The caller preserves the normal interrupted classification
- * for a missing file and uses `envelope_invalid` only for an existing invalid
- * file.
- */
-export declare function decideEnvelopeRepair(hqRoot: string, laneId: string, latest: LatestEnvelopeFile, nowMs: number, spawnRepair: NonNullable<WatcherLoopDeps["spawnRepair"]>, logDecision: (record: Record<string, unknown>) => void): EnvelopeRepairDecision;
-/** Exported so tests can prove the watcher reads the live record, not spawn env. */
-export declare function laneIdentityFromRecord(hqRoot: string, laneId: string): {
-    lane_id: string;
-    company: LaneRecord["company"];
-    project_id: string;
-    story_id: string;
-    senior: LaneRecord["senior"];
-};
-//# sourceMappingURL=watcher.d.ts.map