@indigoai-us/hq-cli 5.125.0 → 5.126.0

package/dist/lib/lanes/accounts.js

@@ -0,0 +1,128 @@
+/**
+ * Provider account resolution (spec §5.5).
+ *
+ * Naming an account and omitting one mean different things: an explicit
+ * disabled id is refused; omitting rotates past a disabled default.
+ * Status reports `configured` and `logged_in` separately. logged_in is
+ * derived from whether <home>/auth.json EXISTS — this module never reads,
+ * prints, copies, or hashes that file.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { AccountResolutionError } from "./errors.js";
+export const PROVIDER_HOME_ENV = {
+    claude: "CLAUDE_CONFIG_DIR",
+    codex: "CODEX_HOME",
+    grok: "GROK_HOME",
+};
+export const AUTH_JSON_NAME = "auth.json";
+function defaultAccountDeps() {
+    return { existsSync: (p) => fs.existsSync(p) };
+}
+function enabledIds(provider) {
+    return Object.entries(provider.accounts)
+        .filter(([, account]) => account.enabled)
+        .map(([id]) => id);
+}
+function rotateEnabled(providerCfg, skipId) {
+    for (const [id, account] of Object.entries(providerCfg.accounts)) {
+        if (!account.enabled)
+            continue;
+        if (skipId !== undefined && id === skipId)
+            continue;
+        return id;
+    }
+    return undefined;
+}
+export function resolveAccount(provider, requestedId, config) {
+    const providerCfg = config.providers[provider];
+    const envVar = PROVIDER_HOME_ENV[provider];
+    const enabled = enabledIds(providerCfg);
+    if (requestedId !== undefined && requestedId.length > 0) {
+        const account = providerCfg.accounts[requestedId];
+        if (account === undefined) {
+            throw new AccountResolutionError("unknown_account", `Unknown account ${JSON.stringify(requestedId)} for ${provider}. Enabled: ${enabled.join(", ") || "(none)"}`, {
+                provider,
+                account: requestedId,
+                enabled,
+            });
+        }
+        if (!account.enabled) {
+            throw new AccountResolutionError("account_disabled", `Account ${JSON.stringify(requestedId)} is disabled${account.disabled_reason ? `: ${account.disabled_reason}` : ""}`, {
+                account: requestedId,
+                reason: account.disabled_reason ?? "",
+            });
+        }
+        return {
+            provider,
+            id: requestedId,
+            home: account.home,
+            enabled: true,
+            envVar,
+        };
+    }
+    const defaultId = providerCfg.default_account;
+    const defaultAccount = providerCfg.accounts[defaultId];
+    if (defaultAccount?.enabled) {
+        return {
+            provider,
+            id: defaultId,
+            home: defaultAccount.home,
+            enabled: true,
+            envVar,
+        };
+    }
+    const rotated = rotateEnabled(providerCfg, defaultAccount ? defaultId : undefined);
+    if (rotated === undefined) {
+        throw new AccountResolutionError("no_enabled_account", `No enabled account for provider ${provider}`, { provider });
+    }
+    const rotatedAccount = providerCfg.accounts[rotated];
+    return {
+        provider,
+        id: rotated,
+        home: rotatedAccount.home,
+        enabled: true,
+        envVar,
+    };
+}
+export function authJsonPath(home) {
+    return path.join(home, AUTH_JSON_NAME);
+}
+export function accountStatus(provider, accountId, config, deps = defaultAccountDeps()) {
+    const envVar = PROVIDER_HOME_ENV[provider];
+    const account = config.providers[provider].accounts[accountId];
+    if (account === undefined) {
+        return {
+            provider,
+            id: accountId,
+            home: "",
+            enabled: false,
+            configured: false,
+            logged_in: false,
+            envVar,
+        };
+    }
+    const authPath = authJsonPath(account.home);
+    const logged_in = deps.existsSync(authPath);
+    const status = {
+        provider,
+        id: accountId,
+        home: account.home,
+        enabled: account.enabled,
+        configured: true,
+        logged_in,
+        envVar,
+    };
+    if (account.disabled_reason !== undefined) {
+        status.disabled_reason = account.disabled_reason;
+    }
+    return status;
+}
+export function listAccountStatuses(provider, config, deps = defaultAccountDeps()) {
+    return Object.keys(config.providers[provider].accounts).map((id) => accountStatus(provider, id, config, deps));
+}
+/** Environment assignment the worker process should receive. */
+export function accountEnv(resolved) {
+    return { [resolved.envVar]: resolved.home };
+}
+//# sourceMappingURL=accounts.js.map

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

