@bookedsolid/rea 0.10.3 → 0.12.0

package/dist/hooks/push-gate/report.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Report output for the push-gate.
+ *
+ * Two channels:
+ *
+ *   1. `.rea/last-review.json` — machine-readable structured dump. Atomic
+ *      write (write-to-tmp + rename), gitignored, overwritten every push.
+ *      Claude reads this as the source of truth for file/line/body during
+ *      the auto-fix loop.
+ *
+ *   2. stderr banner — human-legible severity-sorted summary capped to 20
+ *      findings. The pre-push hook's stderr reaches Claude as the tool
+ *      output of `Bash(git push)`, so this is the primary fast-path to
+ *      surface verdict + first blocking finding.
+ *
+ * Redaction: before serializing anything to disk or stderr we run the
+ * shared `SECRET_PATTERNS` list over `title`, `body`, and `reviewText`. If
+ * Codex accidentally quoted a secret from the diff (common in password-
+ * reset flows, API-key migration PRs, env-file edits) it never hits disk
+ * in cleartext.
+ */
+import type { Finding, ReviewSummary, Verdict } from './findings.js';
+export interface LastReviewPayload {
+    schema_version: 1;
+    /** ISO-8601 UTC timestamp of the review run (wall clock). */
+    generated_at: string;
+    verdict: Verdict;
+    base_ref: string;
+    head_sha: string;
+    finding_count: number;
+    findings: Finding[];
+    /** Full agent text (post-redact). Useful for debugging parser misses. */
+    review_text: string;
+    /** Number of raw JSONL events Codex emitted. */
+    event_count: number;
+    /** Wall clock seconds in the Codex subprocess. */
+    duration_seconds: number;
+}
+export interface WriteLastReviewInput {
+    baseDir: string;
+    summary: ReviewSummary;
+    baseRef: string;
+    headSha: string;
+    eventCount: number;
+    durationSeconds: number;
+    /** Test seam — defaults to `new Date()`. */
+    now?: Date;
+}
+/**
+ * Atomic write of `.rea/last-review.json`. Returns the redacted payload
+ * actually written so the caller can reuse it for stderr rendering
+ * without re-redacting.
+ *
+ * We write to `last-review.json.tmp.<pid>-<rand>` first, fsync the file
+ * descriptor, then rename. rename(2) is atomic within the same
+ * filesystem, so partial writes never surface to readers.
+ */
+export declare function writeLastReview(input: WriteLastReviewInput): LastReviewPayload;
+export interface RenderBannerInput {
+    payload: LastReviewPayload;
+    /** Where was the base ref sourced from (audit / debugging). */
+    baseSource: string;
+    /**
+     * Whether the verdict-level action is BLOCKED or SOFT. Surfaced in the
+     * banner first line. Callers infer this from verdict + concerns_blocks.
+     */
+    blocked: boolean;
+    /** Last-review.json on-disk path — shown as a pointer. */
+    lastReviewPath: string;
+    /** Max findings to enumerate in the banner. Default 20. */
+    maxFindings?: number;
+}
+/**
+ * Build the stderr banner as a single multi-line string. Ends with `\n`.
+ *
+ * Layout:
+ *
+ *   ┌────────────────────────────────────────────┐
+ *   │ push-gate VERDICT — BLOCKED / PROCEEDING   │
+ *   │ base: <ref> (<source>)                     │
+ *   │ head: <sha>                                │
+ *   │ findings: <count>                          │
+ *   └────────────────────────────────────────────┘
+ *   - [P1] Title — file:42
+ *       body-excerpt
+ *   ...
+ *   see .rea/last-review.json for full details
+ */
+export declare function renderBanner(input: RenderBannerInput): string;

package/dist/hooks/push-gate/report.js

