@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/lanes/config.js

@@ -0,0 +1,606 @@
+/**
+ * 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;
+/**
+ * Claude Code's auto-compaction window, in tokens. Override with
+ * `providers.claude.auto_compact_tokens`.
+ */
+export const DEFAULT_AUTO_COMPACT_TOKENS = 200_000;
+/**
+ * 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;
+/** Account hold after a 429 that names no reset time (`quota_default_hold_ms`). */
+export const DEFAULT_QUOTA_HOLD_MS = 15 * 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;
+/** Unanswered session questions move to the next audience after 10 minutes. */
+export const DEFAULT_SESSION_QUESTION_TIMEOUT_SECS = 10 * 60;
+/** Open manager blockers are re-verified every four hours by default. */
+export const DEFAULT_BLOCKER_FRESHNESS_HOURS = 4;
+/** Manager key results must be re-measured within six hours by default. */
+export const DEFAULT_KR_FRESHNESS_HOURS = 6;
+export const DEFAULT_LOW_DISK_MIN_FREE_BYTES = 5 * 1024 ** 3;
+export const DEFAULT_CODEX_ROLLOUT_COMPRESS_AFTER_HOURS = 24;
+export const DEFAULT_CODEX_ROLLOUT_DELETE_AFTER_DAYS = 7;
+export const DEFAULT_TRACKER_CHECKS = {
+    owner_question_surface_ms: 10 * 60 * 1000,
+    open_question_age_ms: 2 * 60 * 60 * 1000,
+    status_stale_ms: 90 * 60 * 1000,
+    task_list_stale_ms: 120 * 60 * 1000,
+    blocker_max_age_ms: 24 * 60 * 60 * 1000,
+    kpi_value_max_age_ms: 24 * 60 * 60 * 1000,
+    directive_ack_timeout_ms: 30 * 60 * 1000,
+};
+export const DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG = {
+    max_age_seconds: 20,
+    find_maxdepth_exempt: 3,
+};
+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 canonicalizeHostHome(hostname, home, deps) {
+    if (hostname === os.hostname())
+        return canonicalizeHome(home, deps);
+    if (home === "~" || home.startsWith("~/")) {
+        return home === "~" ? home : `~/${path.posix.normalize(home.slice(2))}`;
+    }
+    if (!path.isAbsolute(home)) {
+        throw new LanesConfigError("invalid_config", `Host-scoped home for remote host ${JSON.stringify(hostname)} must be absolute or start with ~/`, { hostname, home });
+    }
+    return path.normalize(home);
+}
+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 positiveNumber(value, field, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new LanesConfigError("invalid_config", `${field} must be a positive finite number`, { 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.hosts !== undefined) {
+        const field = `providers.${provider}.accounts.${id}.hosts`;
+        if (!isPlainObject(raw.hosts)) {
+            throw new LanesConfigError("invalid_config", `${field} must be an object keyed by non-empty hostnames`, { provider, account: id, field });
+        }
+        const hosts = Object.create(null);
+        for (const [hostname, value] of Object.entries(raw.hosts)) {
+            const hostField = `${field}.${hostname}`;
+            if (hostname.trim().length === 0 || hostname.trim() !== hostname) {
+                throw new LanesConfigError("invalid_config", `${field} hostnames must be non-empty and have no surrounding whitespace`, { provider, account: id, field, hostname });
+            }
+            if (!isPlainObject(value) || Object.keys(value).some((key) => key !== "home")) {
+                throw new LanesConfigError("invalid_config", `${hostField} must be an object containing only a home field`, { provider, account: id, field: hostField });
+            }
+            if (typeof value.home !== "string" || value.home.trim().length === 0) {
+                throw new LanesConfigError("invalid_config", `${hostField}.home must be a non-empty string`, { provider, account: id, field: `${hostField}.home` });
+            }
+            hosts[hostname] = { home: canonicalizeHostHome(hostname, value.home, deps) };
+        }
+        account.hosts = hosts;
+    }
+    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 parseFastModeModels(value, field) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) ||
+        value.some((model) => typeof model !== "string" || model.trim().length === 0)) {
+        throw new LanesConfigError("invalid_fast_mode_models", `${field} must be an array of non-empty strings`, { field, value });
+    }
+    return value.map((model) => model.trim());
+}
+function parsePreferredAccounts(provider, value, accounts) {
+    const field = `providers.${provider}.preferred_accounts`;
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) ||
+        value.some((id) => typeof id !== "string" ||
+            id.trim().length === 0 ||
+            id.trim() !== id)) {
+        throw new LanesConfigError("invalid_preferred_accounts", `${field} must be an array of non-empty account ids without surrounding whitespace`, { provider, field });
+    }
+    const preferred = value;
+    const seen = new Set();
+    for (const id of preferred) {
+        if (seen.has(id)) {
+            throw new LanesConfigError("invalid_preferred_accounts", `${field} contains duplicate account ${JSON.stringify(id)}`, { provider, field, account: id });
+        }
+        if (accounts[id] === undefined) {
+            throw new LanesConfigError("preferred_account_unconfigured", `${field} names unconfigured account ${JSON.stringify(id)}`, { provider, field, account: id, accounts: Object.keys(accounts) });
+        }
+        seen.add(id);
+    }
+    return [...preferred];
+}
+export function assertUniqueAccountHomes(provider, accounts) {
+    // An override must not let one account reuse another account's shared default home.
+    const declaredHomes = new Map();
+    for (const [id, account] of Object.entries(accounts)) {
+        const homes = new Set([
+            account.home,
+            ...Object.values(account.hosts ?? {}).map(({ home }) => home),
+        ]);
+        for (const home of homes) {
+            const prior = declaredHomes.get(home);
+            if (prior !== undefined && prior !== id) {
+                throw new LanesConfigError("duplicate_account_home", `providers.${provider} accounts ${JSON.stringify(prior)} and ${JSON.stringify(id)} declare the same home ${home}`, { provider, accounts: [prior, id], home });
+            }
+            declaredHomes.set(home, id);
+        }
+    }
+    const hostnames = new Set(Object.values(accounts).flatMap((account) => Object.keys(account.hosts ?? {})));
+    const check = (hostname) => {
+        const seen = new Map();
+        for (const [id, account] of Object.entries(accounts)) {
+            const home = hostname === undefined
+                ? account.home
+                : account.hosts?.[hostname]?.home ?? account.home;
+            const prior = seen.get(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 ${home}${hostname === undefined ? "" : ` on host ${JSON.stringify(hostname)}`}`, {
+                    provider,
+                    accounts: [prior, id],
+                    home,
+                    ...(hostname !== undefined ? { hostname } : {}),
+                });
+            }
+            seen.set(home, id);
+        }
+    };
+    check();
+    for (const hostname of hostnames)
+        check(hostname);
+}
+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);
+        }
+    }
+    assertUniqueAccountHomes(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,
+        preferred_accounts: parsePreferredAccounts(provider, raw.preferred_accounts, accounts),
+    };
+    if (provider === "codex") {
+        parsed.fast_mode_models = parseFastModeModels(raw.fast_mode_models, `providers.${provider}.fast_mode_models`);
+    }
+    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.auto_compact_tokens !== undefined) {
+        parsed.auto_compact_tokens = positiveInt(raw.auto_compact_tokens, `providers.${provider}.auto_compact_tokens`);
+    }
+    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`);
+    }
+    if (raw.quota_default_hold_ms !== undefined) {
+        parsed.quota_default_hold_ms = positiveInt(raw.quota_default_hold_ms, `providers.${provider}.quota_default_hold_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),
+    };
+}
+function parseTrackerChecks(raw) {
+    const tracker = raw === undefined ? {} : raw;
+    if (!isPlainObject(tracker)) {
+        throw new LanesConfigError("invalid_config", "tracker must be an object");
+    }
+    const checks = tracker.checks === undefined ? {} : tracker.checks;
+    if (!isPlainObject(checks)) {
+        throw new LanesConfigError("invalid_config", "tracker.checks must be an object");
+    }
+    return {
+        owner_question_surface_ms: positiveInt(checks.owner_question_surface_ms, "tracker.checks.owner_question_surface_ms", DEFAULT_TRACKER_CHECKS.owner_question_surface_ms),
+        open_question_age_ms: positiveInt(checks.open_question_age_ms, "tracker.checks.open_question_age_ms", DEFAULT_TRACKER_CHECKS.open_question_age_ms),
+        status_stale_ms: positiveInt(checks.status_stale_ms, "tracker.checks.status_stale_ms", DEFAULT_TRACKER_CHECKS.status_stale_ms),
+        task_list_stale_ms: positiveInt(checks.task_list_stale_ms, "tracker.checks.task_list_stale_ms", DEFAULT_TRACKER_CHECKS.task_list_stale_ms),
+        blocker_max_age_ms: positiveInt(checks.blocker_max_age_ms, "tracker.checks.blocker_max_age_ms", DEFAULT_TRACKER_CHECKS.blocker_max_age_ms),
+        kpi_value_max_age_ms: positiveInt(checks.kpi_value_max_age_ms, "tracker.checks.kpi_value_max_age_ms", DEFAULT_TRACKER_CHECKS.kpi_value_max_age_ms),
+        directive_ack_timeout_ms: positiveInt(checks.directive_ack_timeout_ms, "tracker.checks.directive_ack_timeout_ms", DEFAULT_TRACKER_CHECKS.directive_ack_timeout_ms),
+    };
+}
+function parseRunawaySearchGuard(raw) {
+    const guard = raw === undefined ? {} : raw;
+    if (!isPlainObject(guard)) {
+        throw new LanesConfigError("invalid_config", "runaway_search_guard must be an object");
+    }
+    return {
+        max_age_seconds: positiveInt(guard.max_age_seconds, "runaway_search_guard.max_age_seconds", DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG.max_age_seconds),
+        find_maxdepth_exempt: positiveInt(guard.find_maxdepth_exempt, "runaway_search_guard.find_maxdepth_exempt", DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG.find_maxdepth_exempt),
+    };
+}
+export function documentedDefaultConfig(deps = defaultDeps()) {
+    const providers = {};
+    for (const provider of LANE_PROVIDERS) {
+        const providerConfig = {
+            max_running: DEFAULT_PROVIDER_MAX_RUNNING[provider],
+            max_queued: DEFAULT_MAX_QUEUED,
+            accounts: defaultAccountMap(provider, deps),
+            preferred_accounts: [],
+        };
+        if (provider === "codex")
+            providerConfig.fast_mode_models = [];
+        providers[provider] = providerConfig;
+    }
+    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 },
+        tracker: { checks: { ...DEFAULT_TRACKER_CHECKS } },
+        runaway_search_guard: { ...DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG },
+        low_disk_min_free_bytes: DEFAULT_LOW_DISK_MIN_FREE_BYTES,
+        codex_rollout_compress_after_hours: DEFAULT_CODEX_ROLLOUT_COMPRESS_AFTER_HOURS,
+        codex_rollout_delete_after_days: DEFAULT_CODEX_ROLLOUT_DELETE_AFTER_DAYS,
+        session_question_timeout_secs: DEFAULT_SESSION_QUESTION_TIMEOUT_SECS,
+        blocker_freshness_hours: DEFAULT_BLOCKER_FRESHNESS_HOURS,
+        kr_freshness_hours: DEFAULT_KR_FRESHNESS_HOURS,
+    };
+}
+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);
+    }
+    const compressAfterHours = positiveInt(raw.codex_rollout_compress_after_hours, "codex_rollout_compress_after_hours", DEFAULT_CODEX_ROLLOUT_COMPRESS_AFTER_HOURS);
+    const deleteAfterDays = positiveInt(raw.codex_rollout_delete_after_days, "codex_rollout_delete_after_days", DEFAULT_CODEX_ROLLOUT_DELETE_AFTER_DAYS);
+    if (deleteAfterDays * 24 < compressAfterHours) {
+        throw new LanesConfigError("invalid_config", "codex_rollout_delete_after_days must be at least codex_rollout_compress_after_hours / 24", { codex_rollout_compress_after_hours: compressAfterHours, codex_rollout_delete_after_days: deleteAfterDays });
+    }
+    return {
+        schema_version: typeof raw.schema_version === "string"
+            ? raw.schema_version
+            : CONFIG_SCHEMA_VERSION,
+        providers,
+        throttle: parseThrottle(raw.throttle),
+        liveness: parseLiveness(raw.liveness),
+        tracker: { checks: parseTrackerChecks(raw.tracker) },
+        runaway_search_guard: parseRunawaySearchGuard(raw.runaway_search_guard),
+        low_disk_min_free_bytes: positiveInt(raw.low_disk_min_free_bytes, "low_disk_min_free_bytes", DEFAULT_LOW_DISK_MIN_FREE_BYTES),
+        codex_rollout_compress_after_hours: compressAfterHours,
+        codex_rollout_delete_after_days: deleteAfterDays,
+        session_question_timeout_secs: positiveInt(raw.session_question_timeout_secs, "session_question_timeout_secs", DEFAULT_SESSION_QUESTION_TIMEOUT_SECS),
+        blocker_freshness_hours: positiveNumber(raw.blocker_freshness_hours, "blocker_freshness_hours", DEFAULT_BLOCKER_FRESHNESS_HOURS),
+        kr_freshness_hours: positiveNumber(raw.kr_freshness_hours, "kr_freshness_hours", DEFAULT_KR_FRESHNESS_HOURS),
+    };
+}
+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;
+}
+/** Claude Code auto-compaction threshold, defaulting to 200,000 tokens. */
+export function providerAutoCompactTokens(provider) {
+    return provider.auto_compact_tokens ?? DEFAULT_AUTO_COMPACT_TOKENS;
+}
+/** 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;
+}
+/** Hold for a reset-less 429 on this provider's accounts. */
+export function providerQuotaDefaultHoldMs(provider) {
+    return provider.quota_default_hold_ms ?? DEFAULT_QUOTA_HOLD_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/constants.d.ts

@@ -0,0 +1,3 @@
+/** Maximum number of lane levels below the user. */
+export declare const MAX_LANE_DEPTH = 3;
+//# sourceMappingURL=constants.d.ts.map

package/dist/lib/lanes/constants.js

@@ -0,0 +1,3 @@
+/** Maximum number of lane levels below the user. */
+export const MAX_LANE_DEPTH = 3;
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,15 @@
+import { type DeliveryLane, type LaneDeliveryMechanism } from "./delivery.js";
+export interface LaneDeliveryHandlers<T> {
+    dropbox: () => T | Promise<T>;
+    resume: () => T | Promise<T>;
+}
+/**
+ * The shared side-effect seam for lane messages. Both `hq lanes message` and
+ * `hq monitor` use the same delivery decision and cannot choose a provider
+ * path from state independently.
+ */
+export declare function dispatchLaneDelivery<T>(lane: DeliveryLane, handlers: LaneDeliveryHandlers<T>, resolvedMechanism?: LaneDeliveryMechanism): Promise<{
+    mechanism: LaneDeliveryMechanism;
+    value: T;
+}>;
+//# sourceMappingURL=delivery-core.d.ts.map

package/dist/lib/lanes/delivery-core.js

@@ -0,0 +1,21 @@
+import { deliveryRefusalReason, laneDeliveryMechanism, } from "./delivery.js";
+import { LanesError } from "./errors.js";
+/**
+ * The shared side-effect seam for lane messages. Both `hq lanes message` and
+ * `hq monitor` use the same delivery decision and cannot choose a provider
+ * path from state independently.
+ */
+export async function dispatchLaneDelivery(lane, handlers, resolvedMechanism = laneDeliveryMechanism(lane)) {
+    const mechanism = resolvedMechanism;
+    if (mechanism === "none") {
+        const message = deliveryRefusalReason(lane);
+        throw new LanesError("lane_not_accepting_messages", message, {
+            state: lane.state,
+            provider: lane.provider,
+            message,
+        });
+    }
+    const value = await handlers[mechanism]();
+    return { mechanism, value };
+}
+//# sourceMappingURL=delivery-core.js.map