opencode-swarm 7.143.5 → 7.144.0

package/.opencode/skills/swarm-pr-review/SKILL.md

@@ -1135,7 +1135,7 @@ matched family owned exactly once across the dispatch, and every owned family
 attested in that lane's output, or the lane fails for all of them. Include
 the complete exact-set
 `trigger_evaluation` ledger and the same exact current `pr_head_sha` in the
-initial micro dispatch, in a separate batch from base lanes. That first
+initial micro dispatch, in a separate batch from base lanes (those inline `trigger_evaluation` rows carry only `trigger_id`, `result`, and `evidence` — they must never include `source_batch_id` or `source_lane_id`, which belong only to `write_pr_review_trigger_eval`'s `rows`). That first
 dispatch freezes the ledger for the session. A subsequent same-session micro
 batch may omit `trigger_evaluation` and reuse the frozen ledger; when it
 explicitly supplies a copy, the copy must remain exactly identical. The
@@ -1156,7 +1156,7 @@ plus provenance for every `MATCHED` row. The tool atomically writes
 pass the exact reviewed merge-base as `base_sha`, the exact live base branch
 tip/ref used to compute it as `base_ref`, and the same `pr_head_sha` to the
 writer. The writer runs bounded `git merge-base -- <base_ref> <pr_head_sha>` and
-rejects any claimed `base_sha` that is not the exact result. It accepts only an
+rejects any claimed `base_sha` that is not the exact result. When that bounded re-check is unavailable (git timeout, spawn failure, unresolvable ref) but the supplied `base_ref` and `base_sha` exactly equal the durably bound review scope, the writer proceeds and discloses `base_verification: bound_fallback` on the receipt, which synthesis must surface in the final review report (`references/lane-output-recoverability.md`); every other outcome stays fail-closed. It accepts only an
 exact eleven-row v2 receipt backed by verifiable provenance (identity, ownership, digest, retained artifact); a coverage-QUALITY failure is disclosed on the receipt as `coverage_degradations` and the run proceeds, with synthesis disclosing degraded families (`references/lane-output-recoverability.md`). `NOT_TRIGGERED` rows are provenance-free. Counts are recomputed and
 must agree. It never uses keyword or path classification alone as absence
 evidence. Any head mismatch makes persistence fail. Historical unversioned and
@@ -1946,9 +1946,9 @@ are:
    `pr_head_sha`, `base_sha`, and `base_ref`.
 2. **Call `abort_pr_workflow`** with `mode: "PR_REVIEW"`, `kind: "recovery"`,
    and a one-line `reason` describing the blocker. The tool clears the durable gate state
-   and stops the auto-resume loop. It refuses while PR workflow lanes are
-   still in flight (collect their results with `collect_lane_results`
-   first). It accepts both unbound and bound PR_REVIEW workflows so exhausted
+   and stops the auto-resume loop. It refuses only while PR workflow lanes are still LIVE (a recent `updatedAt`); collect those with `collect_lane_results` first.
+   Lanes idle past the 30-minute staleness horizon settle as presumed-stale instead of blocking, disclosed as `presumed_stale_lanes` on the response and in `.swarm/events.jsonl`; a schema-invalid (but JSON-parseable) gate state no longer defeats abort either. See `references/lane-output-recoverability.md`.
+   It accepts both unbound and bound PR_REVIEW workflows so exhausted
    post-bind discovery or validation cannot strand the gate. An audit event is
    appended to `.swarm/events.jsonl`.
    When the tool reports `checkout_restore_required`, immediately call

package/.opencode/skills/swarm-pr-review/references/lane-output-recoverability.md

@@ -52,3 +52,132 @@ synthesis phase MUST disclose every degraded family, with its recorded reason,
 in the final review report. Retries remain the first resort (COVERAGE GATE); a
 missing provenance chain still fails closed, and the reviewer/critic inventory
 skips exactly the receipt-disclosed dispatch tuples.
+
+## Bounded merge-base fallback (`base_verification`)
+
+Every v2 receipt now records how its `base_sha` was verified at write time:
+
+- **`live`** — the writer re-derived the merge base with a bounded
+  `git merge-base -- <base_ref> <pr_head_sha>` and it matched the supplied
+  `base_sha` exactly. This is the normal path.
+- **`bound_fallback`** — that re-derivation was **unavailable**, and the writer
+  proceeded because the supplied `base_ref`/`base_sha` exactly equalled the
+  review scope already bound durably at dispatch time.
+
+The distinction matters because the git helper collapses every failure mode
+into a bare `null`: a timed-out git call, a git process that failed to spawn, a
+`base_ref` that is unresolvable in this checkout, and a ref rejected as an
+unsafe revision token are indistinguishable to the caller. Treating that `null`
+as *refutation* rather than *unavailability* made review completion permanently
+unsatisfiable — every retry re-failed identically, the trigger-eval receipt was
+never written, an omission dispatch could not repair it, and the only exit was
+`abort_pr_workflow`. The bound scope is not a weaker fact: it was itself derived
+by a real `git merge-base` at dispatch and only trimmed/lowercased on the way
+into durable state, so re-deriving it at write time is a redundant re-check.
+
+What `bound_fallback` does and does not mean:
+
+- It does **not** widen what was reviewed. The reviewed range stays SHA-scoped
+  (`base_sha...pr_head_sha`), identical to the `live` path.
+- It does mean post-bind movement or deletion of the base ref would go
+  undetected for this run — the one staleness signal the live re-check provides.
+- It never relaxes a mismatch. If the re-check is unavailable **and** the
+  supplied scope differs from the bound scope in either half, the writer fails
+  closed with an enriched message naming the possible causes and the recovery
+  options. If the gate has no bound base at all, the writer fails closed before
+  attempting resolution.
+
+**Synthesis obligation (skill-directed):** when the trigger-eval result or the persisted receipt
+reports `base_verification: bound_fallback`, the final review report MUST
+disclose it. State that the merge base could not be re-verified live at write time and that the review was
+scoped to the durably bound base. Do not silently present the review as if the
+base had been re-verified. (Unlike `coverage_degradations`, which the workflow gate reads as a machine-enforced waiver filter, `bound_fallback` disclosure is skill-directed.)
+
+## Provenance fields: dispatch ledger vs. writer rows
+
+Two different row shapes carry the trigger evaluation, and mixing them up is a
+recurring source of first-dispatch failures:
+
+- **Dispatch-time `trigger_evaluation` rows** (the inline ledger frozen by the
+  first micro dispatch) use the strict inline schema: `trigger_id`, `result`,
+  and `evidence`, and nothing else. Adding `source_batch_id` or
+  `source_lane_id` there is rejected — at dispatch time no lane has run yet, so
+  there is no provenance to cite, and the frozen-ledger digest is computed over
+  exactly those three fields.
+- **Writer `rows`** (passed to `write_pr_review_trigger_eval` after the lanes
+  settle) carry the provenance: every `MATCHED` row adds the `source_batch_id`
+  and `source_lane_id` returned by its completed micro lane, and every
+  `NOT_TRIGGERED` row must omit both.
+
+Classifications must be identical across the two — the writer rejects
+classification drift from the frozen ledger — while `evidence` may be reworded
+in the writer call and is simply ignored (the frozen values are authoritative).
+
+## Gate-level recovery: stuck lanes, corrupted state, amended inventory
+
+Three wedge states used to leave a workflow with no exit through any tool. Each
+now degrades with disclosure; the contradiction cases still fail closed.
+
+### Stale lanes no longer block abort or completion
+
+A lane whose background process dies without writing a terminal snapshot used to
+count as "in flight" forever, and the same predicate gates `abort_pr_workflow`,
+the PR_REVIEW to PR_FEEDBACK transition, and `complete_pr_workflow` — so the
+escape hatch was refused by the very condition it exists to resolve.
+
+A lane whose delegation record has not advanced its `updatedAt` for 30 minutes is
+now **presumed stale** and settles instead of blocking. The disclosure appears as
+`presumed_stale_lanes` / `presumed_stale_disclosure` on the `abort_pr_workflow`
+and `complete_pr_workflow` responses, as a `pr_workflow_lanes_presumed_stale`
+record in `.swarm/events.jsonl`, and on the `pr_workflow_aborted` audit event.
+The delegation record itself is transitioned to `stale`.
+
+A lane with a **recent** `updatedAt` still blocks — a check that can run and
+reports "still progressing" is not softened. Collect it with
+`collect_lane_results`, or wait for the horizon.
+
+### A corrupted gate state no longer defeats abort
+
+If the durable gate-state file fails schema validation but is still valid JSON,
+`abort_pr_workflow` and `pr_workflow_status` read it through a **recovery-only**
+reader that salvages `sessionID`, `mode`, `prHeadSha`, and — when each is
+individually well-formed — `revision`, `prFeedbackReadyToPublish` and
+`checkoutRecovery`. Every other reader, including all write and completion paths,
+still refuses the file, so a salvaged view can never be acted on as if it were
+valid. `stateSalvaged` / `stateSalvageDisclosure` name the schema errors.
+
+Boundaries that deliberately did NOT soften:
+
+- **Unparseable bytes fail everywhere.** There is nothing to salvage.
+- **Unreadable identity fails everywhere.** Without a readable `sessionID` and
+  `mode` there is no provable subject to act on.
+- **An unreadable `prFeedbackReadyToPublish` is treated as ARMED**, so abort
+  still refuses. Corrupting that one record must never become a way past the
+  armed-abort refusal.
+- When `revision` cannot be salvaged, abort takes the documented
+  compare-and-swap escape and says so:
+  `state revision unsalvageable; cleared without compare-and-swap`.
+
+### The PR_FEEDBACK inventory is append-only, not immutable
+
+A finding discovered after `declarePrFeedbackInventory` used to require
+`abort_pr_workflow` plus a full restart, discarding completed verification work
+for correctly-declared items. Re-declaring with **additional** items is now
+accepted; every previously-declared entry must still be present, so mutation and
+removal still hard-fail (`inventory is append-only after declaration`).
+
+What an amendment costs, and what it preserves:
+
+- Completed **verification** batches for the original items are preserved. Cover
+  the appended item with a new verification batch owning just that item.
+- Stage A must be re-recorded over the full amended inventory, and each ordered
+  gate phase must be re-run with a lane owning every current inventory item —
+  a gate batch recorded before the amendment no longer settles its phase. This
+  is deliberate: it is the control that stops an appended item reaching
+  publication with no verdict.
+- Publication is disarmed by an amendment (the armed record attested coverage of
+  the pre-amendment inventory). Re-arm with one `complete_pr_workflow` call.
+- Every appended entry is recorded in an audit ledger surfaced as
+  `inventory_amendments` on the completion response and `inventoryAmendments` on
+  `pr_workflow_status`. The ledger is bounded at 128 entries and is never pruned;
+  further amendments are refused at the cap.

package/dist/background/delegation-health.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Durable health/status artifact for the background-delegation store (issue #2034,
+ * parent #1659).
+ *
+ * This module owns ONLY the `.swarm/background-delegations-health.json` artifact:
+ * a bounded, machine-readable observation copy of ledger health (bytes/limit/
+ * pressure, last successful checkpoint, recovery source, the most recent durable
+ * uncertainty, and live-set counters). It deliberately imports nothing from the
+ * store itself so `pending-delegations.ts` can write the artifact while holding
+ * the store lock without an import cycle, and so `/swarm status` can read it with
+ * nothing more than `statSync` + one small JSON read — never a ledger fold.
+ *
+ * The artifact is an OBSERVATION copy, never an ownership or settlement record
+ * (issue requirement 8): deleting it loses no state, only visibility. Counters
+ * are computed and refreshed by the store (at compaction time, under the store
+ * lock) and by recovery observations; readers treat a missing artifact as
+ * "nothing to report" rather than "healthy".
+ */
+import { z } from 'zod';
+export declare const BACKGROUND_DELEGATIONS_HEALTH_FILE = "background-delegations-health.json";
+/**
+ * Strict recovery bound for the delegation ledger/tail (issue #2034: the
+ * guard itself is unchanged — compaction exists so normal operation never
+ * approaches it). Lives here so the health module can default a valid artifact
+ * without importing the store (no import cycle).
+ */
+export declare const MAX_RECOVERY_LEDGER_BYTES: number;
+export type DelegationLedgerPressureBand = 'ok' | 'nominal' | 'compact-overdue' | 'fail-closed';
+export interface DelegationCheckpointAuditSummary {
+    dispatchCount: number;
+    terminalsByStatus: {
+        completed: number;
+        error: number;
+        cancelled: number;
+        stale: number;
+    };
+    settledCount: number;
+    preservedCount: number;
+    lateTerminalCount: number;
+    compactedTransitionCount: number;
+    compactedRecordCount: number;
+    firstDispatchAt: number | null;
+    lastTerminalAt: number | null;
+    lastCompactionAt: number;
+}
+export interface DelegationHealthCheckpointSection {
+    sequence: number;
+    createdAt: number;
+    liveRecords: number;
+    closedSummaries: number;
+    bytes: number;
+    audit: DelegationCheckpointAuditSummary;
+}
+export interface DelegationHealthRecoverySection {
+    source: 'checkpoint+tail' | 'checkpoint+ledger-suffix' | 'legacy-ledger' | 'unknown';
+    at: number;
+    ok: boolean;
+    reason?: string;
+    repairHint?: string;
+}
+export interface DelegationHealthUncertaintySection {
+    reason: string;
+    at: number;
+    source: string;
+    repairHint?: string;
+}
+export interface DelegationLedgerHealth {
+    schemaVersion: 1;
+    updatedAt: number;
+    ledger: {
+        bytes: number;
+        limitBytes: number;
+        pressurePct: number;
+        band: DelegationLedgerPressureBand;
+    };
+    checkpoint: DelegationHealthCheckpointSection | null;
+    recovery: DelegationHealthRecoverySection | null;
+    lastUncertainty: DelegationHealthUncertaintySection | null;
+    counts: {
+        activeOwners: number;
+        pendingAdvisories: number;
+        lateTerminals: number;
+        orphanWorktreeOwners: number;
+    };
+}
+export declare const DelegationCheckpointAuditSchema: z.ZodObject<{
+    dispatchCount: z.ZodNumber;
+    terminalsByStatus: z.ZodObject<{
+        completed: z.ZodNumber;
+        error: z.ZodNumber;
+        cancelled: z.ZodNumber;
+        stale: z.ZodNumber;
+    }, z.core.$strict>;
+    settledCount: z.ZodNumber;
+    preservedCount: z.ZodNumber;
+    lateTerminalCount: z.ZodNumber;
+    compactedTransitionCount: z.ZodNumber;
+    compactedRecordCount: z.ZodNumber;
+    firstDispatchAt: z.ZodNullable<z.ZodNumber>;
+    lastTerminalAt: z.ZodNullable<z.ZodNumber>;
+    lastCompactionAt: z.ZodNumber;
+}, z.core.$strict>;
+export declare const DelegationLedgerHealthSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    updatedAt: z.ZodNumber;
+    ledger: z.ZodObject<{
+        bytes: z.ZodNumber;
+        limitBytes: z.ZodNumber;
+        pressurePct: z.ZodNumber;
+        band: z.ZodEnum<{
+            ok: "ok";
+            nominal: "nominal";
+            "compact-overdue": "compact-overdue";
+            "fail-closed": "fail-closed";
+        }>;
+    }, z.core.$strict>;
+    checkpoint: z.ZodNullable<z.ZodObject<{
+        sequence: z.ZodNumber;
+        createdAt: z.ZodNumber;
+        liveRecords: z.ZodNumber;
+        closedSummaries: z.ZodNumber;
+        bytes: z.ZodNumber;
+        audit: z.ZodObject<{
+            dispatchCount: z.ZodNumber;
+            terminalsByStatus: z.ZodObject<{
+                completed: z.ZodNumber;
+                error: z.ZodNumber;
+                cancelled: z.ZodNumber;
+                stale: z.ZodNumber;
+            }, z.core.$strict>;
+            settledCount: z.ZodNumber;
+            preservedCount: z.ZodNumber;
+            lateTerminalCount: z.ZodNumber;
+            compactedTransitionCount: z.ZodNumber;
+            compactedRecordCount: z.ZodNumber;
+            firstDispatchAt: z.ZodNullable<z.ZodNumber>;
+            lastTerminalAt: z.ZodNullable<z.ZodNumber>;
+            lastCompactionAt: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    recovery: z.ZodNullable<z.ZodObject<{
+        source: z.ZodEnum<{
+            unknown: "unknown";
+            "checkpoint+tail": "checkpoint+tail";
+            "checkpoint+ledger-suffix": "checkpoint+ledger-suffix";
+            "legacy-ledger": "legacy-ledger";
+        }>;
+        at: z.ZodNumber;
+        ok: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+        repairHint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    lastUncertainty: z.ZodNullable<z.ZodObject<{
+        reason: z.ZodString;
+        at: z.ZodNumber;
+        source: z.ZodString;
+        repairHint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    counts: z.ZodObject<{
+        activeOwners: z.ZodNumber;
+        pendingAdvisories: z.ZodNumber;
+        lateTerminals: z.ZodNumber;
+        orphanWorktreeOwners: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * Test seam for the atomic-rename retry (issue #2034): tests inject a
+ * transient EPERM here to exercise the real retry loop.
+ */
+export declare const _healthInternals: {
+    renameOnce: (from: string, to: string) => void;
+};
+export declare function healthArtifactPath(directory: string): string;
+/** Read the health artifact; null when absent or malformed (readers fail open). */
+export declare function readDelegationHealthArtifact(directory: string): DelegationLedgerHealth | null;
+/**
+ * Merge a partial update into the current artifact and write it atomically.
+ * Callers that can hold the store lock must do so (compaction, recovery
+ * observation); standalone readers never write. Merge is section-wise: a null
+ * section clears it, an undefined section preserves the existing value.
+ */
+export declare function writeDelegationHealthArtifact(directory: string, update: {
+    ledger?: DelegationLedgerHealth['ledger'];
+    checkpoint?: DelegationLedgerHealth['checkpoint'] | null;
+    recovery?: DelegationLedgerHealth['recovery'] | null;
+    lastUncertainty?: DelegationLedgerHealth['lastUncertainty'] | null;
+    counts?: DelegationLedgerHealth['counts'];
+    uncertainty?: DelegationHealthUncertaintySection;
+}): DelegationLedgerHealth | null;
+/**
+ * Record a startup-recovery observation (called by init-orphan-recovery after
+ * its scans): how the primary store was reconstructed and whether it succeeded.
+ * A failing observation also becomes the durable `lastUncertainty`, so the
+ * incident stays visible in `/swarm status` after the in-memory failure is gone
+ * (issue #1659). Best-effort: never throws.
+ */
+export declare function recordDelegationRecoveryObservation(directory: string, observation: {
+    source: 'checkpoint+tail' | 'checkpoint+ledger-suffix' | 'legacy-ledger' | 'unknown';
+    ok: boolean;
+    reason?: string;
+    repairHint?: string;
+}): void;
+/**
+ * Fold-free health collection for `/swarm status`: statSync of the ledger and
+ * checkpoint, a display-tolerant manifest peek (sequence/tailRolled only), and
+ * the durable artifact. Never reads or folds the ledger contents, so the status
+ * path stays bounded no matter how much history exists (issue #2034 critic #5).
+ */
+export declare function collectDelegationLedgerHealth(directory: string, options: {
+    ledgerLimitBytes: number;
+    lowWaterBytes: number;
+    highWaterBytes: number;
+}): DelegationLedgerHealth | null;

package/dist/background/pending-delegations.d.ts

@@ -1,5 +1,6 @@
 /**
- * Durable pending background-delegation store (issue #1151, PR 2 Stage A).
+ * Durable pending background-delegation store (issue #1151, PR 2 Stage A;
+ * bounded recovery via checkpoint/tail compaction — issue #2034).
  *
  * Append-only JSONL event log under project-root `.swarm/background-delegations.jsonl`.
  * Each line is a full record snapshot; readers fold to the latest snapshot per
@@ -7,38 +8,116 @@
  * async advisory lanes so trusted completions can be correlated to a real dispatch.
  * The stale sweep bounds the number of permanently-running entries by transitioning
  * them to `stale`, so the folded in-memory view stays bounded by distinct correlationIds.
- * The on-disk log itself is append-only and is NOT compacted; each dispatch leaves a
- * small, fixed number of lines.
+ *
+ * Bounded recovery (issue #2034): the raw log alone is no longer the recovery
+ * source once history grows. Compaction — run lazily under the store lock when the
+ * ledger passes `DELEGATION_COMPACTION_HIGH_WATER_BYTES` — checkpoints the folded
+ * authoritative state (active ownership, terminal results, coder settlement, pending
+ * advisory inbox) plus compact closed-record summaries into
+ * `.swarm/background-delegations.checkpoint.json`, publishes it via
+ * `.swarm/background-delegations.manifest.json`, and rolls the ledger to the
+ * post-cut transition tail. Recovery folds checkpoint + bounded tail with hard
+ * byte/count bounds and preserves fail-closed uncertainty; the 4 MiB
+ * `MAX_RECOVERY_LEDGER_BYTES` guard is unchanged and still applies to legacy
+ * uncheckpointed ledgers.
  *
  * Scope: dispatch records `pending`/`running` snapshots, collection or trusted synthetic
  * completions record terminal snapshots, and the stale sweep records `stale` snapshots.
  * This store itself has no gate-advancement side effect. Stage B gate ingestion is a
- * separate consumer of trusted terminal snapshots.
+ * separate consumer of trusted terminal snapshots. Circuit-breaker and transient-retry
+ * counters are invocation-owned and are NEVER serialized here (issue #2034 req 9).
  *
- * Concurrency: all writes (append, sweep) run under a single project-scoped lock via
- * `withEvidenceLock`, so concurrent dispatches/sweeps cannot interleave appends. Reads are
- * lock-free (line-oriented; partial trailing lines are skipped defensively).
+ * Concurrency: all writes (append, sweep, compaction) run under a single
+ * project-scoped lock via `withEvidenceLock`, so concurrent dispatches/sweeps cannot
+ * interleave appends. Reads are lock-free (line-oriented; partial trailing lines are
+ * skipped defensively by the lenient reader; the strict recovery reader fails closed).
  *
- * Containment: the path is validated with `validateSwarmPath`, so it can never escape
- * `.swarm/` (Invariant 4).
+ * Containment: every path is validated with `validateSwarmPath`, so it can never
+ * escape `.swarm/` (Invariant 4).
  */
+import { type DelegationCheckpointAuditSummary } from './delegation-health.js';
 export declare const BACKGROUND_DELEGATIONS_FILE = "background-delegations.jsonl";
 export declare const BACKGROUND_DELEGATION_FALLBACK_DIR = "background-delegation-fallback";
 export declare const BACKGROUND_CODER_RESERVATIONS_FILE = "background-coder-reservations.json";
+export declare const BACKGROUND_DELEGATIONS_CHECKPOINT_FILE = "background-delegations.checkpoint.json";
+export declare const BACKGROUND_DELEGATIONS_MANIFEST_FILE = "background-delegations.manifest.json";
 export declare const MAX_LIVE_BACKGROUND_FALLBACKS = 256;
 export declare const MAX_LIVE_BACKGROUND_CODER_RESERVATIONS = 256;
 export declare const MAX_BACKGROUND_OBSERVED_FILES = 5000;
 export declare const MAX_BACKGROUND_ADVISORY_CHARS = 4000;
+/** Strict recovery bound for the ledger/tail (issue #2034: unchanged guard). */
+export { MAX_RECOVERY_LEDGER_BYTES } from './delegation-health.js';
+/**
+ * Compaction watermarks (issue #2034). Auto-compaction fires above the high
+ * water mark so the post-roll tail plus one in-flight append (~250 KiB worst
+ * case) stays far below the 4 MiB strict recovery bound in normal operation.
+ */
+export declare const DELEGATION_COMPACTION_LOW_WATER_BYTES: number;
+export declare const DELEGATION_COMPACTION_HIGH_WATER_BYTES: number;
+/** Hard validation bound for the checkpoint file on every read. */
+export declare const MAX_CHECKPOINT_BYTES: number;
+/** Hard validation bound for live (non-summary) records in a checkpoint. */
+export declare const MAX_CHECKPOINT_RECORDS = 2048;
+/**
+ * Closed-record summaries younger than this are never evicted to meet the
+ * checkpoint byte budget — evicting them would let a replayed dispatch of a
+ * recently closed session be recorded as fresh (double delivery). Over-budget
+ * young state skips compaction and surfaces pressure instead.
+ */
+export declare const TOMBSTONE_MIN_AGE_MS: number;
 export type RecoveryOwnershipScanResult<T> = {
     status: 'ok';
     owners: T[];
+    /** How the primary store was reconstructed (issue #2034); absent for pre-checkpoint scans. */
+    source?: 'checkpoint+tail' | 'checkpoint+ledger-suffix' | 'legacy-ledger';
 } | {
     status: 'uncertain';
     reason: string;
+    /**
+     * Best-known interpretation mode at failure time; `'unknown'` when the
+     * manifest/checkpoint state itself was unreadable (issue #2034 — the
+     * durable recovery observation must not claim a wrong source).
+     */
+    source?: 'checkpoint+tail' | 'checkpoint+ledger-suffix' | 'legacy-ledger' | 'unknown';
+    /** Operator remediation guidance, when the failure mode has one. */
+    repairHint?: string;
 };
 /** An abandoned ingestion lease may be reclaimed after this bounded interval. */
 export declare const BACKGROUND_INGESTION_LEASE_MS = 30000;
+/**
+ * Canonical default staleness horizon for a tracked background delegation: a
+ * record whose `updatedAt` has not advanced in this long is treated as
+ * abandoned (its backing process died without ever writing a terminal
+ * snapshot) and may be swept to `stale`.
+ *
+ * 30 minutes is the value this subsystem already shipped — it was duplicated as
+ * a module-local literal in `src/tools/dispatch-lanes.ts` and as the
+ * `hooks.background_pending_timeout_minutes` schema default. It lives here so
+ * every consumer agrees on one number: this module imports nothing from
+ * `dispatch-lanes.ts` or `pr-workflow-gate.ts`, so both can reference it
+ * without an import cycle.
+ */
+export declare const DEFAULT_STALE_DELEGATION_TIMEOUT_MS: number;
 export type BackgroundDelegationStatus = 'pending' | 'running' | 'ingesting' | 'ingestion_error' | 'completed' | 'error' | 'cancelled' | 'stale' | 'consumed';
+/**
+ * The status classes the stale sweep is allowed to finalize to `stale`.
+ *
+ * Deliberately a subset of {@link BackgroundDelegationStatus}: a caller may
+ * *narrow* the sweep but can never widen it to a status the sweep was never
+ * meant to touch (`completed`, `consumed`, `ingesting`, ...).
+ */
+export type SweepableDelegationStatus = 'pending' | 'running' | 'ingestion_error';
+/**
+ * Default sweep scope — the exact set the sweep has always finalized.
+ *
+ * `ingestion_error` is included here because the pre-existing lazy-maintenance
+ * caller (`recordPendingDelegation`) relies on it: an ingestion that never
+ * retried within the horizon is genuinely abandoned from that caller's point of
+ * view. Callers for whom `ingestion_error` is still *retryable* — the ingestion
+ * claim gate admits `completed` and `ingestion_error` only, so the `stale` flip
+ * is irreversible — must pass a narrowed set instead.
+ */
+export declare const DEFAULT_SWEEPABLE_DELEGATION_STATUSES: ReadonlySet<SweepableDelegationStatus>;
 export interface BackgroundDelegationRecord {
     schemaVersion: 1 | 2 | 3;
     /** Subagent session id from the dispatch envelope — the correlation key. */
@@ -218,20 +297,81 @@ export interface BackgroundCoderReservation {
     createdAt: number;
     updatedAt: number;
 }
+export interface BackgroundDelegationCheckpoint {
+    schemaVersion: 1;
+    /** Monotonic checkpoint sequence for this store. */
+    sequence: number;
+    /** Diagnostics-only identity of the writing process (never validated). */
+    writerId: string;
+    /** Resolved project root this checkpoint is bound to. */
+    rootPath: string;
+    createdAt: number;
+    /** Byte length of the ledger at the cut. */
+    cutLedgerBytes: number;
+    /** sha256 of the ledger bytes [0..cutLedgerBytes) at the cut. */
+    cutLedgerDigest: string;
+    /** Live full records (bounded by MAX_CHECKPOINT_RECORDS). */
+    records: BackgroundDelegationRecord[];
+    /** Compact closed-record summaries, byte-budget governed. */
+    closed: BackgroundDelegationRecord[];
+    audit: DelegationCheckpointAuditSummary;
+    payloadChecksum: string;
+}
+export interface BackgroundDelegationManifest {
+    schemaVersion: 1;
+    sequence: number;
+    checkpointChecksum: string;
+    writerId: string;
+    rootPath: string;
+    updatedAt: number;
+}
+export declare const _checkpointInternals: {
+    renameWithRetry: (from: string, to: string) => void;
+    renameOnce: (from: string, to: string) => void;
+    syncSleep: (ms: number) => void;
+};
+/**
+ * True when a record still owns an unsettled worktree (mirrors
+ * init-orphan-recovery's protection predicate — exported so both sites share
+ * ONE definition; drift here changes which worktrees orphan cleanup protects).
+ */
+export declare function isUnsettledWorktreeOwner(record: BackgroundDelegationRecord): boolean;
+export interface CompactBackgroundDelegationsResult {
+    status: 'compacted' | 'skipped' | 'uncertain';
+    reason?: string;
+    sequence?: number;
+    tailBytes?: number;
+    checkpointBytes?: number;
+}
+/**
+ * Compact the delegation ledger: checkpoint the folded authoritative state,
+ * publish it via the manifest, and roll the ledger to the post-cut tail.
+ * Runs under the store lock (issue #2034 requirement 1).
+ */
+export declare function compactBackgroundDelegations(directory: string, options?: {
+    force?: boolean;
+}): Promise<CompactBackgroundDelegationsResult>;
 /**
  * Read and fold the store to the latest snapshot per correlationId. Lock-free and
- * defensive: a missing file yields an empty list, and malformed/partial lines are skipped
- * (never throws). Records are returned in first-seen correlationId order.
+ * defensive: a missing file yields an empty list, and malformed/partial lines are
+ * skipped (never throws). Records are returned in first-seen correlationId order.
+ *
+ * Checkpoint-aware (issue #2034): when a published checkpoint exists, the fold is
+ * checkpoint summaries + the bounded transition tail. When the authoritative
+ * state is uncertain (invalid checkpoint/manifest with a rolled tail), this
+ * returns [] — the strict recovery scan is the fail-closed authority.
  *
- * Cost: O(lines on disk) per call — a full read + parse + fold with no in-memory cache.
- * This is intentionally simple and acceptable at advisory-lane volumes (a swarm has few
- * concurrent background delegations, and the on-disk log is small).
+ * Cost: O(checkpoint + tail lines) per call. The tail is bounded by the
+ * compaction high-water mark in normal operation.
  */
 export declare function readDelegations(directory: string): BackgroundDelegationRecord[];
 /**
- * Strict startup-recovery view of the primary ledger. Unlike the ordinary
+ * Strict startup-recovery view of the primary store. Unlike the ordinary
  * advisory reader, this never treats unreadable, oversized, or malformed owner
  * data as absence: destructive orphan cleanup must fail closed on uncertainty.
+ * Checkpoint-aware: folds checkpoint + the applicable bounded tail region and
+ * rejects corrupt or ambiguous cuts (issue #2034). Remains synchronous —
+ * callers depend on it.
  */
 export declare function scanDelegationsForRecovery(directory: string): RecoveryOwnershipScanResult<BackgroundDelegationRecord>;
 /** Returns the folded record for a correlationId, or null. Lock-free read. */
@@ -398,8 +538,16 @@ export declare function findOpenAsyncLaneBatches(directory: string): BackgroundD
 /**
  * Public stale sweep: acquires the store lock and marks overdue pendings as `stale`.
  * Best-effort; returns the number swept (0 on lock timeout / error).
+ *
+ * `options.statuses` narrows which status classes may be finalized; omitting it
+ * preserves the historical scope ({@link DEFAULT_SWEEPABLE_DELEGATION_STATUSES}).
+ * The sweep is directory-wide with no session or mode filter, so a caller whose
+ * own decision covers only some status classes must narrow accordingly rather
+ * than finalizing records it never reasoned about.
  */
-export declare function sweepStaleDelegations(directory: string, timeoutMs: number): Promise<number>;
+export declare function sweepStaleDelegations(directory: string, timeoutMs: number, options?: {
+    statuses?: ReadonlySet<SweepableDelegationStatus>;
+}): Promise<number>;
 export interface BackgroundDelegationFallbackArtifact {
     schemaVersion: 1;
     correlationId: string;

package/dist/background/pr-review-trigger-contract.d.ts

@@ -207,6 +207,16 @@ export interface BuildPrReviewTriggerReceiptV2Args {
     rows: unknown;
     /** Receipt-level degradation disclosure; ledger rows stay untouched so the frozen-ledger digest is unaffected. */
     coverage_degradations?: TriggerCoverageDegradation[];
+    /**
+     * How `base_sha` was verified for this receipt. `live` means the writer
+     * re-derived the merge base with git at write time; `bound_fallback` means
+     * that re-derivation was UNAVAILABLE and the writer accepted the caller's
+     * scope solely because it exactly equalled the durably bound, bind-time
+     * verified review scope. Optional for the same reason
+     * `coverage_degradations` is: the field is receipt-level disclosure, and
+     * making it required would break every existing builder call site.
+     */
+    base_verification?: 'live' | 'bound_fallback';
 }
 export declare function buildPrReviewTriggerReceiptV2(input: BuildPrReviewTriggerReceiptV2Args): {
     run_id: string;
@@ -243,6 +253,7 @@ export declare function buildPrReviewTriggerReceiptV2(input: BuildPrReviewTrigge
         source_lane_id: string;
         reason: string;
     }[];
+    base_verification?: "live" | "bound_fallback" | undefined;
 };
 export interface ParsedPrReviewTriggerReceipt {
     schemaVersion: 0 | 1 | 2;
@@ -255,6 +266,12 @@ export interface ParsedPrReviewTriggerReceipt {
     }>[];
     /** Empty for pre-v2.2 receipts. Present entries mean the family's cited lane is provenance-valid but coverage-degraded. */
     coverageDegradations: TriggerCoverageDegradation[];
+    /**
+     * Undefined for legacy receipts and for v2 receipts written before the field
+     * existed. `bound_fallback` means the writer could not re-derive the merge
+     * base live and accepted the bound scope instead; synthesis must disclose it.
+     */
+    baseVerification?: 'live' | 'bound_fallback';
 }
 /**
  * Bind every micro dispatch to one semantic ledger at bind time.

package/dist/cli/{config-doctor-y8wfw196.js → config-doctor-7gy47evn.js}

@@ -12,8 +12,8 @@ import {
   shouldRunOnStartup,
   writeBackupArtifact,
   writeDoctorArtifact
-} from "./index-a4dkd7m7.js";
-import"./index-04x9wx7d.js";
+} from "./index-evvbmbbv.js";
+import"./index-3q9w6e6v.js";
 import"./index-jqsfsqbx.js";
 import"./index-z6xqpmqg.js";
 import"./index-zjygnfay.js";