@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/implement-epic/checkpoint-store.js

@@ -0,0 +1,542 @@
+/**
+ * Versioned, user-scoped, atomically-written checkpoint store for the
+ * `implement-epic` CLI (BAPI-803).
+ *
+ * The checkpoint is the loop's only durable memory. `/conduct-epic` (BAPI-804)
+ * derives every decision from it plus a freshly probed world, so three
+ * properties are load-bearing and the rest of this module exists to hold them:
+ *
+ * - **A corrupt checkpoint is a hard error, never a fresh start.** Re-creating
+ *   an unreadable file would silently discard the record of which tickets are
+ *   merged and how many attempts they have consumed, and the loop would redo
+ *   work it already paid for. Only `init` may create a checkpoint, and only when
+ *   none exists.
+ * - **A write is all-or-nothing.** The complete next document is validated
+ *   BEFORE a single byte is written, then written to a same-directory temporary
+ *   file and `rename`d over the primary. A crash mid-write leaves the previous
+ *   valid document, never a truncated one — and the previous document is also
+ *   retained at `<EPIC>.json.prev` so an operator has something to fall back to.
+ * - **It lives outside the repository.** `~/.config/bridge/conduct/<repo>/`
+ *   (honoring `XDG_CONFIG_HOME`, mode `0700`, files `0600`) resolves identically
+ *   from the main checkout and from every worktree, needs no `.gitignore` rule,
+ *   and cannot be committed by an agent running `git add`.
+ *
+ * The directory derivation is COPIED from `credential-store.ts`'s
+ * `getPrimaryCredentialStorePath` rather than imported, because it is driven
+ * here by injected `env`/`homedir` seams so tests can exercise both the XDG and
+ * home-relative branches without touching a real home directory.
+ */
+import path from "node:path";
+/** The only checkpoint schema version this module reads or writes. */
+export const CONDUCT_EPIC_CHECKPOINT_VERSION = 1;
+/** Default soft deadline (seconds) written at `init`; operator-editable. */
+export const CONDUCT_EPIC_DEFAULT_SOFT_SECONDS = 3600;
+/** Default hard deadline (seconds) written at `init`; operator-editable. */
+export const CONDUCT_EPIC_DEFAULT_HARD_SECONDS = 10800;
+/** Retained journal lines per ticket. The oldest are dropped first. */
+export const CONDUCT_EPIC_MAX_JOURNAL_LINES = 50;
+/**
+ * BAPI-915 — how many verdictless review observations, at ONE head, the pilot
+ * makes before it commits a terminal disposition.
+ *
+ * A fixed CONSTANT, deliberately: not a policy key, not an operator-editable
+ * checkpoint field, and not a `deadlines` entry. The pilot has no `RunPolicy`
+ * — that is the whole reason v2's `review_policy.verdictless_disposition` is
+ * unreachable from here — and R14 rule 2's spirit is that a new knob needs a
+ * declared home. This has none, so it is not a knob. What IS operator-settable
+ * is the disposition itself, on the `review_state` done-gate condition, which
+ * already has a declared home that both the pilot and the merge path read.
+ *
+ * Six observations at the documented five-minute tick cadence is roughly thirty
+ * minutes — comfortably inside `deadlines.hard_seconds` (10800), so the ceiling
+ * is what an operator actually sees rather than a three-hour `stalled`.
+ *
+ * It is EXPORTED because `cli.ts` publishes it in the status snapshot: the
+ * command compares two numbers it read from that snapshot instead of carrying a
+ * bound in prose, matching "every value is absolute, computed from the Stage 2
+ * snapshot".
+ */
+export const CONDUCT_EPIC_REVIEW_VERDICTLESS_CEILING = 6;
+/** The closed per-ticket status vocabulary. */
+export const CONDUCT_EPIC_TICKET_STATUSES = [
+    "pending",
+    "in_progress",
+    "merged",
+    "done",
+    "needs_human",
+];
+/** Monotonic suffix source for atomic temp files (avoids same-tick collisions). */
+let atomicWriteCounter = 0;
+/**
+ * `~/.config/bridge/conduct/<repo>/` — the per-repository implement-epic state
+ * directory. Copies `getPrimaryCredentialStorePath`'s two-branch derivation so
+ * conduct state sits beside the credential store and honors `XDG_CONFIG_HOME`
+ * identically.
+ */
+export function resolveConductEpicStateDirectory(repoName, deps) {
+    const xdg = deps.env.XDG_CONFIG_HOME;
+    const bridgeDir = xdg && xdg.trim().length > 0
+        ? path.join(xdg, "bridge")
+        : path.join(deps.homedir(), ".config", "bridge");
+    return path.join(bridgeDir, "conduct", repoName);
+}
+/** `<state dir>/<EPIC>.json` — the default checkpoint path. */
+export function resolveConductEpicCheckpointPath(repoName, epicKey, deps) {
+    return path.join(resolveConductEpicStateDirectory(repoName, deps), `${epicKey}.json`);
+}
+/**
+ * `<EPIC>.lock` beside the checkpoint. Derived from the RESOLVED checkpoint path
+ * rather than re-derived from the repo/epic, so `--checkpoint-path` moves the
+ * lock with it and two invocations pointed at one checkpoint always contend on
+ * one lock.
+ */
+export function resolveConductEpicLockPath(checkpointPath) {
+    const dir = path.dirname(checkpointPath);
+    const base = path.basename(checkpointPath).replace(/\.json$/, "");
+    return path.join(dir, `${base}.lock`);
+}
+/** `<EPIC>.json.prev` — the retained previous document. */
+export function resolveConductEpicBackupPath(checkpointPath) {
+    return `${checkpointPath}.prev`;
+}
+/** `<state dir>/<EPIC>/prompts/` — where the caller writes spawn prompt files. */
+export function resolveConductEpicPromptsDirectory(repoName, epicKey, deps) {
+    return path.join(resolveConductEpicStateDirectory(repoName, deps), epicKey, "prompts");
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Supply defaults for per-ticket fields an older version-1 ticket does not
+ * carry, returning a NEW document rather than mutating the input.
+ *
+ * Two generations of additive fields go through here: the pre-BAPI-825
+ * parse-request pair, and the BAPI-915 verdictless-observation pair
+ * (`review_verdictless_observations` → `0`, `review_verdictless_for_sha` →
+ * `null`). Both were added without incrementing
+ * {@link CONDUCT_EPIC_CHECKPOINT_VERSION}, because bumping the version would
+ * make every checkpoint written by an in-flight pilot run instantly
+ * `unsupported-version` — a hard error whose documented recovery is a human
+ * editing the file. Normalizing an absent field to `null` is the compatible
+ * alternative: an old document stays valid, and every downstream TypeScript
+ * reader sees a real `null` instead of `undefined`.
+ *
+ * Only ABSENT keys are filled. A key that is present but malformed is left
+ * exactly as it is, so validation still rejects it rather than having it
+ * quietly repaired into a legal value. That distinction is the point: filling an
+ * absent key is reading an old document, while repairing a present bad one would
+ * be inventing state an operator never wrote and then acting on it.
+ */
+export function normalizeConductEpicCheckpoint(value) {
+    if (!isRecord(value) || !Array.isArray(value.tickets))
+        return value;
+    return {
+        ...value,
+        // BAPI-844: a checkpoint written before the scope field existed reads as an
+        // unscoped epic rather than as invalid state.
+        index_scope_id: "index_scope_id" in value ? value.index_scope_id : null,
+        // BAPI-846: a checkpoint written before the lease field existed reads as
+        // "no lease held", not as invalid state.
+        index_scope_lease_epoch: "index_scope_lease_epoch" in value ? value.index_scope_lease_epoch : null,
+        tickets: value.tickets.map((ticket) => {
+            if (!isRecord(ticket))
+                return ticket;
+            const normalized = { ...ticket };
+            if (!("parse_requested_at" in normalized))
+                normalized.parse_requested_at = null;
+            if (!("parse_requested_for_sha" in normalized))
+                normalized.parse_requested_for_sha = null;
+            // BAPI-915: a checkpoint written before the verdictless ceiling existed
+            // reads as "nothing observed yet, bound to no head", not as invalid state.
+            if (!("review_verdictless_observations" in normalized)) {
+                normalized.review_verdictless_observations = 0;
+            }
+            if (!("review_verdictless_for_sha" in normalized)) {
+                normalized.review_verdictless_for_sha = null;
+            }
+            return normalized;
+        }),
+    };
+}
+/** A non-empty string. Blank-only values are rejected everywhere. */
+function isText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** A non-negative safe integer. */
+function isCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** A non-empty string or an explicit `null` — the shape every nullable field has. */
+function isNullableText(value) {
+    return value === null || isText(value);
+}
+function fail(error) {
+    return { ok: false, error };
+}
+function validateCounters(value, where) {
+    if (!isRecord(value))
+        return fail(`${where}.counters must be an object`);
+    for (const key of ["sessions_spawned", "plan_generations_observed", "merge_attempts"]) {
+        if (!isCount(value[key])) {
+            return fail(`${where}.counters.${key} must be a non-negative integer`);
+        }
+    }
+    if (Object.keys(value).length !== 3) {
+        return fail(`${where}.counters carries unexpected fields`);
+    }
+    return { ok: true };
+}
+function validateTicket(value, index) {
+    const where = `tickets[${index}]`;
+    if (!isRecord(value))
+        return fail(`${where} must be an object`);
+    if (!isText(value.key))
+        return fail(`${where}.key must be a non-empty string`);
+    if (typeof value.status !== "string" ||
+        !CONDUCT_EPIC_TICKET_STATUSES.includes(value.status)) {
+        return fail(`${where}.status must be one of: ${CONDUCT_EPIC_TICKET_STATUSES.join(", ")}`);
+    }
+    if (!isNullableText(value.branch))
+        return fail(`${where}.branch must be a non-empty string or null`);
+    if (value.pr_number !== null && !(isCount(value.pr_number) && value.pr_number > 0)) {
+        return fail(`${where}.pr_number must be a positive integer or null`);
+    }
+    if (!isNullableText(value.last_seen_head)) {
+        return fail(`${where}.last_seen_head must be a non-empty string or null`);
+    }
+    if (!isNullableText(value.last_state_change_at)) {
+        return fail(`${where}.last_state_change_at must be a timestamp string or null`);
+    }
+    if (!isNullableText(value.spawned_at)) {
+        return fail(`${where}.spawned_at must be a timestamp string or null`);
+    }
+    if (!isCount(value.respawns))
+        return fail(`${where}.respawns must be a non-negative integer`);
+    if (!isCount(value.conflict_attempts)) {
+        return fail(`${where}.conflict_attempts must be a non-negative integer`);
+    }
+    const counters = validateCounters(value.counters, where);
+    if (!counters.ok)
+        return counters;
+    // Present-but-malformed is rejected; ABSENT is impossible here, because
+    // `normalizeConductEpicCheckpoint` runs before every validation and fills a
+    // missing parse-request field with `null` (BAPI-825/A2).
+    for (const key of ["parse_requested_at", "parse_requested_for_sha"]) {
+        if (!isNullableText(value[key])) {
+            return fail(`${where}.${key} must be a non-empty string or null`);
+        }
+    }
+    // BAPI-915: same posture — ABSENT is impossible here because
+    // `normalizeConductEpicCheckpoint` filled it, so anything reaching this check
+    // is present, and a present malformed value is REJECTED rather than repaired.
+    if (!isCount(value.review_verdictless_observations)) {
+        return fail(`${where}.review_verdictless_observations must be a non-negative integer`);
+    }
+    if (!isNullableText(value.review_verdictless_for_sha)) {
+        return fail(`${where}.review_verdictless_for_sha must be a non-empty string or null`);
+    }
+    if (!Array.isArray(value.journal) || value.journal.some((line) => typeof line !== "string")) {
+        return fail(`${where}.journal must be an array of strings`);
+    }
+    if (value.journal.length > CONDUCT_EPIC_MAX_JOURNAL_LINES) {
+        return fail(`${where}.journal must hold at most ${CONDUCT_EPIC_MAX_JOURNAL_LINES} entries`);
+    }
+    return { ok: true };
+}
+function validateCiLastPoll(value) {
+    if (value === null)
+        return { ok: true };
+    if (!isRecord(value))
+        return fail("ci_last_poll must be an object or null");
+    if (!isText(value.head_sha))
+        return fail("ci_last_poll.head_sha must be a non-empty string");
+    if (!Array.isArray(value.required) || value.required.some((n) => typeof n !== "string")) {
+        return fail("ci_last_poll.required must be an array of strings");
+    }
+    if (typeof value.results_fingerprint !== "string") {
+        return fail("ci_last_poll.results_fingerprint must be a string");
+    }
+    if (!isText(value.at))
+        return fail("ci_last_poll.at must be a timestamp string");
+    return { ok: true };
+}
+function validateNeedsHuman(value) {
+    if (value === null)
+        return { ok: true };
+    if (!isRecord(value))
+        return fail("needs_human must be an object or null");
+    for (const key of ["reason", "evidence", "at"]) {
+        if (typeof value[key] !== "string")
+            return fail(`needs_human.${key} must be a string`);
+    }
+    return { ok: true };
+}
+function validateLock(value) {
+    if (!isRecord(value))
+        return fail("lock must be an object");
+    if (!isCount(value.owner_pid))
+        return fail("lock.owner_pid must be a non-negative integer");
+    if (typeof value.host !== "string")
+        return fail("lock.host must be a string");
+    if (typeof value.acquired_at !== "string")
+        return fail("lock.acquired_at must be a string");
+    if (Object.keys(value).length !== 3)
+        return fail("lock carries unexpected fields");
+    return { ok: true };
+}
+/**
+ * Validate a complete candidate document against the version-1 schema.
+ *
+ * Deliberately exhaustive rather than a top-level presence check: the failure
+ * this guards against is a partially-hand-edited checkpoint (an operator
+ * unparking a run edits this file by hand) being accepted because its top-level
+ * keys still exist, and then driving the loop from a nonsense value.
+ *
+ * The candidate is passed through {@link normalizeConductEpicCheckpoint} first,
+ * so a version-1 document written before the parse-request fields existed
+ * validates unchanged. Normalization only fills ABSENT keys, so it can never
+ * launder a malformed present value past the rules below.
+ */
+export function validateConductEpicCheckpoint(candidate) {
+    const value = normalizeConductEpicCheckpoint(candidate);
+    if (!isRecord(value))
+        return fail("checkpoint must be a JSON object");
+    if (value.version !== CONDUCT_EPIC_CHECKPOINT_VERSION) {
+        return fail(`checkpoint version must be ${CONDUCT_EPIC_CHECKPOINT_VERSION}`);
+    }
+    for (const key of ["epic_key", "repo_name", "epic_branch", "base_branch_original"]) {
+        if (!isText(value[key]))
+            return fail(`${key} must be a non-empty string`);
+    }
+    for (const key of ["created_at", "updated_at"]) {
+        if (!isText(value[key]))
+            return fail(`${key} must be a timestamp string`);
+    }
+    if (!isNullableText(value.index_scope_id)) {
+        return fail("index_scope_id must be a non-empty string or null");
+    }
+    if (value.index_scope_lease_epoch !== null &&
+        (typeof value.index_scope_lease_epoch !== "number" ||
+            !Number.isInteger(value.index_scope_lease_epoch) ||
+            value.index_scope_lease_epoch < 0)) {
+        return fail("index_scope_lease_epoch must be a non-negative integer or null");
+    }
+    const deadlines = value.deadlines;
+    if (!isRecord(deadlines))
+        return fail("deadlines must be an object");
+    if (!isCount(deadlines.soft_seconds))
+        return fail("deadlines.soft_seconds must be a non-negative integer");
+    if (!isCount(deadlines.hard_seconds))
+        return fail("deadlines.hard_seconds must be a non-negative integer");
+    if (!Array.isArray(value.tickets) || value.tickets.length === 0) {
+        return fail("tickets must be a non-empty array");
+    }
+    const seen = new Set();
+    for (let i = 0; i < value.tickets.length; i += 1) {
+        const result = validateTicket(value.tickets[i], i);
+        if (!result.ok)
+            return result;
+        const key = value.tickets[i].key;
+        if (seen.has(key))
+            return fail(`tickets contains a duplicate key: ${key}`);
+        seen.add(key);
+    }
+    const counters = value.counters;
+    if (!isRecord(counters))
+        return fail("counters must be an object");
+    if (!isCount(counters.iterations))
+        return fail("counters.iterations must be a non-negative integer");
+    if (!isCount(counters.merges))
+        return fail("counters.merges must be a non-negative integer");
+    const needsHuman = validateNeedsHuman(value.needs_human);
+    if (!needsHuman.ok)
+        return needsHuman;
+    const ciLastPoll = validateCiLastPoll(value.ci_last_poll);
+    if (!ciLastPoll.ok)
+        return ciLastPoll;
+    const lock = validateLock(value.lock);
+    if (!lock.ok)
+        return lock;
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Read / create
+// ---------------------------------------------------------------------------
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * Read and validate the checkpoint at `checkpointPath`.
+ *
+ * `ENOENT` is the ONLY input that produces `missing`. An unreadable file
+ * (permissions, an I/O error) is `unreadable`, not `missing` — reporting
+ * "no checkpoint" for a file that exists but cannot be read would let `init`
+ * conclude the epic was never started and re-provision over live state.
+ */
+export async function readConductEpicCheckpoint(checkpointPath, fs) {
+    let raw;
+    try {
+        raw = await fs.readFile(checkpointPath);
+    }
+    catch (err) {
+        if (errorCode(err) === "ENOENT")
+            return { kind: "missing" };
+        return { kind: "unreadable", error: `checkpoint at ${checkpointPath} could not be read` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "corrupt", error: `checkpoint at ${checkpointPath} is not valid JSON` };
+    }
+    // Version is checked before the schema so a future version reports as such
+    // rather than as a pile of unrelated field errors.
+    if (isRecord(parsed) && parsed.version !== CONDUCT_EPIC_CHECKPOINT_VERSION) {
+        return {
+            kind: "unsupported-version",
+            error: `checkpoint at ${checkpointPath} has version ${JSON.stringify(parsed.version)}; ` +
+                `this CLI only understands version ${CONDUCT_EPIC_CHECKPOINT_VERSION}`,
+        };
+    }
+    const validation = validateConductEpicCheckpoint(parsed);
+    if (!validation.ok) {
+        return { kind: "invalid", error: `checkpoint at ${checkpointPath} is invalid: ${validation.error}` };
+    }
+    // Return the NORMALIZED document, not the parsed one. Validation normalizes a
+    // private copy, so handing back `parsed` would give every caller `undefined`
+    // where the interface promises `string | null` — and `undefined` is exactly
+    // the value a `!== null` causal check reads as "a request was recorded".
+    return {
+        kind: "ok",
+        checkpoint: normalizeConductEpicCheckpoint(parsed),
+    };
+}
+/** Build the initial document: every ticket `pending`, every counter zero. */
+export function createInitialConductEpicCheckpoint(input) {
+    return {
+        version: CONDUCT_EPIC_CHECKPOINT_VERSION,
+        epic_key: input.epicKey,
+        repo_name: input.repoName,
+        epic_branch: input.epicBranch,
+        base_branch_original: input.baseBranchOriginal,
+        index_scope_id: input.indexScopeId ?? null,
+        index_scope_lease_epoch: input.indexScopeLeaseEpoch ?? null,
+        created_at: input.now,
+        updated_at: input.now,
+        deadlines: input.deadlines ?? {
+            soft_seconds: CONDUCT_EPIC_DEFAULT_SOFT_SECONDS,
+            hard_seconds: CONDUCT_EPIC_DEFAULT_HARD_SECONDS,
+        },
+        tickets: input.ticketKeys.map((key) => ({
+            key,
+            status: "pending",
+            branch: null,
+            pr_number: null,
+            last_seen_head: null,
+            last_state_change_at: null,
+            spawned_at: null,
+            respawns: 0,
+            conflict_attempts: 0,
+            counters: { sessions_spawned: 0, plan_generations_observed: 0, merge_attempts: 0 },
+            parse_requested_at: null,
+            parse_requested_for_sha: null,
+            review_verdictless_observations: 0,
+            review_verdictless_for_sha: null,
+            journal: [],
+        })),
+        counters: { iterations: 0, merges: 0 },
+        needs_human: null,
+        ci_last_poll: null,
+        lock: input.lock,
+    };
+}
+/**
+ * Append one journal line to `ticket`, keeping only the newest
+ * {@link CONDUCT_EPIC_MAX_JOURNAL_LINES}. Returns a new ticket object; the input
+ * is not mutated, so a caller that fails validation later cannot leave a
+ * half-updated document behind.
+ */
+export function appendTicketJournal(ticket, line) {
+    const journal = [...ticket.journal, line];
+    return {
+        ...ticket,
+        journal: journal.length > CONDUCT_EPIC_MAX_JOURNAL_LINES
+            ? journal.slice(journal.length - CONDUCT_EPIC_MAX_JOURNAL_LINES)
+            : journal,
+    };
+}
+/**
+ * Validate, then write `checkpoint` to `checkpointPath` atomically.
+ *
+ * Order matters and is asserted by tests:
+ *
+ *  1. validate the COMPLETE next document — an invalid document never reaches
+ *     the filesystem, so a rejected write cannot damage the existing state;
+ *  2. create the parent directory `0700`;
+ *  3. write `<path>.tmp-<pid>-<n>` `0600` in the SAME directory (a cross-device
+ *     temp file would make step 5 a copy, which is not atomic);
+ *  4. copy the previous VALID primary to `<path>.prev`;
+ *  5. `rename` the temp file over the primary.
+ *
+ * On failure only the temporary artifact is removed. The pre-existing primary is
+ * never deleted, truncated, or recreated — including when it is itself corrupt,
+ * because "repair by overwriting" is exactly how the operator's record of a
+ * half-finished epic would disappear.
+ */
+export async function writeConductEpicCheckpointAtomic(checkpointPath, checkpoint, fs, options = {}) {
+    const validation = validateConductEpicCheckpoint(checkpoint);
+    if (!validation.ok) {
+        return { ok: false, error: `refusing to write an invalid checkpoint: ${validation.error}` };
+    }
+    const dir = path.dirname(checkpointPath);
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        if (!options.skipChmod)
+            await fs.chmod(dir, 0o700);
+    }
+    catch {
+        return { ok: false, error: `could not prepare the checkpoint directory ${dir}` };
+    }
+    const content = `${JSON.stringify(checkpoint, null, 2)}\n`;
+    const tmpPath = path.join(dir, `${path.basename(checkpointPath)}.tmp-${process.pid}-${atomicWriteCounter++}`);
+    try {
+        await fs.writeFile(tmpPath, content, { mode: 0o600 });
+        if (!options.skipChmod)
+            await fs.chmod(tmpPath, 0o600);
+        // Retain the previous document — but only if it is a document worth
+        // retaining. Copying corrupt bytes over a good `.prev` would destroy the
+        // last recoverable state at precisely the moment it is needed.
+        let previous = null;
+        try {
+            previous = await fs.readFile(checkpointPath);
+        }
+        catch {
+            previous = null;
+        }
+        if (previous !== null) {
+            let previousIsValid = false;
+            try {
+                previousIsValid = validateConductEpicCheckpoint(JSON.parse(previous)).ok;
+            }
+            catch {
+                previousIsValid = false;
+            }
+            if (previousIsValid) {
+                await fs.writeFile(resolveConductEpicBackupPath(checkpointPath), previous, { mode: 0o600 });
+                if (!options.skipChmod)
+                    await fs.chmod(resolveConductEpicBackupPath(checkpointPath), 0o600);
+            }
+        }
+        await fs.rename(tmpPath, checkpointPath);
+        return { ok: true, path: checkpointPath };
+    }
+    catch {
+        await fs.unlink(tmpPath).catch(() => undefined);
+        return { ok: false, error: `could not write the checkpoint at ${checkpointPath}` };
+    }
+}