@@ -0,0 +1,56 @@
+/**
+ * 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 { type LaneProvider, type LanesConfig, type LivenessWindows, type ProviderConfig } from "./types.js";
+export declare const LANES_CONFIG_REL: string;
+export declare const DEFAULT_MAX_QUEUED = 3;
+export declare const DEFAULT_CPU_BUSY_PAUSE = 0.85;
+export declare const DEFAULT_CPU_BUSY_RESUME = 0.7;
+export declare const DEFAULT_MIN_AVAILABLE_MEM_MB = 1024;
+/** Spec §9: last event within 10 minutes → live. */
+export declare const DEFAULT_LIVE_WITHIN_MS: number;
+/** Spec §9: turn_start with no turn_end after 2 hours → lost. */
+export declare const DEFAULT_TURN_START_LOST_MS: number;
+/** Spec §9: no event for 12 hours (and no session_end) → lost. */
+export declare const DEFAULT_SILENT_LOST_MS: number;
+export declare const DEFAULT_LIVENESS_WINDOWS: LivenessWindows;
+export declare const DEFAULT_PROVIDER_MAX_RUNNING: Record<LaneProvider, number>;
+export declare const DEFAULT_ACCOUNT_HOMES: Record<LaneProvider, string>;
+export interface ConfigLoadDeps {
+    homedir: () => string;
+    realpathSync: (p: string) => string;
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string, encoding: "utf8") => string;
+}
+export declare function expandHome(home: string, homedir: string): string;
+/**
+ * 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 declare function canonicalizeHome(home: string, deps?: Pick<ConfigLoadDeps, "homedir" | "realpathSync" | "existsSync">): string;
+export declare function documentedDefaultConfig(deps?: ConfigLoadDeps): LanesConfig;
+export declare function parseLanesConfig(raw: unknown, deps?: ConfigLoadDeps): LanesConfig;
+export declare function lanesConfigPath(hqRoot: string): string;
+/**
+ * Load operator config. Missing file → documented defaults. Unreadable or
+ * invalid JSON is an error (never a silent default).
+ */
+export declare function loadLanesConfig(hqRoot: string, deps?: ConfigLoadDeps): LanesConfig;
+export interface ConfigWriteDeps {
+    mkdirSync: typeof fs.mkdirSync;
+    writeFileSync: typeof fs.writeFileSync;
+    renameSync: typeof fs.renameSync;
+    unlinkSync: typeof fs.unlinkSync;
+}
+/** Persist operator config. Homes are stored as already-canonicalised paths. */
+export declare function writeLanesConfig(hqRoot: string, config: LanesConfig, deps?: ConfigWriteDeps): void;
+/** Account running cap, defaulting to the provider ceiling when unset. */
+export declare function accountMaxRunning(provider: ProviderConfig, accountId: string): number;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/lanes/config.js

