@indigoai-us/hq-cli 5.313.0 → 5.314.0

package/dist/lib/lanes/story-ledger.js

@@ -1,815 +0,0 @@
-import { randomBytes } from "node:crypto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { resolveProcessFlagGate } from "../flag-registry.js";
-import { LanesError } from "./errors.js";
-import { isTerminalLaneState } from "./types.js";
-export const LANE_STORY_LEDGER_FLAG = "lanes.story-ledger";
-const LOCK_TIMEOUT_MS = 10_000;
-const LOCK_STALE_MS = 60_000;
-const LOCK_RETRY_MS = 10;
-const STORY_STATES = ["todo", "in_progress", "blocked", "in_review", "verification", "done", "dropped"];
-const MANAGER_OWNED_STATES = new Set(["in_review", "verification", "done", "dropped"]);
-const TERMINAL_STATES = new Set(["done", "failed", "interrupted", "cancelled", "killed"]);
-export function laneStoryLedgerEnabled() {
-    return resolveProcessFlagGate(LANE_STORY_LEDGER_FLAG, { fallback: false }, () => false);
-}
-function isSafePathSegment(value) {
-    return /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value) &&
-        value !== "." &&
-        value !== "..";
-}
-export function resolveProjectStoryLedger(hqRoot, projectId, companySlug) {
-    const normalizedProject = projectId.trim();
-    if (!isSafePathSegment(normalizedProject)) {
-        throw new LanesError("story_ledger_project_invalid", "Project id must be a single safe path segment", { project_id: projectId });
-    }
-    if (companySlug !== undefined && !isSafePathSegment(companySlug)) {
-        throw new LanesError("story_ledger_company_invalid", "Company slug must be a single safe path segment", { company: companySlug });
-    }
-    const projectRoot = companySlug === undefined
-        ? path.join(hqRoot, "personal", "projects", normalizedProject)
-        : path.join(hqRoot, "companies", companySlug, "projects", normalizedProject);
-    return {
-        projectId: normalizedProject,
-        ...(companySlug === undefined ? {} : { companySlug }),
-        path: path.join(projectRoot, "prd.json"),
-    };
-}
-function ledgerError(error, message, ledger, details = {}) {
-    const fix = error === "story_not_in_ledger"
-        ? "Add the story to userStories in " + ledger.path + ", then retry."
-        : error === "story_ledger_missing"
-            ? "Create " + ledger.path + " with a userStories array containing the story, then retry."
-            : error === "story_ledger_unreadable"
-                ? "Make " + ledger.path + " readable and add the story to its userStories array, then retry."
-                : error === "story_ledger_malformed" || error === "story_ledger_invalid"
-                    ? "Repair " + ledger.path + " so it contains valid JSON with a userStories array, add the story, then retry."
-                    : undefined;
-    return new LanesError(error, message, {
-        project_id: ledger.projectId,
-        path: ledger.path,
-        ...(fix ? { fix } : {}),
-        ...details,
-    });
-}
-function readLedger(ledger) {
-    let text;
-    try {
-        text = fs.readFileSync(ledger.path, "utf8");
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === "ENOENT") {
-            throw ledgerError("story_ledger_missing", "Story ledger is missing at " + ledger.path + ". Add the story to userStories in that file, then retry.", ledger, { filesystem_code: code });
-        }
-        throw ledgerError("story_ledger_unreadable", "Story ledger could not be read at " + ledger.path + ". Check access to the project file.", ledger, { filesystem_code: code ?? "unknown" });
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch {
-        throw ledgerError("story_ledger_malformed", "Story ledger is not valid JSON at " + ledger.path, ledger);
-    }
-    if (parsed === null ||
-        typeof parsed !== "object" ||
-        Array.isArray(parsed) ||
-        !Array.isArray(parsed.userStories)) {
-        throw ledgerError("story_ledger_invalid", "Story ledger must be an object with a userStories array at " + ledger.path, ledger);
-    }
-    const stories = parsed.userStories;
-    const seen = new Set();
-    const validated = [];
-    for (const [index, value] of stories.entries()) {
-        const id = isJsonObject(value) ? value.id : undefined;
-        if (!isJsonObject(value) ||
-            typeof id !== "string" ||
-            id.trim() === "") {
-            throw ledgerError("story_ledger_invalid", "Story ledger contains a userStories entry without a non-empty id at " + ledger.path, ledger, { index });
-        }
-        const normalizedId = id.trim();
-        if (seen.has(normalizedId)) {
-            throw ledgerError("story_ledger_ambiguous", "Story ledger contains duplicate story id " + JSON.stringify(normalizedId) + " at " + ledger.path, ledger, { story_id: normalizedId });
-        }
-        seen.add(normalizedId);
-        validated.push(value);
-    }
-    return { ...parsed, userStories: validated };
-}
-export function validateProjectStories(hqRoot, projectId, storyIds, companySlug) {
-    const ledger = resolveProjectStoryLedger(hqRoot, projectId, companySlug);
-    const parsed = readLedger(ledger);
-    const known = new Set(parsed.userStories.map((story) => story.id.trim()));
-    for (const rawId of storyIds) {
-        const storyId = rawId.trim();
-        if (!storyId) {
-            throw ledgerError("story_ledger_story_invalid", "Story id must not be empty", ledger);
-        }
-        if (!known.has(storyId)) {
-            throw ledgerError("story_not_in_ledger", "Story " + JSON.stringify(storyId) + " was not found in " + ledger.path +
-                ". Add it to userStories in that file, then retry.", ledger, { story_id: storyId, add_to: "userStories" });
-        }
-    }
-    return ledger;
-}
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function lockPathFor(filePath) {
-    return filePath + ".hq-lanes-lock";
-}
-function lockOwnerPath(lockPath) {
-    return path.join(lockPath, "owner.json");
-}
-function isInvalidLockOwnerReceipt(err, lockPath) {
-    return err instanceof LanesError &&
-        err.error === "story_ledger_lock_invalid" &&
-        err.details.path === lockOwnerPath(lockPath);
-}
-function readLockOwner(lockPath) {
-    const ownerPath = lockOwnerPath(lockPath);
-    let contents;
-    try {
-        contents = fs.readFileSync(ownerPath, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return { kind: "missing" };
-        throw new LanesError("story_ledger_lock_unavailable", "Could not read story ledger lock owner receipt: " + ownerPath, { path: ownerPath });
-    }
-    let owner;
-    try {
-        owner = JSON.parse(contents);
-    }
-    catch {
-        throw new LanesError("story_ledger_lock_invalid", "Story ledger lock owner receipt is not valid JSON: " + ownerPath, { path: ownerPath });
-    }
-    return { kind: "present", owner };
-}
-function hasLockOwnerToken(ownerRead) {
-    return ownerRead.kind === "present" &&
-        typeof ownerRead.owner.token === "string" && ownerRead.owner.token.length > 0;
-}
-function lockNow(deps) {
-    return deps.clock?.now() ?? Date.now();
-}
-function lockSleep(deps, ms) {
-    if (deps.clock)
-        deps.clock.sleep(ms);
-    else
-        sleepSync(ms);
-}
-function restoreMovedLockWithoutReplacement(lockPath, stalePath) {
-    const entries = fs.readdirSync(stalePath);
-    const isOwnerTemp = (entry) => /^\.owner-[a-f0-9]{24}\.tmp$/.test(entry);
-    if (entries.some((entry) => entry !== "owner.json" && !isOwnerTemp(entry))) {
-        throw new Error("Unexpected entry in moved story ledger lock");
-    }
-    const files = entries.map((entry) => ({
-        name: entry,
-        contents: fs.readFileSync(path.join(stalePath, entry), "utf8"),
-    }));
-    fs.mkdirSync(lockPath);
-    for (const file of files) {
-        fs.writeFileSync(path.join(lockPath, file.name), file.contents, {
-            encoding: "utf8",
-            flag: "wx",
-            mode: 0o600,
-        });
-    }
-    fs.rmSync(stalePath, { recursive: true, force: true });
-}
-function clearStaleLock(lockPath, deps) {
-    let stat;
-    try {
-        stat = fs.lstatSync(lockPath);
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return true;
-        throw err;
-    }
-    if (!stat.isDirectory() || stat.isSymbolicLink()) {
-        throw new LanesError("story_ledger_lock_invalid", "Story ledger lock path is not a regular directory: " + lockPath, { path: lockPath });
-    }
-    let ownerRead;
-    try {
-        ownerRead = readLockOwner(lockPath);
-    }
-    catch (err) {
-        if (!isInvalidLockOwnerReceipt(err, lockPath) || lockNow(deps) - stat.mtimeMs >= LOCK_STALE_MS) {
-            throw err;
-        }
-        return false;
-    }
-    let lockAt = stat.mtimeMs;
-    if (hasLockOwnerToken(ownerRead) && typeof ownerRead.owner.at === "string") {
-        const parsedAt = Date.parse(ownerRead.owner.at);
-        if (Number.isFinite(parsedAt))
-            lockAt = parsedAt;
-    }
-    if (lockNow(deps) - lockAt < LOCK_STALE_MS)
-        return false;
-    deps.beforeStaleLockRename?.(lockPath);
-    const stalePath = lockPath + ".stale-" + randomBytes(8).toString("hex");
-    try {
-        fs.renameSync(lockPath, stalePath);
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return true;
-        throw err;
-    }
-    const moved = fs.lstatSync(stalePath);
-    let movedOwnerRead;
-    try {
-        movedOwnerRead = readLockOwner(stalePath);
-    }
-    catch (err) {
-        if (!isInvalidLockOwnerReceipt(err, stalePath))
-            throw err;
-        const stillFresh = lockNow(deps) - moved.mtimeMs < LOCK_STALE_MS;
-        try {
-            // Put the moved directory back before retrying or reporting the invalid receipt.
-            restoreMovedLockWithoutReplacement(lockPath, stalePath);
-        }
-        catch {
-            throw new LanesError("story_ledger_lock_race", "A replacement story ledger lock was preserved at " + stalePath +
-                " because it could not safely be restored to " + lockPath, { path: lockPath, preserved_path: stalePath });
-        }
-        if (stillFresh)
-            return false;
-        throw err;
-    }
-    let movedLockAt = moved.mtimeMs;
-    if (hasLockOwnerToken(movedOwnerRead) && typeof movedOwnerRead.owner.at === "string") {
-        const parsedAt = Date.parse(movedOwnerRead.owner.at);
-        if (Number.isFinite(parsedAt))
-            movedLockAt = parsedAt;
-    }
-    if (moved.dev !== stat.dev || moved.ino !== stat.ino ||
-        lockNow(deps) - movedLockAt < LOCK_STALE_MS) {
-        try {
-            // mkdir is exclusive, unlike rename on POSIX which can replace a fresh
-            // empty lock directory that appears between an existence check and rename.
-            restoreMovedLockWithoutReplacement(lockPath, stalePath);
-        }
-        catch {
-            throw new LanesError("story_ledger_lock_race", "A replacement story ledger lock was preserved at " + stalePath +
-                " because it could not safely be restored to " + lockPath, { path: lockPath, preserved_path: stalePath });
-        }
-        return false;
-    }
-    fs.rmSync(stalePath, { recursive: true, force: true });
-    return true;
-}
-function acquireLedgerLock(filePath, deps) {
-    const lockPath = lockPathFor(filePath);
-    const token = randomBytes(12).toString("hex");
-    const started = lockNow(deps);
-    const timeoutMs = deps.lockTimeoutMs ?? LOCK_TIMEOUT_MS;
-    const retryMs = deps.lockRetryMs ?? LOCK_RETRY_MS;
-    while (lockNow(deps) - started < timeoutMs) {
-        try {
-            fs.mkdirSync(lockPath);
-            const ownerTempPath = path.join(lockPath, ".owner-" + token + ".tmp");
-            try {
-                fs.writeFileSync(ownerTempPath, JSON.stringify({ pid: process.pid, token, at: new Date(lockNow(deps)).toISOString() }) + "\n", { encoding: "utf8", flag: "wx", mode: 0o600 });
-                fs.renameSync(ownerTempPath, lockOwnerPath(lockPath));
-            }
-            finally {
-                fs.rmSync(ownerTempPath, { force: true });
-            }
-            return { lockPath, token };
-        }
-        catch (err) {
-            if (err.code !== "EEXIST") {
-                throw new LanesError("story_ledger_lock_unavailable", "Could not create story ledger lock for " + filePath, { path: filePath });
-            }
-            if (clearStaleLock(lockPath, deps))
-                continue;
-            lockSleep(deps, retryMs);
-        }
-    }
-    throw new LanesError("story_ledger_lock_timeout", "Timed out waiting for story ledger lock for " + filePath, { path: filePath });
-}
-function releaseLedgerLock(lock) {
-    try {
-        const owner = JSON.parse(fs.readFileSync(lockOwnerPath(lock.lockPath), "utf8"));
-        if (owner.token !== lock.token)
-            return;
-        fs.unlinkSync(lockOwnerPath(lock.lockPath));
-        fs.rmdirSync(lock.lockPath);
-    }
-    catch (err) {
-        if (err.code !== "ENOENT")
-            throw err;
-    }
-}
-function atomicWriteLedger(filePath, bytes, deps, attempt) {
-    const mode = fs.statSync(filePath).mode & 0o777;
-    const temp = filePath + "." + process.pid + "." + randomBytes(6).toString("hex") + ".tmp";
-    let fd;
-    try {
-        fd = fs.openSync(temp, "wx", mode);
-        fs.writeFileSync(fd, bytes, "utf8");
-        fs.fsyncSync(fd);
-        fs.closeSync(fd);
-        fd = undefined;
-        deps.beforeRename?.(filePath, attempt);
-        fs.renameSync(temp, filePath);
-        const directoryFd = fs.openSync(path.dirname(filePath), "r");
-        try {
-            fs.fsyncSync(directoryFd);
-        }
-        finally {
-            fs.closeSync(directoryFd);
-        }
-    }
-    catch (err) {
-        if (fd !== undefined) {
-            try {
-                fs.closeSync(fd);
-            }
-            catch {
-                // Preserve the write error.
-            }
-        }
-        try {
-            fs.unlinkSync(temp);
-        }
-        catch (cleanupErr) {
-            if (cleanupErr.code !== "ENOENT")
-                throw cleanupErr;
-        }
-        throw err;
-    }
-}
-function updateLedgerAtomically(ledger, update, deps = {}) {
-    const lock = acquireLedgerLock(ledger.path, deps);
-    try {
-        for (let attempt = 0; attempt < 5; attempt += 1) {
-            let original;
-            try {
-                original = fs.readFileSync(ledger.path, "utf8");
-            }
-            catch (err) {
-                const code = err.code;
-                if (code === "ENOENT") {
-                    throw ledgerError("story_ledger_missing", "Story ledger disappeared at " + ledger.path, ledger, { filesystem_code: code });
-                }
-                throw ledgerError("story_ledger_unreadable", "Story ledger could not be read at " + ledger.path, ledger, { filesystem_code: code ?? "unknown" });
-            }
-            const current = readLedger(ledger);
-            const next = update(current);
-            const serialized = JSON.stringify(next, null, 2) + "\n";
-            if (serialized === original)
-                return;
-            try {
-                atomicWriteLedger(ledger.path, serialized, {
-                    beforeRename(filePath, hookAttempt) {
-                        deps.beforeRename?.(filePath, hookAttempt);
-                        let latest;
-                        try {
-                            latest = fs.readFileSync(filePath, "utf8");
-                        }
-                        catch {
-                            latest = "";
-                        }
-                        if (latest !== original) {
-                            throw new LanesError("story_ledger_write_conflict", "Story ledger changed while it was being updated at " + filePath, { path: filePath });
-                        }
-                    },
-                }, attempt);
-                return;
-            }
-            catch (err) {
-                if (err instanceof LanesError && err.error === "story_ledger_write_conflict")
-                    continue;
-                throw err;
-            }
-        }
-        throw ledgerError("story_ledger_write_conflict", "Story ledger kept changing while it was being updated at " + ledger.path, ledger);
-    }
-    finally {
-        releaseLedgerLock(lock);
-    }
-}
-function laneStoriesForLedger(lane) {
-    if (lane.no_story_reason && (!lane.stories || lane.stories.length === 0))
-        return [];
-    if (Array.isArray(lane.stories) && lane.stories.length > 0) {
-        return lane.stories.map((story) => ({
-            project_id: story.project_id,
-            story_id: story.story_id,
-            status: story.status,
-            blocked_reason: story.blocked_reason,
-        }));
-    }
-    return lane.story_id.trim()
-        ? [{ project_id: lane.project_id, story_id: lane.story_id }]
-        : [];
-}
-function extractPullRequestLinks(artifacts) {
-    const links = new Set();
-    const seen = new Set();
-    const visit = (value, depth) => {
-        if (depth > 5 || value === null || value === undefined)
-            return;
-        if (typeof value === "string") {
-            const match = value.match(/https?:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/pull\/[0-9]+(?:\/)?/);
-            if (match)
-                links.add(match[0].replace(/\/$/, ""));
-            return;
-        }
-        if (typeof value !== "object" || seen.has(value))
-            return;
-        seen.add(value);
-        if (Array.isArray(value)) {
-            for (const item of value)
-                visit(item, depth + 1);
-            return;
-        }
-        for (const nested of Object.values(value))
-            visit(nested, depth + 1);
-    };
-    for (const artifact of artifacts)
-        visit(artifact, 0);
-    return [...links].sort();
-}
-function isJsonObject(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function laneHistoryState(entry) {
-    return isJsonObject(entry) ? entry.state : undefined;
-}
-function setLaneEntry(story, lane, laneState, laneStoryStatus, prs, pendingQuestionIds, blockedReason) {
-    if (story.lanes === undefined)
-        story.lanes = [];
-    if (!Array.isArray(story.lanes)) {
-        throw new LanesError("story_ledger_invalid", "Story lanes must be an array for story " + String(story.id), { story_id: story.id });
-    }
-    const lanes = story.lanes;
-    const matches = lanes
-        .map((value, index) => ({ value, index }))
-        .filter(({ value }) => value === lane.lane_id || (isJsonObject(value) && value.lane_id === lane.lane_id));
-    if (matches.length > 1) {
-        throw new LanesError("story_ledger_ambiguous_lane", "Story ledger contains more than one lane entry for lane " + lane.lane_id, { story_id: story.id, lane_id: lane.lane_id });
-    }
-    const existing = isJsonObject(matches[0]?.value) ? matches[0]?.value : undefined;
-    const oldState = laneHistoryState(existing);
-    const at = lane.updated_at || lane.created_at;
-    const allPrs = [...new Set([...(Array.isArray(existing?.prs) ? existing.prs.filter((v) => typeof v === "string") : []), ...prs])];
-    const priorHistory = existing?.history;
-    if (priorHistory !== undefined && !Array.isArray(priorHistory)) {
-        throw new LanesError("story_ledger_invalid", "Lane history must be an array for lane " + lane.lane_id, { story_id: story.id, lane_id: lane.lane_id });
-    }
-    const history = Array.isArray(priorHistory) ? [...priorHistory] : [];
-    const terminal = isTerminalLaneState(laneState);
-    const alreadyRecorded = history.some((item) => isJsonObject(item) &&
-        item.lane_id === lane.lane_id &&
-        item.state === laneState &&
-        item.terminal === true);
-    const stateChanged = oldState !== laneState;
-    if (stateChanged || (terminal && !alreadyRecorded)) {
-        const operatorReason = lane.terminal_details?.operator_reason;
-        history.push({
-            lane_id: lane.lane_id,
-            state: laneState,
-            at,
-            prs,
-            ...(terminal ? { terminal: true } : {}),
-            ...(terminal && typeof operatorReason === "string" && operatorReason.trim() !== ""
-                ? { reason: operatorReason }
-                : {}),
-        });
-    }
-    const entry = {
-        ...(existing ?? {}),
-        lane_id: lane.lane_id,
-        state: laneState,
-        ...(laneStoryStatus === undefined ? {} : { story_status: laneStoryStatus }),
-        at,
-        prs: allPrs,
-        artifacts: lane.last_envelope?.artifacts ?? [],
-        history,
-        pending_questions: [...new Set(pendingQuestionIds)],
-        ...(laneState === "blocked" && blockedReason ? { blocked_on: blockedReason } : {}),
-    };
-    if (laneState !== "blocked" || !blockedReason)
-        delete entry.blocked_on;
-    if (matches.length === 0) {
-        lanes.push(entry);
-    }
-    else {
-        lanes[matches[0]?.index] = entry;
-    }
-    story.lanes = lanes;
-}
-function validPriorQuestions(value, storyId) {
-    if (value === undefined)
-        return [];
-    if (!Array.isArray(value)) {
-        throw new LanesError("story_ledger_invalid", "pending_questions must be an array for story " + String(storyId), { story_id: storyId });
-    }
-    return value;
-}
-function setLaneStatusFields(story, lane, laneStoryStatus) {
-    const laneStatus = story.lane_status;
-    if (laneStatus !== undefined && !isJsonObject(laneStatus)) {
-        throw new LanesError("story_ledger_invalid", "lane_status must be an object for story " + String(story.id), { story_id: story.id });
-    }
-    const entries = Array.isArray(story.lanes)
-        ? story.lanes.filter((entry) => isJsonObject(entry) && typeof entry.lane_id === "string")
-        : [];
-    const active = entries.filter((entry) => !TERMINAL_STATES.has(String(entry.state)));
-    const blockers = active.filter((entry) => (entry.state === "blocked" || (entry.state === "awaiting_input" && Array.isArray(entry.pending_questions) && entry.pending_questions.length > 0)));
-    const saved = isJsonObject(laneStatus) && isJsonObject(laneStatus.saved)
-        ? laneStatus.saved
-        : {
-            state: story.state,
-            blocked_on: story.blocked_on,
-            pending_questions: story.pending_questions,
-        };
-    const priorBlockedOn = saved?.blocked_on;
-    if (priorBlockedOn !== undefined && typeof priorBlockedOn !== "string") {
-        throw new LanesError("story_ledger_invalid", "blocked_on must be a string for story " + String(story.id), { story_id: story.id });
-    }
-    const laneBlockedOn = blockers
-        .filter((entry) => entry.state === "blocked")
-        .map((entry) => "Lane " + String(entry.lane_id) + ": " +
-        (typeof entry.blocked_on === "string" && entry.blocked_on.trim() ? entry.blocked_on : "blocked"));
-    if (laneBlockedOn.length > 0) {
-        story.blocked_on = [typeof priorBlockedOn === "string" ? priorBlockedOn : "", ...laneBlockedOn]
-            .filter((value) => value.trim())
-            .join("\n");
-    }
-    else if (priorBlockedOn === undefined) {
-        delete story.blocked_on;
-    }
-    else {
-        story.blocked_on = priorBlockedOn;
-    }
-    const priorQuestions = validPriorQuestions(saved?.pending_questions, story.id);
-    const generatedQuestions = active.flatMap((entry) => isJsonObject(entry) && Array.isArray(entry.pending_questions)
-        ? entry.pending_questions.map((questionId) => ({
-            lane_id: entry.lane_id,
-            question_id: questionId,
-        }))
-        : []);
-    if (priorQuestions.length > 0 || generatedQuestions.length > 0) {
-        story.pending_questions = [
-            ...priorQuestions,
-            ...generatedQuestions.filter((question) => !priorQuestions.some((prior) => isJsonObject(prior) &&
-                prior.lane_id === question.lane_id &&
-                prior.question_id === question.question_id)),
-        ];
-    }
-    else {
-        delete story.pending_questions;
-    }
-    if (MANAGER_OWNED_STATES.has(String(story.state))) {
-        // A manager decision always wins over lane-derived status.
-    }
-    else if (blockers.length > 0) {
-        story.state = "blocked";
-    }
-    else if (laneStoryStatus === "review") {
-        story.state = "in_review";
-    }
-    else if (laneStoryStatus === "done") {
-        story.state = "done";
-    }
-    else if (laneStoryStatus === "in_progress" || lane.state === "queued" || lane.state === "running" || lane.state === "awaiting_input") {
-        story.state = "in_progress";
-    }
-    else if (saved !== undefined && story.state === "blocked") {
-        const previous = saved.state;
-        story.state = typeof previous === "string" && STORY_STATES.includes(previous)
-            ? previous
-            : "in_progress";
-    }
-    if (blockers.length > 0)
-        story.lane_status = { saved };
-    else
-        delete story.lane_status;
-    story.updated_at = lane.updated_at || lane.created_at;
-}
-function updateOneStory(current, ledger, lane, storyId, projectId, questionRefs) {
-    const story = current.userStories.find((item) => item.id === storyId);
-    if (!story) {
-        throw ledgerError("story_not_in_ledger", "Story " + JSON.stringify(storyId) + " was not found in " + ledger.path +
-            ". Add it to userStories in that file, then retry.", ledger, { story_id: storyId });
-    }
-    const prLinks = extractPullRequestLinks(lane.last_envelope?.artifacts ?? []);
-    const laneStory = lane.stories?.find((entry) => entry.project_id === projectId && entry.story_id === storyId);
-    const pendingQuestionIds = questionRefs
-        .filter((question) => question.project_id === projectId && question.story_id === storyId)
-        .map((question) => question.question_id);
-    const blockedReason = laneStory?.blocked_reason ??
-        (laneStoriesForLedger(lane).length <= 1 ? lane.last_envelope?.blocked_reason : undefined);
-    const laneState = storyLaneState(lane, laneStory?.status, pendingQuestionIds);
-    setLaneEntry(story, lane, laneState, laneStory?.status, prLinks, pendingQuestionIds, blockedReason);
-    setLaneStatusFields(story, lane, laneStory?.status);
-    if (prLinks.length > 0) {
-        if (story.prs === undefined)
-            story.prs = [];
-        if (!Array.isArray(story.prs)) {
-            throw new LanesError("story_ledger_invalid", "Story prs must be an array for story " + storyId, { story_id: storyId });
-        }
-        const prs = story.prs;
-        for (const url of prLinks) {
-            if (!prs.includes(url))
-                prs.push(url);
-        }
-    }
-    return current;
-}
-export function syncLaneToProjectStoryLedger(hqRoot, lane, questionRefs = [], deps = {}) {
-    if (!laneStoryLedgerEnabled())
-        return;
-    const stories = laneStoriesForLedger(lane);
-    if (stories.length === 0)
-        return;
-    const refs = [...new Map(stories.map((story) => [
-            story.project_id + "\u0000" + story.story_id,
-            { projectId: story.project_id, storyId: story.story_id, laneStory: story },
-        ])).values()].sort((a, b) => a.projectId.localeCompare(b.projectId) || a.storyId.localeCompare(b.storyId));
-    for (const ref of refs) {
-        const ledger = resolveProjectStoryLedger(hqRoot, ref.projectId, lane.company?.slug);
-        updateLedgerAtomically(ledger, (current) => {
-            return updateOneStory(current, ledger, lane, ref.storyId, ref.projectId, questionRefs);
-        }, deps);
-    }
-}
-function storyLaneState(lane, laneStoryStatus, pendingQuestionIds) {
-    if (isTerminalLaneState(lane.state))
-        return lane.state;
-    if (lane.state === "blocked" && laneStoriesForLedger(lane).length <= 1)
-        return "blocked";
-    if (laneStoryStatus === "blocked")
-        return "blocked";
-    if (laneStoryStatus === "done")
-        return "done";
-    if (lane.state === "awaiting_input" && pendingQuestionIds.length > 0)
-        return "awaiting_input";
-    if (laneStoryStatus === undefined)
-        return lane.state;
-    if (lane.state === "queued" && laneStoryStatus === "in_progress")
-        return "queued";
-    return "running";
-}
-function storyState(story) {
-    const state = story.state;
-    if (typeof state === "string" && STORY_STATES.includes(state)) {
-        return state;
-    }
-    return story.passes === true ? "done" : "todo";
-}
-/** Read canonical ledger states for the story ids currently carried by a lane. */
-export function readProjectStoryStates(hqRoot, projectId, storyIds, companySlug) {
-    const parsed = readLedger(resolveProjectStoryLedger(hqRoot, projectId, companySlug));
-    const wanted = new Set(storyIds);
-    return new Map(parsed.userStories
-        .filter((story) => wanted.has(story.id.trim()))
-        .map((story) => [story.id.trim(), storyState(story)]));
-}
-function laneStoryRefs(lane, projectId) {
-    return laneStoriesForLedger(lane)
-        .filter((story) => story.project_id === projectId)
-        .map((story) => story.story_id);
-}
-export function buildLaneStatusSnapshot(input) {
-    const ledger = resolveProjectStoryLedger(input.hqRoot, input.projectId, input.companySlug);
-    const parsed = readLedger(ledger);
-    const projectLanes = input.lanes
-        .filter((lane) => {
-        const sameCompany = lane.company?.slug === input.companySlug &&
-            (input.companyUid === undefined || lane.company?.uid === input.companyUid);
-        return sameCompany && (laneStoriesForLedger(lane).some((story) => story.project_id === input.projectId) ||
-            (lane.no_story_reason !== undefined && lane.project_id === input.projectId));
-    })
-        .sort((a, b) => a.created_at.localeCompare(b.created_at) || a.lane_id.localeCompare(b.lane_id));
-    const workers = projectLanes.map((lane) => ({
-        lane_id: lane.lane_id,
-        company: lane.company?.slug ?? null,
-        provider: lane.provider,
-        account: lane.account ?? null,
-        model: lane.model ?? null,
-        effort: lane.effort ?? null,
-        stories: laneStoryRefs(lane, input.projectId),
-        no_story_reason: lane.no_story_reason ?? null,
-        state: lane.state,
-        queued_reason: lane.queued_reason ?? null,
-    }));
-    const projectPrs = [];
-    const blockers = [];
-    const pendingQuestions = [];
-    const byState = Object.fromEntries(STORY_STATES.map((state) => [state, 0]));
-    for (const story of parsed.userStories) {
-        const storyId = story.id;
-        const state = storyState(story);
-        byState[state] += 1;
-        for (const reference of Array.isArray(story.prs) ? story.prs : []) {
-            if (typeof reference === "string" && reference.trim()) {
-                projectPrs.push({ story_id: storyId, reference: reference.trim() });
-            }
-        }
-        if (typeof story.blocked_on === "string" && story.blocked_on.trim()) {
-            blockers.push({ story_id: storyId, reason: story.blocked_on.trim() });
-        }
-        if (Array.isArray(story.pending_questions)) {
-            for (const item of story.pending_questions) {
-                if (isJsonObject(item) && typeof item.lane_id === "string" && typeof item.question_id === "string") {
-                    pendingQuestions.push({
-                        story_id: storyId,
-                        lane_id: item.lane_id,
-                        question_ids: [item.question_id],
-                    });
-                }
-            }
-        }
-    }
-    for (const lane of projectLanes) {
-        const carriedStories = laneStoriesForLedger(lane)
-            .filter((story) => story.project_id === input.projectId);
-        for (const carriedStory of carriedStories) {
-            const ids = (input.pendingQuestions?.get(lane.lane_id) ?? [])
-                .filter((question) => question.project_id === carriedStory.project_id && question.story_id === carriedStory.story_id)
-                .map((question) => question.question_id);
-            const state = storyLaneState(lane, carriedStory.status, ids);
-            if (state === "blocked") {
-                const reason = carriedStory.blocked_reason ??
-                    (carriedStories.length <= 1 ? lane.last_envelope?.blocked_reason : undefined) ?? "blocked";
-                const alreadyListed = blockers.some((blocker) => blocker.story_id === carriedStory.story_id &&
-                    (blocker.lane_id === lane.lane_id || blocker.reason.startsWith("Lane " + lane.lane_id + ":")));
-                if (!alreadyListed)
-                    blockers.push({ story_id: carriedStory.story_id, lane_id: lane.lane_id, reason });
-            }
-            if (ids.length > 0) {
-                pendingQuestions.push({ story_id: carriedStory.story_id, lane_id: lane.lane_id, question_ids: ids });
-            }
-        }
-    }
-    const uniquePrs = [...new Map(projectPrs.map((pr) => [pr.story_id + "\u0000" + pr.reference, pr])).values()];
-    const uniqueBlockers = [...new Map(blockers.map((item) => [
-            item.story_id + "\u0000" + (item.lane_id ?? "") + "\u0000" + item.reason,
-            item,
-        ])).values()];
-    const uniqueQuestions = [...new Map(pendingQuestions.map((item) => [
-            item.story_id + "\u0000" + item.lane_id + "\u0000" + item.question_ids.join(","),
-            item,
-        ])).values()];
-    return {
-        schema_version: "hq-lanes-status.v1",
-        project_id: input.projectId,
-        ledger_path: ledger.path,
-        generated_at: input.generatedAt,
-        workers,
-        prs: uniquePrs,
-        blockers: uniqueBlockers,
-        pending_questions: uniqueQuestions,
-        story_counts: {
-            total: parsed.userStories.length,
-            by_state: byState,
-        },
-    };
-}
-export function formatLaneStatusHuman(snapshot) {
-    const counts = Object.entries(snapshot.story_counts.by_state)
-        .map(([state, count]) => state + "=" + count)
-        .join("  ");
-    const lines = [
-        "Project " + snapshot.project_id + " (" + snapshot.workers.length + " lanes)",
-        "Stories: " + counts,
-        "Workers:",
-        ...(snapshot.workers.length === 0
-            ? ["  none"]
-            : snapshot.workers.map((worker) => {
-                const storyLabel = worker.stories.length > 0
-                    ? worker.stories.join(", ")
-                    : "no story: " + (worker.no_story_reason ?? "reason not recorded");
-                const model = worker.model ? " / " + worker.model : "";
-                const effort = worker.effort ? " (" + worker.effort + ")" : "";
-                const account = worker.account ? " account " + worker.account : "";
-                const queued = worker.queued_reason ? " queued: " + worker.queued_reason : "";
-                return "  " + worker.lane_id + "  " + worker.state + "  " + storyLabel +
-                    "  " + worker.provider + model + effort + account + queued;
-            })),
-        "PRs (may include merged):",
-        ...(snapshot.prs.length === 0
-            ? ["  none"]
-            : snapshot.prs.map((pr) => "  " + pr.story_id + "  " + pr.reference)),
-        "Blockers:",
-        ...(snapshot.blockers.length === 0
-            ? ["  none"]
-            : snapshot.blockers.map((blocker) => "  " + blocker.story_id + (blocker.lane_id ? " / " + blocker.lane_id : "") + "  " + blocker.reason)),
-        "Pending questions:",
-        ...(snapshot.pending_questions.length === 0
-            ? ["  none"]
-            : snapshot.pending_questions.map((pending) => "  " + pending.story_id + " / " + pending.lane_id + "  " + pending.question_ids.join(", "))),
-    ];
-    return lines.join("\n");
-}
-//# sourceMappingURL=story-ledger.js.map