@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/lanes/store.js

@@ -0,0 +1,1822 @@
+/**
+ * File-backed lane / question record store (spec §10, §10.1).
+ *
+ * Root: workspace/lanes/ under the HQ root. One stable path per record;
+ * `status` is the pending/answered discriminator — files are never moved
+ * between directories. Every mutation is temp-file-plus-rename and a
+ * compare-and-set on `version`. Histories are capped at 50 at the append site.
+ */
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import semver from "semver";
+import { CLI_VERSION } from "../../cli-version.js";
+import { generateUlid } from "../mesh/live/ulid.js";
+import { resolveLanesHqRoot } from "./hq-root.js";
+import { readOutpostIdentity } from "./admission-host.js";
+import { LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesError, isLaneVersionConflict, } from "./errors.js";
+import { HISTORY_CAP, HOST_KINDS, LANE_STORY_STATUSES, LANE_SCHEMA_VERSION, QUESTION_SCHEMA_VERSION, SENIOR_KINDS, isHostKind, isLaneProvider, isQueuedReason, isLaneState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseMajorSchema, REQUIRED_LANE_RECORD_FIELDS, LANE_FIELD_WRITERS, LANE_WRITERS, } from "./types.js";
+import { laneStories } from "./stories.js";
+import { laneStoryLedgerEnabled, syncLaneToProjectStoryLedger, } from "./story-ledger.js";
+export const LANES_STORE_REL = path.join("workspace", "lanes");
+export const LANE_RECORDS_DIR = "lanes";
+export const QUESTION_RECORDS_DIR = "questions";
+export const PENDING_INDEX_DIR = path.join("questions", "index", "pending");
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 10;
+const LOCK_TIMEOUT_MS = 5_000;
+function defaultStoreDeps() {
+    return {
+        now: () => new Date(),
+        hostname: () => os.hostname(),
+        outpostIdentity: () => readOutpostIdentity(),
+        mkdirSync: fs.mkdirSync.bind(fs),
+        readFileSync: fs.readFileSync.bind(fs),
+        writeFileSync: fs.writeFileSync.bind(fs),
+        renameSync: fs.renameSync.bind(fs),
+        unlinkSync: fs.unlinkSync.bind(fs),
+        existsSync: fs.existsSync.bind(fs),
+        readdirSync: fs.readdirSync.bind(fs),
+        openSync: fs.openSync.bind(fs),
+        closeSync: fs.closeSync.bind(fs),
+        fsyncSync: fs.fsyncSync.bind(fs),
+        chmodSync: fs.chmodSync.bind(fs),
+    };
+}
+export function resolveStoreHqRoot(hqRoot, env = process.env, cwd) {
+    return hqRoot ?? resolveLanesHqRoot({ env, cwd });
+}
+export function lanesStoreRoot(hqRoot) {
+    return path.join(resolveStoreHqRoot(hqRoot), LANES_STORE_REL);
+}
+export function laneRecordPath(hqRoot, laneId) {
+    return path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR, `${laneId}.json`);
+}
+export function questionRecordPath(hqRoot, questionId) {
+    return path.join(lanesStoreRoot(hqRoot), QUESTION_RECORDS_DIR, `${questionId}.json`);
+}
+export function pendingMarkerPath(hqRoot, questionId) {
+    return path.join(lanesStoreRoot(hqRoot), PENDING_INDEX_DIR, questionId);
+}
+export function sanitizeHostComponent(hostname) {
+    const cleaned = hostname
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return (cleaned || "host").slice(0, 32);
+}
+/** Collision-safe across machines: ULID plus a host component. */
+export function mintLaneId(deps = defaultStoreDeps()) {
+    const host = sanitizeHostComponent(deps.hostname());
+    const timestampMs = deps.now().getTime();
+    return `${(deps.generateLaneUlid ?? generateUlid)(timestampMs)}_${host}`;
+}
+export function mintQuestionId(deps = defaultStoreDeps()) {
+    const host = sanitizeHostComponent(deps.hostname());
+    const extra = randomBytes(2).toString("hex");
+    return `q_${generateUlid(deps.now().getTime())}_${host}_${extra}`;
+}
+export function appendCappedHistory(history, entry, cap = HISTORY_CAP) {
+    const next = [...history, entry];
+    if (next.length <= cap)
+        return next;
+    return next.slice(next.length - cap);
+}
+function ensureDir(dir, deps) {
+    deps.mkdirSync(dir, { recursive: true });
+}
+function fsyncDir(dir, deps) {
+    try {
+        const fd = deps.openSync(dir, "r");
+        try {
+            deps.fsyncSync(fd);
+        }
+        finally {
+            deps.closeSync(fd);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EISDIR" || code === "EINVAL" || code === "ENOTSUP")
+            return;
+        // Directory fsync is best-effort on platforms that reject it; log once.
+        process.stderr.write(`lanes store: directory fsync failed for ${dir}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+function atomicWriteJson(target, value, deps) {
+    const dir = path.dirname(target);
+    ensureDir(dir, deps);
+    const tmp = path.join(dir, `.${path.basename(target)}.tmp.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}`);
+    let fd;
+    try {
+        fd = deps.openSync(tmp, "wx");
+        const buf = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+        fs.writeSync(fd, buf);
+        deps.fsyncSync(fd);
+        deps.closeSync(fd);
+        fd = undefined;
+        deps.renameSync(tmp, target);
+        fsyncDir(dir, deps);
+        try {
+            deps.chmodSync(target, 0o600);
+        }
+        catch (err) {
+            process.stderr.write(`lanes store: chmod 0600 failed for ${target}: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    catch (err) {
+        if (fd !== undefined) {
+            try {
+                deps.closeSync(fd);
+            }
+            catch (closeErr) {
+                process.stderr.write(`lanes store: close failed for ${tmp}: ${closeErr instanceof Error ? closeErr.message : String(closeErr)}\n`);
+            }
+        }
+        try {
+            deps.unlinkSync(tmp);
+        }
+        catch (unlinkErr) {
+            const code = unlinkErr.code;
+            if (code !== "ENOENT") {
+                process.stderr.write(`lanes store: unlink tmp failed for ${tmp}: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}\n`);
+            }
+        }
+        throw err;
+    }
+}
+function wait(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function lockPathFor(recordPath) {
+    return `${recordPath}.lock`;
+}
+function withRecordLock(recordPath, deps, fn) {
+    const lockPath = lockPathFor(recordPath);
+    ensureDir(path.dirname(recordPath), deps);
+    const started = Date.now();
+    while (true) {
+        let fd;
+        try {
+            fd = deps.openSync(lockPath, "wx");
+            try {
+                fs.writeSync(fd, Buffer.from(`${process.pid}\n${Date.now()}\n`, "utf8"));
+            }
+            catch (err) {
+                deps.closeSync(fd);
+                fd = undefined;
+                throw err;
+            }
+            try {
+                return fn();
+            }
+            finally {
+                try {
+                    deps.closeSync(fd);
+                }
+                catch (err) {
+                    process.stderr.write(`lanes store: lock close failed for ${lockPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+                try {
+                    deps.unlinkSync(lockPath);
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code !== "ENOENT") {
+                        process.stderr.write(`lanes store: lock unlink failed for ${lockPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+            if (Date.now() - started > LOCK_TIMEOUT_MS) {
+                throw new LanesError("store_lock_timeout", `Timed out waiting for lock ${lockPath}`, { path: lockPath });
+            }
+            try {
+                const raw = deps.readFileSync(lockPath, "utf8");
+                const tsLine = raw.split("\n")[1];
+                const ts = tsLine ? Number(tsLine) : NaN;
+                if (Number.isFinite(ts) && Date.now() - ts > LOCK_STALE_MS) {
+                    try {
+                        deps.unlinkSync(lockPath);
+                    }
+                    catch (unlinkErr) {
+                        const unlinkCode = unlinkErr.code;
+                        if (unlinkCode !== "ENOENT")
+                            throw unlinkErr;
+                    }
+                    continue;
+                }
+            }
+            catch (statErr) {
+                const statCode = statErr.code;
+                if (statCode !== "ENOENT") {
+                    process.stderr.write(`lanes store: stale-lock probe failed for ${lockPath}: ${statErr instanceof Error ? statErr.message : String(statErr)}\n`);
+                }
+            }
+            wait(LOCK_RETRY_MS);
+        }
+    }
+}
+/** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
+export function withLaneRecordFileLock(recordPath, fn) {
+    return withRecordLock(recordPath, defaultStoreDeps(), fn);
+}
+function readJsonFile(filePath, deps) {
+    let text;
+    try {
+        text = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new LaneSchemaError(`Invalid JSON in ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new LaneSchemaError(`Expected non-empty string for ${field}`, {
+            field,
+        });
+    }
+    return value;
+}
+function requireTimestamp(value, field, filePath) {
+    const parsedAt = typeof value === "string" ? Date.parse(value) : NaN;
+    const datePart = typeof value === "string" ? value.slice(0, 10) : "";
+    const datePartAt = /^\d{4}-\d{2}-\d{2}$/.test(datePart)
+        ? Date.parse(`${datePart}T00:00:00.000Z`)
+        : NaN;
+    if (typeof value !== "string" ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) ||
+        !Number.isFinite(parsedAt) ||
+        !Number.isFinite(datePartAt) ||
+        new Date(datePartAt).toISOString().slice(0, 10) !== datePart) {
+        throw new LaneSchemaError(`Expected ISO timestamp for ${field}`, {
+            path: filePath,
+            field,
+            value,
+        });
+    }
+    return value;
+}
+function requireInt(value, field) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new LaneSchemaError(`Expected integer for ${field}`, { field });
+    }
+    return value;
+}
+/**
+ * Company on a lane/question record is either a slug+uid pair or JSON `null`.
+ * Absence (omitted key) is normalised to `null`. Empty strings stay a schema
+ * error so a no-company lane cannot be confused with a broken company object.
+ */
+function parseOptionalCompanyField(raw, filePath) {
+    if (raw.company === undefined) {
+        raw.company = null;
+        return;
+    }
+    if (raw.company === null)
+        return;
+    if (!isPlainObject(raw.company)) {
+        throw new LaneSchemaError("company must be an object", { path: filePath });
+    }
+    requireString(raw.company.slug, "company.slug");
+    requireString(raw.company.uid, "company.uid");
+}
+function parseOptionalMeshCompanyField(raw, filePath) {
+    if (raw.mesh_company === undefined)
+        return;
+    if (!isPlainObject(raw.mesh_company)) {
+        throw new LaneSchemaError("mesh_company must be an object", { path: filePath });
+    }
+    requireString(raw.mesh_company.slug, "mesh_company.slug");
+    requireString(raw.mesh_company.uid, "mesh_company.uid");
+}
+function legacyLaneStory(raw) {
+    const status = raw.state === "blocked"
+        ? "blocked"
+        : raw.story_status === "review"
+            ? "review"
+            : raw.story_status === "done" || raw.story_complete === true
+                ? "review"
+                : "in_progress";
+    const story = {
+        project_id: requireString(raw.project_id, "project_id"),
+        story_id: requireString(raw.story_id, "story_id"),
+        status,
+        added_at: requireString(raw.created_at, "created_at"),
+        updated_at: requireString(raw.updated_at, "updated_at"),
+    };
+    if (typeof raw.blocked_reason === "string" && raw.blocked_reason.length > 0) {
+        story.blocked_reason = raw.blocked_reason;
+    }
+    return story;
+}
+function parseLaneStories(raw, filePath) {
+    if (raw.stories === undefined) {
+        if (raw.story_id === "" && typeof raw.no_story_reason === "string") {
+            raw.stories = [];
+            return;
+        }
+        // v1 records carried one story in the top-level fields. Keep the old
+        // fields authoritative for the migration and give worker-completed work
+        // the review state until a senior explicitly verifies it.
+        raw.stories = [legacyLaneStory(raw)];
+        return;
+    }
+    if (!Array.isArray(raw.stories) ||
+        (raw.stories.length === 0 && !(raw.story_id === "" && typeof raw.no_story_reason === "string"))) {
+        throw new LaneSchemaError("stories must be a non-empty array when present", {
+            path: filePath,
+            field: "stories",
+        });
+    }
+    for (const [index, value] of raw.stories.entries()) {
+        const field = `stories[${index}]`;
+        if (!isPlainObject(value)) {
+            throw new LaneSchemaError(`${field} must be an object`, { path: filePath, field });
+        }
+        requireString(value.project_id, `${field}.project_id`);
+        requireString(value.story_id, `${field}.story_id`);
+        requireString(value.added_at, `${field}.added_at`);
+        requireString(value.updated_at, `${field}.updated_at`);
+        if (typeof value.status !== "string" ||
+            !LANE_STORY_STATUSES.includes(value.status)) {
+            throw new LaneSchemaError(`Unknown story status ${JSON.stringify(value.status)}`, {
+                path: filePath,
+                field: `${field}.status`,
+                value: value.status,
+                accepted: [...LANE_STORY_STATUSES],
+            });
+        }
+        if (value.blocked_reason !== undefined) {
+            requireString(value.blocked_reason, `${field}.blocked_reason`);
+        }
+        if (value.verified_at !== undefined) {
+            requireString(value.verified_at, `${field}.verified_at`);
+        }
+        if (value.verified_by !== undefined) {
+            if (!isPlainObject(value.verified_by)) {
+                throw new LaneSchemaError(`${field}.verified_by must be an object`, {
+                    path: filePath,
+                    field: `${field}.verified_by`,
+                });
+            }
+            if (!isSeniorKind(value.verified_by.kind)) {
+                throw new LaneSchemaError(`Unknown senior kind ${JSON.stringify(value.verified_by.kind)}`, { path: filePath, field: `${field}.verified_by.kind` });
+            }
+            if (value.verified_by.kind !== "user") {
+                requireString(value.verified_by.id, `${field}.verified_by.id`);
+            }
+        }
+    }
+}
+export function parseLaneRecord(raw, filePath) {
+    if (!isPlainObject(raw)) {
+        throw new LaneSchemaError("Lane record must be a JSON object", {
+            path: filePath,
+        });
+    }
+    for (const field of REQUIRED_LANE_RECORD_FIELDS) {
+        if (!(field in raw)) {
+            throw new LaneSchemaError(`Missing required lane record field ${field}`, { path: filePath, field });
+        }
+    }
+    const schema_version = requireString(raw.schema_version, "schema_version");
+    parseMajorSchema(schema_version, "hq-lane", 1);
+    requireString(raw.lane_id, "lane_id");
+    if (raw.written_by_version !== undefined) {
+        const writtenByVersion = requireString(raw.written_by_version, "written_by_version");
+        if (!semver.valid(writtenByVersion)) {
+            throw new LaneSchemaError("written_by_version must be a valid semver version", {
+                path: filePath,
+                field: "written_by_version",
+                value: writtenByVersion,
+            });
+        }
+    }
+    if (raw.owner_written_by_version !== undefined) {
+        const ownerWrittenByVersion = requireString(raw.owner_written_by_version, "owner_written_by_version");
+        if (!semver.valid(ownerWrittenByVersion)) {
+            throw new LaneSchemaError("owner_written_by_version must be a valid semver version", {
+                path: filePath,
+                field: "owner_written_by_version",
+                value: ownerWrittenByVersion,
+            });
+        }
+    }
+    requireInt(raw.version, "version");
+    requireInt(raw.depth, "depth");
+    requireInt(raw.priority, "priority");
+    if (raw.ended_at !== undefined) {
+        requireTimestamp(raw.ended_at, "ended_at", filePath);
+    }
+    if (raw.envelope_summary !== undefined &&
+        (typeof raw.envelope_summary !== "string" || raw.envelope_summary.trim() === "")) {
+        throw new LaneSchemaError("envelope_summary must be a non-empty string when present", {
+            path: filePath,
+            field: "envelope_summary",
+            value: raw.envelope_summary,
+        });
+    }
+    if (raw.hire_grant !== undefined &&
+        (typeof raw.hire_grant !== "number" || !Number.isSafeInteger(raw.hire_grant) || raw.hire_grant < 0)) {
+        throw new LaneSchemaError("Expected non-negative safe integer for hire_grant", {
+            path: filePath,
+            field: "hire_grant",
+            value: raw.hire_grant,
+        });
+    }
+    if (raw.keep_alive !== undefined && typeof raw.keep_alive !== "boolean") {
+        throw new LaneSchemaError("keep_alive must be a boolean", {
+            path: filePath,
+            field: "keep_alive",
+            value: raw.keep_alive,
+        });
+    }
+    if (raw.keep_alive_standing !== undefined && typeof raw.keep_alive_standing !== "boolean") {
+        throw new LaneSchemaError("keep_alive_standing must be a boolean", {
+            path: filePath,
+            field: "keep_alive_standing",
+            value: raw.keep_alive_standing,
+        });
+    }
+    const keepAliveBlockedReason = raw.keep_alive_blocked_reason;
+    const validKeepAliveBlockedReasons = [
+        "not_opted_in",
+        "missing_opt_in_time",
+        "envelope_before_opt_in",
+        "interruption_before_opt_in",
+        "missing_interruption_time",
+        "retired",
+        "superseded",
+        "retired_list_invalid",
+        "terminal_state",
+    ];
+    if (keepAliveBlockedReason !== undefined &&
+        (typeof keepAliveBlockedReason !== "string" ||
+            !validKeepAliveBlockedReasons.includes(keepAliveBlockedReason))) {
+        throw new LaneSchemaError("keep_alive_blocked_reason is invalid", {
+            path: filePath,
+            field: "keep_alive_blocked_reason",
+            value: keepAliveBlockedReason,
+        });
+    }
+    if (raw.keep_alive_resume_count !== undefined &&
+        (typeof raw.keep_alive_resume_count !== "number" ||
+            !Number.isSafeInteger(raw.keep_alive_resume_count) ||
+            raw.keep_alive_resume_count < 0 || raw.keep_alive_resume_count > 24)) {
+        throw new LaneSchemaError("keep_alive_resume_count must be an integer from 0 through 24", {
+            path: filePath,
+            field: "keep_alive_resume_count",
+            value: raw.keep_alive_resume_count,
+        });
+    }
+    if (raw.keep_alive_blocked_resume_streak !== undefined &&
+        (typeof raw.keep_alive_blocked_resume_streak !== "number" ||
+            !Number.isSafeInteger(raw.keep_alive_blocked_resume_streak) ||
+            raw.keep_alive_blocked_resume_streak < 0 || raw.keep_alive_blocked_resume_streak > 2)) {
+        throw new LaneSchemaError("keep_alive_blocked_resume_streak must be an integer from 0 through 2", {
+            path: filePath,
+            field: "keep_alive_blocked_resume_streak",
+            value: raw.keep_alive_blocked_resume_streak,
+        });
+    }
+    for (const field of [
+        "keep_alive_opted_in_at",
+        "keep_alive_last_resume_at",
+        "keep_alive_next_eligible_at",
+        "keep_alive_exhausted_at",
+        "interrupted_at",
+        "last_run_usage_at",
+    ]) {
+        if (raw[field] !== undefined)
+            requireTimestamp(raw[field], field, filePath);
+    }
+    requireString(raw.project_id, "project_id");
+    if (typeof raw.story_id !== "string" ||
+        (raw.story_id.trim() === "" && raw.no_story_reason === undefined)) {
+        throw new LaneSchemaError("Expected non-empty string for story_id", {
+            path: filePath,
+            field: "story_id",
+            value: raw.story_id,
+        });
+    }
+    if (raw.no_story_reason !== undefined && (typeof raw.no_story_reason !== "string" || raw.no_story_reason.trim() === "")) {
+        throw new LaneSchemaError("no_story_reason must be a non-empty string", { path: filePath, field: "no_story_reason" });
+    }
+    if (raw.story_id.trim() !== "" && raw.no_story_reason !== undefined) {
+        throw new LaneSchemaError("no_story_reason requires an empty story_id", { path: filePath, field: "no_story_reason" });
+    }
+    if (raw.ledger_sync_error !== undefined && (typeof raw.ledger_sync_error !== "string" || raw.ledger_sync_error.trim() === "")) {
+        throw new LaneSchemaError("ledger_sync_error must be a non-empty string", { path: filePath, field: "ledger_sync_error" });
+    }
+    if (raw.pending_question_ids !== undefined && (!Array.isArray(raw.pending_question_ids) ||
+        raw.pending_question_ids.some((id) => typeof id !== "string" || id.trim() === "") ||
+        new Set(raw.pending_question_ids).size !== raw.pending_question_ids.length)) {
+        throw new LaneSchemaError("pending_question_ids must be an array of unique non-empty ids", { path: filePath, field: "pending_question_ids" });
+    }
+    if (raw.envelope_validation_errors !== undefined && (!Array.isArray(raw.envelope_validation_errors) ||
+        raw.envelope_validation_errors.length === 0 ||
+        raw.envelope_validation_errors.some((error) => typeof error !== "string" || error.trim() === ""))) {
+        throw new LaneSchemaError("envelope_validation_errors must be a non-empty array of non-empty strings", { path: filePath, field: "envelope_validation_errors" });
+    }
+    if (raw.fallback_question_cancellation_failures !== undefined) {
+        if (!Array.isArray(raw.fallback_question_cancellation_failures)) {
+            throw new LaneSchemaError("fallback_question_cancellation_failures must be an array", {
+                path: filePath,
+                field: "fallback_question_cancellation_failures",
+            });
+        }
+        for (const [index, entry] of raw.fallback_question_cancellation_failures.entries()) {
+            const field = `fallback_question_cancellation_failures[${index}]`;
+            if (!isPlainObject(entry) ||
+                Object.keys(entry).some((key) => !["at", "caller", "trigger", "question_ids", "error"].includes(key)) ||
+                (entry.trigger !== "message" && entry.trigger !== "resume") ||
+                !Array.isArray(entry.question_ids) ||
+                entry.question_ids.some((id) => typeof id !== "string" || id.trim() === "")) {
+                throw new LaneSchemaError(`${field} must be a fallback question-cancellation failure`, {
+                    path: filePath,
+                    field,
+                });
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+            requireString(entry.caller, `${field}.caller`);
+            requireString(entry.error, `${field}.error`);
+        }
+    }
+    requireTimestamp(raw.created_at, "created_at", filePath);
+    requireTimestamp(raw.updated_at, "updated_at", filePath);
+    if (raw.queued_reason !== undefined && !isQueuedReason(raw.queued_reason)) {
+        throw new LaneSchemaError(`Unknown queued reason ${JSON.stringify(raw.queued_reason)}`, {
+            path: filePath,
+            field: "queued_reason",
+            value: raw.queued_reason,
+        });
+    }
+    let normalized;
+    if (raw.queued_details !== undefined) {
+        const details = raw.queued_details;
+        if (details === null || typeof details !== "object" || Array.isArray(details) ||
+            typeof details.reason !== "string") {
+            throw new LaneSchemaError("queued_details must describe a supported queue condition", {
+                path: filePath,
+                field: "queued_details",
+            });
+        }
+        const detailsRecord = details;
+        if (detailsRecord.reason === "worker_profile_changed") {
+            if ((detailsRecord.expected_hash !== null && typeof detailsRecord.expected_hash !== "string") ||
+                typeof detailsRecord.actual_hash !== "string" || detailsRecord.actual_hash === "" ||
+                typeof detailsRecord.recovery_command !== "string" || detailsRecord.recovery_command.trim() === "") {
+                throw new LaneSchemaError("queued_details must describe a worker_profile_changed queue reason", {
+                    path: filePath,
+                    field: "queued_details",
+                });
+            }
+            if (raw.queued_reason !== "worker_profile_changed") {
+                if (raw.queued_reason === undefined) {
+                    throw new LaneSchemaError("queued_details requires queued_reason worker_profile_changed", {
+                        path: filePath,
+                        field: "queued_details",
+                        queued_reason: raw.queued_reason,
+                    });
+                }
+                normalized = { ...raw };
+                delete normalized.queued_details;
+            }
+        }
+        else if (detailsRecord.reason === "outpost_dispatch_unknown") {
+            if (raw.state !== "queued" ||
+                detailsRecord.outcome_unknown !== true ||
+                (detailsRecord.command_id !== null &&
+                    (typeof detailsRecord.command_id !== "string" || detailsRecord.command_id.trim() === ""))) {
+                throw new LaneSchemaError("queued_details must describe an unknown Outpost dispatch on a queued lane", {
+                    path: filePath,
+                    field: "queued_details",
+                });
+            }
+        }
+        else if (detailsRecord.reason === "low_disk") {
+            if (raw.state !== "queued" || raw.queued_reason !== "low_disk" ||
+                !Number.isSafeInteger(detailsRecord.hq_free_bytes) || detailsRecord.hq_free_bytes < 0 ||
+                !Number.isSafeInteger(detailsRecord.provider_free_bytes) || detailsRecord.provider_free_bytes < 0) {
+                throw new LaneSchemaError("queued_details must describe measured low-disk queue state", {
+                    path: filePath,
+                    field: "queued_details",
+                });
+            }
+            requireTimestamp(detailsRecord.measured_at, "queued_details.measured_at", filePath);
+        }
+        else {
+            throw new LaneSchemaError("queued_details must describe a supported queue condition", {
+                path: filePath,
+                field: "queued_details",
+            });
+        }
+    }
+    if (raw.queued_at !== undefined)
+        requireTimestamp(raw.queued_at, "queued_at", filePath);
+    if (raw.admission_reserved_at !== undefined) {
+        requireTimestamp(raw.admission_reserved_at, "admission_reserved_at", filePath);
+    }
+    if (raw.admission_accounts !== undefined) {
+        if (!Array.isArray(raw.admission_accounts) ||
+            raw.admission_accounts.length === 0 ||
+            raw.admission_accounts.some((account) => typeof account !== "string" || account.trim() === "") ||
+            new Set(raw.admission_accounts).size !== raw.admission_accounts.length) {
+            throw new LaneSchemaError("admission_accounts must be a non-empty array of unique account ids", { path: filePath, field: "admission_accounts" });
+        }
+        if (typeof raw.account !== "string" || !raw.admission_accounts.includes(raw.account)) {
+            throw new LaneSchemaError("account must be present in admission_accounts", { path: filePath, field: "admission_accounts", account: raw.account });
+        }
+    }
+    if (!isLaneState(raw.state)) {
+        throw new LaneSchemaError(`Unknown lane state ${JSON.stringify(raw.state)}`, { path: filePath, value: raw.state });
+    }
+    if (!isLaneProvider(raw.provider)) {
+        throw new LaneSchemaError(`Unknown provider ${JSON.stringify(raw.provider)}`, { path: filePath, value: raw.provider });
+    }
+    if (raw.worker_policy_delivery !== undefined &&
+        raw.worker_policy_delivery !== "hook" &&
+        raw.worker_policy_delivery !== "prompt") {
+        throw new LaneSchemaError(`Unknown worker policy delivery mode ${JSON.stringify(raw.worker_policy_delivery)}`, { path: filePath, field: "worker_policy_delivery", value: raw.worker_policy_delivery });
+    }
+    if (raw.registry_worker !== undefined) {
+        const worker = raw.registry_worker;
+        if (!isPlainObject(worker) || Object.keys(worker).some((key) => !["id", "path", "worker_yaml_sha256", "approval_required", "human_checkpoints"].includes(key))) {
+            throw new LaneSchemaError("registry_worker must be a pinned registry worker record", {
+                path: filePath,
+                field: "registry_worker",
+            });
+        }
+        for (const key of ["id", "path"]) {
+            if (typeof worker[key] !== "string" || worker[key].trim().length === 0) {
+                throw new LaneSchemaError(`registry_worker.${key} must be a non-empty string`, {
+                    path: filePath,
+                    field: `registry_worker.${key}`,
+                });
+            }
+        }
+        const registryPath = worker.path.replaceAll("\\", "/");
+        if (path.posix.isAbsolute(registryPath) || registryPath.split("/").some((part) => part === ".." || part === ".")) {
+            throw new LaneSchemaError("registry_worker.path must stay within HQ_ROOT", {
+                path: filePath,
+                field: "registry_worker.path",
+            });
+        }
+        if (typeof worker.worker_yaml_sha256 !== "string" || !/^sha256:[a-f0-9]{64}$/.test(worker.worker_yaml_sha256)) {
+            throw new LaneSchemaError("registry_worker.worker_yaml_sha256 must be a SHA-256 hash", {
+                path: filePath,
+                field: "registry_worker.worker_yaml_sha256",
+            });
+        }
+        if (typeof worker.approval_required !== "boolean") {
+            throw new LaneSchemaError("registry_worker.approval_required must be a boolean", {
+                path: filePath,
+                field: "registry_worker.approval_required",
+            });
+        }
+        if (!Array.isArray(worker.human_checkpoints) || worker.human_checkpoints.some((checkpoint) => typeof checkpoint !== "string" || checkpoint.trim().length === 0) ||
+            new Set(worker.human_checkpoints).size !== worker.human_checkpoints.length) {
+            throw new LaneSchemaError("registry_worker.human_checkpoints must be unique non-empty strings", {
+                path: filePath,
+                field: "registry_worker.human_checkpoints",
+            });
+        }
+    }
+    if (raw.registry_worker_approval_history !== undefined) {
+        if (!Array.isArray(raw.registry_worker_approval_history)) {
+            throw new LaneSchemaError("registry_worker_approval_history must be an array when present", {
+                path: filePath,
+                field: "registry_worker_approval_history",
+            });
+        }
+        for (const [index, entry] of raw.registry_worker_approval_history.entries()) {
+            const field = `registry_worker_approval_history[${index}]`;
+            if (!isPlainObject(entry)) {
+                throw new LaneSchemaError(`${field} must be an approval audit event`, { path: filePath, field });
+            }
+            const expected = entry.event === "approved"
+                ? ["event", "approval_id", "checkpoint", "registry_worker_id", "worker_yaml_sha256", "reason", "actor", "at"]
+                : entry.event === "consumed"
+                    ? ["event", "approval_id", "envelope_ref", "at"]
+                    : [];
+            if (expected.length === 0 || Object.keys(entry).some((key) => !expected.includes(key))) {
+                throw new LaneSchemaError(`${field} has an unknown event or field`, { path: filePath, field });
+            }
+            for (const key of ["approval_id", ...(entry.event === "approved" ? ["checkpoint", "reason", "actor"] : ["envelope_ref"])]) {
+                if (typeof entry[key] !== "string" || entry[key].trim().length === 0) {
+                    throw new LaneSchemaError(`${field}.${key} must be a non-empty string`, { path: filePath, field });
+                }
+            }
+            if (entry.event === "approved" && entry.worker_yaml_sha256 !== undefined &&
+                (typeof entry.worker_yaml_sha256 !== "string" || !/^sha256:[a-f0-9]{64}$/.test(entry.worker_yaml_sha256))) {
+                throw new LaneSchemaError(`${field}.worker_yaml_sha256 must be a SHA-256 hash`, {
+                    path: filePath,
+                    field: `${field}.worker_yaml_sha256`,
+                });
+            }
+            if (entry.event === "approved" && entry.registry_worker_id !== undefined &&
+                (typeof entry.registry_worker_id !== "string" || entry.registry_worker_id.trim().length === 0)) {
+                throw new LaneSchemaError(`${field}.registry_worker_id must be a non-empty string`, {
+                    path: filePath,
+                    field: `${field}.registry_worker_id`,
+                });
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+        }
+    }
+    parseLaneStories(raw, filePath);
+    if (raw.last_envelope !== undefined) {
+        if (!isPlainObject(raw.last_envelope) || typeof raw.last_envelope.ref !== "string" ||
+            typeof raw.last_envelope.at !== "string" ||
+            !["done", "ask", "blocked"].includes(raw.last_envelope.decision) ||
+            (raw.last_envelope.artifacts !== undefined && !Array.isArray(raw.last_envelope.artifacts)) ||
+            (raw.last_envelope.blocked_reason !== undefined && typeof raw.last_envelope.blocked_reason !== "string")) {
+            throw new LaneSchemaError("last_envelope is malformed", { path: filePath, field: "last_envelope" });
+        }
+    }
+    parseOptionalCompanyField(raw, filePath);
+    parseOptionalMeshCompanyField(raw, filePath);
+    if (!isPlainObject(raw.senior)) {
+        throw new LaneSchemaError("senior must be an object", { path: filePath });
+    }
+    if (!isSeniorKind(raw.senior.kind)) {
+        throw new LaneSchemaError(`Unknown senior kind ${JSON.stringify(raw.senior.kind)}`, {
+            path: filePath,
+            field: "senior.kind",
+            value: raw.senior.kind,
+            accepted: [...SENIOR_KINDS],
+        });
+    }
+    if (raw.senior.kind !== "user") {
+        requireString(raw.senior.id, "senior.id");
+    }
+    if (!isPlainObject(raw.host)) {
+        throw new LaneSchemaError("host must be an object", { path: filePath });
+    }
+    if (!isHostKind(raw.host.kind)) {
+        throw new LaneSchemaError(`Unknown host kind ${JSON.stringify(raw.host.kind)}`, {
+            path: filePath,
+            field: "host.kind",
+            value: raw.host.kind,
+            accepted: [...HOST_KINDS],
+        });
+    }
+    requireString(raw.host.id, "host.id");
+    if (!Array.isArray(raw.senior_history)) {
+        throw new LaneSchemaError("senior_history must be an array", {
+            path: filePath,
+        });
+    }
+    if (raw.account_history !== undefined && !Array.isArray(raw.account_history)) {
+        throw new LaneSchemaError("account_history must be an array when present", {
+            path: filePath,
+        });
+    }
+    if (isPlainObject(raw.pending_resume) &&
+        raw.pending_resume.caller !== undefined) {
+        requireString(raw.pending_resume.caller, "pending_resume.caller");
+    }
+    if (raw.keep_alive_history !== undefined) {
+        if (!Array.isArray(raw.keep_alive_history) || raw.keep_alive_history.length > HISTORY_CAP) {
+            throw new LaneSchemaError(`keep_alive_history must be an array capped at ${HISTORY_CAP} entries`, {
+                path: filePath,
+                field: "keep_alive_history",
+            });
+        }
+        for (const [index, value] of raw.keep_alive_history.entries()) {
+            const field = `keep_alive_history[${index}]`;
+            if (!isPlainObject(value) ||
+                Object.keys(value).some((key) => !["at", "resumed_from", "account"].includes(key)) ||
+                (value.resumed_from !== "done" && value.resumed_from !== "interrupted" && value.resumed_from !== "blocked") ||
+                (value.account !== null && typeof value.account !== "string")) {
+                throw new LaneSchemaError(`${field} must be a keep-alive resume history entry`, {
+                    path: filePath,
+                    field,
+                    value,
+                });
+            }
+            requireTimestamp(value.at, `${field}.at`, filePath);
+        }
+    }
+    if (raw.resume_history !== undefined) {
+        if (!Array.isArray(raw.resume_history) || raw.resume_history.length > HISTORY_CAP) {
+            throw new LaneSchemaError(`resume_history must be an array capped at ${HISTORY_CAP} entries`, {
+                path: filePath,
+                field: "resume_history",
+            });
+        }
+        for (const [index, value] of raw.resume_history.entries()) {
+            const field = `resume_history[${index}]`;
+            if (!isPlainObject(value) ||
+                Object.keys(value).some((key) => !["at", "trigger", "caller"].includes(key))) {
+                throw new LaneSchemaError(`${field} must be a resume history entry`, {
+                    path: filePath,
+                    field,
+                    value,
+                });
+            }
+            requireTimestamp(value.at, `${field}.at`, filePath);
+            requireString(value.trigger, `${field}.trigger`);
+            if (value.caller !== undefined)
+                requireString(value.caller, `${field}.caller`);
+        }
+    }
+    if (raw.stop_history !== undefined) {
+        if (!Array.isArray(raw.stop_history)) {
+            throw new LaneSchemaError("stop_history must be an array when present", {
+                path: filePath,
+                field: "stop_history",
+            });
+        }
+        for (const [index, entry] of raw.stop_history.entries()) {
+            const field = `stop_history[${index}]`;
+            if (!isPlainObject(entry) || Object.keys(entry).some((key) => !["at", "reason"].includes(key))) {
+                throw new LaneSchemaError(`${field} must be a stop history entry`, { path: filePath, field });
+            }
+            if (typeof entry.reason !== "string" || entry.reason.trim() === "") {
+                throw new LaneSchemaError(`${field}.reason must be a non-empty string`, { path: filePath, field });
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+        }
+    }
+    if (raw.settings_history !== undefined) {
+        if (!Array.isArray(raw.settings_history)) {
+            throw new LaneSchemaError("settings_history must be an array when present", {
+                path: filePath,
+                field: "settings_history",
+            });
+        }
+        for (const [index, entry] of raw.settings_history.entries()) {
+            const field = `settings_history[${index}]`;
+            if (!isPlainObject(entry) ||
+                Object.keys(entry).some((key) => !["at", "actor", "model", "effort", "reason"].includes(key)) ||
+                (entry.model === undefined && entry.effort === undefined)) {
+                throw new LaneSchemaError(`${field} must be a settings history entry`, { path: filePath, field });
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+            if (typeof entry.actor !== "string" || entry.actor.trim() === "") {
+                throw new LaneSchemaError(`${field}.actor must be a non-empty string`, { path: filePath, field });
+            }
+            if (entry.reason !== undefined && (typeof entry.reason !== "string" || entry.reason.trim() === "")) {
+                throw new LaneSchemaError(`${field}.reason must be a non-empty string when present`, { path: filePath, field });
+            }
+            for (const key of ["model", "effort"]) {
+                const change = entry[key];
+                if (change === undefined)
+                    continue;
+                if (!isPlainObject(change) ||
+                    Object.keys(change).some((k) => k !== "from" && k !== "to") ||
+                    typeof change.to !== "string" || change.to.trim() === "" ||
+                    (change.from !== null && typeof change.from !== "string")) {
+                    throw new LaneSchemaError(`${field}.${key} must be a {from, to} change`, { path: filePath, field });
+                }
+            }
+        }
+    }
+    if (raw.worker_profile_repin_history !== undefined) {
+        if (!Array.isArray(raw.worker_profile_repin_history)) {
+            throw new LaneSchemaError("worker_profile_repin_history must be an array when present", {
+                path: filePath,
+                field: "worker_profile_repin_history",
+            });
+        }
+        for (const [index, entry] of raw.worker_profile_repin_history.entries()) {
+            const field = `worker_profile_repin_history[${index}]`;
+            if (!isPlainObject(entry) || Object.keys(entry).some((key) => !["old_hash", "new_hash", "actor", "at", "reason"].includes(key))) {
+                throw new LaneSchemaError(`${field} must be an audit entry`, { path: filePath, field });
+            }
+            if (entry.old_hash !== null && (typeof entry.old_hash !== "string" || !entry.old_hash.trim())) {
+                throw new LaneSchemaError(`${field}.old_hash must be a non-empty string or null`, { path: filePath, field });
+            }
+            for (const key of ["new_hash", "actor", "reason"]) {
+                if (typeof entry[key] !== "string" || !entry[key].trim()) {
+                    throw new LaneSchemaError(`${field}.${key} must be a non-empty string`, { path: filePath, field });
+                }
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+        }
+    }
+    if (raw.account_selection !== undefined) {
+        parseLaneAccountSelection(raw.account_selection, filePath);
+    }
+    if (raw.placement_default !== undefined) {
+        const placement = raw.placement_default;
+        if (!isPlainObject(placement) ||
+            (placement.kind !== "local" && placement.kind !== "auto" && placement.kind !== "outpost") ||
+            (placement.kind === "outpost" && (typeof placement.id !== "string" || placement.id.trim() === "")) ||
+            (placement.kind !== "outpost" && "id" in placement)) {
+            throw new LaneSchemaError("placement_default must be local, auto, or a pinned Outpost", {
+                path: filePath,
+                field: "placement_default",
+            });
+        }
+    }
+    if (!Array.isArray(raw.attribution_history)) {
+        throw new LaneSchemaError("attribution_history must be an array", {
+            path: filePath,
+        });
+    }
+    // Spread-preserving: return the original object so unknown keys survive
+    // a parse/rewrite cycle (spec §5.1 field-preservation).
+    return (normalized ?? raw);
+}
+function parseLaneAccountSelection(value, filePath) {
+    const failure = (field) => new LaneSchemaError(`Invalid account_selection.${field}`, {
+        path: filePath,
+        field: `account_selection.${field}`,
+    });
+    if (!isPlainObject(value))
+        throw failure("must be an object");
+    const selection = value;
+    if (typeof selection.account !== "string" || selection.account.trim() === "")
+        throw failure("account");
+    if (selection.signal !== "usage" && selection.signal !== "recent_usage" && selection.signal !== "lane_count" && selection.signal !== "explicit")
+        throw failure("signal");
+    if (selection.reason !== "least_loaded" && selection.reason !== "explicit")
+        throw failure("reason");
+    if (typeof selection.selected_at !== "string" || !Number.isFinite(Date.parse(selection.selected_at)))
+        throw failure("selected_at");
+    const parseHost = (host, field) => {
+        if (!isPlainObject(host) || !isHostKind(host.kind) || typeof host.id !== "string" || host.id.trim() === "")
+            throw failure(field);
+    };
+    parseHost(selection.target_host, "target_host");
+    if (!Array.isArray(selection.considered) || !Array.isArray(selection.skipped_accounts) || !Array.isArray(selection.unavailable_hosts)) {
+        throw failure("arrays");
+    }
+    for (const [index, rowValue] of selection.considered.entries()) {
+        if (!isPlainObject(rowValue))
+            throw failure(`considered.${index}`);
+        const row = rowValue;
+        if (typeof row.account !== "string" || row.account.trim() === "" || typeof row.eligible !== "boolean" || typeof row.live_lanes !== "number" || !Number.isInteger(row.live_lanes) || row.live_lanes < 0 || typeof row.counts_complete !== "boolean" || !Array.isArray(row.hosts))
+            throw failure(`considered.${index}`);
+        if (row.ineligible_reason !== undefined && typeof row.ineligible_reason !== "string")
+            throw failure(`considered.${index}.ineligible_reason`);
+        if (row.recent_usage_at !== undefined && row.recent_usage_at !== null &&
+            (typeof row.recent_usage_at !== "string" || !Number.isFinite(Date.parse(row.recent_usage_at)))) {
+            throw failure(`considered.${index}.recent_usage_at`);
+        }
+        if (row.usage !== null) {
+            if (!isPlainObject(row.usage))
+                throw failure(`considered.${index}.usage`);
+            for (const key of ["five_hour_percent", "weekly_percent"]) {
+                const percent = row.usage[key];
+                if (percent !== undefined && (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0 || percent > 100))
+                    throw failure(`considered.${index}.usage.${key}`);
+            }
+            if (row.usage.sampled_at !== undefined && (typeof row.usage.sampled_at !== "string" || !Number.isFinite(Date.parse(row.usage.sampled_at))))
+                throw failure(`considered.${index}.usage.sampled_at`);
+        }
+        for (const [hostIndex, hostValue] of row.hosts.entries()) {
+            if (!isPlainObject(hostValue))
+                throw failure(`considered.${index}.hosts.${hostIndex}`);
+            const host = hostValue;
+            parseHost(host.host, `considered.${index}.hosts.${hostIndex}.host`);
+            if (typeof host.enabled !== "boolean" || !(host.logged_in === null || typeof host.logged_in === "boolean"))
+                throw failure(`considered.${index}.hosts.${hostIndex}.status`);
+            if (!(host.live_lanes === null || (typeof host.live_lanes === "number" && Number.isInteger(host.live_lanes) && host.live_lanes >= 0)))
+                throw failure(`considered.${index}.hosts.${hostIndex}.live_lanes`);
+            if (!isPlainObject(host.lane_counts))
+                throw failure(`considered.${index}.hosts.${hostIndex}.lane_counts`);
+            for (const key of ["running", "queued", "awaiting_input"]) {
+                const count = host.lane_counts[key];
+                if (!(count === null || (typeof count === "number" && Number.isInteger(count) && count >= 0)))
+                    throw failure(`considered.${index}.hosts.${hostIndex}.lane_counts.${key}`);
+            }
+            if (!["lane_list", "capacity", "capacity_partial", "unavailable"].includes(String(host.count_source)))
+                throw failure(`considered.${index}.hosts.${hostIndex}.count_source`);
+        }
+    }
+    for (const [index, rowValue] of selection.skipped_accounts.entries()) {
+        if (!isPlainObject(rowValue))
+            throw failure(`skipped_accounts.${index}`);
+        const row = rowValue;
+        if (typeof row.account !== "string" || row.account.trim() === "" || typeof row.reason !== "string" || row.reason.trim() === "")
+            throw failure(`skipped_accounts.${index}`);
+        parseHost(row.host, `skipped_accounts.${index}.host`);
+    }
+    for (const [index, rowValue] of selection.unavailable_hosts.entries()) {
+        if (!isPlainObject(rowValue))
+            throw failure(`unavailable_hosts.${index}`);
+        const row = rowValue;
+        if (typeof row.reason !== "string" || row.reason.trim() === "")
+            throw failure(`unavailable_hosts.${index}`);
+        if (isPlainObject(row.host) && row.host.kind === "unknown" && row.host.id === "unknown")
+            continue;
+        parseHost(row.host, `unavailable_hosts.${index}.host`);
+    }
+    return selection;
+}
+export function parseQuestionRecord(raw, filePath) {
+    if (!isPlainObject(raw)) {
+        throw new LaneSchemaError("Question record must be a JSON object", {
+            path: filePath,
+        });
+    }
+    const schema_version = requireString(raw.schema_version, "schema_version");
+    parseMajorSchema(schema_version, "hq-lane-question", 1);
+    if (!isQuestionStatus(raw.status)) {
+        throw new LaneSchemaError(`Unknown question status ${JSON.stringify(raw.status)}`, { path: filePath, value: raw.status });
+    }
+    requireString(raw.question_id, "question_id");
+    requireString(raw.lane_id, "lane_id");
+    if (raw.priority !== undefined && raw.priority !== null && raw.priority !== "P0" && raw.priority !== "P1" && raw.priority !== "P2") {
+        throw new LaneSchemaError("priority must be P0, P1, or P2 when present", {
+            path: filePath,
+            value: raw.priority,
+        });
+    }
+    requireInt(raw.version, "version");
+    requireInt(raw.hop, "hop");
+    parseOptionalCompanyField(raw, filePath);
+    if (!isPlainObject(raw.body)) {
+        throw new LaneSchemaError("body must be an object", { path: filePath });
+    }
+    if (!Array.isArray(raw.routing_history)) {
+        throw new LaneSchemaError("routing_history must be an array", {
+            path: filePath,
+        });
+    }
+    // Optional on the record, but merge-on-read spreads it; a non-array from a
+    // synced sidecar must fail here, inside the per-sidecar skip, not later.
+    if (raw.answer_history !== undefined && !Array.isArray(raw.answer_history)) {
+        throw new LaneSchemaError("answer_history must be an array when present", {
+            path: filePath,
+        });
+    }
+    const delivered_at = raw.delivered_at === undefined ? null : raw.delivered_at;
+    if (delivered_at !== null &&
+        (typeof delivered_at !== "string" || !Number.isFinite(Date.parse(delivered_at)))) {
+        throw new LaneSchemaError("delivered_at must be a valid timestamp or null", {
+            path: filePath,
+            value: delivered_at,
+        });
+    }
+    return {
+        ...raw,
+        delivered_at,
+        ...(raw.priority === null ? { priority: undefined } : {}),
+    };
+}
+/**
+ * HQ Sync sibling-twin grammar from `@indigoai-us/hq-cloud` `buildConflictPath`:
+ * `<file>.json.conflict-<ISO-with-dashes>-<machine>.json`
+ * (legacy twins; current engines park losers under `.hq/conflict-backups/`,
+ * but merge-on-read still has to recover the ones already on disk).
+ */
+export function isConflictSidecarName(recordBasename, name) {
+    if (name === recordBasename || name.startsWith("."))
+        return false;
+    return name.startsWith(`${recordBasename}.conflict-`);
+}
+function sidecarPathsFor(recordPath, deps) {
+    if (deps.conflictSidecarPathsFor) {
+        return [...deps.conflictSidecarPathsFor(recordPath)];
+    }
+    const dir = path.dirname(recordPath);
+    const base = path.basename(recordPath);
+    if (!deps.existsSync(dir))
+        return [];
+    const names = deps.readdirSync(dir);
+    const sidecars = [];
+    for (const name of names) {
+        if (typeof name !== "string")
+            continue;
+        if (!isConflictSidecarName(base, name))
+            continue;
+        sidecars.push(path.join(dir, name));
+    }
+    return sidecars;
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(obj[key])}`).join(",")}}`;
+}
+function historyTimestamp(entry) {
+    if (!isPlainObject(entry))
+        return "";
+    if (typeof entry.at === "string")
+        return entry.at;
+    if (typeof entry.answered_at === "string")
+        return entry.answered_at;
+    return "";
+}
+/**
+ * Attribution identity is the message that caused the re-point (spec §2).
+ * Senior and routing entries have no named id; union is by canonical entry.
+ */
+function attributionIdentity(entry) {
+    if (typeof entry.message_id === "string" && entry.message_id.length > 0) {
+        return `message_id:${entry.message_id}`;
+    }
+    return `entry:${canonicalJson(entry)}`;
+}
+function entryIdentity(entry) {
+    return canonicalJson(entry);
+}
+function questionAnswerHistory(record) {
+    return [
+        ...(record.answer_history ?? []),
+        ...(record.answer ? [record.answer] : []),
+    ];
+}
+function unionHistory(lists, identity, preferred) {
+    const map = new Map();
+    for (const entry of preferred) {
+        map.set(identity(entry), entry);
+    }
+    for (const list of lists) {
+        for (const entry of list) {
+            const id = identity(entry);
+            if (!map.has(id))
+                map.set(id, entry);
+        }
+    }
+    const merged = [...map.values()].sort((a, b) => historyTimestamp(a).localeCompare(historyTimestamp(b)));
+    if (merged.length <= HISTORY_CAP)
+        return merged;
+    return merged.slice(merged.length - HISTORY_CAP);
+}
+function higherVersionRecord(live, others) {
+    let best = live;
+    for (const other of others) {
+        if (other.version > best.version)
+            best = other;
+    }
+    return best;
+}
+function laneStoryIdentity(story) {
+    return `${story.project_id}\u0000${story.story_id}`;
+}
+function mergeLaneStories(records, base) {
+    const baseStories = laneStories(base);
+    const merged = new Map();
+    const baseOrder = [];
+    for (const story of baseStories) {
+        const key = laneStoryIdentity(story);
+        if (!merged.has(key))
+            baseOrder.push(key);
+        merged.set(key, story);
+    }
+    for (const record of records) {
+        if (record === base)
+            continue;
+        for (const story of laneStories(record)) {
+            const key = laneStoryIdentity(story);
+            const current = merged.get(key);
+            if (!current || story.updated_at > current.updated_at) {
+                merged.set(key, story);
+            }
+        }
+    }
+    const sideOnly = [...merged.keys()]
+        .filter((key) => !baseOrder.includes(key))
+        .sort();
+    return [...baseOrder, ...sideOnly]
+        .map((key) => merged.get(key))
+        .filter((story) => story !== undefined);
+}
+export function mergeLaneRecords(live, sidecars) {
+    if (sidecars.length === 0)
+        return live;
+    const all = [live, ...sidecars];
+    const base = higherVersionRecord(live, sidecars);
+    return {
+        ...base,
+        senior_history: unionHistory(all.map((record) => record.senior_history), entryIdentity, base.senior_history),
+        attribution_history: unionHistory(all.map((record) => record.attribution_history), attributionIdentity, base.attribution_history),
+        ...(all.some((record) => record.account_history !== undefined)
+            ? {
+                account_history: unionHistory(all.map((record) => record.account_history ?? []), entryIdentity, base.account_history ?? []),
+            }
+            : {}),
+        ...(all.some((record) => record.worker_profile_repin_history !== undefined)
+            ? {
+                worker_profile_repin_history: unionHistory(all.map((record) => record.worker_profile_repin_history ?? []), entryIdentity, base.worker_profile_repin_history ?? []),
+            }
+            : {}),
+        ...(all.some((record) => record.registry_worker_approval_history !== undefined)
+            ? {
+                registry_worker_approval_history: unionHistory(all.map((record) => record.registry_worker_approval_history ?? []), entryIdentity, base.registry_worker_approval_history ?? []),
+            }
+            : {}),
+        ...(all.some((record) => record.failed_resume_history !== undefined)
+            ? {
+                failed_resume_history: unionHistory(all.map((record) => record.failed_resume_history ?? []), entryIdentity, base.failed_resume_history ?? []),
+            }
+            : {}),
+        ...(all.some((record) => record.resume_history !== undefined)
+            ? {
+                resume_history: unionHistory(all.map((record) => record.resume_history ?? []), entryIdentity, base.resume_history ?? []),
+            }
+            : {}),
+        ...(all.some((record) => record.settings_history !== undefined)
+            ? {
+                settings_history: unionHistory(all.map((record) => record.settings_history ?? []), entryIdentity, base.settings_history ?? []),
+            }
+            : {}),
+        ...(all.some((record) => record.stop_history !== undefined)
+            ? {
+                stop_history: unionHistory(all.map((record) => record.stop_history ?? []), entryIdentity, base.stop_history ?? []),
+            }
+            : {}),
+        stories: mergeLaneStories(all, base),
+    };
+}
+export function mergeQuestionRecords(live, sidecars) {
+    if (sidecars.length === 0)
+        return live;
+    const all = [live, ...sidecars];
+    const base = higherVersionRecord(live, sidecars);
+    const deliveredAt = all
+        .map((record) => record.delivered_at)
+        .filter((value) => typeof value === "string" && Number.isFinite(Date.parse(value)))
+        .sort((a, b) => Date.parse(a) - Date.parse(b))[0] ?? null;
+    return {
+        ...base,
+        delivered_at: deliveredAt,
+        answer_history: unionHistory(all.map(questionAnswerHistory), entryIdentity, questionAnswerHistory(base)),
+        routing_history: unionHistory(all.map((record) => record.routing_history), entryIdentity, base.routing_history),
+    };
+}
+function loadSidecarRecords(recordPath, parse, deps) {
+    const paths = sidecarPathsFor(recordPath, deps);
+    const records = [];
+    for (const sidecarPath of paths) {
+        try {
+            const raw = readJsonFile(sidecarPath, deps);
+            if (raw === null)
+                continue;
+            records.push(parse(raw, sidecarPath));
+        }
+        catch (err) {
+            process.stderr.write(`lanes store: skipping unreadable conflict sidecar ${sidecarPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    return records;
+}
+function readMergedRecord(filePath, parse, merge, deps) {
+    const raw = readJsonFile(filePath, deps);
+    if (raw === null)
+        return null;
+    const live = parse(raw, filePath);
+    const sidecars = loadSidecarRecords(filePath, parse, deps);
+    if (sidecars.length === 0)
+        return live;
+    return merge(live, sidecars);
+}
+export function tryReadLane(hqRoot, laneId, deps = defaultStoreDeps()) {
+    const filePath = laneRecordPath(hqRoot, laneId);
+    return readMergedRecord(filePath, parseLaneRecord, mergeLaneRecords, deps);
+}
+export function readLane(hqRoot, laneId, deps = defaultStoreDeps()) {
+    const record = tryReadLane(hqRoot, laneId, deps);
+    if (!record)
+        throw new LaneNotFoundError("lane", laneId);
+    return record;
+}
+/** Reads all lanes, indexing sidecars once and sorting by creation time then id. */
+export function readAllLanes(hqRoot, deps = defaultStoreDeps()) {
+    const laneIds = listLaneIds(hqRoot, deps);
+    if (laneIds.length === 0)
+        return [];
+    const laneDir = path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR);
+    let names;
+    try {
+        names = deps.readdirSync(laneDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            names = [];
+        else
+            throw err;
+    }
+    const sidecarsByRecord = new Map();
+    for (const name of names) {
+        if (typeof name !== "string")
+            continue;
+        const marker = name.indexOf(".json.conflict-");
+        if (marker < 0 || name.startsWith("."))
+            continue;
+        const recordBasename = name.slice(0, marker + ".json".length);
+        if (!isConflictSidecarName(recordBasename, name))
+            continue;
+        const sidecars = sidecarsByRecord.get(recordBasename) ?? [];
+        sidecars.push(path.join(laneDir, name));
+        sidecarsByRecord.set(recordBasename, sidecars);
+    }
+    const indexedDeps = {
+        ...deps,
+        conflictSidecarPathsFor: (recordPath) => sidecarsByRecord.get(path.basename(recordPath)) ?? [],
+    };
+    const records = [];
+    for (const laneId of laneIds) {
+        try {
+            records.push(readLane(hqRoot, laneId, indexedDeps));
+        }
+        catch (err) {
+            if (!(err instanceof LaneSchemaError))
+                throw err;
+            const filePath = laneRecordPath(hqRoot, laneId);
+            const raw = readJsonFile(filePath, indexedDeps);
+            const host = raw !== null && typeof raw === "object" && !Array.isArray(raw)
+                ? raw.host
+                : undefined;
+            const hostRecord = host !== null && typeof host === "object" && !Array.isArray(host)
+                ? host
+                : undefined;
+            const outpostId = hostRecord?.kind === "outpost" &&
+                typeof hostRecord.id === "string" && hostRecord.id.trim() !== ""
+                ? hostRecord.id
+                : undefined;
+            const identity = indexedDeps.outpostIdentity();
+            const isRemoteMirror = outpostId !== undefined && (identity.kind === "not_outpost" ||
+                (identity.kind === "id" && identity.id !== outpostId));
+            if (!isRemoteMirror)
+                throw err;
+            const field = typeof err.details.field === "string" ? err.details.field : "unknown_field";
+            process.stderr.write(`lanes store: skipping malformed mirrored lane ${laneId} field ${field}: ${err.message}\n`);
+        }
+    }
+    return records.sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at) ||
+        a.lane_id.localeCompare(b.lane_id));
+}
+export function tryReadQuestion(hqRoot, questionId, deps = defaultStoreDeps()) {
+    const filePath = questionRecordPath(hqRoot, questionId);
+    return readMergedRecord(filePath, parseQuestionRecord, mergeQuestionRecords, deps);
+}
+export function readQuestion(hqRoot, questionId, deps = defaultStoreDeps()) {
+    const record = tryReadQuestion(hqRoot, questionId, deps);
+    if (!record)
+        throw new LaneNotFoundError("question", questionId);
+    return record;
+}
+/** Semver precedence includes prerelease identifiers (for example, rc.2 > rc.1). */
+export function isLaneStoreVersionNewer(storedVersion, runningVersion) {
+    if (!semver.valid(storedVersion)) {
+        throw new LanesError("lane_store_version_invalid", "Lane store writer version is not valid semver", {
+            stored_version: storedVersion,
+        });
+    }
+    if (!semver.valid(runningVersion)) {
+        throw new LanesError("lane_store_version_invalid", "Running hq-cli version is not valid semver", {
+            running_version: runningVersion,
+        });
+    }
+    return semver.gt(storedVersion, runningVersion);
+}
+const OLDER_LANE_STORE_WRITE_OVERRIDE = "HQ_LANES_ALLOW_OLDER_WRITE";
+export const LANE_STORE_UPGRADE_COMMAND = "npm install -g @indigoai-us/hq-cli@latest";
+const warnedBackgroundWriterLaneIds = new Set();
+function assertLaneStoreWriteAllowed(lane, laneId, writer) {
+    const storedVersion = lane.written_by_version;
+    if (storedVersion === undefined || !isLaneStoreVersionNewer(storedVersion, CLI_VERSION))
+        return;
+    const warning = `Lane ${laneId} was last written by hq-cli ${storedVersion}, newer than running hq-cli ${CLI_VERSION}. Upgrade with \`${LANE_STORE_UPGRADE_COMMAND}\` before writing.`;
+    if (writer === "command" || writer === "creator") {
+        if (process.env[OLDER_LANE_STORE_WRITE_OVERRIDE] === "1") {
+            console.warn(`${warning} Proceeding because ${OLDER_LANE_STORE_WRITE_OVERRIDE}=1 was set for this command.`);
+            return;
+        }
+        throw new LanesError("lane_store_newer_cli", `${warning} For a one-command override, set ${OLDER_LANE_STORE_WRITE_OVERRIDE}=1.`, {
+            lane_id: laneId,
+            stored_version: storedVersion,
+            running_version: CLI_VERSION,
+            upgrade_command: LANE_STORE_UPGRADE_COMMAND,
+            override: `${OLDER_LANE_STORE_WRITE_OVERRIDE}=1`,
+        });
+    }
+    if (!warnedBackgroundWriterLaneIds.has(laneId)) {
+        warnedBackgroundWriterLaneIds.add(laneId);
+        console.warn(`${warning} Continuing background ${writer} writes and preserving the newer stamp.`);
+    }
+}
+function newestLaneStoreVersion(storedVersion) {
+    if (storedVersion !== undefined && isLaneStoreVersionNewer(storedVersion, CLI_VERSION)) {
+        return storedVersion;
+    }
+    return CLI_VERSION;
+}
+function recordsEquivalentAsideFromClock(current, updated) {
+    if (updated === current)
+        return true;
+    const strip = (record) => {
+        const copy = { ...record };
+        delete copy.version;
+        delete copy.updated_at;
+        return copy;
+    };
+    return JSON.stringify(strip(current)) === JSON.stringify(strip(updated));
+}
+function casWrite(filePath, expectedVersion, parse, merge, updater, deps, options = {}) {
+    return withRecordLock(filePath, deps, () => {
+        const current = readMergedRecord(filePath, parse, merge, deps);
+        if (current === null) {
+            throw new LaneSchemaError(`Record disappeared under lock: ${filePath}`, {
+                path: filePath,
+            });
+        }
+        if (current.version !== expectedVersion) {
+            throw new LaneVersionConflict({
+                path: filePath,
+                expectedVersion,
+                actualVersion: current.version,
+            });
+        }
+        const updated = updater(current);
+        if (recordsEquivalentAsideFromClock(current, updated)) {
+            return current;
+        }
+        options.beforeWrite?.(current);
+        const next = {
+            ...current,
+            ...updated,
+            ...options.stamp?.(current),
+            version: current.version + 1,
+            updated_at: deps.now().toISOString(),
+        };
+        atomicWriteJson(filePath, next, deps);
+        return next;
+    });
+}
+export function createLane(hqRoot, init, deps = defaultStoreDeps()) {
+    const now = deps.now().toISOString();
+    const lane_id = init.lane_id ?? mintLaneId(deps);
+    const filePath = laneRecordPath(hqRoot, lane_id);
+    const record = {
+        ...init,
+        written_by_version: CLI_VERSION,
+        hire_grant: init.hire_grant ?? 0,
+        schema_version: init.schema_version ?? LANE_SCHEMA_VERSION,
+        lane_id,
+        version: 1,
+        created_at: init.created_at ?? now,
+        updated_at: init.updated_at ?? now,
+        ...(init.state === "queued"
+            ? { queued_at: init.queued_at ?? init.created_at ?? now }
+            : {}),
+        senior_history: init.senior_history ?? [],
+        attribution_history: init.attribution_history ?? [],
+    };
+    parseLaneRecord(record, filePath);
+    const created = withRecordLock(filePath, deps, () => {
+        if (deps.existsSync(filePath)) {
+            throw new LanesError("lane_exists", `Lane ${lane_id} already exists`, { lane_id });
+        }
+        atomicWriteJson(filePath, record, deps);
+        return record;
+    });
+    return syncStoryLedgerForLane(hqRoot, created, deps);
+}
+/** Hierarchy lock: separate from record writes so callers can CAS-write while holding it. */
+export function withLaneHireLocks(hqRoot, laneIds, fn, deps = defaultStoreDeps()) {
+    const uniqueIds = [...new Set(laneIds)].sort();
+    const acquire = (index) => {
+        const laneId = uniqueIds[index];
+        if (laneId === undefined)
+            return fn();
+        const lockPath = path.join(lanesStoreRoot(hqRoot), "hire-locks", `${laneId}.json`);
+        return withRecordLock(lockPath, deps, () => acquire(index + 1));
+    };
+    return acquire(0);
+}
+/** Value equality over JSON-shaped record fields; the clone breaks reference identity. */
+function fieldUnchanged(before, after) {
+    if (Object.is(before, after))
+        return true;
+    if (before === undefined || after === undefined)
+        return false;
+    return JSON.stringify(before) === JSON.stringify(after);
+}
+export function updateLane(hqRoot, laneId, expectedVersion, writer, updater, deps = defaultStoreDeps()) {
+    if (!LANE_WRITERS.includes(writer)) {
+        throw new LanesError("lane_writer_unknown", `Unknown lane writer ${String(writer)}`, { writer });
+    }
+    let before;
+    const updated = casWrite(laneRecordPath(hqRoot, laneId), expectedVersion, parseLaneRecord, mergeLaneRecords, (current) => {
+        before = current;
+        // `current` is the pre-update snapshot and stays untouched: the updater
+        // receives a deep clone, so mutating its argument in place cannot reach
+        // the record the ownership check compares against.
+        const updated = updater(structuredClone(current));
+        for (const key of Object.keys(updated)) {
+            if (key === "version" || key === "updated_at" || fieldUnchanged(current[key], updated[key]))
+                continue;
+            const allowedWriters = LANE_FIELD_WRITERS[key];
+            // Unknown forward-version fields are preserved, never assigned an
+            // ownership rule by a v1 reader.
+            if (allowedWriters && !allowedWriters.includes(writer)) {
+                throw new LanesError("lane_writer_unauthorized", `Writer ${writer} cannot write lane field ${key}`, { writer, field: key });
+            }
+        }
+        return updated;
+    }, deps, {
+        beforeWrite: (current) => assertLaneStoreWriteAllowed(current, laneId, writer),
+        stamp: (current) => ({ written_by_version: newestLaneStoreVersion(current.written_by_version) }),
+    });
+    if (laneStoryLedgerEnabled() && before && laneLedgerRelevantChange(before, updated)) {
+        return syncStoryLedgerForLane(hqRoot, updated, deps);
+    }
+    return updated;
+}
+function laneLedgerRelevantChange(before, after) {
+    return before.state !== after.state || before.project_id !== after.project_id ||
+        before.story_id !== after.story_id || before.no_story_reason !== after.no_story_reason ||
+        JSON.stringify(before.pending_question_ids) !== JSON.stringify(after.pending_question_ids) ||
+        JSON.stringify(before.stories) !== JSON.stringify(after.stories) ||
+        JSON.stringify(before.last_envelope) !== JSON.stringify(after.last_envelope);
+}
+function syncStoryLedgerForLane(hqRoot, lane, deps) {
+    if (!laneStoryLedgerEnabled())
+        return lane;
+    try {
+        const questionRefs = [];
+        for (const questionId of lane.pending_question_ids ?? []) {
+            const question = readQuestion(hqRoot, questionId, deps);
+            const sameCompany = question.company === null
+                ? lane.company === null
+                : lane.company !== null &&
+                    question.company.uid === lane.company.uid &&
+                    question.company.slug === lane.company.slug;
+            if (question.lane_id !== lane.lane_id || !sameCompany) {
+                throw new LanesError("story_ledger_question_mismatch", `Pending question ${questionId} does not belong to lane ${lane.lane_id}`, {
+                    lane_id: lane.lane_id,
+                    question_id: questionId,
+                    question_lane_id: question.lane_id,
+                    company: question.company?.slug ?? null,
+                });
+            }
+            if (question.status === "pending") {
+                questionRefs.push({
+                    question_id: question.question_id,
+                    project_id: question.project_id,
+                    story_id: question.story_id,
+                });
+            }
+        }
+        syncLaneToProjectStoryLedger(hqRoot, lane, questionRefs);
+        if (lane.ledger_sync_error !== undefined) {
+            retryUpdateLane(hqRoot, lane.lane_id, "story-ledger", (current) => current.ledger_sync_error === undefined
+                ? current
+                : { ...current, ledger_sync_error: undefined }, deps);
+        }
+        return readLane(hqRoot, lane.lane_id, deps);
+    }
+    catch (error) {
+        const message = (error instanceof Error ? error.message : String(error)).slice(0, 1000) || "Story ledger synchronization failed";
+        try {
+            retryUpdateLane(hqRoot, lane.lane_id, "story-ledger", (current) => current.ledger_sync_error === message
+                ? current
+                : { ...current, ledger_sync_error: message }, deps);
+            return readLane(hqRoot, lane.lane_id, deps);
+        }
+        catch (recordError) {
+            throw new LanesError("story_ledger_sync_error_unrecorded", "Story ledger synchronization failed and the failure could not be recorded on lane " + lane.lane_id, { lane_id: lane.lane_id, cause: recordError instanceof Error ? recordError.message : String(recordError) });
+        }
+    }
+}
+/**
+ * Replace the primary copy with a terminal snapshot returned by the Outpost
+ * that owns the lane. The owner is authoritative on equal versions; a newer
+ * primary version is a conflict and must not be overwritten.
+ */
+export function syncLaneRecordFromOwner(hqRoot, laneId, outpostId, rawOwnerLane, deps = defaultStoreDeps(), options = {}) {
+    let ownerLane;
+    try {
+        ownerLane = parseLaneRecord(rawOwnerLane);
+    }
+    catch (err) {
+        throw new LanesError("outpost_lane_sync_invalid", `Outpost ${outpostId} returned an invalid lane snapshot for ${laneId}`, {
+            lane_id: laneId,
+            outpost_id: outpostId,
+            cause: err instanceof Error ? err.message : String(err),
+        });
+    }
+    if (ownerLane.lane_id !== laneId ||
+        ownerLane.host.kind !== "outpost" ||
+        ownerLane.host.id !== outpostId ||
+        (!options.allowNonTerminal && !isTerminalLaneState(ownerLane.state))) {
+        throw new LanesError("outpost_lane_sync_invalid", `Outpost ${outpostId} did not return an owned lane snapshot for lane ${laneId}`, {
+            lane_id: laneId,
+            outpost_id: outpostId,
+            owner_lane_id: ownerLane.lane_id,
+            owner_host: ownerLane.host,
+            owner_state: ownerLane.state,
+            require_terminal: !options.allowNonTerminal,
+        });
+    }
+    const filePath = laneRecordPath(hqRoot, laneId);
+    const synced = withRecordLock(filePath, deps, () => {
+        const current = readMergedRecord(filePath, parseLaneRecord, mergeLaneRecords, deps);
+        if (current === null) {
+            throw new LaneSchemaError(`Record disappeared under lock: ${filePath}`, {
+                path: filePath,
+            });
+        }
+        if (current.lane_id !== laneId ||
+            current.host.kind !== "outpost" ||
+            current.host.id !== outpostId) {
+            throw new LanesError("outpost_lane_sync_conflict", `Primary lane ${laneId} is no longer owned by Outpost ${outpostId}`, {
+                lane_id: laneId,
+                outpost_id: outpostId,
+                current_lane_id: current.lane_id,
+                current_host: current.host,
+            });
+        }
+        if (ownerLane.version < current.version) {
+            throw new LanesError("outpost_lane_sync_conflict", `Outpost ${outpostId} returned lane ${laneId} at version ${ownerLane.version}, behind primary version ${current.version}`, {
+                lane_id: laneId,
+                outpost_id: outpostId,
+                owner_version: ownerLane.version,
+                primary_version: current.version,
+            });
+        }
+        const ownerSnapshot = ownerLane.outpost_command_id === undefined &&
+            current.outpost_command_id !== undefined
+            ? { ...ownerLane, outpost_command_id: current.outpost_command_id }
+            : ownerLane;
+        const merged = mergeLaneRecords(ownerSnapshot, [current]);
+        const synced = {
+            ...merged,
+            written_by_version: newestLaneStoreVersion(current.written_by_version),
+            owner_written_by_version: ownerLane.written_by_version,
+        };
+        parseLaneRecord(synced, filePath);
+        atomicWriteJson(filePath, synced, deps);
+        return synced;
+    });
+    return syncStoryLedgerForLane(hqRoot, synced, deps);
+}
+/** Compare-and-set with conflict retry. Callers that race a concurrent writer re-read. */
+export function retryUpdateLane(hqRoot, laneId, writer, updater, deps = defaultStoreDeps(), attempts = 5) {
+    let last;
+    for (let i = 0; i < attempts; i += 1) {
+        try {
+            const current = readLane(hqRoot, laneId, deps);
+            return updateLane(hqRoot, laneId, current.version, writer, updater, deps);
+        }
+        catch (err) {
+            last = err;
+            if (!isLaneVersionConflict(err) || i === attempts - 1)
+                throw err;
+        }
+    }
+    throw last;
+}
+/** Compare-and-set with conflict retry for question records (spec §6.2). */
+export function retryUpdateQuestion(hqRoot, questionId, updater, deps = defaultStoreDeps(), attempts = 5) {
+    let last;
+    for (let i = 0; i < attempts; i += 1) {
+        try {
+            const current = readQuestion(hqRoot, questionId, deps);
+            return updateQuestion(hqRoot, questionId, current.version, updater, deps);
+        }
+        catch (err) {
+            last = err;
+            if (!isLaneVersionConflict(err) || i === attempts - 1)
+                throw err;
+        }
+    }
+    throw last;
+}
+export function appendLaneSeniorHistory(hqRoot, laneId, expectedVersion, entry, deps = defaultStoreDeps()) {
+    return updateLane(hqRoot, laneId, expectedVersion, "command", (current) => ({
+        ...current,
+        senior_history: appendCappedHistory(current.senior_history, entry),
+    }), deps);
+}
+export function appendLaneAttribution(hqRoot, laneId, expectedVersion, entry, deps = defaultStoreDeps()) {
+    return updateLane(hqRoot, laneId, expectedVersion, "command", (current) => ({
+        ...current,
+        attribution_history: appendCappedHistory(current.attribution_history, entry),
+    }), deps);
+}
+function syncPendingMarker(hqRoot, question, deps) {
+    const marker = pendingMarkerPath(hqRoot, question.question_id);
+    if (question.status === "pending") {
+        ensureDir(path.dirname(marker), deps);
+        if (!deps.existsSync(marker)) {
+            deps.writeFileSync(marker, "", { encoding: "utf8" });
+        }
+        return;
+    }
+    try {
+        deps.unlinkSync(marker);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+}
+export function createQuestion(hqRoot, init, deps = defaultStoreDeps()) {
+    const question_id = init.question_id ?? mintQuestionId(deps);
+    const filePath = questionRecordPath(hqRoot, question_id);
+    const record = {
+        ...init,
+        schema_version: init.schema_version ?? QUESTION_SCHEMA_VERSION,
+        question_id,
+        delivered_at: init.delivered_at ?? null,
+        version: 1,
+        routing_history: init.routing_history ?? [],
+    };
+    parseQuestionRecord(record, filePath);
+    const created = withRecordLock(filePath, deps, () => {
+        if (deps.existsSync(filePath)) {
+            throw new LanesError("question_exists", `Question ${question_id} already exists`, { question_id });
+        }
+        atomicWriteJson(filePath, record, deps);
+        syncPendingMarker(hqRoot, record, deps);
+        return record;
+    });
+    syncLaneQuestionReference(hqRoot, created, deps);
+    return created;
+}
+export function updateQuestion(hqRoot, questionId, expectedVersion, updater, deps = defaultStoreDeps()) {
+    const next = casWrite(questionRecordPath(hqRoot, questionId), expectedVersion, parseQuestionRecord, mergeQuestionRecords, updater, deps);
+    syncPendingMarker(hqRoot, next, deps);
+    syncLaneQuestionReference(hqRoot, next, deps);
+    return next;
+}
+function syncLaneQuestionReference(hqRoot, question, deps) {
+    if (!laneStoryLedgerEnabled())
+        return;
+    const lane = tryReadLane(hqRoot, question.lane_id, deps);
+    if (!lane || question.company?.slug !== lane.company?.slug || question.company?.uid !== lane.company?.uid)
+        return;
+    retryUpdateLane(hqRoot, lane.lane_id, "story-ledger", (current) => {
+        if (question.company?.slug !== current.company?.slug || question.company?.uid !== current.company?.uid)
+            return current;
+        const ids = new Set(current.pending_question_ids ?? []);
+        const hadQuestion = ids.has(question.question_id);
+        if (question.status === "pending")
+            ids.add(question.question_id);
+        else
+            ids.delete(question.question_id);
+        if (hadQuestion === (question.status === "pending"))
+            return current;
+        return { ...current, pending_question_ids: [...ids].sort() };
+    }, deps);
+}
+export function appendQuestionRouting(hqRoot, questionId, expectedVersion, entry, deps = defaultStoreDeps()) {
+    return updateQuestion(hqRoot, questionId, expectedVersion, (current) => ({
+        ...current,
+        routing_history: appendCappedHistory(current.routing_history, entry),
+    }), deps);
+}
+function jsonRecordIds(names) {
+    return names
+        .filter((name) => typeof name === "string" &&
+        name.endsWith(".json") &&
+        !name.startsWith(".") &&
+        !name.includes(".conflict-"))
+        .map((name) => name.slice(0, -".json".length));
+}
+/**
+ * Absent directory → empty list. A path that exists but cannot be listed
+ * (ENOTDIR, EACCES, …) is unknown, not empty — throw `store_unreadable`.
+ */
+function listRecordIds(dir, label, deps) {
+    let names;
+    try {
+        names = deps.readdirSync(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return [];
+        throw new LanesError("store_unreadable", `Failed to read ${label} directory ${dir}: ${err instanceof Error ? err.message : String(err)}`, { path: dir });
+    }
+    return jsonRecordIds(names);
+}
+export function listLaneIds(hqRoot, deps = defaultStoreDeps()) {
+    return listRecordIds(path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR), "lane", deps);
+}
+export function listQuestionIds(hqRoot, deps = defaultStoreDeps()) {
+    return listRecordIds(path.join(lanesStoreRoot(hqRoot), QUESTION_RECORDS_DIR), "question", deps);
+}
+//# sourceMappingURL=store.js.map