@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/lanes/config.js

@@ -0,0 +1,408 @@
+/**
+ * Load and validate personal/lanes/config.json (spec §5.5).
+ *
+ * A missing file is the documented defaults, not an error. A `providers` key
+ * outside {claude, codex, grok} is rejected with the accepted list. Account
+ * homes are canonicalised with realpath; two account ids for one provider
+ * that resolve to the same home are refused (identity-keyed-cap rule).
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parseConfigEffort } from "./effort.js";
+import { LanesConfigError } from "./errors.js";
+import { CONFIG_SCHEMA_VERSION, LANE_PROVIDERS, isLaneProvider, parseMajorSchema, } from "./types.js";
+export const LANES_CONFIG_REL = path.join("personal", "lanes", "config.json");
+export const DEFAULT_MAX_QUEUED = 3;
+export const DEFAULT_CPU_BUSY_PAUSE = 0.85;
+export const DEFAULT_CPU_BUSY_RESUME = 0.7;
+export const DEFAULT_MIN_AVAILABLE_MEM_MB = 1024;
+/**
+ * Owner directive 2026-09-22: "if it's been an hour since last msg, always
+ * run compact". Override per provider with `compact_after_ms`.
+ */
+export const DEFAULT_COMPACT_AFTER_MS = 60 * 60 * 1000;
+/**
+ * Watcher `lane_progress` throttle: at most one thread event per five minutes
+ * per lane, and only when the tick saw new activity. Override per provider
+ * with `progress_event_min_interval_ms`.
+ */
+export const DEFAULT_PROGRESS_EVENT_MIN_INTERVAL_MS = 5 * 60 * 1000;
+/** Spec §9: last event within 10 minutes → live. */
+export const DEFAULT_LIVE_WITHIN_MS = 10 * 60 * 1000;
+/** Spec §9: turn_start with no turn_end after 2 hours → lost. */
+export const DEFAULT_TURN_START_LOST_MS = 2 * 60 * 60 * 1000;
+/** Spec §9: no event for 12 hours (and no session_end) → lost. */
+export const DEFAULT_SILENT_LOST_MS = 12 * 60 * 60 * 1000;
+export const DEFAULT_LIVENESS_WINDOWS = {
+    live_within_ms: DEFAULT_LIVE_WITHIN_MS,
+    turn_start_lost_ms: DEFAULT_TURN_START_LOST_MS,
+    silent_lost_ms: DEFAULT_SILENT_LOST_MS,
+};
+export const DEFAULT_PROVIDER_MAX_RUNNING = {
+    claude: 2,
+    codex: 4,
+    grok: 4,
+};
+export const DEFAULT_ACCOUNT_HOMES = {
+    claude: "~/.claude",
+    codex: "~/.codex",
+    grok: "~/.grok",
+};
+function defaultDeps() {
+    return {
+        homedir: () => os.homedir(),
+        realpathSync: (p) => fs.realpathSync(p),
+        existsSync: (p) => fs.existsSync(p),
+        readFileSync: (p, encoding) => fs.readFileSync(p, encoding),
+    };
+}
+export function expandHome(home, homedir) {
+    if (home === "~")
+        return homedir;
+    if (home.startsWith("~/") || home.startsWith("~\\")) {
+        return path.join(homedir, home.slice(2));
+    }
+    return home;
+}
+/**
+ * Canonical principal for an account home: realpath when the path exists,
+ * otherwise resolve existing ancestors and rejoin the missing tail so two
+ * not-yet-created spellings of the same directory still collide.
+ */
+export function canonicalizeHome(home, deps = defaultDeps()) {
+    const expanded = path.resolve(expandHome(home, deps.homedir()));
+    try {
+        return deps.realpathSync(expanded);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+    let cur = expanded;
+    const missing = [];
+    for (let i = 0; i < 64; i += 1) {
+        if (deps.existsSync(cur)) {
+            try {
+                return path.join(deps.realpathSync(cur), ...missing.reverse());
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "ENOENT")
+                    throw err;
+            }
+        }
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            break;
+        missing.push(path.basename(cur));
+        cur = parent;
+    }
+    return expanded;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function positiveInt(value, field, fallback) {
+    if (value === undefined && fallback !== undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new LanesConfigError("invalid_config", `${field} must be a positive integer`, { field, value });
+    }
+    return value;
+}
+function unitInterval(value, field, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw new LanesConfigError("invalid_config", `${field} must be a number in [0, 1]`, { field, value });
+    }
+    return value;
+}
+function parseAccount(provider, id, raw, deps) {
+    if (!isPlainObject(raw)) {
+        throw new LanesConfigError("invalid_config", `providers.${provider}.accounts.${id} must be an object`, { provider, account: id });
+    }
+    if (typeof raw.home !== "string" || raw.home.length === 0) {
+        throw new LanesConfigError("invalid_config", `providers.${provider}.accounts.${id}.home must be a non-empty string`, { provider, account: id });
+    }
+    if (typeof raw.enabled !== "boolean") {
+        throw new LanesConfigError("invalid_config", `providers.${provider}.accounts.${id}.enabled must be a boolean`, { provider, account: id });
+    }
+    const account = {
+        home: canonicalizeHome(raw.home, deps),
+        enabled: raw.enabled,
+    };
+    if (raw.disabled_reason !== undefined) {
+        if (typeof raw.disabled_reason !== "string") {
+            throw new LanesConfigError("invalid_config", `providers.${provider}.accounts.${id}.disabled_reason must be a string`, { provider, account: id });
+        }
+        account.disabled_reason = raw.disabled_reason;
+    }
+    if (raw.max_running !== undefined) {
+        account.max_running = positiveInt(raw.max_running, `providers.${provider}.accounts.${id}.max_running`);
+    }
+    if (raw.model !== undefined) {
+        account.model = nonEmptyModel(raw.model, `providers.${provider}.accounts.${id}.model`);
+    }
+    if (raw.effort !== undefined) {
+        account.effort = parseConfigEffort(provider, raw.effort, `providers.${provider}.accounts.${id}.effort`);
+    }
+    return account;
+}
+function nonEmptyModel(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new LanesConfigError("invalid_config", `${field} must be a non-empty string`, { field, value });
+    }
+    return value.trim();
+}
+function rejectDuplicateHomes(provider, accounts) {
+    const seen = new Map();
+    for (const [id, account] of Object.entries(accounts)) {
+        const prior = seen.get(account.home);
+        if (prior !== undefined) {
+            throw new LanesConfigError("duplicate_account_home", `providers.${provider} accounts ${JSON.stringify(prior)} and ${JSON.stringify(id)} resolve to the same home ${account.home}`, {
+                provider,
+                accounts: [prior, id],
+                home: account.home,
+            });
+        }
+        seen.set(account.home, id);
+    }
+}
+function defaultAccountMap(provider, deps) {
+    return {
+        a: {
+            home: canonicalizeHome(DEFAULT_ACCOUNT_HOMES[provider], deps),
+            enabled: true,
+        },
+    };
+}
+function parseProvider(provider, raw, deps) {
+    if (!isPlainObject(raw)) {
+        throw new LanesConfigError("invalid_config", `providers.${provider} must be an object`, { provider });
+    }
+    const accountsRaw = raw.accounts;
+    const accounts = {};
+    if (accountsRaw === undefined) {
+        Object.assign(accounts, defaultAccountMap(provider, deps));
+    }
+    else {
+        if (!isPlainObject(accountsRaw)) {
+            throw new LanesConfigError("invalid_config", `providers.${provider}.accounts must be an object`, { provider });
+        }
+        for (const [id, value] of Object.entries(accountsRaw)) {
+            if (id.length === 0) {
+                throw new LanesConfigError("invalid_config", `providers.${provider} account ids must be non-empty strings`, { provider });
+            }
+            accounts[id] = parseAccount(provider, id, value, deps);
+        }
+    }
+    rejectDuplicateHomes(provider, accounts);
+    // default_account is accepted so existing files parse, and ignored for
+    // selection. An omitted field is not an error.
+    let defaultAccount;
+    if (raw.default_account !== undefined) {
+        if (typeof raw.default_account !== "string" || raw.default_account.length === 0) {
+            throw new LanesConfigError("invalid_config", `providers.${provider}.default_account must be a non-empty string`, { provider, field: "default_account" });
+        }
+        defaultAccount = raw.default_account;
+        if (Object.keys(accounts).length > 0 && accounts[defaultAccount] === undefined) {
+            throw new LanesConfigError("invalid_config", `providers.${provider}.default_account ${JSON.stringify(defaultAccount)} is not a configured account`, { provider, default_account: defaultAccount, accounts: Object.keys(accounts) });
+        }
+    }
+    const parsed = {
+        max_running: positiveInt(raw.max_running, `providers.${provider}.max_running`, DEFAULT_PROVIDER_MAX_RUNNING[provider]),
+        max_queued: positiveInt(raw.max_queued, `providers.${provider}.max_queued`, DEFAULT_MAX_QUEUED),
+        accounts,
+    };
+    if (defaultAccount !== undefined)
+        parsed.default_account = defaultAccount;
+    if (raw.model !== undefined) {
+        parsed.model = nonEmptyModel(raw.model, `providers.${provider}.model`);
+    }
+    if (raw.effort !== undefined) {
+        parsed.effort = parseConfigEffort(provider, raw.effort, `providers.${provider}.effort`);
+    }
+    if (raw.compact_after_ms !== undefined) {
+        parsed.compact_after_ms = positiveInt(raw.compact_after_ms, `providers.${provider}.compact_after_ms`);
+    }
+    if (raw.progress_event_min_interval_ms !== undefined) {
+        parsed.progress_event_min_interval_ms = positiveInt(raw.progress_event_min_interval_ms, `providers.${provider}.progress_event_min_interval_ms`);
+    }
+    return parsed;
+}
+function parseThrottle(raw) {
+    const obj = raw === undefined ? {} : raw;
+    if (!isPlainObject(obj)) {
+        throw new LanesConfigError("invalid_config", "throttle must be an object");
+    }
+    const pause = unitInterval(obj.cpu_busy_pause, "throttle.cpu_busy_pause", DEFAULT_CPU_BUSY_PAUSE);
+    const resume = unitInterval(obj.cpu_busy_resume, "throttle.cpu_busy_resume", DEFAULT_CPU_BUSY_RESUME);
+    if (resume > pause) {
+        throw new LanesConfigError("invalid_config", "throttle.cpu_busy_resume must be <= throttle.cpu_busy_pause", { cpu_busy_pause: pause, cpu_busy_resume: resume });
+    }
+    let minMem = DEFAULT_MIN_AVAILABLE_MEM_MB;
+    if (obj.min_available_mem_mb !== undefined) {
+        if (typeof obj.min_available_mem_mb !== "number" ||
+            !Number.isFinite(obj.min_available_mem_mb) ||
+            obj.min_available_mem_mb < 0) {
+            throw new LanesConfigError("invalid_config", "throttle.min_available_mem_mb must be a non-negative number", { value: obj.min_available_mem_mb });
+        }
+        minMem = obj.min_available_mem_mb;
+    }
+    return {
+        cpu_busy_pause: pause,
+        cpu_busy_resume: resume,
+        min_available_mem_mb: minMem,
+    };
+}
+function parseLiveness(raw) {
+    const obj = raw === undefined ? {} : raw;
+    if (!isPlainObject(obj)) {
+        throw new LanesConfigError("invalid_config", "liveness must be an object");
+    }
+    return {
+        live_within_ms: positiveInt(obj.live_within_ms, "liveness.live_within_ms", DEFAULT_LIVE_WITHIN_MS),
+        turn_start_lost_ms: positiveInt(obj.turn_start_lost_ms, "liveness.turn_start_lost_ms", DEFAULT_TURN_START_LOST_MS),
+        silent_lost_ms: positiveInt(obj.silent_lost_ms, "liveness.silent_lost_ms", DEFAULT_SILENT_LOST_MS),
+    };
+}
+export function documentedDefaultConfig(deps = defaultDeps()) {
+    const providers = {};
+    for (const provider of LANE_PROVIDERS) {
+        providers[provider] = {
+            max_running: DEFAULT_PROVIDER_MAX_RUNNING[provider],
+            max_queued: DEFAULT_MAX_QUEUED,
+            accounts: defaultAccountMap(provider, deps),
+        };
+    }
+    return {
+        schema_version: CONFIG_SCHEMA_VERSION,
+        providers,
+        throttle: {
+            cpu_busy_pause: DEFAULT_CPU_BUSY_PAUSE,
+            cpu_busy_resume: DEFAULT_CPU_BUSY_RESUME,
+            min_available_mem_mb: DEFAULT_MIN_AVAILABLE_MEM_MB,
+        },
+        liveness: { ...DEFAULT_LIVENESS_WINDOWS },
+    };
+}
+export function parseLanesConfig(raw, deps = defaultDeps()) {
+    if (!isPlainObject(raw)) {
+        throw new LanesConfigError("invalid_config", "lanes config must be a JSON object");
+    }
+    if (typeof raw.schema_version === "string") {
+        parseMajorSchema(raw.schema_version, "hq-lanes-config", 1);
+    }
+    const providersRaw = raw.providers;
+    if (providersRaw !== undefined && !isPlainObject(providersRaw)) {
+        throw new LanesConfigError("invalid_config", "providers must be an object");
+    }
+    if (isPlainObject(providersRaw)) {
+        const unknown = Object.keys(providersRaw).filter((key) => !isLaneProvider(key));
+        if (unknown.length > 0) {
+            throw new LanesConfigError("unknown_provider", `Unknown provider(s) ${unknown.join(", ")}. Accepted: ${LANE_PROVIDERS.join(", ")}`, { accepted: [...LANE_PROVIDERS], value: unknown });
+        }
+    }
+    // Spec §5.5: a missing *file* yields the documented defaults, and the
+    // enable switch — not omission — is how an operator turns an account off.
+    // The provider set is fixed at {claude, codex, grok} (§5), so a present
+    // config that names only `grok` still receives the documented claude and
+    // codex defaults (including real-home `~/.claude` / `~/.codex`). Omitting
+    // a provider key is not a disable.
+    const providers = {};
+    for (const provider of LANE_PROVIDERS) {
+        const entry = isPlainObject(providersRaw) ? providersRaw[provider] : undefined;
+        providers[provider] =
+            entry === undefined
+                ? documentedDefaultConfig(deps).providers[provider]
+                : parseProvider(provider, entry, deps);
+    }
+    return {
+        schema_version: typeof raw.schema_version === "string"
+            ? raw.schema_version
+            : CONFIG_SCHEMA_VERSION,
+        providers,
+        throttle: parseThrottle(raw.throttle),
+        liveness: parseLiveness(raw.liveness),
+    };
+}
+export function lanesConfigPath(hqRoot) {
+    return path.join(hqRoot, LANES_CONFIG_REL);
+}
+/**
+ * Load operator config. Missing file → documented defaults. Unreadable or
+ * invalid JSON is an error (never a silent default).
+ */
+export function loadLanesConfig(hqRoot, deps = defaultDeps()) {
+    const filePath = lanesConfigPath(hqRoot);
+    if (!deps.existsSync(filePath)) {
+        return documentedDefaultConfig(deps);
+    }
+    let text;
+    try {
+        text = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new LanesConfigError("config_unreadable", `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new LanesConfigError("invalid_config", `Invalid JSON in ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+    return parseLanesConfig(parsed, deps);
+}
+function defaultWriteDeps() {
+    return {
+        mkdirSync: fs.mkdirSync.bind(fs),
+        writeFileSync: fs.writeFileSync.bind(fs),
+        renameSync: fs.renameSync.bind(fs),
+        unlinkSync: fs.unlinkSync.bind(fs),
+    };
+}
+/** Persist operator config. Homes are stored as already-canonicalised paths. */
+export function writeLanesConfig(hqRoot, config, deps = defaultWriteDeps()) {
+    const filePath = lanesConfigPath(hqRoot);
+    const dir = path.dirname(filePath);
+    deps.mkdirSync(dir, { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        deps.writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, {
+            encoding: "utf8",
+        });
+        deps.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            deps.unlinkSync(tmp);
+        }
+        catch (unlinkErr) {
+            const code = unlinkErr.code;
+            if (code !== "ENOENT") {
+                process.stderr.write(`lanes config: unlink tmp failed for ${tmp}: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}\n`);
+            }
+        }
+        throw err;
+    }
+}
+/** Resume-time compaction threshold for a provider, defaulting to one hour. */
+export function providerCompactAfterMs(provider) {
+    return provider.compact_after_ms ?? DEFAULT_COMPACT_AFTER_MS;
+}
+/** Minimum gap between two `lane_progress` events, defaulting to five minutes. */
+export function providerProgressEventMinIntervalMs(provider) {
+    return provider.progress_event_min_interval_ms ?? DEFAULT_PROGRESS_EVENT_MIN_INTERVAL_MS;
+}
+/** Account running cap, defaulting to the provider ceiling when unset. */
+export function accountMaxRunning(provider, accountId) {
+    const account = provider.accounts[accountId];
+    if (account?.max_running !== undefined)
+        return account.max_running;
+    return provider.max_running;
+}
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1,151 @@
+/**
+ * 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) has
+ * `--resume <id>` and its `--single --output-format json` result carries a
+ * `sessionId`, but no live run has shown `--single --resume` continue a
+ * session (the grok account was out of balance when this was written), so
+ * an exited grok lane keeps no delivery path until that is proven.
+ *
+ * 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 } 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;
+/**
+ * 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`, and the
+ * reconcile pass resumes it once every question is answered. `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; the operator has not seen why. `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];
+export type DeliveryLane = Pick<LaneRecord, "state" | "provider" | "provider_session_id">;
+/**
+ * `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;
+/** 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;
+} | {
+    /** `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;
+    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): {
+    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): readonly LaneState[];
+//# sourceMappingURL=delivery.d.ts.map