clinkx 1.0.0 → 1.1.1

package/dist/progress-report/store.js

@@ -0,0 +1,766 @@
+import { createHash } from "node:crypto";
+import { randomBytes } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, mkdir, open, readdir, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { ProgressReportDocumentSchema, } from "../../clinkx-workflows/dist/dashboard/progress-report-contract.js";
+import { getStateDir } from "../../clinkx-workflows/dist/config.js";
+import { ExecutionError, InvalidParamsError } from "../errors.js";
+import { logger } from "../logger.js";
+import { withSessionLock } from "./lock.js";
+export const REPORTS_SUBDIR = "progress-reports";
+export const REPORT_FILENAME = "report-data.json";
+export const CONTROL_FILENAME = ".control.json";
+/** Mirrors the dashboard reader's own per-file cap (progress-report-reader.ts). */
+export const MAX_REPORT_FILE_BYTES = 8 * 1024 * 1024;
+/** Bound directory enumeration the same way the reader does. */
+export const SCAN_CAP = 10_000;
+/**
+ * How many directories are actually READ per listing. Enumeration is stat-only;
+ * only the newest this many are opened, exactly as the dashboard reader does.
+ */
+export const MAX_LIST_CANDIDATES = 200;
+/** Aggregate read budget for one listing, matching the reader's own budget. */
+export const MAX_LIST_SCAN_BYTES = 256 * 1024 * 1024;
+/** How many bounded request_id receipts to retain per session. */
+export const RECEIPT_RETENTION = 32;
+/** Section caps, straight from ProgressReportDocumentSchema. */
+const CAPS = {
+    agents: 50,
+    tasks: 200,
+    log: 200,
+    files: 500,
+    blockers: 50,
+    decisions: 100,
+};
+export function reportsRoot(env = process.env) {
+    return join(getStateDir(env), REPORTS_SUBDIR);
+}
+function sessionDirFor(sessionId, env) {
+    return join(reportsRoot(env), sessionId);
+}
+function nowIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * `SESSION-<32 hex>`, a PURE FUNCTION of request_id.
+ *
+ * This is what makes `progress_report_start` idempotent: a retry derives the
+ * same directory, so the exclusive `mkdir` that already reserves the id doubles
+ * as the replay detector and no second session can be created. Any timestamp
+ * component would defeat that — a retry one second later would derive a
+ * different id and silently create a duplicate report, which is precisely the
+ * failure this tool surface exists to remove. The start time is not lost: it is
+ * `session.started_at` inside the document. Nothing parses the id (the dashboard
+ * sorts on updated_at with the id as an opaque string tie-break), so dropping the
+ * embedded timestamp costs only human scannability of directory names.
+ *
+ * The `\u0000` between the domain tag and the request_id is a domain separator
+ * and is load-bearing: normalizing it to a space changes every derived id, so a
+ * retry would no longer find its own directory and would open a duplicate
+ * report. It is written as an ESCAPE, never as a raw byte — a raw NUL makes git
+ * classify this file as binary, which hides it from diffs, blame and grep.
+ */
+function buildSessionId(requestId) {
+    const digest = createHash("sha256")
+        .update(`clinkx-progress-report-start\u0000${requestId}`)
+        .digest("hex");
+    return `SESSION-${digest.slice(0, 32)}`;
+}
+function digestOf(value) {
+    return createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+/** Key-sorted JSON so a replayed request digests identically regardless of key order. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+// --- persistence -------------------------------------------------------
+/**
+ * Reject a session path that is not a real directory.
+ *
+ * `lstat`, not `stat`: the dashboard reader refuses a symlinked session
+ * directory outright, and a writer that silently followed one would write
+ * outside the reports root while the report stayed invisible on the dashboard.
+ * Writer and reader must admit exactly the same set.
+ */
+async function isRealDirectory(dir) {
+    const stats = await lstat(dir).catch(() => null);
+    return stats !== null && stats.isDirectory() && !stats.isSymbolicLink();
+}
+async function writeAtomic(dir, filename, text) {
+    const tmp = join(dir, `.tmp-${randomBytes(8).toString("hex")}.json`);
+    let renamed = false;
+    try {
+        const handle = await open(tmp, "wx", 0o600);
+        try {
+            await handle.writeFile(text, "utf8");
+            // Durability, not just atomicity: rename is atomic against other readers
+            // but says nothing about surviving power loss.
+            await handle.sync().catch(() => undefined);
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tmp, join(dir, filename));
+        renamed = true;
+        const dirHandle = await open(dir, fsConstants.O_RDONLY).catch(() => null);
+        if (dirHandle !== null) {
+            try {
+                await dirHandle.sync().catch(() => undefined);
+            }
+            finally {
+                await dirHandle.close();
+            }
+        }
+    }
+    finally {
+        // A temp left behind by a failed write or rename is invisible to the reader
+        // but accumulates forever, since nothing else enumerates it.
+        if (!renamed)
+            await unlink(tmp).catch(() => undefined);
+    }
+}
+/**
+ * Read and fully validate one report.
+ *
+ * `expectedId` closes the directory/document identity gap: a session directory
+ * whose name disagrees with the `session.id` inside it (a renamed directory, a
+ * partially-restored backup) would otherwise let a write land in one directory
+ * while the receipt — and the dashboard row — claim another id, so the row's
+ * detail link resolves to a different report. Fail closed.
+ */
+async function readDocument(sessionDir, expectedId) {
+    const path = join(sessionDir, REPORT_FILENAME);
+    const stats = await lstat(path).catch(() => null);
+    if (stats === null || !stats.isFile() || stats.isSymbolicLink()) {
+        throw new InvalidParamsError(`progress report not found: ${path}`);
+    }
+    if (stats.size > MAX_REPORT_FILE_BYTES) {
+        throw new ExecutionError(`progress report exceeds the ${String(MAX_REPORT_FILE_BYTES)}-byte cap and cannot be updated`);
+    }
+    let raw;
+    try {
+        // O_NOFOLLOW so a symlinked report file is refused rather than followed,
+        // matching the reader's containment discipline.
+        const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        try {
+            raw = await handle.readFile("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ELOOP") {
+            throw new ExecutionError(`progress report at ${path} is a symlink and was refused`);
+        }
+        throw new ExecutionError(`progress report at ${path} could not be read: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ExecutionError(`progress report at ${path} is not valid JSON; the session cannot be written until an operator removes the directory`);
+    }
+    const result = ProgressReportDocumentSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ExecutionError(`progress report at ${path} does not satisfy progress-report-v1: ${result.error.issues
+            .slice(0, 3)
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ")}`);
+    }
+    if (expectedId !== undefined && result.data.session.id !== expectedId) {
+        throw new ExecutionError(`progress report identity mismatch: directory ${JSON.stringify(expectedId)} holds a document whose session.id is ${JSON.stringify(result.data.session.id)}`);
+    }
+    return {
+        document: result.data,
+        digest: createHash("sha256").update(raw, "utf8").digest("hex"),
+    };
+}
+function receiptsFrom(value, path) {
+    if (!Array.isArray(value)) {
+        throw new ExecutionError(`progress report control sidecar at ${path} has a malformed receipts list`);
+    }
+    return value.map((entry) => {
+        const record = entry;
+        const requestId = record?.["request_id"];
+        const revision = record?.["revision"];
+        const digest = record?.["digest"];
+        if (typeof entry !== "object" ||
+            entry === null ||
+            typeof requestId !== "string" ||
+            typeof revision !== "number" ||
+            !Number.isSafeInteger(revision) ||
+            typeof digest !== "string") {
+            throw new ExecutionError(`progress report control sidecar at ${path} has a malformed receipt entry`);
+        }
+        const status = record["status"];
+        const updatedAt = record["updated_at"];
+        return {
+            request_id: requestId,
+            revision,
+            digest,
+            ...(typeof status === "string" ? { status } : {}),
+            ...(typeof updatedAt === "string" ? { updated_at: updatedAt } : {}),
+            ...(record["kind"] === "start" ? { kind: "start" } : {}),
+        };
+    });
+}
+/**
+ * Read the control sidecar, FAILING CLOSED on corruption.
+ *
+ * Only a genuinely ABSENT sidecar starts a fresh revision line — that is the
+ * legitimate case of a report written before the sidecar existed. Every other
+ * failure (a truncated file, a permission error, a non-integer revision) throws.
+ * Collapsing those into the same silent `{revision: 1}` fallback would void the
+ * entire compare-and-swap contract: an established report at revision 40 would
+ * silently reset to 1, and a stale `expected_revision: 1` write would then be
+ * ACCEPTED. The repair for a corrupt sidecar is to delete it, which returns the
+ * session to the legacy path deliberately rather than by accident.
+ */
+async function readControl(sessionDir) {
+    const path = join(sessionDir, CONTROL_FILENAME);
+    let raw;
+    try {
+        const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        try {
+            raw = await handle.readFile("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { revision: 1, receipts: [] };
+        throw new ExecutionError(`progress report control sidecar at ${path} could not be read (${String(code)}); delete it to restart the revision line`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ExecutionError(`progress report control sidecar at ${path} is not valid JSON; delete it to restart the revision line`);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new ExecutionError(`progress report control sidecar at ${path} is not an object; delete it to restart the revision line`);
+    }
+    const record = parsed;
+    const revision = record["revision"];
+    if (typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < 1) {
+        // revision 0 or a negative would be unmatchable by any legal
+        // expected_revision (which is .min(1)), wedging the session forever.
+        throw new ExecutionError(`progress report control sidecar at ${path} has an invalid revision; delete it to restart the revision line`);
+    }
+    const documentDigest = record["document_digest"];
+    return {
+        revision,
+        receipts: receiptsFrom(record["receipts"] ?? [], path),
+        ...(typeof documentDigest === "string" ? { document_digest: documentDigest } : {}),
+    };
+}
+/**
+ * Whether the control sidecar exists at all.
+ *
+ * `readControl` deliberately maps only ENOENT onto a fresh revision line, so an
+ * absent sidecar and a sidecar that merely lacks a given receipt are
+ * indistinguishable from its return value — and they need opposite handling on
+ * the start path.
+ */
+async function controlSidecarExists(sessionDir) {
+    return (await lstat(join(sessionDir, CONTROL_FILENAME)).catch(() => null)) !== null;
+}
+function serializeDocument(document) {
+    const text = `${JSON.stringify(document, null, 2)}\n`;
+    if (Buffer.byteLength(text, "utf8") > MAX_REPORT_FILE_BYTES) {
+        throw new InvalidParamsError(`resulting progress report would exceed the ${String(MAX_REPORT_FILE_BYTES)}-byte cap`);
+    }
+    return text;
+}
+/**
+ * Write the document, then the sidecar that describes it.
+ *
+ * These are two renames, not one transaction. The sidecar records the document's
+ * digest so a tear between them is DETECTABLE rather than silent: a reader that
+ * finds a digest mismatch knows the document is one commit ahead of the recorded
+ * revision, and `updateReport` heals it into a visible revision_conflict instead
+ * of letting a retry pass the CAS and double-apply an append.
+ */
+async function commit(sessionDir, document, control) {
+    const text = serializeDocument(document);
+    const next = {
+        ...control,
+        document_digest: createHash("sha256").update(text, "utf8").digest("hex"),
+    };
+    await writeAtomic(sessionDir, REPORT_FILENAME, text);
+    await writeAtomic(sessionDir, CONTROL_FILENAME, `${JSON.stringify(next, null, 2)}\n`);
+}
+/**
+ * Read the document and its revision as a COHERENT PAIR.
+ *
+ * Control FIRST, then the document, then control again to prove nothing moved
+ * in between. A writer commits document-then-sidecar, so reading in that same
+ * order can hand back a stale document with a fresh revision — and a patch
+ * computed from that view would pass the CAS and silently lose the concurrent
+ * write. Reading control first biases the other way: at worst the caller gets a
+ * spurious revision_conflict, which is self-correcting.
+ *
+ * Every unlocked reader must use this. `listReports` reading the document and
+ * then the control is the same defect, reached through a path callers are told
+ * to hit before every start.
+ */
+async function readCoherentSnapshot(sessionDir, expectedId) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const before = await readControl(sessionDir);
+        const loaded = await readDocument(sessionDir, expectedId);
+        const after = await readControl(sessionDir);
+        if (before.revision === after.revision)
+            return { loaded, revision: before.revision };
+    }
+    throw new ExecutionError(`progress report ${expectedId} is being written too rapidly to read a coherent snapshot; retry`);
+}
+function receiptFor(document, sessionDir, revision, replayed) {
+    return {
+        session_id: document.session.id,
+        revision,
+        path: join(sessionDir, REPORT_FILENAME),
+        status: document.session.status,
+        updated_at: document.session.updated_at,
+        replayed,
+    };
+}
+/** A replay returns what the ORIGINAL write produced, not the report's current state. */
+function replayReceipt(stored, loaded, sessionDir) {
+    return {
+        session_id: loaded.document.session.id,
+        revision: stored.revision,
+        path: join(sessionDir, REPORT_FILENAME),
+        status: stored.status ?? loaded.document.session.status,
+        updated_at: stored.updated_at ?? loaded.document.session.updated_at,
+        replayed: true,
+    };
+}
+/** Keep the pinned opening receipt plus the newest others, never evicting start. */
+function appendReceipt(existing, next) {
+    const start = existing.find((r) => r.kind === "start");
+    const others = existing.filter((r) => r.kind !== "start");
+    const budget = RECEIPT_RETENTION - (start === undefined ? 0 : 1);
+    const kept = [...others, next].slice(-budget);
+    return start === undefined ? kept : [start, ...kept];
+}
+function validateDocument(document) {
+    const result = ProgressReportDocumentSchema.safeParse(document);
+    if (!result.success) {
+        // Without this the raw ZodError escapes as an unclassified error, losing the
+        // -32602 / isError distinction the rest of this server relies on.
+        throw new InvalidParamsError(`progress report would become invalid: ${result.error.issues
+            .slice(0, 5)
+            .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("; ")}`);
+    }
+    return result.data;
+}
+// --- operations --------------------------------------------------------
+/**
+ * The document a start OPENS, as a pure function of the input plus the one
+ * server-owned timestamp.
+ *
+ * Factored out so the fresh-start path and the torn-open replay check cannot
+ * drift: the replay check's whole argument is that it rebuilds byte-for-byte
+ * what this request WOULD have written, so any divergence between the two
+ * constructions would silently turn a genuine replay into a conflict or, worse,
+ * a changed request into an accepted replay.
+ */
+function buildOpeningDocument(input, sessionId, startedAt) {
+    return {
+        schema_version: "progress-report-v1",
+        session: {
+            id: sessionId,
+            title: input.title,
+            goal: input.goal,
+            status: "running",
+            started_at: startedAt,
+            updated_at: startedAt,
+            project_folder: input.project_folder,
+        },
+        ...(input.agents != null
+            ? { agents: input.agents.map((a) => ({ ...a, updated_at: startedAt })) }
+            : {}),
+        ...(input.tasks != null ? { tasks: input.tasks } : {}),
+        log: [{ t: startedAt, agent: input.opened_by, kind: "info", msg: "session started" }],
+    };
+}
+export async function startReport(input, env = process.env) {
+    const root = reportsRoot(env);
+    try {
+        await mkdir(root, { recursive: true });
+    }
+    catch (err) {
+        throw new ExecutionError(`could not create the progress reports root at ${root}: ${err.message}`);
+    }
+    const sessionId = buildSessionId(input.request_id);
+    const sessionDir = join(root, sessionId);
+    try {
+        // Exclusive mkdir IS the reservation. Because the id is a pure function of
+        // request_id, EEXIST is now SEMANTIC — it means "this request already ran".
+        await mkdir(sessionDir, { recursive: false, mode: 0o700 });
+    }
+    catch (err) {
+        if (err.code !== "EEXIST") {
+            throw new ExecutionError(`could not reserve progress report directory ${sessionDir}: ${err.message}`);
+        }
+    }
+    if (!(await isRealDirectory(sessionDir))) {
+        throw new ExecutionError(`progress report path ${sessionDir} exists but is not a real directory`);
+    }
+    const startedAt = nowIso();
+    const requestDigest = digestOf(input);
+    // Creation is never authority: a concurrent identical start may have won the
+    // mkdir and still be initializing, so always inspect under the lock.
+    return withSessionLock(sessionDir, async (guard) => {
+        let existing;
+        try {
+            existing = await readDocument(sessionDir, sessionId);
+        }
+        catch (err) {
+            if (err instanceof InvalidParamsError) {
+                // No document yet: a fresh reservation, or a previous start that created
+                // the directory and died before committing. Both heal by initializing.
+                existing = null;
+            }
+            else {
+                throw err;
+            }
+        }
+        if (existing !== null) {
+            const control = await readControl(sessionDir);
+            const prior = control.receipts.find((r) => r.request_id === input.request_id);
+            if (prior === undefined) {
+                if (await controlSidecarExists(sessionDir)) {
+                    // The sidecar is present and the start receipt is PINNED, so a real
+                    // opening receipt would still be in it. Something else wrote here.
+                    throw new ExecutionError(`progress report ${sessionId} already exists but has no receipt for this request_id; refusing to overwrite it`);
+                }
+                // No sidecar at all: the opening commit may have torn between its two
+                // renames. The directory name is the first 128 bits of a domain-separated
+                // sha256(request_id) and the document's session.id matches it, so this
+                // document can only have come from THIS request_id,
+                // and synthesizing the receipt it should have had is the only way the
+                // retrying caller ever gets its session id back — start is the only tool
+                // that returns one for a new report.
+                //
+                // But the directory name proves the request ID ONLY, never the request
+                // BODY, and the receipt that would have carried the request digest is
+                // exactly what is missing here. So prove content the other way round:
+                // rebuild THIS request's opening document and compare digests. That is a
+                // SOUND FAIL-CLOSED test, not an exact one. An absent sidecar does NOT
+                // prove the document is pristine — an operator deleting `.control.json`,
+                // or a backup restoring `report-data.json` without its sidecar, both land
+                // here over a document that HAS been updated, and both mismatch. What the
+                // comparison actually establishes is the only thing that matters: when it
+                // does not match, we cannot prove this request produced this report, so we
+                // refuse.
+                //
+                // Refusing is right rather than replaying because `readControl` reports
+                // revision 1 for an absent sidecar. Synthesizing a start receipt on top of
+                // a document already at revision 2 would rewind an established revision
+                // line (2 -> 1) and make a stale `expected_revision: 1` acceptable again —
+                // the exact silent-CAS-void failure that `readControl`'s own fail-closed
+                // design exists to prevent. Accepting a changed retry would additionally
+                // record THIS digest against the ORIGINAL document and lock the genuine
+                // original request out of its own report forever.
+                const rebuilt = validateDocument(buildOpeningDocument(input, sessionId, existing.document.session.started_at));
+                if (digestOf(rebuilt) !== digestOf(existing.document)) {
+                    throw new InvalidParamsError(`request_id_conflict: the document on disk does not match what this request would have opened. Either request_id ${JSON.stringify(input.request_id)} was reused with different content, or this report's control sidecar was removed after the report had already been updated. If this report is yours, adopt it with progress_report_update (progress_report_list will show it); use a fresh request_id only for a genuinely new report.`);
+                }
+                logger.warn({ sessionDir, sessionId }, "progress-report: opening commit left no control sidecar; reconstructing the start receipt");
+                const reconstructed = {
+                    request_id: input.request_id,
+                    revision: control.revision,
+                    digest: requestDigest,
+                    status: existing.document.session.status,
+                    updated_at: existing.document.session.updated_at,
+                    kind: "start",
+                };
+                await guard.assertHeld();
+                await commit(sessionDir, existing.document, {
+                    revision: control.revision,
+                    receipts: [reconstructed],
+                });
+                return replayReceipt(reconstructed, existing, sessionDir);
+            }
+            if (prior.digest !== requestDigest) {
+                throw new InvalidParamsError(`request_id_conflict: request_id ${JSON.stringify(input.request_id)} already opened a progress report with different content. If that report is yours, adopt it with progress_report_update (progress_report_list will show it); use a fresh request_id only for a genuinely new report.`);
+            }
+            return replayReceipt(prior, existing, sessionDir);
+        }
+        const validated = validateDocument(buildOpeningDocument(input, sessionId, startedAt));
+        await guard.assertHeld();
+        await commit(sessionDir, validated, {
+            revision: 1,
+            receipts: [
+                {
+                    request_id: input.request_id,
+                    revision: 1,
+                    digest: requestDigest,
+                    status: validated.session.status,
+                    updated_at: validated.session.updated_at,
+                    kind: "start",
+                },
+            ],
+        });
+        return receiptFor(validated, sessionDir, 1, false);
+    });
+}
+export async function updateReport(args, env = process.env) {
+    const sessionDir = sessionDirFor(args.report_id, env);
+    if (!(await isRealDirectory(sessionDir))) {
+        // Never recreate: a removed directory is an explicit operator action.
+        throw new InvalidParamsError(`unknown progress report id: ${args.report_id}`);
+    }
+    return withSessionLock(sessionDir, async (guard) => {
+        let control = await readControl(sessionDir);
+        const requestDigest = digestOf({
+            changes: args.changes,
+            reopen: args.reopen ?? false,
+        });
+        const prior = control.receipts.find((r) => r.request_id === args.request_id);
+        if (prior !== undefined) {
+            if (prior.digest !== requestDigest) {
+                throw new InvalidParamsError(`request_id_conflict: request_id ${JSON.stringify(args.request_id)} was already used for a different update on this report`);
+            }
+            const existing = await readDocument(sessionDir, args.report_id);
+            return replayReceipt(prior, existing, sessionDir);
+        }
+        const current = await readDocument(sessionDir, args.report_id);
+        if (control.document_digest === undefined) {
+            // No baseline: every report written before document_digest existed, plus
+            // every legacy report with no sidecar at all. Without one, torn-commit
+            // detection is simply SKIPPED — an update whose document lands and whose
+            // sidecar does not leaves a retry finding revision N with neither a
+            // receipt nor a digest, so it passes the CAS and applies its appends a
+            // second time. Record the digest of what is ALREADY on disk, at the SAME
+            // revision, so this establishes a baseline and never a version bump.
+            await guard.assertHeld();
+            await commit(sessionDir, current.document, {
+                revision: control.revision,
+                receipts: control.receipts,
+            });
+            control = await readControl(sessionDir);
+        }
+        else if (control.document_digest !== current.digest) {
+            // A digest mismatch proves the last commit tore between its two renames:
+            // the document landed, the sidecar did not. Heal it into a visible
+            // conflict — otherwise a retry finds no receipt, passes the CAS against a
+            // revision that no longer describes the document, and double-applies its
+            // appends.
+            const healed = control.revision + 1;
+            logger.warn({ sessionDir, recorded: control.revision, healed }, "progress-report: torn commit detected; advancing the revision to match the document on disk");
+            await guard.assertHeld();
+            await commit(sessionDir, current.document, {
+                revision: healed,
+                receipts: control.receipts,
+            });
+            control = await readControl(sessionDir);
+        }
+        if (control.revision !== args.expected_revision) {
+            throw new InvalidParamsError(`revision_conflict: expected_revision ${String(args.expected_revision)} but the report is at revision ${String(control.revision)} — re-read it with progress_report_get and retry`);
+        }
+        const next = applyChanges(current.document, args.changes, args.reopen ?? false);
+        const validated = validateDocument(next);
+        const revision = control.revision + 1;
+        await guard.assertHeld();
+        await commit(sessionDir, validated, {
+            revision,
+            receipts: appendReceipt(control.receipts, {
+                request_id: args.request_id,
+                revision,
+                digest: requestDigest,
+                status: validated.session.status,
+                updated_at: validated.session.updated_at,
+            }),
+        });
+        return receiptFor(validated, sessionDir, revision, false);
+    });
+}
+export async function getReport(reportId, env = process.env) {
+    const sessionDir = sessionDirFor(reportId, env);
+    const { loaded, revision } = await readCoherentSnapshot(sessionDir, reportId);
+    return {
+        document: loaded.document,
+        revision,
+        path: join(sessionDir, REPORT_FILENAME),
+    };
+}
+export async function listReports(options, env = process.env) {
+    const root = reportsRoot(env);
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    // Pass 1 is stat-only. The previous implementation opened and fully validated
+    // every candidate BEFORE applying `limit`, on a path callers are told to hit
+    // before every start, against a set that only grows because retention pruning
+    // is deliberately disabled.
+    const seen = [];
+    let scanned = 0;
+    let hitScanCap = false;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            continue;
+        if (scanned >= SCAN_CAP) {
+            hitScanCap = true;
+            break;
+        }
+        scanned += 1;
+        const stats = await lstat(join(root, entry.name, REPORT_FILENAME)).catch(() => null);
+        if (stats === null || !stats.isFile() || stats.isSymbolicLink())
+            continue;
+        seen.push({ name: entry.name, mtimeMs: stats.mtimeMs, size: stats.size });
+    }
+    seen.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const admitted = seen.slice(0, MAX_LIST_CANDIDATES);
+    let truncated = hitScanCap || seen.length > MAX_LIST_CANDIDATES;
+    const candidates = [];
+    let bytes = 0;
+    for (const item of admitted) {
+        if (bytes + item.size > MAX_LIST_SCAN_BYTES) {
+            truncated = true;
+            break;
+        }
+        bytes += item.size;
+        const sessionDir = join(root, item.name);
+        let loaded;
+        let revision;
+        try {
+            // One coherent read, so a listing can never pair a stale document with a
+            // revision fresh enough to pass the CAS on a later adopt-then-write.
+            ({ loaded, revision } = await readCoherentSnapshot(sessionDir, item.name));
+        }
+        catch (err) {
+            // Silence here is exactly the "where did my report go" case the identity
+            // check exists to catch, so say something instead of dropping it mutely —
+            // a report missing from a listing an agent was told to consult first is a
+            // report that gets opened a second time. This covers an unreadable
+            // document, a corrupt sidecar and a snapshot that would not stabilise.
+            logger.warn({ sessionDir, err: err.message }, "progress-report: skipping an unreadable report directory");
+            continue;
+        }
+        if (options.project_folder !== undefined &&
+            loaded.document.session.project_folder !== options.project_folder) {
+            continue;
+        }
+        candidates.push({
+            id: loaded.document.session.id,
+            path: join(sessionDir, REPORT_FILENAME),
+            title: loaded.document.session.title,
+            goal: loaded.document.session.goal,
+            status: loaded.document.session.status,
+            revision,
+            updated_at: loaded.document.session.updated_at,
+            agents: (loaded.document.agents ?? []).map((a) => a.name),
+            tasks: (loaded.document.tasks ?? []).map((t) => t.title),
+        });
+    }
+    // Timestamps are second-granularity, so ties are ordinary rather than rare.
+    // Break them on id so the candidate order a caller walks is a deterministic
+    // total order, not filesystem enumeration order.
+    candidates.sort((a, b) => {
+        const byTime = Date.parse(b.updated_at) - Date.parse(a.updated_at);
+        if (byTime !== 0)
+            return byTime;
+        return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+    });
+    if (candidates.length > options.limit)
+        truncated = true;
+    return { candidates: candidates.slice(0, options.limit), truncated };
+}
+// --- patch application -------------------------------------------------
+function upsert(existing, incoming, key, cap, label) {
+    const merged = [...(existing ?? [])];
+    for (const item of incoming) {
+        const index = merged.findIndex((m) => m[key] === item[key]);
+        if (index >= 0) {
+            merged[index] = { ...merged[index], ...item };
+        }
+        else {
+            merged.push(item);
+        }
+    }
+    if (merged.length > cap) {
+        // Keyed sections do NOT evict: silently dropping the oldest agent, task or
+        // file would delete an entity that may still be live and still referenced,
+        // and the board would then under-report the work without telling anyone. A
+        // loud refusal is better than a quiet lie.
+        throw new InvalidParamsError(`${label} is at its ${String(cap)}-entry cap; there is no removal operation — update an existing entry in place, or start a new report`);
+    }
+    return merged;
+}
+/**
+ * Apply one bounded patch. Every server-owned field (timestamps, ids) is
+ * stamped here rather than trusted from the caller, so a caller cannot publish
+ * a guessed clock or rewrite an identity.
+ */
+export function applyChanges(current, changes, reopen) {
+    const at = nowIso();
+    const terminal = current.session.status === "done" || current.session.status === "failed";
+    const reopening = reopen || (changes.session?.status != null && changes.session.status === "running");
+    if (terminal && !reopening) {
+        throw new InvalidParamsError(`progress report ${current.session.id} is ${current.session.status}; pass reopen:true (or set session.status to "running") to write to it again`);
+    }
+    const next = {
+        ...current,
+        session: {
+            ...current.session,
+            ...(changes.session?.title != null ? { title: changes.session.title } : {}),
+            ...(changes.session?.goal != null ? { goal: changes.session.goal } : {}),
+            ...(changes.session?.status != null
+                ? { status: changes.session.status }
+                : reopen
+                    ? { status: "running" }
+                    : {}),
+            updated_at: at,
+        },
+    };
+    if (changes.agents_upsert != null) {
+        next.agents = upsert(current.agents, changes.agents_upsert.map((a) => ({ ...a, updated_at: at })), "name", CAPS.agents, "agents");
+    }
+    if (changes.tasks_upsert != null) {
+        next.tasks = upsert(current.tasks, changes.tasks_upsert, "id", CAPS.tasks, "tasks");
+    }
+    if (changes.files_upsert != null) {
+        next.files = upsert(current.files, changes.files_upsert, "path", CAPS.files, "files");
+    }
+    if (changes.log_append != null) {
+        // Oldest-first eviction is the documented behavior for log, not an error.
+        const log = [...(current.log ?? []), ...changes.log_append.map((e) => ({ ...e, t: at }))];
+        next.log = log.slice(-CAPS.log);
+    }
+    if (changes.decisions_append != null) {
+        // Decisions are a chronological stream like log, so they evict rather than
+        // wedging the section at the cap with no way to make room.
+        const decisions = [
+            ...(current.decisions ?? []),
+            ...changes.decisions_append.map((d) => ({ ...d, t: at })),
+        ];
+        next.decisions = decisions.slice(-CAPS.decisions);
+    }
+    if (changes.tests_set != null) {
+        next.tests = { ...changes.tests_set, last_run: at };
+    }
+    if (changes.blockers_set != null) {
+        if (changes.blockers_set.length > CAPS.blockers) {
+            throw new InvalidParamsError(`blockers would exceed its ${String(CAPS.blockers)}-entry cap`);
+        }
+        next.blockers = [...changes.blockers_set];
+    }
+    return next;
+}
+//# sourceMappingURL=store.js.map