@bridge_gpt/mcp-server 0.2.39 → 0.2.42

package/build/conduct-epic/bridge-client.js

@@ -91,119 +91,6 @@ function nullableString(value) {
         return value;
     return undefined;
 }
-/** Parse the `override` member, or `undefined` when it is malformed. */
-function parseOverride(value) {
-    if (value === null || value === undefined)
-        return null;
-    if (!isRecord(value))
-        return undefined;
-    const original = nullableString(value["original_base_branch"]);
-    if (typeof value["repo_name"] !== "string" ||
-        original === undefined ||
-        typeof value["override_branch"] !== "string" ||
-        typeof value["created_at"] !== "string") {
-        return undefined;
-    }
-    return {
-        repo_name: value["repo_name"],
-        original_base_branch: original,
-        override_branch: value["override_branch"],
-        created_at: value["created_at"],
-    };
-}
-/**
- * Validate a 200 body against {@link IndexBranchStatus}, returning `null` when it
- * does not match.
- *
- * A body that parsed as JSON but is not this shape is treated as a failure
- * rather than cast through: `changed` and `current_base_branch` drive
- * destructive branch decisions in the caller, and a missing `changed` read as
- * `undefined` would silently mean "nothing happened".
- */
-function parseStatus(body) {
-    if (!isRecord(body))
-        return null;
-    const current = nullableString(body["current_base_branch"]);
-    const override = parseOverride(body["override"]);
-    if (typeof body["repo_name"] !== "string" ||
-        current === undefined ||
-        override === undefined ||
-        typeof body["changed"] !== "boolean") {
-        return null;
-    }
-    return {
-        repo_name: body["repo_name"],
-        current_base_branch: current,
-        override,
-        changed: body["changed"],
-    };
-}
-/** Wrap a parsed body into a success result, or a generic failure if malformed. */
-function toStatusResult(body) {
-    const status = parseStatus(body);
-    if (status === null) {
-        return { ok: false, status: null, error: GENERIC_ERROR };
-    }
-    return { ok: true, value: status };
-}
-/**
- * `POST /jira/index-branch/repoint` — point the indexed base branch at `branch`.
- *
- * A repeat call with the same branch resolves `{ ok: true }` with
- * `value.changed === false`. A call for a *different* branch while an override is
- * active resolves `{ ok: false, status: 409 }` with an error naming the override
- * the server preserved — it is not an exception, because a conflict is an
- * expected outcome the CLI must report and continue from.
- */
-export async function repointIndexBranch(access, input, fetchImpl = globalThis.fetch) {
-    try {
-        // `buildConductorJiraUrl` already appends the `/jira` segment.
-        const url = buildConductorJiraUrl(access.baseUrl, "/index-branch/repoint");
-        const body = await fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName, branch: input.branch }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
-        return toStatusResult(body);
-    }
-    catch (err) {
-        return toFailure(err, access);
-    }
-}
-/**
- * `POST /jira/index-branch/restore` — write the stored original branch back and
- * drop the override.
- *
- * Idempotent: with no active override the call resolves `{ ok: true }` with
- * `value.changed === false` and `value.override === null`. That matters because
- * restore is the recovery path — it must be safe to run after a crash whose
- * position is unknown.
- */
-export async function restoreIndexBranch(access, fetchImpl = globalThis.fetch) {
-    try {
-        const url = buildConductorJiraUrl(access.baseUrl, "/index-branch/restore");
-        const body = await fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
-        return toStatusResult(body);
-    }
-    catch (err) {
-        return toFailure(err, access);
-    }
-}
-/**
- * `GET /jira/index-branch?repo_name=` — report the current indexed branch and any
- * active override.
- *
- * This is how a stale override left behind by a crashed loop becomes visible;
- * `value.changed` is always `false` because a read changes nothing.
- */
-export async function getIndexBranch(access, fetchImpl = globalThis.fetch) {
-    try {
-        const url = buildConductorJiraUrl(access.baseUrl, "/index-branch", {
-            repo_name: access.repoName,
-        });
-        const body = await fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
-        return toStatusResult(body);
-    }
-    catch (err) {
-        return toFailure(err, access);
-    }
-}
 /**
  * Run `operation` and convert any thrown value into a sanitized failure result.
  *
@@ -343,3 +230,357 @@ export async function getConfigFieldBaseBranch(access, fetchImpl = globalThis.fe
     const trimmed = raw.trim();
     return { ok: true, value: { base_branch: trimmed.length === 0 ? null : trimmed } };
 }
+const INDEX_SCOPE_FRESHNESS_VALUES = new Set([
+    "fresh",
+    "pending",
+    "blocked",
+    "failed",
+    "unavailable",
+]);
+/**
+ * Read the server's freshness verdict, failing CLOSED.
+ *
+ * An absent or unrecognized value becomes `null` rather than a guess, and every
+ * caller treats `null` as "not fresh". A malformed control-plane response must
+ * never be the thing that lets a conductor proceed against a stale index.
+ */
+function parseFreshnessStatus(value) {
+    return typeof value === "string" && INDEX_SCOPE_FRESHNESS_VALUES.has(value)
+        ? value
+        : null;
+}
+/**
+ * Read a soft envelope's refusal, or `null` when the body reports success.
+ *
+ * A body that is not an object at all is a refusal too: silently treating an
+ * unparseable response as success is how a cut gets recorded against a commit
+ * nobody verified.
+ */
+function softEnvelopeFailure(body) {
+    if (!isRecord(body))
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    if (body["ok"] === true)
+        return null;
+    const error = typeof body["error"] === "string" && body["error"].length > 0 ? body["error"] : GENERIC_ERROR;
+    const message = typeof body["message"] === "string" && body["message"].length > 0 ? body["message"] : null;
+    return { ok: false, status: null, error: message ? `${error}: ${message}` : error };
+}
+/** Read a required string field, or `null` when it is absent or empty. */
+function requiredString(body, key) {
+    const value = body[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * `POST /jira/index-scope/cut/begin` — lease a cut hold at the indexed commit.
+ *
+ * `candidateCommitSha` is the CLI's own preflight observation, sent as a
+ * cross-check. The server re-reads the canonical snapshot under the parse lock
+ * and refuses on disagreement, which is the "the index moved while I was
+ * checking" case the protocol re-drives rather than papers over.
+ */
+export async function beginIndexScopeCut(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/cut/begin");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({
+            repo_name: access.repoName,
+            feature_branch: request.featureBranch,
+            base_branch: request.baseBranch,
+            candidate_commit_sha: request.candidateCommitSha ?? null,
+            epic_run_id: request.epicRunId ?? null,
+        }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    const body = result.value;
+    const cutHoldId = requiredString(body, "cut_hold_id");
+    const scopeId = requiredString(body, "scope_id");
+    const shadowRepoName = requiredString(body, "shadow_repo_name");
+    const cutCommitSha = requiredString(body, "cut_commit_sha");
+    if (!cutHoldId || !scopeId || !shadowRepoName || !cutCommitSha) {
+        // An `ok: true` body missing any of these is not a usable lease, and acting
+        // on a partial one would push a ref at `undefined`.
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    return { ok: true, value: { cut_hold_id: cutHoldId, scope_id: scopeId, shadow_repo_name: shadowRepoName, cut_commit_sha: cutCommitSha } };
+}
+/**
+ * `POST /jira/index-scope/cut/commit` — record the immutable cut.
+ *
+ * `epicRefCommitSha` is what the CLI read back from `origin` AFTER creating the
+ * ref, not what it intended to create. The server proves the two agree.
+ */
+export async function commitIndexScopeCut(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/cut/commit");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({
+            repo_name: access.repoName,
+            scope_id: request.scopeId,
+            cut_hold_id: request.cutHoldId,
+            epic_ref_commit_sha: request.epicRefCommitSha,
+        }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    const body = result.value;
+    const scopeId = requiredString(body, "scope_id");
+    const shadowRepoName = requiredString(body, "shadow_repo_name");
+    const cutCommitSha = requiredString(body, "cut_commit_sha");
+    if (!scopeId || !shadowRepoName || !cutCommitSha) {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    return {
+        ok: true,
+        value: {
+            scope_id: scopeId,
+            shadow_repo_name: shadowRepoName,
+            cut_commit_sha: cutCommitSha,
+            outcome: requiredString(body, "outcome"),
+        },
+    };
+}
+/**
+ * `POST /jira/index-scope/cut/abandon` — release this CLI's own cut hold.
+ *
+ * Called from `init`'s `finally` on every pre-seed outcome. Idempotent: a hold
+ * already released (or already reclaimed) still resolves successfully, so the
+ * cleanup path can never turn a primary failure into a second one.
+ */
+export async function abandonIndexScopeCut(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/cut/abandon");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({
+            repo_name: access.repoName,
+            scope_id: request.scopeId,
+            cut_hold_id: request.cutHoldId,
+        }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    return { ok: true, value: true };
+}
+/**
+ * `POST /jira/index-scope/bootstrap` — seed the scope and drive its verifying
+ * parse.
+ *
+ * Accepted means SCHEDULED, never ready. Readiness is observed through
+ * {@link getIndexScopeStatus}, because the bootstrap copies a repository's whole
+ * parse cache and then runs a parse.
+ */
+export async function bootstrapIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/bootstrap");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName, scope_id: request.scopeId }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    return { ok: true, value: true };
+}
+/** `GET /jira/index-scope/status?repo_name=&scope_id=` — the scope's own state. */
+export async function getIndexScopeStatus(access, scopeId, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/status", {
+            repo_name: access.repoName,
+            scope_id: scopeId,
+        });
+        return fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    const body = result.value;
+    const resolvedScopeId = requiredString(body, "scope_id");
+    const shadowRepoName = requiredString(body, "shadow_repo_name");
+    const lifecycleState = requiredString(body, "lifecycle_state");
+    if (!resolvedScopeId || !shadowRepoName || !lifecycleState) {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    return {
+        ok: true,
+        value: {
+            scope_id: resolvedScopeId,
+            shadow_repo_name: shadowRepoName,
+            lifecycle_state: lifecycleState,
+            cut_commit_sha: nullableString(body["cut_commit_sha"]) ?? null,
+            required_commit_sha: nullableString(body["required_commit_sha"]) ?? null,
+            indexed_commit_sha: nullableString(body["indexed_commit_sha"]) ?? null,
+            seed_source_commit_sha: nullableString(body["seed_source_commit_sha"]) ?? null,
+            last_error: nullableString(body["last_error"]) ?? null,
+            freshness_status: parseFreshnessStatus(body["freshness_status"]),
+            blocked_reason: nullableString(body["blocked_reason"]) ?? null,
+        },
+    };
+}
+function nullableNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Read a boolean field, defaulting to the SAFE value rather than to `false`.
+ *
+ * The safe default differs per field and each caller passes it, because guessing
+ * uniformly would be wrong in both directions: an unreadable `lease_valid` must
+ * read as `true` (assume it is live, do not offer to reclaim it) while an
+ * unreadable `retention_elapsed` must read as `false` (assume the window has not
+ * passed).
+ */
+function booleanOr(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function parseLifecycleEntry(value) {
+    if (!isRecord(value))
+        return null;
+    const scopeId = requiredString(value, "scope_id");
+    if (!scopeId)
+        return null;
+    const blockers = Array.isArray(value["blockers"])
+        ? value["blockers"].filter((entry) => typeof entry === "string")
+        : [];
+    return {
+        scope_id: scopeId,
+        shadow_repo_name: nullableString(value["shadow_repo_name"]) ?? null,
+        feature_branch: nullableString(value["feature_branch"]) ?? null,
+        epic_run_id: nullableString(value["epic_run_id"]) ?? null,
+        lifecycle_state: nullableString(value["lifecycle_state"]) ?? null,
+        lease_epoch: nullableNumber(value["lease_epoch"]),
+        lease_expires_at: nullableString(value["lease_expires_at"]) ?? null,
+        // Fail closed on each: an unreadable field must never make a scope look more
+        // reclaimable than it is.
+        lease_valid: booleanOr(value["lease_valid"], true),
+        retention_deadline: nullableString(value["retention_deadline"]) ?? null,
+        retention_elapsed: booleanOr(value["retention_elapsed"], false),
+        recoverable: booleanOr(value["recoverable"], false),
+        active_parse_run: booleanOr(value["active_parse_run"], true),
+        parse_lock_held: booleanOr(value["parse_lock_held"], true),
+        active_automation_run: booleanOr(value["active_automation_run"], true),
+        active_epic_run: booleanOr(value["active_epic_run"], true),
+        identity_valid: booleanOr(value["identity_valid"], false),
+        blockers,
+    };
+}
+/** `GET /jira/index-scope/lifecycle?repo_name=` — every scope this repo owns. */
+export async function getIndexScopeLifecycle(access, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/lifecycle", {
+            repo_name: access.repoName,
+        });
+        return fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    const body = result.value;
+    const rawScopes = Array.isArray(body["scopes"]) ? body["scopes"] : [];
+    const scopes = [];
+    for (const raw of rawScopes) {
+        const parsed = parseLifecycleEntry(raw);
+        // A malformed entry is DROPPED rather than failing the whole listing: the
+        // listing is a diagnostic, and showing an operator four readable scopes plus
+        // nothing about a fifth beats showing them nothing at all.
+        if (parsed !== null)
+            scopes.push(parsed);
+    }
+    return {
+        ok: true,
+        value: { retention_seconds: nullableNumber(body["retention_seconds"]), scopes },
+    };
+}
+/** Shared parser for the three lease verbs, whose response shape is identical. */
+function toLeaseResult(body) {
+    const refusal = softEnvelopeFailure(body);
+    if (refusal)
+        return refusal;
+    const record = body;
+    const scopeId = requiredString(record, "scope_id");
+    if (!scopeId)
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    return {
+        ok: true,
+        value: {
+            scope_id: scopeId,
+            lifecycle_state: nullableString(record["lifecycle_state"]) ?? null,
+            lease_epoch: nullableNumber(record["lease_epoch"]),
+            lease_expires_at: nullableString(record["lease_expires_at"]) ?? null,
+            already_retired: booleanOr(record["already_retired"], false),
+        },
+    };
+}
+async function postScopeLifecycle(access, path, body, fetchImpl) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, path);
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName, ...body }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    return toLeaseResult(result.value);
+}
+/** `POST /jira/index-scope/heartbeat` — renew the lease under `leaseEpoch`. */
+export async function heartbeatIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    return postScopeLifecycle(access, "/index-scope/heartbeat", { scope_id: request.scopeId, lease_epoch: request.leaseEpoch }, fetchImpl);
+}
+/**
+ * `POST /jira/index-scope/recover` — take a new ownership generation.
+ *
+ * Deliberately sends NO epoch: recovery exists for the case where the caller has
+ * no valid one, and the server's increment is what fences the previous owner.
+ */
+export async function recoverIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    return postScopeLifecycle(access, "/index-scope/recover", { scope_id: request.scopeId }, fetchImpl);
+}
+/** `POST /jira/index-scope/retire` — start retention; delete nothing. */
+export async function retireIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    return postScopeLifecycle(access, "/index-scope/retire", { scope_id: request.scopeId, lease_epoch: request.leaseEpoch }, fetchImpl);
+}
+/**
+ * `POST /jira/index-scope/reclaim` — schedule the server-side teardown.
+ *
+ * There is deliberately no raw-deletion mode and no field that could name a
+ * namespace, table, or repository: the only knob is `overrideRetention`, which
+ * waives the two TIME blockers and nothing else. Everything actually deleted is
+ * derived server-side from the scope id.
+ *
+ * A refusal carries the server's ordered blocker tokens so the CLI can print WHY
+ * rather than a generic failure.
+ */
+export async function reclaimIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/reclaim");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({
+            repo_name: access.repoName,
+            scope_id: request.scopeId,
+            override_retention: request.overrideRetention === true,
+        }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal) {
+        const body = isRecord(result.value) ? result.value : {};
+        const blockers = Array.isArray(body["blockers"])
+            ? body["blockers"].filter((entry) => typeof entry === "string")
+            : undefined;
+        return blockers && blockers.length > 0 ? { ...refusal, blockers } : refusal;
+    }
+    const body = result.value;
+    return {
+        ok: true,
+        value: {
+            scope_id: nullableString(body["scope_id"]) ?? null,
+            scheduled: booleanOr(body["scheduled"], false),
+        },
+    };
+}

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

