@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/lanes/types.js

@@ -0,0 +1,350 @@
+/**
+ * Lane record, question routing record, envelope, and config types (spec §3,
+ * §4, §5.5, §6.2). Finite sets are string-literal unions plus `const` arrays
+ * so the command layer can validate flags explicitly.
+ */
+import { LanesError, LaneSchemaError } from "./errors.js";
+export const LANE_SCHEMA_VERSION = "hq-lane.v1";
+export const QUESTION_SCHEMA_VERSION = "hq-lane-question.v1";
+export const ENVELOPE_SCHEMA_VERSION = "hq-lane-envelope.v1";
+export const CONFIG_SCHEMA_VERSION = "hq-lanes-config.v1";
+/**
+ * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
+ * check; this is the text handed to a worker on the repair turn (spec §4) so
+ * the two never drift apart in what they name.
+ */
+export const LANE_ENVELOPE_JSON_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "hq-lane-envelope.v1",
+    type: "object",
+    additionalProperties: false,
+    required: ["schema_version", "decision", "summary", "story_status", "artifacts"],
+    properties: {
+        schema_version: { const: "hq-lane-envelope.v1" },
+        decision: { enum: ["done", "ask", "blocked"] },
+        summary: { type: "string", minLength: 1 },
+        questions: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["question", "context", "options"],
+                properties: {
+                    question: { type: "string" },
+                    context: { type: "string" },
+                    options: { type: "array", items: { type: "string" } },
+                    recommended: { type: "string" },
+                },
+            },
+        },
+        story_status: { enum: ["queued", "in_progress", "review", "done"] },
+        artifacts: { type: "array" },
+        blocked_reason: { type: "string" },
+        story_complete: { type: "boolean" },
+        story_complete_reason: { type: "string", minLength: 1 },
+    },
+    allOf: [
+        {
+            if: { properties: { decision: { const: "ask" } } },
+            then: { required: ["questions"], properties: { questions: { minItems: 1 } } },
+            else: { not: { required: ["questions"] } },
+        },
+        {
+            if: { properties: { decision: { const: "blocked" } } },
+            then: { required: ["blocked_reason"], properties: { blocked_reason: { minLength: 1 } } },
+            else: { not: { required: ["blocked_reason"] } },
+        },
+        {
+            if: { required: ["story_complete"], properties: { story_complete: { const: true } } },
+            then: {
+                required: ["story_complete_reason"],
+                properties: { story_status: { const: "done" }, story_complete_reason: { minLength: 1 } },
+            },
+            else: {
+                if: { required: ["story_complete"] },
+                then: {
+                    required: ["story_complete_reason"],
+                    properties: { story_status: { not: { const: "done" } }, story_complete_reason: { minLength: 1 } },
+                },
+                else: { not: { required: ["story_complete_reason"] } },
+            },
+        },
+    ],
+    description: "questions is present and non-empty exactly when decision is ask. " +
+        "blocked_reason is present exactly when decision is blocked. " +
+        "story_complete true requires story_status done; story_complete false requires story_status other than done; " +
+        "story_complete_reason is required whenever story_complete is present.",
+};
+export const LANE_STATES = [
+    "queued",
+    "running",
+    "awaiting_input",
+    "blocked",
+    "done",
+    "failed",
+    "interrupted",
+    "cancelled",
+    "killed",
+];
+/** Exact terminal set from spec §6.7. `awaiting_input` and `blocked` are not terminal. */
+export const TERMINAL_LANE_STATES = [
+    "done",
+    "failed",
+    "interrupted",
+    "cancelled",
+    "killed",
+];
+export const LANE_PROVIDERS = ["claude", "codex", "grok"];
+export const QUEUED_REASONS = ["cap", "queue_position", "throttle", "provider_binary_missing"];
+export const HOST_KINDS = ["local", "outpost"];
+export const SENIOR_KINDS = ["session", "lane", "user"];
+export const ENVELOPE_DECISIONS = ["done", "ask", "blocked"];
+export const STORY_STATUSES = [
+    "queued",
+    "in_progress",
+    "review",
+    "done",
+];
+/**
+ * `expired` is accepted on read for records that already carry it. Spec §9
+ * ageing advances hop with `unanswered_timeout` and never expires a question,
+ * so reconcile (the only writer that may age without an operator) does not
+ * write this value. Kept in the enum so `--status expired` and old files parse.
+ */
+export const QUESTION_STATUSES = [
+    "pending",
+    "answered",
+    "cancelled",
+    "expired",
+];
+export const RAISED_VIA = ["cli", "envelope"];
+export const ROUTING_REASONS = [
+    "asked",
+    "escalated",
+    "audience_ended",
+    "reparented",
+    "unanswered_timeout",
+    "cancelled",
+];
+export const QUESTION_BODY_STORES = ["company", "personal"];
+export const LIVENESS_STATES = ["live", "idle", "ended", "lost"];
+export const HISTORY_CAP = 50;
+const TERMINAL_SET = new Set(TERMINAL_LANE_STATES);
+export function isLaneState(value) {
+    return typeof value === "string" && LANE_STATES.includes(value);
+}
+export function isTerminalLaneState(value) {
+    return typeof value === "string" && TERMINAL_SET.has(value);
+}
+export function isLaneProvider(value) {
+    return (typeof value === "string" &&
+        LANE_PROVIDERS.includes(value));
+}
+export function isSeniorKind(value) {
+    return (typeof value === "string" &&
+        SENIOR_KINDS.includes(value));
+}
+export function isHostKind(value) {
+    return (typeof value === "string" &&
+        HOST_KINDS.includes(value));
+}
+export function isEnvelopeDecision(value) {
+    return (typeof value === "string" &&
+        ENVELOPE_DECISIONS.includes(value));
+}
+export function isQuestionStatus(value) {
+    return (typeof value === "string" &&
+        QUESTION_STATUSES.includes(value));
+}
+export function isLivenessState(value) {
+    return (typeof value === "string" &&
+        LIVENESS_STATES.includes(value));
+}
+export function parseLaneProvider(value) {
+    if (isLaneProvider(value))
+        return value;
+    throw new LanesError("unknown_provider", `Unknown provider ${JSON.stringify(value)}. Accepted: ${LANE_PROVIDERS.join(", ")}`, { accepted: [...LANE_PROVIDERS], value });
+}
+export function parseLaneState(value) {
+    if (isLaneState(value))
+        return value;
+    throw new LanesError("unknown_state", `Unknown lane state ${JSON.stringify(value)}. Accepted: ${LANE_STATES.join(", ")}`, { accepted: [...LANE_STATES], value });
+}
+export function parseQuestionStatus(value) {
+    if (isQuestionStatus(value))
+        return value;
+    throw new LanesError("unknown_status", `Unknown question status ${JSON.stringify(value)}. Accepted: ${QUESTION_STATUSES.join(", ")}`, { accepted: [...QUESTION_STATUSES], value });
+}
+export function parseLivenessState(value) {
+    if (isLivenessState(value))
+        return value;
+    throw new LanesError("unknown_state", `Unknown session liveness state ${JSON.stringify(value)}. Accepted: ${LIVENESS_STATES.join(", ")}`, { accepted: [...LIVENESS_STATES], value });
+}
+export function parseSeniorKind(value) {
+    if (isSeniorKind(value))
+        return value;
+    throw new LanesError("unknown_senior_kind", `Unknown senior kind ${JSON.stringify(value)}. Accepted: ${SENIOR_KINDS.join(", ")}`, { accepted: [...SENIOR_KINDS], value });
+}
+/** The v1 fields that must exist on every durable lane record (spec §3). */
+export const REQUIRED_LANE_RECORD_FIELDS = [
+    "schema_version", "lane_id", "company", "project_id", "story_id", "depth",
+    "senior", "senior_history", "state", "priority", "provider", "host",
+    "version", "created_at", "updated_at", "attribution_history",
+];
+export const LANE_WRITERS = ["creator", "command", "watcher", "reconcile", "spawn"];
+/** Field ownership at the durable-record mutation boundary (spec §10.1). */
+export const LANE_FIELD_WRITERS = {
+    schema_version: ["creator"], lane_id: ["creator"], company: ["creator"],
+    project_id: ["command"], story_id: ["command"], thread_id: ["creator", "command"],
+    depth: ["command"], senior: ["command"], senior_history: ["command"],
+    state: ["creator", "command", "watcher", "reconcile", "spawn"], queued_reason: ["creator", "command", "spawn", "reconcile"],
+    priority: ["command"], worker: ["creator"], worker_path: ["creator"], worker_pack: ["creator"],
+    provider: ["creator"], account: ["creator", "spawn"], host: ["creator"], origin_host: ["creator"], origin_host_source: ["creator"],
+    version: ["creator"], created_at: ["creator"], updated_at: ["creator"], attribution_history: ["command"],
+    last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn"], effort: ["creator", "spawn"], effort_source: ["creator", "spawn"],
+    last_message_at: ["command"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
+    overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
+    admitted_reason: ["reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], terminal_details: ["command", "spawn"],
+    quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
+    provider_session_id: ["watcher"], provider_session_id_absent: ["watcher"], last_resume: ["spawn"], last_run_usage: ["watcher"], envelope_repair: ["watcher", "reconcile"], last_progress_event_at: ["watcher"],
+};
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new LaneSchemaError(`Expected non-empty string for ${field}`, {
+            field,
+        });
+    }
+    return value;
+}
+export function parseMajorSchema(schemaVersion, expectedPrefix, expectedMajor) {
+    const match = new RegExp(`^${expectedPrefix}\\.v(\\d+)$`).exec(schemaVersion);
+    if (!match) {
+        throw new LaneSchemaError(`Unknown schema_version ${JSON.stringify(schemaVersion)} (expected ${expectedPrefix}.v${expectedMajor})`, { schema_version: schemaVersion, expected: `${expectedPrefix}.v${expectedMajor}` });
+    }
+    const major = Number(match[1]);
+    if (major !== expectedMajor) {
+        throw new LaneSchemaError(`Unsupported ${expectedPrefix} major version ${major} (found ${schemaVersion})`, { schema_version: schemaVersion, major });
+    }
+}
+export function parseLaneEnvelope(raw) {
+    if (!isPlainObject(raw)) {
+        throw new LaneSchemaError("Lane envelope must be a JSON object");
+    }
+    const extra = Object.keys(raw).filter((key) => ![
+        "schema_version",
+        "decision",
+        "summary",
+        "questions",
+        "story_status",
+        "artifacts",
+        "blocked_reason",
+        "story_complete",
+        "story_complete_reason",
+    ].includes(key));
+    if (extra.length > 0) {
+        throw new LaneSchemaError(`Lane envelope rejects unknown properties: ${extra.join(", ")}`, { extra });
+    }
+    const schema_version = requireString(raw.schema_version, "schema_version");
+    parseMajorSchema(schema_version, "hq-lane-envelope", 1);
+    if (!isEnvelopeDecision(raw.decision)) {
+        throw new LaneSchemaError(`Unknown envelope decision ${JSON.stringify(raw.decision)}. Accepted: ${ENVELOPE_DECISIONS.join(", ")}`, { accepted: [...ENVELOPE_DECISIONS], value: raw.decision });
+    }
+    const summary = requireString(raw.summary, "summary");
+    if (typeof raw.story_status !== "string" ||
+        !STORY_STATUSES.includes(raw.story_status)) {
+        throw new LaneSchemaError(`Unknown story_status ${JSON.stringify(raw.story_status)}. Accepted: ${STORY_STATUSES.join(", ")}`, { accepted: [...STORY_STATUSES], value: raw.story_status });
+    }
+    if (!Array.isArray(raw.artifacts)) {
+        throw new LaneSchemaError("Envelope artifacts must be an array");
+    }
+    const questions = raw.questions;
+    if (raw.decision === "ask") {
+        if (!Array.isArray(questions) || questions.length === 0) {
+            throw new LaneSchemaError('questions must be non-empty when decision is "ask"');
+        }
+    }
+    else if (questions !== undefined) {
+        throw new LaneSchemaError('questions is present exactly when decision is "ask"');
+    }
+    if (raw.decision === "blocked") {
+        if (typeof raw.blocked_reason !== "string" || raw.blocked_reason.length === 0) {
+            throw new LaneSchemaError('blocked_reason is required when decision is "blocked"');
+        }
+    }
+    else if (raw.blocked_reason !== undefined) {
+        throw new LaneSchemaError('blocked_reason is present exactly when decision is "blocked"');
+    }
+    const storyStatus = raw.story_status;
+    let storyComplete;
+    let storyCompleteReason;
+    if (raw.story_complete !== undefined) {
+        if (typeof raw.story_complete !== "boolean") {
+            throw new LaneSchemaError("story_complete must be a boolean", {
+                field: "story_complete",
+            });
+        }
+        if (typeof raw.story_complete_reason !== "string" ||
+            raw.story_complete_reason.trim().length === 0) {
+            throw new LaneSchemaError("story_complete_reason is required when story_complete is present", { field: "story_complete_reason" });
+        }
+        if (raw.story_complete === true && storyStatus !== "done") {
+            throw new LaneSchemaError("story_complete true requires story_status done", {
+                error: "story_complete_status_mismatch",
+                story_complete: true,
+                story_status: storyStatus,
+            });
+        }
+        if (raw.story_complete === false && storyStatus === "done") {
+            throw new LaneSchemaError("story_complete false forbids story_status done", {
+                error: "story_complete_status_mismatch",
+                story_complete: false,
+                story_status: storyStatus,
+            });
+        }
+        storyComplete = raw.story_complete;
+        storyCompleteReason = raw.story_complete_reason.trim();
+    }
+    else if (raw.story_complete_reason !== undefined) {
+        throw new LaneSchemaError("story_complete_reason is present exactly when story_complete is present", { field: "story_complete_reason" });
+    }
+    const envelope = {
+        schema_version: ENVELOPE_SCHEMA_VERSION,
+        decision: raw.decision,
+        summary,
+        story_status: storyStatus,
+        artifacts: raw.artifacts,
+    };
+    if (storyComplete !== undefined) {
+        envelope.story_complete = storyComplete;
+        envelope.story_complete_reason = storyCompleteReason;
+    }
+    if (Array.isArray(questions) && questions.length > 0) {
+        envelope.questions = questions.map((item, index) => {
+            if (!isPlainObject(item)) {
+                throw new LaneSchemaError(`questions[${index}] must be an object`);
+            }
+            const options = item.options;
+            if (!Array.isArray(options) ||
+                options.some((opt) => typeof opt !== "string")) {
+                throw new LaneSchemaError(`questions[${index}].options must be string[]`);
+            }
+            const parsed = {
+                question: requireString(item.question, `questions[${index}].question`),
+                context: requireString(item.context, `questions[${index}].context`),
+                options,
+            };
+            if (item.recommended !== undefined) {
+                parsed.recommended = requireString(item.recommended, `questions[${index}].recommended`);
+            }
+            return parsed;
+        });
+    }
+    if (typeof raw.blocked_reason === "string") {
+        envelope.blocked_reason = raw.blocked_reason;
+    }
+    return envelope;
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=watcher-main.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * 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 { runWatcherLoop } from "./watcher.js";
+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).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);
+    });
+}
+main();
+//# sourceMappingURL=watcher-main.js.map

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

@@ -0,0 +1,216 @@
+/**
+ * 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 { type LaneEnvelope, type LaneRecord, type LaneState } from "./types.js";
+import { type QuotaSignal } from "./quota.js";
+import { type LaneMesh } from "./mesh-events.js";
+import { type EnvelopeRepairSpawnInput } 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;
+/** 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", "classification", "terminal_write", "mesh_event", "mesh_event_failed"];
+/** Terminal reason when the envelope failed to parse after the repair turn (spec §4). */
+export declare const ENVELOPE_INVALID_REASON: "envelope_invalid";
+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;
+}
+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;
+}): TerminalClassification;
+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;
+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;
+    at?: string;
+    quota?: QuotaSignal | 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;
+};
+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 when `envelope` is null. */
+    error: string | null;
+}
+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;
+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;
+}
+/**
+ * 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): string[];
+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 envelope file does not
+ * parse. 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. Anything
+ * else (already attempted, no session id on a resumable provider, spawn
+ * failure): give up with every error collected, and the caller classifies
+ * the lane `failed` with reason `envelope_invalid`.
+ */
+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