@@ -0,0 +1,351 @@
+/**
+ * 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 { 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;
+/** 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`);
+    }
+    return account;
+}
+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);
+    const defaultAccount = typeof raw.default_account === "string" && raw.default_account.length > 0
+        ? raw.default_account
+        : "a";
+    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) });
+    }
+    return {
+        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),
+        default_account: defaultAccount,
+        accounts,
+    };
+}
+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,
+            default_account: "a",
+            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 });
+        }
+    }
+    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;
+    }
+}
+/** 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/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", 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" | "personal_worker_unindexed" | "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

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

@@ -0,0 +1,19 @@
+/**
+ * Library layer for `hq lanes`. The command module should import from here.
+ */
+export { AccountResolutionError, LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesConfigError, LanesError, WorkerResolutionError, isLaneVersionConflict, isLanesError, } from "./errors.js";
+export { CONFIG_SCHEMA_VERSION, ENVELOPE_DECISIONS, ENVELOPE_SCHEMA_VERSION, HISTORY_CAP, HOST_KINDS, LANE_PROVIDERS, LANE_SCHEMA_VERSION, LANE_STATES, LIVENESS_STATES, QUESTION_BODY_STORES, QUESTION_SCHEMA_VERSION, QUESTION_STATUSES, QUEUED_REASONS, RAISED_VIA, ROUTING_REASONS, SENIOR_KINDS, STORY_STATUSES, TERMINAL_LANE_STATES, isEnvelopeDecision, isHostKind, isLaneProvider, isLaneState, isLivenessState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseLaneEnvelope, parseLaneProvider, parseLaneState, parseLivenessState, parseMajorSchema, parseQuestionStatus, parseSeniorKind, } from "./types.js";
+export type { AccountConfig, AttributionHistoryEntry, EnvelopeDecision, EnvelopeQuestion, HostKind, LaneCompanyRef, LaneEnvelope, LaneHost, LaneProvider, LaneRecord, LaneState, LanesConfig, LastEnvelopeRef, LivenessState, LivenessWindows, ProviderConfig, QuestionAnswer, QuestionBodyRef, QuestionRecord, QuestionStatus, QueuedReason, RaisedVia, RoutingHistoryEntry, RoutingReason, SeniorHistoryEntry, SeniorKind, SeniorRef, StoryStatus, TerminalLaneState, ThrottleConfig, } from "./types.js";
+export { DEFAULT_ACCOUNT_HOMES, DEFAULT_CPU_BUSY_PAUSE, DEFAULT_CPU_BUSY_RESUME, DEFAULT_LIVE_WITHIN_MS, DEFAULT_LIVENESS_WINDOWS, DEFAULT_MAX_QUEUED, DEFAULT_MIN_AVAILABLE_MEM_MB, DEFAULT_PROVIDER_MAX_RUNNING, DEFAULT_SILENT_LOST_MS, DEFAULT_TURN_START_LOST_MS, LANES_CONFIG_REL, accountMaxRunning, canonicalizeHome, documentedDefaultConfig, expandHome, lanesConfigPath, loadLanesConfig, parseLanesConfig, writeLanesConfig, } from "./config.js";
+export type { ConfigLoadDeps, ConfigWriteDeps } from "./config.js";
+export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, updateLane, updateQuestion, } from "./store.js";
+export type { StoreDeps } from "./store.js";
+export { CPU_SAMPLE_MS, LANES_CPU_BUSY_OVERRIDE, LANES_CPU_CHECK, PROC_MEMINFO, STARVATION_MAX_DEFERRALS, STARVATION_MAX_MS, applyThrottleDecision, busyFractionFromDeltas, cpuTimesSnapshot, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, parseMemAvailableKb, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyFraction, starvationBoundReached, throttleStatePath, writeThrottleState, } from "./throttle.js";
+export type { CpuTimes, ThrottleAdmitReason, ThrottleDecision, ThrottleDeferReason, ThrottleDeps, ThrottleState, } from "./throttle.js";
+export { AUTH_JSON_NAME, PROVIDER_HOME_ENV, accountEnv, accountStatus, authJsonPath, listAccountStatuses, resolveAccount, } from "./accounts.js";
+export type { AccountStatus, ResolvedAccount } from "./accounts.js";
+export { LIVE_WITHIN_MS, LIVENESS_EVENT_KINDS, SILENT_LOST_MS, TURN_START_LOST_MS, buildLivenessIndexFromSpool, classifySessionLiveness, defaultLivenessDeps, defaultSpoolPath, ingestSpoolLine, listSessionLiveness, livenessIndexPath, loadLivenessIndex, readLivenessIndex, rebuildLivenessIndex, sessionLiveness, } from "./liveness.js";
+export type { LivenessDeps, LivenessEventKind, LivenessIndex, SessionIndexEntry, } from "./liveness.js";
+export { WORKER_REGISTRY_REL, personalWorkerDir, personalWorkerExists, readWorkerRegistryFile, registryPath, resolveContextBasePaths, resolveLaneWorker, resolveSkillFiles, tenancyFromRegistryPath, } from "./registry.js";
+export type { RegistryWorkerEntry, ResolvedLaneWorker, WorkerTenancy, WorkerYaml, } from "./registry.js";
+//# sourceMappingURL=index.d.ts.map