@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -0,0 +1,815 @@
+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