@@ -0,0 +1,140 @@
+/**
+ * Report output for the push-gate.
+ *
+ * Two channels:
+ *
+ *   1. `.rea/last-review.json` — machine-readable structured dump. Atomic
+ *      write (write-to-tmp + rename), gitignored, overwritten every push.
+ *      Claude reads this as the source of truth for file/line/body during
+ *      the auto-fix loop.
+ *
+ *   2. stderr banner — human-legible severity-sorted summary capped to 20
+ *      findings. The pre-push hook's stderr reaches Claude as the tool
+ *      output of `Bash(git push)`, so this is the primary fast-path to
+ *      surface verdict + first blocking finding.
+ *
+ * Redaction: before serializing anything to disk or stderr we run the
+ * shared `SECRET_PATTERNS` list over `title`, `body`, and `reviewText`. If
+ * Codex accidentally quoted a secret from the diff (common in password-
+ * reset flows, API-key migration PRs, env-file edits) it never hits disk
+ * in cleartext.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { compileDefaultSecretPatterns, redactSecrets, } from '../../gateway/middleware/redact.js';
+const LAST_REVIEW_FILENAME = 'last-review.json';
+/**
+ * Atomic write of `.rea/last-review.json`. Returns the redacted payload
+ * actually written so the caller can reuse it for stderr rendering
+ * without re-redacting.
+ *
+ * We write to `last-review.json.tmp.<pid>-<rand>` first, fsync the file
+ * descriptor, then rename. rename(2) is atomic within the same
+ * filesystem, so partial writes never surface to readers.
+ */
+export function writeLastReview(input) {
+    const { baseDir, summary, baseRef, headSha, eventCount, durationSeconds } = input;
+    const now = input.now ?? new Date();
+    const patterns = compileDefaultSecretPatterns({ source: 'default' });
+    const payload = {
+        schema_version: 1,
+        generated_at: now.toISOString(),
+        verdict: summary.verdict,
+        base_ref: baseRef,
+        head_sha: headSha,
+        finding_count: summary.findings.length,
+        findings: summary.findings.map((f) => redactFinding(f, patterns)),
+        review_text: redactString(summary.reviewText, patterns),
+        event_count: eventCount,
+        duration_seconds: Number.isFinite(durationSeconds) ? durationSeconds : 0,
+    };
+    const reaDir = path.join(baseDir, '.rea');
+    ensureDir(reaDir);
+    const finalPath = path.join(reaDir, LAST_REVIEW_FILENAME);
+    const tmpPath = `${finalPath}.tmp.${process.pid}-${randomBytes(4).toString('hex')}`;
+    const fd = fs.openSync(tmpPath, 'w', 0o600);
+    try {
+        fs.writeFileSync(fd, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf8' });
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmpPath, finalPath);
+    return payload;
+}
+function redactFinding(f, patterns) {
+    return {
+        severity: f.severity,
+        title: redactString(f.title, patterns),
+        body: redactString(f.body, patterns),
+        ...(f.file !== undefined ? { file: f.file } : {}),
+        ...(f.line !== undefined ? { line: f.line } : {}),
+    };
+}
+function redactString(s, patterns) {
+    const { output } = redactSecrets(s, patterns);
+    return output;
+}
+function ensureDir(dir) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch (e) {
+        // mkdir -p is idempotent; EEXIST is fine, anything else surfaces to
+        // the caller and becomes an exit-2 error.
+        const code = e.code;
+        if (code !== 'EEXIST')
+            throw e;
+    }
+}
+const SEVERITY_ORDER = { P1: 0, P2: 1, P3: 2 };
+/**
+ * Build the stderr banner as a single multi-line string. Ends with `\n`.
+ *
+ * Layout:
+ *
+ *   ┌────────────────────────────────────────────┐
+ *   │ push-gate VERDICT — BLOCKED / PROCEEDING   │
+ *   │ base: <ref> (<source>)                     │
+ *   │ head: <sha>                                │
+ *   │ findings: <count>                          │
+ *   └────────────────────────────────────────────┘
+ *   - [P1] Title — file:42
+ *       body-excerpt
+ *   ...
+ *   see .rea/last-review.json for full details
+ */
+export function renderBanner(input) {
+    const { payload, baseSource, blocked, lastReviewPath } = input;
+    const max = input.maxFindings ?? 20;
+    const verdictLabel = blocked ? 'BLOCKED' : 'PROCEEDING';
+    const lines = [];
+    lines.push('');
+    lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    lines.push(`rea push-gate: ${payload.verdict.toUpperCase()} — ${verdictLabel}`);
+    lines.push(`base:     ${payload.base_ref}  (${baseSource})`);
+    lines.push(`head:     ${payload.head_sha}`);
+    lines.push(`findings: ${payload.finding_count}`);
+    lines.push(`elapsed:  ${payload.duration_seconds.toFixed(1)}s`);
+    lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    if (payload.findings.length === 0) {
+        lines.push('(no findings)');
+    }
+    else {
+        const sorted = [...payload.findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+        const shown = sorted.slice(0, max);
+        for (const f of shown) {
+            const loc = f.file !== undefined ? ` — ${f.file}${f.line !== undefined ? `:${f.line}` : ''}` : '';
+            lines.push(`- [${f.severity}] ${f.title}${loc}`);
+        }
+        if (sorted.length > shown.length) {
+            lines.push(`... ${sorted.length - shown.length} additional finding(s) suppressed (see JSON)`);
+        }
+    }
+    lines.push('');
+    lines.push(`machine-readable: ${lastReviewPath}`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/policy/loader.d.ts

@@ -32,16 +32,19 @@ declare const PolicySchema: z.ZodObject<{
     }>>;
     review: z.ZodOptional<z.ZodObject<{
         codex_required: z.ZodOptional<z.ZodBoolean>;
-        cache_max_age_seconds: z.ZodOptional<z.ZodNumber>;
-        allow_skip_in_ci: z.ZodOptional<z.ZodBoolean>;
+        concerns_blocks: z.ZodOptional<z.ZodBoolean>;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
+        last_n_commits: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
-        cache_max_age_seconds?: number | undefined;
-        allow_skip_in_ci?: boolean | undefined;
+        concerns_blocks?: boolean | undefined;
+        timeout_ms?: number | undefined;
+        last_n_commits?: number | undefined;
     }, {
         codex_required?: boolean | undefined;
-        cache_max_age_seconds?: number | undefined;
-        allow_skip_in_ci?: boolean | undefined;
+        concerns_blocks?: boolean | undefined;
+        timeout_ms?: number | undefined;
+        last_n_commits?: number | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -133,8 +136,9 @@ declare const PolicySchema: z.ZodObject<{
     } | undefined;
     review?: {
         codex_required?: boolean | undefined;
-        cache_max_age_seconds?: number | undefined;
-        allow_skip_in_ci?: boolean | undefined;
+        concerns_blocks?: boolean | undefined;
+        timeout_ms?: number | undefined;
+        last_n_commits?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -176,8 +180,9 @@ declare const PolicySchema: z.ZodObject<{
     } | undefined;
     review?: {
         codex_required?: boolean | undefined;
-        cache_max_age_seconds?: number | undefined;
-        allow_skip_in_ci?: boolean | undefined;
+        concerns_blocks?: boolean | undefined;
+        timeout_ms?: number | undefined;
+        last_n_commits?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;

package/dist/policy/loader.js

@@ -16,16 +16,18 @@ const ContextProtectionSchema = z.object({
     max_bash_output_lines: z.number().int().positive().optional(),
 });
 /**
- * G11.2: minimal review policy. Only `codex_required` is recognized today;
- * G11.4 will expand this (profile defaults, reviewer pin, token caps).
- * Kept strict so a typo (`codex_require`) fails loudly instead of silently
- * defaulting.
+ * 0.11.0 push-gate review policy. Three knobs only — the stateless gate does
+ * not have a cache and does not treat CI differently. Strict mode so typos
+ * (`codex_require`, `concerns_block`) fail loudly rather than silently
+ * defaulting. `rea upgrade` strips the removed 0.10.x fields
+ * (`cache_max_age_seconds`, `allow_skip_in_ci`) from consumer policy files.
  */
 const ReviewPolicySchema = z
     .object({
     codex_required: z.boolean().optional(),
-    cache_max_age_seconds: z.number().int().positive().optional(),
-    allow_skip_in_ci: z.boolean().optional(),
+    concerns_blocks: z.boolean().optional(),
+    timeout_ms: z.number().int().positive().optional(),
+    last_n_commits: z.number().int().positive().optional(),
 })
     .strict();
 /**

package/dist/policy/types.d.ts

@@ -19,38 +19,89 @@ export interface ContextProtection {
     max_bash_output_lines?: number;
 }
 /**
- * Review policy knobs. G11.2 only needs `codex_required` as an optional
- * signal to the reviewer selector; G11.4 will flesh this out into a full
- * first-class no-Codex mode (profile defaults, init defaults, etc.).
+ * Review policy knobs for the 0.11.0 stateless push-gate.
+ *
+ * The gate runs `codex exec review --json` on every push and infers a verdict
+ * from the streamed findings (see `src/hooks/push-gate/findings.ts`). No
+ * cache, no audit-receipt consultation, no SHA-keyed attestation. These
+ * knobs shape only the immediate run.
+ *
+ * The 0.10.x knobs `cache_max_age_seconds` and `allow_skip_in_ci` were
+ * removed in 0.11.0. `rea upgrade` strips them from consumer policy files.
  */
 export interface ReviewPolicy {
     /**
-     * When `false`, the selector treats ClaudeSelfReviewer as the preferred
-     * reviewer (not degraded). When `true` or unset, Codex is preferred and
-     * a ClaudeSelfReviewer result is marked `degraded: true` in the audit
-     * log. Default when unset is `true` (Codex required).
+     * When `true` or unset, `git push` runs `codex exec review` before the
+     * push is allowed to proceed. When `false`, the push-gate short-circuits
+     * to `disabled` (exit 0, audit event still recorded). No middle state —
+     * either we run Codex or we don't.
+     *
+     * Profile default: `true` in `bst-internal`, `client-engagement`,
+     * `lit-wc`, `open-source`. `false` in `*-no-codex` variants.
      */
     codex_required?: boolean;
     /**
-     * Review-cache TTL used by `rea cache check` (BUG-009). Entries older
-     * than this window are treated as a miss, forcing re-review. Default
-     * when unset is 3600 seconds (1 hour) — matches the windows the
-     * push-review-gate hook already assumes. Express in seconds, positive
-     * integer.
+     * Whether a `concerns` verdict blocks the push. `true` (default) means any
+     * non-trivial Codex finding halts the push; the agent must address the
+     * concerns (or re-run with `REA_ALLOW_CONCERNS=1` for a one-push override)
+     * before retrying. `false` means only `blocking` verdicts halt — concerns
+     * are logged and written to `.rea/last-review.json` but the push proceeds.
+     *
+     * Added in 0.11.0. Default when unset is `true` — safer posture for
+     * consumers who have not thought about it.
+     */
+    concerns_blocks?: boolean;
+    /**
+     * Hard cap on the `codex exec review` subprocess in milliseconds. Exceeding
+     * this kills the subprocess and the gate returns exit 2 with a timeout
+     * error (audited). Default when unset is 1_800_000 (30 minutes) as of
+     * 0.12.0 — raised from 10 minutes after the helixir migration session
+     * 2026-04-26 showed realistic feature-branch diffs routinely exceeded
+     * the previous default. Operators with explicit `timeout_ms:` in
+     * `.rea/policy.yaml` are unaffected.
+     *
+     * Positive integer only. The loader rejects zero/negative values.
      */
-    cache_max_age_seconds?: number;
+    timeout_ms?: number;
     /**
-     * Authorization for `REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW` when
-     * the `CI` environment variable is set. The skip hatches are ambient and
-     * unauthenticated — a leaked env file or a malicious parent process can
-     * bypass the gate and record a forged actor (git config is mutable repo
-     * config). Refusing these hatches in CI contexts by default removes that
-     * bypass surface. Set `true` ONLY on build agents where the operator has
-     * an independent reason to trust the environment. Default `false`.
+     * When set, `rea hook push-gate` resolves the diff base to `HEAD~N`
+     * instead of the upstream → origin/HEAD ladder. Useful when a feature
+     * branch accumulates many commits and the full origin/main diff
+     * overwhelms the reviewer (the helixir 2026-04-26 case: 50+ commits
+     * relative to origin/main produced non-deterministic Codex verdicts and
+     * 10-minute timeouts).
+     *
+     * Precedence: explicit `--base <ref>` flag wins; then `--last-n-commits N`
+     * flag; then this policy key; then refspec-aware base resolution; then
+     * the upstream-ladder fallback. When `--base` AND
+     * `--last-n-commits`/`policy.last_n_commits` are both set, `--base`
+     * wins and a stderr warning is emitted.
+     *
+     * Resolution: `git rev-parse HEAD~N`. When `HEAD~N` is unreachable
+     * the resolver consults `git rev-parse --is-shallow-repository` to
+     * pick the right clamp:
+     *
+     *   - FULL clone, branch shorter than N: clamps to the empty-tree
+     *     sentinel so the root commit's changes are included
+     *     (`git diff base..HEAD` excludes `base`, so diffing against
+     *     `HEAD~K` would silently drop the root commit). Reports
+     *     `last_n_commits: K+1` — every commit on the branch reviewed.
+     *
+     *   - SHALLOW clone: clamps to `HEAD~K` (the deepest LOCALLY
+     *     resolvable ancestor) since older history exists on the remote
+     *     but isn't fetched. Using empty-tree here would balloon the
+     *     review to every tracked file in the checkout. Reports
+     *     `last_n_commits: K`. The K-th commit's content is excluded —
+     *     accepted as the cost of the shallow clone.
+     *
+     * A stderr warning surfaces the requested-vs-clamped numbers in
+     * both cases. Audit metadata records `base_source: 'last-n-commits'`,
+     * `last_n_commits: <count actually reviewed>`, and
+     * `last_n_commits_requested: N` (only present when clamped).
      *
-     * Added in 0.5.0 as Codex F2 on the PR1 adversarial review.
+     * Positive integer. The loader rejects zero/negative values.
      */
-    allow_skip_in_ci?: boolean;
+    last_n_commits?: number;
 }
 /**
  * User-supplied redaction pattern entry. Each pattern has a stable `name` used

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.10.3",
+  "version": "0.12.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",

package/scripts/tarball-smoke.sh

@@ -74,8 +74,13 @@ echo "[smoke]   → $VERSION_OUT"
 echo "[smoke] rea --help"
 ./node_modules/.bin/rea --help >/dev/null
 
-echo "[smoke] rea init --yes --profile open-source"
-./node_modules/.bin/rea init --yes --profile open-source
+echo "[smoke] rea init --yes --profile open-source-no-codex"
+# 0.12.0+: doctor hard-fails when policy.review.codex_required: true and codex
+# is not on PATH (fix C of the helixir migration unblocker — see PR #85). CI
+# does not provision the codex CLI, so the smoke uses the -no-codex profile
+# variant which defaults codex_required: false. The new doctor probe is
+# covered by unit tests in src/cli/doctor.test.ts.
+./node_modules/.bin/rea init --yes --profile open-source-no-codex
 
 # Verify the installed layout matches what init claims it wrote.
 for expected in .rea/policy.yaml .rea/registry.yaml .claude/settings.json CLAUDE.md .rea/install-manifest.json; do

package/dist/cache/review-cache.d.ts

@@ -1,115 +0,0 @@
-/**
- * Review cache (BUG-009). The push-review-gate hook (`hooks/push-review-gate.sh`)
- * has shipped since 0.3.x calling `rea cache check <sha>` to skip re-review on
- * a previously-approved diff, and `rea cache set <sha> pass ...` as the
- * operator's advertised way to complete the gate. Neither subcommand existed
- * in the CLI through 0.4.0. Once BUG-008's pre-push stdin adapter lands and
- * the gate actually fires, a protected-path push has no completion path
- * without this cache — hence "paired ship blocker."
- *
- * ## File layout
- *
- * `.rea/review-cache.jsonl` — one JSON object per line, terminated with `\n`.
- * Each entry:
- *
- *   {
- *     "sha": "<diff-sha256>",
- *     "branch": "<feature-branch>",
- *     "base": "<target-branch>",
- *     "result": "pass" | "fail",
- *     "recorded_at": "<ISO-8601>",
- *     "reason"?: "<free text>"   // optional, populated on fail or on skip
- *   }
- *
- * The `sha` is whatever the caller supplies — the hook happens to use a
- * SHA-256 of the full diff, but the cache does not interpret or validate the
- * value. Hash-chained is intentionally NOT required: this is a keyed cache,
- * not an append-only integrity log. The audit log at `.rea/audit.jsonl`
- * remains the integrity story.
- *
- * ## Concurrency
- *
- * Every write takes the same `proper-lockfile` lock on the `.rea/` parent
- * directory that the audit helpers use (`withAuditLock`). This means a
- * concurrent audit append and cache write serialize against each other — a
- * negligible cost given cache writes happen once per push gate completion.
- *
- * ## Idempotency
- *
- * `appendEntry` writes a new line unconditionally. `lookup` returns the most
- * recent entry matching `(sha, branch, base)`. This "last write wins" keeps
- * the write path O(1) and the read path O(n) over the file; n is bounded by
- * typical review frequency (dozens per week, not millions). If a future
- * operator needs a compact file, `rea cache clear <sha>` drops matching
- * entries and a separate `rea cache compact` (not in 0.5.0) could rewrite.
- *
- * ## TTL
- *
- * `lookup` honors `review.cache_max_age_seconds` (default 3600). Entries
- * older than the window are treated as a miss. Expired entries are not
- * garbage-collected on read — `rea cache clear` or `rea cache compact`
- * is the operator tool for shrinking.
- */
-/** Default TTL when policy does not supply one. */
-export declare const DEFAULT_CACHE_MAX_AGE_SECONDS = 3600;
-export type CacheResult = 'pass' | 'fail';
-export interface CacheEntry {
-    sha: string;
-    branch: string;
-    base: string;
-    result: CacheResult;
-    recorded_at: string;
-    reason?: string;
-}
-export interface CacheLookupInput {
-    sha: string;
-    branch: string;
-    base: string;
-    /** Epoch ms used as the "now" reference for TTL comparison. Defaults to `Date.now()`. */
-    nowMs?: number;
-    /** TTL in seconds; defaults to {@link DEFAULT_CACHE_MAX_AGE_SECONDS}. */
-    maxAgeSeconds?: number;
-}
-export interface CacheLookupResult {
-    hit: boolean;
-    entry?: CacheEntry;
-    /** Reason for a miss. One of `'no-entry' | 'expired' | 'empty-file'`. Always set when `hit === false`. */
-    missReason?: 'no-entry' | 'expired' | 'empty-file';
-}
-export interface CacheAppendInput {
-    sha: string;
-    branch: string;
-    base: string;
-    result: CacheResult;
-    reason?: string;
-    /** ISO-8601 timestamp. Defaults to `new Date().toISOString()`. */
-    timestamp?: string;
-}
-export declare function resolveCacheFile(baseDir: string): string;
-/**
- * Append an entry to the cache. Writes are serialized through the shared
- * `.rea/` directory lock so audit writes and cache writes do not interleave.
- */
-export declare function appendEntry(baseDir: string, input: CacheAppendInput): Promise<CacheEntry>;
-/**
- * Find the most-recent entry matching `(sha, branch, base)` within the TTL
- * window. Idempotent and side-effect free.
- */
-export declare function lookup(baseDir: string, input: CacheLookupInput): Promise<CacheLookupResult>;
-/**
- * Remove every entry matching `sha`. Returns the count removed. A `0` return
- * is a valid outcome (sha not present). Writes back via the same lock as
- * `appendEntry`, so concurrent sets do not lose entries.
- *
- * Writes use temp-file + `fs.rename` (atomic within a single directory on
- * POSIX) so unlocked readers (`lookup`, `list`) can never observe a torn or
- * empty intermediate state. Codex F4 on the 0.5.0 PR1 review.
- */
-export declare function clear(baseDir: string, sha: string): Promise<number>;
-/**
- * Return every entry, optionally filtered by branch. Entries are returned in
- * file order (oldest first). Callers that want "newest first" should reverse.
- */
-export declare function list(baseDir: string, options?: {
-    branch?: string;
-}): Promise<CacheEntry[]>;