@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/lanes/dropbox.js

@@ -0,0 +1,408 @@
+/**
+ * Lane drop box: append-only inbox.jsonl plus exactly-once drain (spec §6.5).
+ *
+ * Consume is `rename(inbox.jsonl → draining/<unique>)` — atomic on this box.
+ * Two overlapping drainers cannot both claim the same bytes; a crash after
+ * rename leaves the messages in draining/ for the next drain to recover.
+ * A read-then-truncate is not this mechanism and loses or duplicates under
+ * overlap.
+ */
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+import { LANES_RUNS_REL, readProcStarttime } from "./spawn.js";
+export const DROPBOX_DIR = "dropbox";
+export const INBOX_NAME = "inbox.jsonl";
+export const DRAINING_DIR = "draining";
+export const DELIVERED_DIR = "delivered";
+export const INFLIGHT_DIR = "inflight";
+function defaultDrainDeps() {
+    return {
+        mkdirSync: fs.mkdirSync.bind(fs),
+        renameSync: fs.renameSync.bind(fs),
+        readFileSync: fs.readFileSync.bind(fs),
+        writeFileSync: fs.writeFileSync.bind(fs),
+        unlinkSync: fs.unlinkSync.bind(fs),
+        existsSync: fs.existsSync.bind(fs),
+        readdirSync: fs.readdirSync.bind(fs),
+        rmdirSync: fs.rmdirSync.bind(fs),
+        kill: (pid, signal) => {
+            process.kill(pid, signal);
+        },
+        pid: process.pid,
+        unique: mintClaimId,
+        readStarttime: readProcStarttime,
+    };
+}
+export function mintClaimId() {
+    return `${process.pid}.${process.hrtime.bigint()}.${randomBytes(4).toString("hex")}`;
+}
+export function assertSafeLaneId(laneId) {
+    if (!laneId || laneId.trim() !== laneId || laneId.length === 0) {
+        throw new LanesError("invalid_lane_id", "HQ_LANE_ID is empty or padded", {
+            lane_id: laneId,
+        });
+    }
+    if (laneId.includes("/") ||
+        laneId.includes("\\") ||
+        laneId.includes("\0") ||
+        laneId === "." ||
+        laneId === ".." ||
+        laneId.includes("..")) {
+        throw new LanesError("invalid_lane_id", `HQ_LANE_ID ${JSON.stringify(laneId)} is not a single path segment`, { lane_id: laneId });
+    }
+}
+export function dropboxDir(hqRoot, laneId) {
+    assertSafeLaneId(laneId);
+    return path.join(hqRoot, LANES_RUNS_REL, laneId, DROPBOX_DIR);
+}
+export function dropboxInboxPath(hqRoot, laneId) {
+    return path.join(dropboxDir(hqRoot, laneId), INBOX_NAME);
+}
+/**
+ * Worker tool-call liveness (watcher.ts reads it). A Claude worker run with
+ * `--output-format json` writes nothing to worker.out until it exits, so the
+ * only thing it does observably while working is call tools. Every tool call
+ * runs this drain hook, and the hook records the call here before it touches
+ * the drop box. The file's mtime is the signal; the body is for humans.
+ */
+export const TOOL_ACTIVITY_NAME = "tool-activity.json";
+export function toolActivityPath(hqRoot, laneId) {
+    assertSafeLaneId(laneId);
+    return path.join(hqRoot, LANES_RUNS_REL, laneId, "logs", TOOL_ACTIVITY_NAME);
+}
+export function recordToolActivity(hqRoot, laneId, at = new Date().toISOString()) {
+    const dest = toolActivityPath(hqRoot, laneId);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const record = { at, hook_pid: process.pid, hook_event: "PreToolUse" };
+    const tmp = `${dest}.${process.pid}.${mintClaimId()}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(record)}\n`, "utf8");
+    fs.renameSync(tmp, dest);
+    return record;
+}
+export function readToolActivity(hqRoot, laneId) {
+    let text;
+    try {
+        text = fs.readFileSync(toolActivityPath(hqRoot, laneId), "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.at !== "string" || typeof parsed.hook_pid !== "number")
+            return null;
+        return { at: parsed.at, hook_pid: parsed.hook_pid, hook_event: "PreToolUse" };
+    }
+    catch (err) {
+        process.stderr.write(`hq lanes: tool activity for ${laneId} is unparseable: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+export function appendDropboxMessage(hqRoot, laneId, message) {
+    const inbox = dropboxInboxPath(hqRoot, laneId);
+    fs.mkdirSync(path.dirname(inbox), { recursive: true });
+    fs.appendFileSync(inbox, `${JSON.stringify(message)}\n`, "utf8");
+    return message;
+}
+function listNames(dir, deps) {
+    try {
+        return deps.readdirSync(dir).filter((name) => !name.startsWith("."));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return [];
+        throw new LanesError("dropbox_unreadable", `Failed to read drop box directory ${dir}: ${err instanceof Error ? err.message : String(err)}`, { path: dir });
+    }
+}
+function tryRename(src, dest, deps) {
+    try {
+        deps.renameSync(src, dest);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+function pidAlive(pid, deps, starttime) {
+    try {
+        deps.kill(pid, 0);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM") {
+            /* still check starttime below */
+        }
+        else {
+            throw err;
+        }
+    }
+    // Unknown starttime is not proof of liveness. Recover. Skip steal only
+    // when the pid is alive, recorded starttime is non-zero, and it matches.
+    if (starttime === undefined || starttime === 0)
+        return false;
+    const live = (deps.readStarttime ?? readProcStarttime)(pid);
+    if (live === null || live === 0)
+        return false;
+    return live === starttime;
+}
+function parseJsonl(text, filePath) {
+    const messages = [];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line === undefined || line.trim() === "")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (err) {
+            process.stderr.write(`hq-lanes-drain: skipping unparseable drop box line ${i + 1} of ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`);
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            process.stderr.write(`hq-lanes-drain: skipping non-object drop box line ${i + 1} of ${filePath}\n`);
+            continue;
+        }
+        const rec = parsed;
+        const textField = rec.text;
+        messages.push({
+            ...rec,
+            text: typeof textField === "string"
+                ? textField
+                : JSON.stringify(rec),
+        });
+    }
+    return messages;
+}
+function readClaimedFile(filePath, deps) {
+    let text;
+    try {
+        text = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new LanesError("dropbox_unreadable", `Failed to read drop box file ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+    return parseJsonl(text, filePath);
+}
+/**
+ * Drain this lane's inbox exactly once. Concurrent callers: one rename wins;
+ * the loser sees ENOENT and returns whatever it separately claimed (usually
+ * nothing). Leftovers in draining/ and dead inflight dirs are recovered.
+ */
+export function drainDropbox(hqRoot, laneId, depsInput = {}) {
+    const deps = { ...defaultDrainDeps(), ...depsInput };
+    const box = dropboxDir(hqRoot, laneId);
+    const inbox = path.join(box, INBOX_NAME);
+    const draining = path.join(box, DRAINING_DIR);
+    const delivered = path.join(box, DELIVERED_DIR);
+    const inflightRoot = path.join(box, INFLIGHT_DIR);
+    try {
+        deps.mkdirSync(box, { recursive: true });
+        deps.mkdirSync(draining, { recursive: true });
+        deps.mkdirSync(delivered, { recursive: true });
+        deps.mkdirSync(inflightRoot, { recursive: true });
+    }
+    catch (err) {
+        throw new LanesError("dropbox_unreadable", `Failed to open drop box ${box}: ${err instanceof Error ? err.message : String(err)}`, { path: box });
+    }
+    const starttime = (deps.readStarttime ?? readProcStarttime)(deps.pid) ?? 0;
+    const inflightDir = path.join(inflightRoot, `${deps.pid}.${starttime}.${deps.unique()}`);
+    deps.mkdirSync(inflightDir, { recursive: true });
+    if (deps.existsSync(inbox)) {
+        deps.afterObserveInbox?.();
+        tryRename(inbox, path.join(inflightDir, INBOX_NAME), deps);
+    }
+    for (const name of listNames(draining, deps)) {
+        tryRename(path.join(draining, name), path.join(inflightDir, name), deps);
+    }
+    for (const name of listNames(inflightRoot, deps)) {
+        const other = path.join(inflightRoot, name);
+        if (other === inflightDir)
+            continue;
+        const parts = name.split(".");
+        const pidPart = Number(parts[0]);
+        const startPart = Number(parts[1]);
+        if (Number.isInteger(pidPart) &&
+            pidPart !== deps.pid &&
+            pidAlive(pidPart, deps, Number.isInteger(startPart) ? startPart : undefined)) {
+            continue;
+        }
+        for (const file of listNames(other, deps)) {
+            tryRename(path.join(other, file), path.join(inflightDir, file), deps);
+        }
+        try {
+            deps.rmdirSync(other);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "ENOTEMPTY")
+                throw err;
+        }
+    }
+    const claimed = listNames(inflightDir, deps);
+    const messages = [];
+    for (const name of claimed) {
+        messages.push(...readClaimedFile(path.join(inflightDir, name), deps));
+    }
+    deps.afterRead?.();
+    for (const name of claimed) {
+        const src = path.join(inflightDir, name);
+        const dest = path.join(delivered, `${deps.unique()}.${name}`);
+        if (!tryRename(src, dest, deps)) {
+            throw new LanesError("dropbox_unreadable", `Claimed drop box file disappeared before delivery archive: ${src}`, { path: src });
+        }
+    }
+    try {
+        deps.rmdirSync(inflightDir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT" && code !== "ENOTEMPTY")
+            throw err;
+    }
+    return messages;
+}
+export function formatOperatorInstruction(messages) {
+    const body = messages
+        .map((msg, i) => {
+        const header = msg.kind === "question_answer"
+            ? `${i + 1}. Answer to question ${msg.question_id ?? "?"} — choice: ${msg.choice ?? "?"}`
+            : `${i + 1}.`;
+        return `${header}\n${msg.text}`;
+    })
+        .join("\n\n");
+    return [
+        "OPERATOR INSTRUCTION (outranks the lane brief).",
+        "The following messages were delivered through this lane's drop box. Treat them as operator instructions that outrank the brief.",
+        "",
+        body,
+    ].join("\n");
+}
+export function hookAdditionalContextJson(messages) {
+    return `${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: formatOperatorInstruction(messages),
+        },
+    })}\n`;
+}
+/**
+ * Hook protocol. HQ_LANE_ID absent or empty → exit 0, empty stdout, empty stderr.
+ * That no-op is load-bearing: this hook is registered in the grok home and runs
+ * on every session on the box.
+ */
+export function runDrainHook(env) {
+    const laneId = env.HQ_LANE_ID ?? "";
+    if (laneId === "") {
+        return { exitCode: 0, stdout: "", stderr: "" };
+    }
+    const hqRoot = env.HQ_ROOT ?? "";
+    if (hqRoot === "") {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "hq-lanes-drain: HQ_ROOT is unset while HQ_LANE_ID is set\n",
+        };
+    }
+    // Liveness first: a failed drain must still leave proof the worker called
+    // a tool. A failure here is reported, never fatal to delivery.
+    let stderr = "";
+    try {
+        recordToolActivity(hqRoot, laneId);
+    }
+    catch (err) {
+        stderr += `hq-lanes-drain: failed to record tool activity: ${err instanceof Error ? err.message : String(err)}\n`;
+    }
+    try {
+        const messages = drainDropbox(hqRoot, laneId);
+        if (messages.length === 0) {
+            return { exitCode: 0, stdout: "", stderr };
+        }
+        return { exitCode: 0, stdout: hookAdditionalContextJson(messages), stderr };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `${stderr}hq-lanes-drain: ${message}\n`,
+        };
+    }
+}
+/** Spec §6.5: only a still-running lane gets drop-box delivery. */
+export function laneAcceptsDropboxDelivery(lane) {
+    return lane.state === "running";
+}
+/**
+ * Operator `hq lanes message` delivery. Queued is accepted because the
+ * worker that will spawn drains the inbox on its first tool event.
+ * `laneAcceptsDropboxDelivery` refuses queued, so it is the wrong guard here.
+ */
+export function laneAcceptsOperatorMessage(lane) {
+    const state = lane.state;
+    switch (state) {
+        case "queued":
+        case "running":
+            return true;
+        case "awaiting_input":
+        case "blocked":
+        case "interrupted":
+        case "done":
+        case "failed":
+        case "cancelled":
+        case "killed":
+            return false;
+        default: {
+            const _exhaustive = state;
+            return _exhaustive;
+        }
+    }
+}
+export function operatorMessageRefusalReason(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 "blocked":
+            return "Lane is blocked. The worker has exited and there is no delivery path.";
+        case "interrupted":
+        case "done":
+        case "failed":
+        case "cancelled":
+        case "killed":
+            return `Lane is ${state}. The worker is gone and there is no durable fallback record.`;
+        default: {
+            const _exhaustive = state;
+            return _exhaustive;
+        }
+    }
+}
+/** Delivery target is the lane_id on the question record. Never a project/story lookup. */
+export function laneIdForAnswerDelivery(question) {
+    return question.lane_id;
+}
+export function answerDropboxMessage(question, choice, at, messageId) {
+    return {
+        at,
+        message_id: messageId,
+        kind: "question_answer",
+        question_id: question.question_id,
+        choice,
+        text: `OPERATOR INSTRUCTION (outranks the lane brief). Question ${question.question_id} was answered with choice: ${choice}. Treat this as an operator decision that outranks the brief.`,
+    };
+}
+//# sourceMappingURL=dropbox.js.map

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