@@ -87,6 +87,45 @@ export function resolveConductEpicPromptsDirectory(repoName, epicKey, deps) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * Supply `null` for parse-request fields a pre-BAPI-825 version-1 ticket does
+ * not carry, returning a NEW document rather than mutating the input.
+ *
+ * The two fields 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.
+ */
+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;
+            return normalized;
+        }),
+    };
+}
 /** A non-empty string. Blank-only values are rejected everywhere. */
 function isText(value) {
     return typeof value === "string" && value.trim().length > 0;
@@ -147,6 +186,14 @@ function validateTicket(value, index) {
     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`);
+        }
+    }
     if (!Array.isArray(value.journal) || value.journal.some((line) => typeof line !== "string")) {
         return fail(`${where}.journal must be an array of strings`);
     }
@@ -203,8 +250,14 @@ function validateLock(value) {
  * 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(value) {
+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) {
@@ -218,6 +271,15 @@ export function validateConductEpicCheckpoint(value) {
         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");
@@ -301,7 +363,14 @@ export async function readConductEpicCheckpoint(checkpointPath, fs) {
     if (!validation.ok) {
         return { kind: "invalid", error: `checkpoint at ${checkpointPath} is invalid: ${validation.error}` };
     }
-    return { kind: "ok", checkpoint: parsed };
+    // 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) {
@@ -311,6 +380,8 @@ export function createInitialConductEpicCheckpoint(input) {
         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 ?? {
@@ -328,6 +399,8 @@ export function createInitialConductEpicCheckpoint(input) {
             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,
             journal: [],
         })),
         counters: { iterations: 0, merges: 0 },