@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -0,0 +1,180 @@
+/**
+ * Follow-up delivery decision, per provider and per lane state, in one place.
+ *
+ * Two mechanisms exist. A live provider process drains the drop box on its
+ * next `PreToolUse` event (dropbox.ts). A Claude process is print-and-exit,
+ * so after it exits the only way to deliver is `claude -p --resume <sid>`,
+ * which continues the recorded session and keeps its prompt cache. Codex
+ * (0.155.1) has `codex exec resume <thread-id>`; the id is the `thread_id`
+ * of the `thread.started` event on the `--json` stdout stream, and the same
+ * id comes back on every resumed turn. Grok's CLI (1.0.34) prints a
+ * `sessionId` in its `--single --output-format json` result, and
+ * `grok --single <prompt> --resume <id>` continues that session with the same
+ * id and a warm prompt cache (verified live 2026-09-26: the resumed turn
+ * recalled the earlier turn's tool calls and read 33,792 cached tokens).
+ *
+ * Every dispatch site (`hq lanes message`, spawn, reconcile resume) asks this
+ * module rather than testing provider or state inline. A guard bound at one
+ * site and not another is the defect class this branch has already shipped.
+ */
+import { type LaneProvider, type LaneRecord, type LaneState, type SeniorRef } from "./types.js";
+/** Which providers can continue an exited worker from a recorded session id. */
+export declare const PROVIDER_SESSION_RESUME: Record<LaneProvider, boolean>;
+export declare function providerSupportsSessionResume(provider: LaneProvider): boolean;
+/**
+ * Which providers' sessions can be copied to another account's home before a
+ * resume (move-account.ts). Grok resumes on the account that recorded the
+ * session, but copying its session directory between homes is not proven.
+ */
+export declare const PROVIDER_SESSION_PORTABLE: Record<LaneProvider, boolean>;
+export declare function providerSessionPortable(provider: LaneProvider): boolean;
+export declare function sessionNotPortableMessage(provider: LaneProvider): string;
+/**
+ * States an operator message may resume from, given a session id.
+ *
+ * `done`: the worker finished its brief, wrote a done envelope and exited on
+ * its own. Nothing about the lane says the operator is finished with it; a
+ * follow-up is the normal next step, and the session is intact.
+ *
+ * `blocked`: the worker exited after writing a blocked envelope that names
+ * what it needs. An operator message is usually that missing input. The state
+ * is not terminal (spec §6.7) and nothing stopped the lane deliberately.
+ *
+ * Refused by `hq lanes message`:
+ * `awaiting_input` has its own path, `hq lanes questions answer`, while a
+ * senior may resume it when no answerable pending question remains. `killed` and
+ * `cancelled` were stopped on purpose by the operator; a message must not
+ * silently restart them. `failed` means the run ended without an envelope or
+ * never started; only the lane's senior can explicitly recover it with
+ * `hq lanes resume <lane-id> --from-failed --reason <text>`. `interrupted` exited with
+ * partial output and no envelope, so the lane's state was never closed
+ * cleanly; only the explicit `hq lanes resume` opt-in continues it
+ * (RESUME_COMMAND_STATES). `queued` and `running` take the drop box, not a
+ * resume.
+ */
+export declare const RESUMABLE_LANE_STATES: readonly ["done", "blocked"];
+export type ResumableLaneState = (typeof RESUMABLE_LANE_STATES)[number];
+export declare function isResumableLaneState(state: LaneState): state is ResumableLaneState;
+/**
+ * States `hq lanes resume` continues from. `interrupted` is the one a plain
+ * message refuses: the run ended without closing its state, and continuing
+ * it is a decision the operator makes by name. `done` and `blocked` are here
+ * so the one command covers every exited-with-a-session case.
+ */
+export declare const RESUME_COMMAND_STATES: readonly ["interrupted", "done", "blocked"];
+export type ResumeCommandState = (typeof RESUME_COMMAND_STATES)[number];
+export declare function isResumeCommandState(state: LaneState): state is ResumeCommandState;
+export declare const LANE_DELIVERY_MECHANISMS: readonly ["dropbox", "resume", "none"];
+export type LaneDeliveryMechanism = (typeof LANE_DELIVERY_MECHANISMS)[number];
+/** Additional presentation-only result used by `hq lanes show`. */
+export type LaneShowDeliveryMechanism = LaneDeliveryMechanism | "questions";
+export type DeliveryLane = Pick<LaneRecord, "state" | "provider" | "provider_session_id" | "terminal_reason" | "envelope_repair">;
+/** Only the terminal result of a failed automatic envelope repair is recoverable. */
+export declare function isFailedEnvelopeRepairLane(lane: DeliveryLane): boolean;
+/**
+ * `dropbox`: a process is (or is about to be) alive to drain the inbox.
+ * `resume`: the process has exited, the provider can resume, the state allows
+ * it, and a session id was recorded from the worker's own result.
+ * `none`: nothing can deliver; the caller must refuse and write nothing.
+ */
+export declare function laneDeliveryMechanism(lane: DeliveryLane): LaneDeliveryMechanism;
+export declare function hasRecordedSessionId(lane: Pick<LaneRecord, "provider_session_id">): lane is Pick<LaneRecord, "provider_session_id"> & {
+    provider_session_id: string;
+};
+export declare function deliveryRefusalReason(lane: DeliveryLane): string;
+/** Reasons a resumable provider's exit recorded no session id. Never a fabricated value. */
+export declare const SESSION_ID_ABSENT_REASONS: readonly ["worker_out_missing", "no_result_json", "no_session_id_field", "no_thread_started_event"];
+export type SessionIdAbsentReason = (typeof SESSION_ID_ABSENT_REASONS)[number];
+export interface WorkerRunResult {
+    session_id: string | null;
+    session_id_absent: SessionIdAbsentReason | null;
+    cache_read_input_tokens: number | null;
+    cache_creation_input_tokens: number | null;
+}
+/**
+ * Parse the `claude -p --output-format json` result. stdout is appended
+ * across runs of the same lane, so the last `type: "result"` object is this
+ * run's. Only `session_id` and the two cache counters are read out; the
+ * prompt, the response body and everything else in the payload stay on disk.
+ */
+export declare function parseClaudeResultOutput(text: string): WorkerRunResult;
+/**
+ * Parse the `codex exec --json` event stream. The first event of a run is
+ * `{"type":"thread.started","thread_id":"<uuid>"}`; that id is what
+ * `codex exec resume <id>` takes, and a resumed run emits the same id again.
+ * Usage comes from the last `turn.completed` event: `cached_input_tokens`
+ * is the cache read and `cache_write_input_tokens` the cache creation.
+ * Nothing else on the stream is read out.
+ */
+export declare function parseCodexEventOutput(text: string): WorkerRunResult;
+/**
+ * Parse the `grok --single --output-format json` result. Grok prints one
+ * pretty-printed JSON object (`sessionId`, `usage`, ...) at the end of the
+ * run, so the last top-level object in this run's stdout is the result.
+ * Only `sessionId` and the two cache counters are read out.
+ */
+export declare function parseGrokResultOutput(text: string): WorkerRunResult;
+/** Per-provider stdout parser; null for a provider whose exit carries nothing to record. */
+export declare function parseWorkerRunOutput(provider: LaneProvider, text: string): WorkerRunResult | null;
+/**
+ * Read this run's result from the worker's own stdout. stdout is opened in
+ * append mode across runs, so only bytes past `workerOutOffset` (recorded in
+ * spawn.json at launch) are this run's. Returns null for a provider whose
+ * exit carries nothing to record, so those lanes keep behaving exactly as
+ * before.
+ */
+export declare function readWorkerRunResult(runDir: string, provider: LaneProvider, 
+/** Bytes of worker.out that belong to earlier runs; parsing starts after them. */
+workerOutOffset?: number): WorkerRunResult | null;
+export declare const LAUNCH_TRIGGERS: readonly ["admit", "answered_questions", "message", "resume"];
+export type LaunchTriggerKind = (typeof LAUNCH_TRIGGERS)[number];
+export type LaunchTrigger = {
+    kind: "admit";
+} | {
+    kind: "answered_questions";
+} | {
+    kind: "message";
+    text: string;
+    message_id: string;
+    monitor_event?: true;
+    system_notice?: true;
+} | {
+    /** `hq lanes resume`: the operator's explicit opt-in to continue an exited lane. */
+    kind: "resume";
+    /** Lane state at the moment of the command; recorded as `last_resume.resumed_from`. */
+    from: ResumeCommandState | "failed" | "awaiting_input";
+    allowAwaitingInput?: true;
+    fromFailed?: true;
+    /** Senior that authorized a failed-lane resume, rechecked at the claim CAS. */
+    expectedSenior?: SeniorRef;
+    text?: string;
+    message_id?: string;
+};
+export type LaunchPlan = {
+    mode: "fresh";
+} | {
+    mode: "resume";
+    session_id: string;
+};
+/**
+ * Refusal for `hq lanes resume`, in precedence order: wrong state, provider
+ * without a resume path, no recorded session. Null when the resume can go.
+ */
+export declare function resumeCommandRefusal(lane: DeliveryLane, options?: {
+    allowFailed?: boolean;
+    allowAwaitingInput?: boolean;
+}): {
+    error: "lane_not_resumable" | "resume_unsupported" | "no_provider_session";
+    message: string;
+} | null;
+/**
+ * Decide fresh-vs-resume for a spawn. Admission always starts fresh with the
+ * brief. Answered questions resume the recorded session when the provider
+ * can, else start fresh with the answers file (today's behaviour). An operator
+ * message can only be a resume, and only when `laneDeliveryMechanism` says so.
+ * `hq lanes resume` is also always a resume, gated by `resumeCommandRefusal`.
+ */
+export declare function planLaneLaunch(lane: DeliveryLane, trigger: LaunchTrigger): LaunchPlan;
+/** Lane states a launch may claim `running` from, per trigger. */
+export declare function claimableStatesFor(trigger: LaunchTrigger, lane?: DeliveryLane): readonly LaneState[];
+//# sourceMappingURL=delivery.d.ts.map