@@ -0,0 +1,50 @@
+/**
+ * Effort (reasoning depth) per lane provider.
+ *
+ * Every provider CLI here tolerates or ignores a bad value in some way:
+ * `claude --effort bogus` warns and runs at the default, and
+ * `codex -c model_reasoning_effort=bogus` loads without complaint. hq-cli
+ * therefore validates the value against each provider's own set before any
+ * spawn, and refuses anything else with `invalid_effort`.
+ *
+ * Measured 2026-09-22:
+ * - claude: `--effort <level>`; the CLI's own warning lists
+ *   low, medium, high, xhigh, max.
+ * - codex 0.155.1: `exec` has no effort flag. The config key
+ *   `model_reasoning_effort` is set with `-c`. The value set is the
+ *   binary's ReasoningEffort enum (minimal, low, medium, high, xhigh, max,
+ *   ultra); per-model support is in ~/.codex/models_cache.json.
+ * - grok 1.0.34: `--reasoning-effort <level>` (alias `--effort`); an unknown
+ *   value is rejected with "use one of: xhigh, high, medium, low".
+ */
+import type { LaneProvider } from "./types.js";
+export declare const PROVIDER_EFFORT_LEVELS: Record<LaneProvider, readonly string[]>;
+export declare const EFFORT_SOURCES: readonly ["cli", "account", "provider", "default_rule", "none"];
+export type EffortSource = (typeof EFFORT_SOURCES)[number];
+export interface ResolvedEffort {
+    effort?: string;
+    source: EffortSource;
+}
+/** Validate `--effort` for a provider. Undefined in, undefined out. */
+export declare function parseCliEffort(provider: LaneProvider, raw: string | undefined): string | undefined;
+/** Validate an `effort` field from personal/lanes/config.json. */
+export declare function parseConfigEffort(provider: LaneProvider, raw: unknown, field: string): string;
+/**
+ * Effort applied when nothing sets one. Owner directive 2026-09-22,
+ * verbatim: "make sure opus and fable are used on low by default".
+ * Keyed on the model already chosen for the lane; it does not pick a model.
+ */
+export declare function defaultEffortForModel(model: string | undefined): string | undefined;
+/** Precedence: `--effort`, then the account, then the provider, then the default rule. */
+export declare function resolveLaneEffort(input: {
+    cliEffort?: string;
+    accountEffort?: string;
+    providerEffort?: string;
+    model?: string;
+}): ResolvedEffort;
+/**
+ * Add the provider's effort argument. Codex takes it as a config override,
+ * which must precede the `--` that ends its options.
+ */
+export declare function appendEffortFlag(provider: LaneProvider, args: string[], effort: string | undefined): string[];
+//# sourceMappingURL=effort.d.ts.map