package/dist/lib/lanes/delivery.js

@@ -0,0 +1,443 @@
+/**
+ * Follow-up delivery decision, per provider and per lane state, in one place.
+ *
+ * Two mechanisms exist. A live provider process drains the drop box on its
+ * next `PreToolUse` event (dropbox.ts). A Claude process is print-and-exit,
+ * so after it exits the only way to deliver is `claude -p --resume <sid>`,
+ * which continues the recorded session and keeps its prompt cache. Codex
+ * (0.155.1) has `codex exec resume <thread-id>`; the id is the `thread_id`
+ * of the `thread.started` event on the `--json` stdout stream, and the same
+ * id comes back on every resumed turn. Grok's CLI (1.0.34) prints a
+ * `sessionId` in its `--single --output-format json` result, and
+ * `grok --single <prompt> --resume <id>` continues that session with the same
+ * id and a warm prompt cache (verified live 2026-09-26: the resumed turn
+ * recalled the earlier turn's tool calls and read 33,792 cached tokens).
+ *
+ * Every dispatch site (`hq lanes message`, spawn, reconcile resume) asks this
+ * module rather than testing provider or state inline. A guard bound at one
+ * site and not another is the defect class this branch has already shipped.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+import { parseLaneProvider, ENVELOPE_INVALID_REASON, } from "./types.js";
+/** Which providers can continue an exited worker from a recorded session id. */
+export const PROVIDER_SESSION_RESUME = {
+    claude: true,
+    codex: true,
+    grok: true,
+};
+export function providerSupportsSessionResume(provider) {
+    return PROVIDER_SESSION_RESUME[parseLaneProvider(provider)];
+}
+/**
+ * Which providers' sessions can be copied to another account's home before a
+ * resume (move-account.ts). Grok resumes on the account that recorded the
+ * session, but copying its session directory between homes is not proven.
+ */
+export const PROVIDER_SESSION_PORTABLE = {
+    claude: true,
+    codex: true,
+    grok: false,
+};
+export function providerSessionPortable(provider) {
+    const parsed = parseLaneProvider(provider);
+    return PROVIDER_SESSION_RESUME[parsed] && PROVIDER_SESSION_PORTABLE[parsed];
+}
+export function sessionNotPortableMessage(provider) {
+    return providerSupportsSessionResume(provider)
+        ? `Provider ${provider} session files are not copied between accounts, so the lane cannot move to another ${provider} account`
+        : `Provider ${provider} has no session resume, so a lane cannot move between its accounts`;
+}
+/**
+ * States an operator message may resume from, given a session id.
+ *
+ * `done`: the worker finished its brief, wrote a done envelope and exited on
+ * its own. Nothing about the lane says the operator is finished with it; a
+ * follow-up is the normal next step, and the session is intact.
+ *
+ * `blocked`: the worker exited after writing a blocked envelope that names
+ * what it needs. An operator message is usually that missing input. The state
+ * is not terminal (spec §6.7) and nothing stopped the lane deliberately.
+ *
+ * Refused by `hq lanes message`:
+ * `awaiting_input` has its own path, `hq lanes questions answer`, while a
+ * senior may resume it when no answerable pending question remains. `killed` and
+ * `cancelled` were stopped on purpose by the operator; a message must not
+ * silently restart them. `failed` means the run ended without an envelope or
+ * never started; only the lane's senior can explicitly recover it with
+ * `hq lanes resume <lane-id> --from-failed --reason <text>`. `interrupted` exited with
+ * partial output and no envelope, so the lane's state was never closed
+ * cleanly; only the explicit `hq lanes resume` opt-in continues it
+ * (RESUME_COMMAND_STATES). `queued` and `running` take the drop box, not a
+ * resume.
+ */
+export const RESUMABLE_LANE_STATES = ["done", "blocked"];
+export function isResumableLaneState(state) {
+    return RESUMABLE_LANE_STATES.includes(state);
+}
+/**
+ * States `hq lanes resume` continues from. `interrupted` is the one a plain
+ * message refuses: the run ended without closing its state, and continuing
+ * it is a decision the operator makes by name. `done` and `blocked` are here
+ * so the one command covers every exited-with-a-session case.
+ */
+export const RESUME_COMMAND_STATES = ["interrupted", "done", "blocked"];
+export function isResumeCommandState(state) {
+    return RESUME_COMMAND_STATES.includes(state);
+}
+export const LANE_DELIVERY_MECHANISMS = ["dropbox", "resume", "none"];
+/** Only the terminal result of a failed automatic envelope repair is recoverable. */
+export function isFailedEnvelopeRepairLane(lane) {
+    return (lane.state === "failed" &&
+        lane.terminal_reason === ENVELOPE_INVALID_REASON &&
+        lane.envelope_repair?.attempted === true &&
+        lane.envelope_repair.succeeded === false);
+}
+/**
+ * `dropbox`: a process is (or is about to be) alive to drain the inbox.
+ * `resume`: the process has exited, the provider can resume, the state allows
+ * it, and a session id was recorded from the worker's own result.
+ * `none`: nothing can deliver; the caller must refuse and write nothing.
+ */
+export function laneDeliveryMechanism(lane) {
+    if (lane.state === "queued" || lane.state === "running")
+        return "dropbox";
+    if (providerSupportsSessionResume(lane.provider) &&
+        (isResumableLaneState(lane.state) || lane.state === "awaiting_input" || isFailedEnvelopeRepairLane(lane)) &&
+        hasRecordedSessionId(lane)) {
+        return "resume";
+    }
+    return "none";
+}
+export function hasRecordedSessionId(lane) {
+    return (typeof lane.provider_session_id === "string" &&
+        lane.provider_session_id.trim().length > 0);
+}
+export function deliveryRefusalReason(lane) {
+    const state = lane.state;
+    switch (state) {
+        case "queued":
+        case "running":
+            return "";
+        case "awaiting_input":
+            return "Lane is awaiting_input. The worker has exited after writing an ask envelope. Use hq lanes questions answer <question-id>.";
+        case "done":
+        case "blocked": {
+            if (!providerSupportsSessionResume(lane.provider)) {
+                return `Lane is ${state}. Provider ${lane.provider} cannot resume an exited worker; there is no delivery path.`;
+            }
+            if (!hasRecordedSessionId(lane)) {
+                return `Lane is ${state}. No provider session id was recorded from the worker's result, so the session cannot be resumed.`;
+            }
+            return "";
+        }
+        case "killed":
+        case "cancelled":
+            return `Lane is ${state}. The operator stopped it on purpose; a message does not restart it. Resuming from ${state} needs an explicit opt-in, which does not exist yet.`;
+        case "interrupted":
+            return `Lane is ${state}. The run did not close cleanly and the operator has not decided what to do with it. Resuming from ${state} needs an explicit opt-in: hq lanes resume <lane-id> [--text <message>].`;
+        case "failed":
+            return `Lane is ${state}. A plain message does not restart it. Its senior can resume the recorded session with: hq lanes resume <lane-id> --from-failed --reason <text>.`;
+        default: {
+            const _exhaustive = state;
+            return _exhaustive;
+        }
+    }
+}
+/** Reasons a resumable provider's exit recorded no session id. Never a fabricated value. */
+export const SESSION_ID_ABSENT_REASONS = [
+    "worker_out_missing",
+    "no_result_json",
+    "no_session_id_field",
+    "no_thread_started_event",
+];
+function nonNegativeInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0
+        ? value
+        : null;
+}
+/**
+ * Parse the `claude -p --output-format json` result. stdout is appended
+ * across runs of the same lane, so the last `type: "result"` object is this
+ * run's. Only `session_id` and the two cache counters are read out; the
+ * prompt, the response body and everything else in the payload stay on disk.
+ */
+export function parseClaudeResultOutput(text) {
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = (lines[i] ?? "").trim();
+        if (!line.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const rec = parsed;
+        if (rec.type !== "result")
+            continue;
+        const usage = rec.usage && typeof rec.usage === "object" && !Array.isArray(rec.usage)
+            ? rec.usage
+            : {};
+        const sessionId = typeof rec.session_id === "string" && rec.session_id.trim().length > 0
+            ? rec.session_id.trim()
+            : null;
+        return {
+            session_id: sessionId,
+            session_id_absent: sessionId === null ? "no_session_id_field" : null,
+            cache_read_input_tokens: nonNegativeInt(usage.cache_read_input_tokens),
+            cache_creation_input_tokens: nonNegativeInt(usage.cache_creation_input_tokens),
+        };
+    }
+    return {
+        session_id: null,
+        session_id_absent: "no_result_json",
+        cache_read_input_tokens: null,
+        cache_creation_input_tokens: null,
+    };
+}
+/**
+ * Parse the `codex exec --json` event stream. The first event of a run is
+ * `{"type":"thread.started","thread_id":"<uuid>"}`; that id is what
+ * `codex exec resume <id>` takes, and a resumed run emits the same id again.
+ * Usage comes from the last `turn.completed` event: `cached_input_tokens`
+ * is the cache read and `cache_write_input_tokens` the cache creation.
+ * Nothing else on the stream is read out.
+ */
+export function parseCodexEventOutput(text) {
+    let threadId = null;
+    let usage = {};
+    let sawEvent = false;
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const rec = parsed;
+        if (typeof rec.type !== "string")
+            continue;
+        sawEvent = true;
+        if (rec.type === "thread.started" && threadId === null) {
+            threadId =
+                typeof rec.thread_id === "string" && rec.thread_id.trim().length > 0
+                    ? rec.thread_id.trim()
+                    : null;
+        }
+        else if (rec.type === "turn.completed") {
+            usage =
+                rec.usage && typeof rec.usage === "object" && !Array.isArray(rec.usage)
+                    ? rec.usage
+                    : {};
+        }
+    }
+    return {
+        session_id: threadId,
+        session_id_absent: threadId !== null ? null : sawEvent ? "no_thread_started_event" : "no_result_json",
+        cache_read_input_tokens: nonNegativeInt(usage.cached_input_tokens),
+        cache_creation_input_tokens: nonNegativeInt(usage.cache_write_input_tokens),
+    };
+}
+/**
+ * Parse the `grok --single --output-format json` result. Grok prints one
+ * pretty-printed JSON object (`sessionId`, `usage`, ...) at the end of the
+ * run, so the last top-level object in this run's stdout is the result.
+ * Only `sessionId` and the two cache counters are read out.
+ */
+export function parseGrokResultOutput(text) {
+    const lines = text.split("\n");
+    let sawJson = false;
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        if (!(lines[i] ?? "").startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(lines.slice(i).join("\n").trim());
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        sawJson = true;
+        const rec = parsed;
+        if (!("sessionId" in rec) && !("stopReason" in rec))
+            continue;
+        const usage = rec.usage && typeof rec.usage === "object" && !Array.isArray(rec.usage)
+            ? rec.usage
+            : {};
+        const sessionId = typeof rec.sessionId === "string" && rec.sessionId.trim().length > 0
+            ? rec.sessionId.trim()
+            : null;
+        return {
+            session_id: sessionId,
+            session_id_absent: sessionId === null ? "no_session_id_field" : null,
+            cache_read_input_tokens: nonNegativeInt(usage.cache_read_input_tokens),
+            cache_creation_input_tokens: nonNegativeInt(usage.cache_creation_input_tokens),
+        };
+    }
+    return {
+        session_id: null,
+        session_id_absent: sawJson ? "no_session_id_field" : "no_result_json",
+        cache_read_input_tokens: null,
+        cache_creation_input_tokens: null,
+    };
+}
+/** Per-provider stdout parser; null for a provider whose exit carries nothing to record. */
+export function parseWorkerRunOutput(provider, text) {
+    switch (parseLaneProvider(provider)) {
+        case "claude":
+            return parseClaudeResultOutput(text);
+        case "codex":
+            return parseCodexEventOutput(text);
+        case "grok":
+            return parseGrokResultOutput(text);
+        default:
+            return null;
+    }
+}
+/**
+ * Read this run's result from the worker's own stdout. stdout is opened in
+ * append mode across runs, so only bytes past `workerOutOffset` (recorded in
+ * spawn.json at launch) are this run's. Returns null for a provider whose
+ * exit carries nothing to record, so those lanes keep behaving exactly as
+ * before.
+ */
+export function readWorkerRunResult(runDir, provider, 
+/** Bytes of worker.out that belong to earlier runs; parsing starts after them. */
+workerOutOffset = 0) {
+    if (!providerSupportsSessionResume(provider))
+        return null;
+    const outPath = path.join(runDir, "logs", "worker.out");
+    let text;
+    try {
+        const bytes = fs.readFileSync(outPath);
+        text = bytes.subarray(Math.min(workerOutOffset, bytes.length)).toString("utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                session_id: null,
+                session_id_absent: "worker_out_missing",
+                cache_read_input_tokens: null,
+                cache_creation_input_tokens: null,
+            };
+        }
+        process.stderr.write(`hq lanes: failed to read ${outPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        throw err;
+    }
+    return parseWorkerRunOutput(provider, text);
+}
+export const LAUNCH_TRIGGERS = ["admit", "answered_questions", "message", "resume"];
+/**
+ * Refusal for `hq lanes resume`, in precedence order: wrong state, provider
+ * without a resume path, no recorded session. Null when the resume can go.
+ */
+export function resumeCommandRefusal(lane, options = {}) {
+    if (!isResumeCommandState(lane.state) &&
+        !(options.allowAwaitingInput === true && lane.state === "awaiting_input") &&
+        !isFailedEnvelopeRepairLane(lane) &&
+        !(options.allowFailed === true && lane.state === "failed")) {
+        return {
+            error: "lane_not_resumable",
+            message: `Lane is ${lane.state}. hq lanes resume continues a lane in ${RESUME_COMMAND_STATES.join(", ")}; ${lane.state === "awaiting_input"
+                ? "use hq lanes questions answer <question-id>."
+                : lane.state === "queued"
+                    ? "use hq lanes admit <lane-id>."
+                    : lane.state === "running"
+                        ? "use hq lanes message for a live lane."
+                        : "a lane in this state is not resumed."}`,
+        };
+    }
+    if (!providerSupportsSessionResume(lane.provider)) {
+        return {
+            error: "resume_unsupported",
+            message: `Lane is ${lane.state}. Provider ${lane.provider} cannot resume an exited worker; there is no delivery path.`,
+        };
+    }
+    if (!hasRecordedSessionId(lane)) {
+        return {
+            error: "no_provider_session",
+            message: `Lane is ${lane.state}. No provider session id was recorded from the worker's result, so the session cannot be resumed.`,
+        };
+    }
+    return null;
+}
+/**
+ * Decide fresh-vs-resume for a spawn. Admission always starts fresh with the
+ * brief. Answered questions resume the recorded session when the provider
+ * can, else start fresh with the answers file (today's behaviour). An operator
+ * message can only be a resume, and only when `laneDeliveryMechanism` says so.
+ * `hq lanes resume` is also always a resume, gated by `resumeCommandRefusal`.
+ */
+export function planLaneLaunch(lane, trigger) {
+    switch (trigger.kind) {
+        case "admit":
+            return { mode: "fresh" };
+        case "answered_questions":
+            if (providerSupportsSessionResume(lane.provider) && hasRecordedSessionId(lane)) {
+                return { mode: "resume", session_id: lane.provider_session_id };
+            }
+            return { mode: "fresh" };
+        case "message": {
+            if (laneDeliveryMechanism(lane) !== "resume" || !hasRecordedSessionId(lane)) {
+                throw new LanesError("lane_not_accepting_messages", deliveryRefusalReason(lane) || `Lane is ${lane.state} and cannot be resumed`, { state: lane.state, provider: lane.provider });
+            }
+            return { mode: "resume", session_id: lane.provider_session_id };
+        }
+        case "resume": {
+            const refusal = resumeCommandRefusal(lane, {
+                allowFailed: trigger.fromFailed === true,
+                allowAwaitingInput: trigger.allowAwaitingInput === true,
+            });
+            if (refusal !== null || !hasRecordedSessionId(lane)) {
+                throw new LanesError(refusal?.error ?? "no_provider_session", refusal?.message ?? `Lane is ${lane.state} and has no recorded provider session`, { state: lane.state, provider: lane.provider });
+            }
+            return { mode: "resume", session_id: lane.provider_session_id };
+        }
+        default: {
+            const _exhaustive = trigger;
+            return _exhaustive;
+        }
+    }
+}
+/** Lane states a launch may claim `running` from, per trigger. */
+export function claimableStatesFor(trigger, lane) {
+    const envelopeRepairFailed = lane !== undefined && isFailedEnvelopeRepairLane(lane) && hasRecordedSessionId(lane);
+    switch (trigger.kind) {
+        case "admit":
+            return ["queued"];
+        case "answered_questions":
+            return ["awaiting_input"];
+        case "message":
+            return envelopeRepairFailed
+                ? [...RESUMABLE_LANE_STATES, "failed"]
+                : lane?.state === "awaiting_input"
+                    ? [...RESUMABLE_LANE_STATES, "awaiting_input"]
+                    : RESUMABLE_LANE_STATES;
+        case "resume": {
+            const states = trigger.fromFailed === true || envelopeRepairFailed
+                ? [...RESUME_COMMAND_STATES, "failed"]
+                : [...RESUME_COMMAND_STATES];
+            return lane?.state === "awaiting_input" ? [...states, "awaiting_input"] : states;
+        }
+        default: {
+            const _exhaustive = trigger;
+            return _exhaustive;
+        }
+    }
+}
+//# sourceMappingURL=delivery.js.map