package/dist/lib/lanes/effort.js

@@ -0,0 +1,109 @@
+/**
+ * Effort (reasoning depth) per lane provider.
+ *
+ * Every provider CLI here tolerates or ignores a bad value in some way:
+ * `claude --effort bogus` warns and runs at the default, and
+ * `codex -c model_reasoning_effort=bogus` loads without complaint. hq-cli
+ * therefore validates the value against each provider's own set before any
+ * spawn, and refuses anything else with `invalid_effort`.
+ *
+ * Measured 2026-09-22:
+ * - claude: `--effort <level>`; the CLI's own warning lists
+ *   low, medium, high, xhigh, max.
+ * - codex 0.155.1: `exec` has no effort flag. The config key
+ *   `model_reasoning_effort` is set with `-c`. The value set is the
+ *   binary's ReasoningEffort enum (minimal, low, medium, high, xhigh, max,
+ *   ultra); per-model support is in ~/.codex/models_cache.json.
+ * - grok 1.0.34: `--reasoning-effort <level>` (alias `--effort`); an unknown
+ *   value is rejected with "use one of: xhigh, high, medium, low".
+ */
+import { LanesConfigError, LanesError } from "./errors.js";
+export const PROVIDER_EFFORT_LEVELS = {
+    claude: ["low", "medium", "high", "xhigh", "max"],
+    codex: ["minimal", "low", "medium", "high", "xhigh", "max", "ultra"],
+    grok: ["low", "medium", "high", "xhigh"],
+};
+export const EFFORT_SOURCES = [
+    "cli",
+    "account",
+    "provider",
+    "default_rule",
+    "none",
+];
+function acceptedList(provider) {
+    return PROVIDER_EFFORT_LEVELS[provider].join(", ");
+}
+/** Validate `--effort` for a provider. Undefined in, undefined out. */
+export function parseCliEffort(provider, raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw.trim();
+    const accepted = PROVIDER_EFFORT_LEVELS[provider];
+    if (!accepted.includes(value)) {
+        throw new LanesError("invalid_effort", `Invalid --effort ${JSON.stringify(raw)} for ${provider}. Accepted: ${acceptedList(provider)}`, { provider, value: raw, accepted: [...accepted] });
+    }
+    return value;
+}
+/** Validate an `effort` field from personal/lanes/config.json. */
+export function parseConfigEffort(provider, raw, field) {
+    const accepted = PROVIDER_EFFORT_LEVELS[provider];
+    if (typeof raw !== "string" || !accepted.includes(raw.trim())) {
+        throw new LanesConfigError("invalid_effort", `${field} must be one of ${acceptedList(provider)}`, { field, provider, value: raw, accepted: [...accepted] });
+    }
+    return raw.trim();
+}
+/**
+ * Effort applied when nothing sets one. Owner directive 2026-09-22,
+ * verbatim: "make sure opus and fable are used on low by default".
+ * Keyed on the model already chosen for the lane; it does not pick a model.
+ */
+export function defaultEffortForModel(model) {
+    if (model === undefined)
+        return undefined;
+    if (model.startsWith("claude-opus-") || model.startsWith("claude-fable-")) {
+        return "low";
+    }
+    return undefined;
+}
+/** Precedence: `--effort`, then the account, then the provider, then the default rule. */
+export function resolveLaneEffort(input) {
+    if (input.cliEffort !== undefined)
+        return { effort: input.cliEffort, source: "cli" };
+    if (input.accountEffort !== undefined) {
+        return { effort: input.accountEffort, source: "account" };
+    }
+    if (input.providerEffort !== undefined) {
+        return { effort: input.providerEffort, source: "provider" };
+    }
+    const fallback = defaultEffortForModel(input.model);
+    if (fallback !== undefined)
+        return { effort: fallback, source: "default_rule" };
+    return { source: "none" };
+}
+/**
+ * Add the provider's effort argument. Codex takes it as a config override,
+ * which must precede the `--` that ends its options.
+ */
+export function appendEffortFlag(provider, args, effort) {
+    if (effort === undefined)
+        return args;
+    const value = parseCliEffort(provider, effort);
+    switch (provider) {
+        case "claude":
+            return [...args, "--effort", value];
+        case "grok":
+            return [...args, "--reasoning-effort", value];
+        case "codex": {
+            const flag = ["-c", `model_reasoning_effort="${value}"`];
+            const end = args.indexOf("--");
+            if (end === -1)
+                return [...args, ...flag];
+            return [...args.slice(0, end), ...flag, ...args.slice(end)];
+        }
+        default: {
+            const _exhaustive = provider;
+            return _exhaustive;
+        }
+    }
+}
+//# sourceMappingURL=effort.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * Distinguishable errors for the lanes library. `error` matches the spec's
+ * JSON `error` field so the command layer can print `err.toJSON()` as-is.
+ */
+export declare class LanesError extends Error {
+    readonly error: string;
+    readonly details: Record<string, unknown>;
+    constructor(error: string, message: string, details?: Record<string, unknown>);
+    toJSON(): Record<string, unknown>;
+}
+export declare function isLanesError(err: unknown): err is LanesError;
+/** Compare-and-set miss. Callers retry after re-reading the record. */
+export declare class LaneVersionConflict extends LanesError {
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    readonly recordPath: string;
+    constructor(opts: {
+        path: string;
+        expectedVersion: number;
+        actualVersion: number;
+    });
+}
+export declare function isLaneVersionConflict(err: unknown): err is LaneVersionConflict;
+export declare class LaneNotFoundError extends LanesError {
+    constructor(kind: "lane" | "question", id: string);
+}
+export declare class LaneSchemaError extends LanesError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class LanesConfigError extends LanesError {
+    constructor(error: string, message: string, details?: Record<string, unknown>);
+}
+export declare class AccountResolutionError extends LanesError {
+    constructor(error: "unknown_account" | "account_disabled" | "no_enabled_account" | "account_model_unavailable" | "account_quota_exhausted", message: string, details?: Record<string, unknown>);
+}
+export declare class WorkerResolutionError extends LanesError {
+    constructor(error: "worker_not_found" | "worker_tenancy_unresolved" | "worker_not_available" | "worker_not_active" | "worker_id_conflict" | "package_workers_unmounted" | "worker_registry_unreadable", message: string, details?: Record<string, unknown>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/lanes/errors.js

@@ -0,0 +1,72 @@
+/**
+ * Distinguishable errors for the lanes library. `error` matches the spec's
+ * JSON `error` field so the command layer can print `err.toJSON()` as-is.
+ */
+export class LanesError extends Error {
+    error;
+    details;
+    constructor(error, message, details = {}) {
+        super(message);
+        this.name = "LanesError";
+        this.error = error;
+        this.details = details;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    toJSON() {
+        return { error: this.error, ...this.details };
+    }
+}
+export function isLanesError(err) {
+    return err instanceof LanesError;
+}
+/** Compare-and-set miss. Callers retry after re-reading the record. */
+export class LaneVersionConflict extends LanesError {
+    expectedVersion;
+    actualVersion;
+    recordPath;
+    constructor(opts) {
+        super("version_conflict", `Lane record version conflict at ${opts.path}: expected ${opts.expectedVersion}, found ${opts.actualVersion}`, {
+            path: opts.path,
+            expected: opts.expectedVersion,
+            actual: opts.actualVersion,
+        });
+        this.name = "LaneVersionConflict";
+        this.expectedVersion = opts.expectedVersion;
+        this.actualVersion = opts.actualVersion;
+        this.recordPath = opts.path;
+    }
+}
+export function isLaneVersionConflict(err) {
+    return err instanceof LaneVersionConflict;
+}
+export class LaneNotFoundError extends LanesError {
+    constructor(kind, id) {
+        super(kind === "lane" ? "lane_not_found" : "question_not_found", `${kind} ${id} not found`, { [`${kind}_id`]: id });
+        this.name = "LaneNotFoundError";
+    }
+}
+export class LaneSchemaError extends LanesError {
+    constructor(message, details = {}) {
+        super("schema_error", message, details);
+        this.name = "LaneSchemaError";
+    }
+}
+export class LanesConfigError extends LanesError {
+    constructor(error, message, details = {}) {
+        super(error, message, details);
+        this.name = "LanesConfigError";
+    }
+}
+export class AccountResolutionError extends LanesError {
+    constructor(error, message, details = {}) {
+        super(error, message, details);
+        this.name = "AccountResolutionError";
+    }
+}
+export class WorkerResolutionError extends LanesError {
+    constructor(error, message, details = {}) {
+        super(error, message, details);
+        this.name = "WorkerResolutionError";
+    }
+}
+//# sourceMappingURL=errors.js.map