@loopover/miner 0.1.0

package/lib/pretooluse-hook.js

@@ -0,0 +1,93 @@
+// PreToolUse-hook-enforced house rules (#2343). Wraps the pure `evaluateDenyHooks` decision function
+// (deny-hooks.js, #2295) into a real Claude Agent SDK PreToolUse hook callback -- the actual live
+// interception point a CodingAgentDriver session registers via `options.hooks.PreToolUse` (the exact
+// seam `agent-sdk-driver.ts`'s `hooks` passthrough documents as "#2343's stated attachment point").
+//
+// WHY THIS HOLDS EVEN UNDER bypassPermissions: per the Agent SDK's own documented permission-evaluation
+// order (https://code.claude.com/docs/en/agent-sdk/permissions), hooks run FIRST -- before deny rules,
+// ask rules, the permission mode check, and allow rules -- and "Hooks still execute and can block
+// operations if needed" even when `permissionMode: 'bypassPermissions'` is set: "Deny rules
+// (disallowed_tools), explicit ask rules, and hooks are evaluated before the mode check and can still
+// block a tool." This module does not implement that guarantee -- the SDK does. This module's job is
+// only to return a correctly-shaped, fail-closed deny decision every time; the SDK is what makes that
+// decision unbypassable.
+//
+// FAIL CLOSED: any internal error (a malformed tool-call shape, a governor-ledger append failure) denies
+// rather than silently allowing.
+
+import { DEFAULT_DENY_RULES, evaluateDenyHooks } from "./deny-hooks.js";
+import { appendGovernorEvent } from "./governor-ledger.js";
+
+function recordDenial(append, repoFullName, reason, payload) {
+  try {
+    append({
+      eventType: "denied",
+      repoFullName: repoFullName ?? null,
+      actionClass: "pretooluse_hook",
+      decision: "deny",
+      reason,
+      payload,
+    });
+  } catch {
+    // A ledger append failure must never suppress or alter the deny decision itself -- the tool call is
+    // still blocked even if the audit write fails. Silently allowing on a logging failure would be a far
+    // worse outcome for a security boundary than an unrecorded (but still enforced) denial.
+  }
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/**
+ * Build a Claude Agent SDK `PreToolUse` hook callback enforcing the house-rule denylist. Register the
+ * returned function under `options.hooks.PreToolUse` (e.g. `{ hooks: [PreToolUse: [{ hooks: [built] }]] }`
+ * on the object passed to `createAgentSdkCodingAgentDriver({ hooks })`).
+ *
+ * House rules are sourced from a single, auditable list: {@link DEFAULT_DENY_RULES} by default, or an
+ * effective rule set built by the caller (e.g. `resolveEffectiveDenyRules` from deny-hook-synthesis.js,
+ * merging in maintainer-approved synthesized rules) — this module composes whatever rule set it is given,
+ * it does not own deriving one.
+ *
+ * @param {object} [config]
+ * @param {ReadonlyArray<import("./deny-hooks.js").DenyRule>} [config.rules] defaults to DEFAULT_DENY_RULES
+ * @param {string} [config.repoFullName] target repo, for governor-ledger scoping of recorded denials
+ * @param {{ append?: typeof appendGovernorEvent }} [options]
+ * @returns {(input: unknown, toolUseId?: string, context?: unknown) => Promise<Record<string, unknown>>}
+ */
+export function buildHouseRulesPreToolUseHook(config = {}, options = {}) {
+  const rules = config.rules ?? DEFAULT_DENY_RULES;
+  const repoFullName = config.repoFullName;
+  const append = options.append ?? appendGovernorEvent;
+
+  return async function houseRulesPreToolUseHook(input) {
+    try {
+      const toolName = input && typeof input === "object" ? input.tool_name : undefined;
+      const toolInput = input && typeof input === "object" ? input.tool_input : undefined;
+      const verdict = evaluateDenyHooks({ name: toolName, input: toolInput }, rules);
+
+      if (verdict.allowed) return {};
+
+      // `verdict.blockedBy` is always set together with `!verdict.allowed` (evaluateDenyHooks's only two return
+      // shapes), and `.matcher` is always a defined string on it (ruleMatches gates every match on
+      // `typeof rule.matcher === "string"` -- a rule can never become `blockedBy` otherwise). `.reason` has no
+      // equivalent gate, so a caller-supplied custom rule omitting it is a real, reachable case.
+      const reason = verdict.blockedBy.reason ?? "House rule denylist match.";
+      recordDenial(append, repoFullName, reason, {
+        toolName: typeof toolName === "string" ? toolName : null,
+        matcher: verdict.blockedBy.matcher,
+      });
+      return denyOutput(reason);
+    } catch (error) {
+      const reason = `pretooluse_hook_internal_error: ${error instanceof Error ? error.message : String(error)}`;
+      recordDenial(append, repoFullName, reason, {});
+      return denyOutput(reason);
+    }
+  };
+}

package/lib/process-lifecycle.d.ts

@@ -0,0 +1,31 @@
+/** Process lifecycle / crash-safety for the miner CLI (#4826). Local stores register on open and the CLI installs
+ * signal/error handlers once at startup so an interrupted run closes every open ledger cleanly. */
+
+/** A closable store (`{ close() }`) or a plain cleanup callback. */
+export type CleanupResource = { close: () => void } | (() => void);
+
+/** The subset of `process` the handlers use; injectable for tests. */
+export type ProcessLike = {
+  on: (event: string, listener: (...args: unknown[]) => void) => unknown;
+  exit: (code?: number) => void;
+};
+
+export type InstallCliSignalHandlersOptions = {
+  process?: ProcessLike;
+  log?: (message: string) => void;
+  exit?: (code: number) => void;
+  /** Reinstall even if handlers were already installed (mainly for tests). */
+  force?: boolean;
+};
+
+/** Register a resource to close on exit; returns an idempotent unregister function. */
+export function registerCleanupResource(resource: CleanupResource | null | undefined): () => void;
+
+export function cleanupResourceCount(): number;
+
+export function closeAllCleanupResources(options?: { onError?: (error: unknown) => void }): void;
+
+/** Install signal + error handlers once. Returns false if already installed (and `force` was not set). */
+export function installCliSignalHandlers(options?: InstallCliSignalHandlersOptions): boolean;
+
+export function resetProcessLifecycleForTesting(): void;

package/lib/process-lifecycle.js

@@ -0,0 +1,106 @@
+/** Process lifecycle / crash-safety for the miner CLI (#4826). The CLI dispatches through a chain of bare
+ * `process.exit()` calls with no cleanup hook, so a SIGINT/SIGTERM mid-run — or an uncaught exception — used to
+ * kill the process mid-write, leaving whatever local SQLite ledger it was touching in an undefined state. This
+ * module is the single cleanup chokepoint: local stores register themselves when opened (see `local-store.js`), and
+ * `installCliSignalHandlers` (called once at CLI startup) flushes/closes every still-open resource before exiting
+ * cleanly on a signal, and logs + exits non-zero on an uncaught exception / unhandled rejection instead of crashing
+ * silently. Cleanup ONLY — no command business logic lives here. Every dependency (`process`, `log`, `exit`) is
+ * injectable so the handlers are unit-testable without actually signalling the test runner. */
+
+// 128 + signal number, the conventional shell exit code for a process terminated by that signal (SIGINT=2 -> 130,
+// SIGTERM=15 -> 143).
+const SIGNAL_EXIT_CODES = Object.freeze({ SIGINT: 130, SIGTERM: 143 });
+
+/** Resources to close on exit. A resource is either a `{ close() }` object (e.g. an open SQLite store) or a plain
+ * cleanup function. Held in insertion order so cleanup is deterministic. */
+const cleanupResources = new Set();
+let handlersInstalled = false;
+
+/** Render any thrown value as a single log-safe string, preferring an Error's stack. */
+function describeError(value) {
+  if (value instanceof Error) return value.stack ?? value.message;
+  return String(value);
+}
+
+/**
+ * Register a resource to be closed on clean exit or crash. Returns an idempotent unregister function (call it from
+ * the resource's own normal `close()` so a resource closed during the happy path is not double-closed at exit).
+ */
+export function registerCleanupResource(resource) {
+  if (resource === null || resource === undefined) return () => {};
+  cleanupResources.add(resource);
+  return () => {
+    cleanupResources.delete(resource);
+  };
+}
+
+/** Number of currently-registered cleanup resources (exposed for tests / diagnostics). */
+export function cleanupResourceCount() {
+  return cleanupResources.size;
+}
+
+/**
+ * Close every registered resource, swallowing each individual failure (a store that fails to close must not stop
+ * the others from closing) and reporting it via `options.onError`. Idempotent: the registry is emptied afterwards.
+ */
+export function closeAllCleanupResources(options = {}) {
+  const onError = typeof options.onError === "function" ? options.onError : null;
+  for (const resource of [...cleanupResources]) {
+    try {
+      if (typeof resource === "function") resource();
+      else resource.close();
+    } catch (error) {
+      if (onError) onError(error);
+    }
+  }
+  cleanupResources.clear();
+}
+
+/**
+ * Install top-level signal + error handlers once. On SIGINT/SIGTERM: close all resources and exit with the
+ * conventional 128+signal code. On uncaughtException/unhandledRejection: log the error, close all resources, and
+ * exit non-zero. No-op (returns false) if already installed unless `options.force` is set. All of `process`, `log`,
+ * and `exit` are injectable for testing.
+ */
+export function installCliSignalHandlers(options = {}) {
+  const proc = options.process ?? process;
+  const log = typeof options.log === "function" ? options.log : (message) => console.error(message);
+  const exit = typeof options.exit === "function" ? options.exit : (code) => proc.exit(code);
+
+  if (handlersInstalled && options.force !== true) return false;
+  handlersInstalled = true;
+
+  const runCleanup = () => {
+    closeAllCleanupResources({
+      onError: (error) => log(`gittensory-miner: cleanup error while exiting: ${describeError(error)}`),
+    });
+  };
+
+  for (const [signal, code] of Object.entries(SIGNAL_EXIT_CODES)) {
+    proc.on(signal, () => {
+      log(`gittensory-miner: received ${signal}, closing open resources and exiting.`);
+      runCleanup();
+      exit(code);
+    });
+  }
+
+  proc.on("uncaughtException", (error) => {
+    log(`gittensory-miner: uncaught exception: ${describeError(error)}`);
+    runCleanup();
+    exit(1);
+  });
+
+  proc.on("unhandledRejection", (reason) => {
+    log(`gittensory-miner: unhandled promise rejection: ${describeError(reason)}`);
+    runCleanup();
+    exit(1);
+  });
+
+  return true;
+}
+
+/** Test-only: clear the registry and the installed flag so each test starts from a clean lifecycle. */
+export function resetProcessLifecycleForTesting() {
+  cleanupResources.clear();
+  handlersInstalled = false;
+}

package/lib/purge-cli.d.ts

@@ -0,0 +1,44 @@
+import type { ClaimLedger } from "./claim-ledger.js";
+import type { EventLedger } from "./event-ledger.js";
+import type { GovernorLedger } from "./governor-ledger.js";
+import type { PredictionLedger } from "./prediction-ledger.js";
+
+export const ATTEMPT_LOG_NOT_PURGEABLE_NOTE: string;
+
+export type ParsedPurgeArgs = { json: boolean; dryRun: boolean; repoFullName: string } | { error: string };
+
+export function parsePurgeArgs(args: string[]): ParsedPurgeArgs;
+
+export type PurgeStoreResult = { store: string; purged: number | null; error?: string; note?: string };
+export type PurgeDryRunStoreResult = { store: string; wouldPurge: number | null; error?: string };
+
+export type PurgeDryRunResult = {
+  outcome: "dry_run";
+  repoFullName: string;
+  stores: PurgeDryRunStoreResult[];
+  attemptLogNote: string;
+  attemptLogTotalRows: number;
+};
+
+export type PurgeSummary = {
+  outcome: "purged" | "partial";
+  repoFullName: string;
+  totalPurged: number;
+  stores: PurgeStoreResult[];
+  purgedAt: string;
+};
+
+export type PurgeCliOptions = {
+  openClaimLedger?: () => ClaimLedger;
+  initEventLedger?: () => EventLedger;
+  initGovernorLedger?: () => GovernorLedger;
+  initPredictionLedger?: () => PredictionLedger;
+  resolveDbPaths?: Record<string, () => string>;
+};
+
+export function runPurgeDryRun(
+  parsed: { repoFullName: string; json: boolean },
+  options?: PurgeCliOptions,
+): number;
+
+export function runPurge(args: string[], options?: PurgeCliOptions): number;

package/lib/purge-cli.js

@@ -0,0 +1,198 @@
+// `gittensory-miner purge` (#5564): an explicit, operator-invoked right-to-be-forgotten path across the local
+// ledgers. Deletes every row for one repo from the four stores that have a real `repoColumn` (claim-ledger,
+// event-ledger, governor-ledger, prediction-ledger), via each store's own `purgeByRepo` method (which reuses
+// `store-maintenance.js`'s shared, identifier-guarded `purgeStoreByRepo`). `attempt-log.js` is deliberately
+// reported as not-purgeable rather than silently skipped or approximated: its payload is a free-form
+// `Record<string, unknown>` with no dedicated repo column, so a precise per-repo match isn't possible there
+// without risking false matches -- see store-maintenance.js's own purge-spec doc comment.
+//
+// Every purge is audit-observable by design (#5564's own acceptance criteria): the real (non-dry-run) path
+// always prints a per-store summary, even under --json, so a purge can never be silent. A failure in one store
+// does not prevent reporting what succeeded in the others -- see purgeOneStore's own per-store try/catch.
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { openClaimLedger, resolveClaimLedgerDbPath } from "./claim-ledger.js";
+import { initEventLedger, resolveEventLedgerDbPath } from "./event-ledger.js";
+import { initGovernorLedger, resolveGovernorLedgerDbPath } from "./governor-ledger.js";
+import { initPredictionLedger, resolvePredictionLedgerDbPath } from "./prediction-ledger.js";
+import { resolveAttemptLogDbPath } from "./attempt-log.js";
+import {
+  CLAIM_LEDGER_PURGE_SPEC,
+  EVENT_LEDGER_PURGE_SPEC,
+  GOVERNOR_LEDGER_PURGE_SPEC,
+  PREDICTION_LEDGER_PURGE_SPEC,
+  countStoreByRepo,
+  describeError,
+} from "./store-maintenance.js";
+
+const PURGE_USAGE = "Usage: gittensory-miner purge --repo <owner/repo> [--dry-run] [--json]";
+
+export const ATTEMPT_LOG_NOT_PURGEABLE_NOTE =
+  "attempt-log has no repoFullName column and cannot be purged by repo (#5564); its rows are unaffected";
+
+const REAL_PURGE_TARGETS = [
+  { name: "claim-ledger", optionKey: "openClaimLedger", opener: openClaimLedger, resolveDbPath: resolveClaimLedgerDbPath, spec: CLAIM_LEDGER_PURGE_SPEC },
+  { name: "event-ledger", optionKey: "initEventLedger", opener: initEventLedger, resolveDbPath: resolveEventLedgerDbPath, spec: EVENT_LEDGER_PURGE_SPEC },
+  { name: "governor-ledger", optionKey: "initGovernorLedger", opener: initGovernorLedger, resolveDbPath: resolveGovernorLedgerDbPath, spec: GOVERNOR_LEDGER_PURGE_SPEC },
+  { name: "prediction-ledger", optionKey: "initPredictionLedger", opener: initPredictionLedger, resolveDbPath: resolvePredictionLedgerDbPath, spec: PREDICTION_LEDGER_PURGE_SPEC },
+];
+
+function parseRepoArg(value, usage) {
+  if (!value) return { error: usage };
+  const trimmed = value.trim();
+  const [owner, repo, extra] = trimmed.split("/");
+  if (!owner || !repo || extra !== undefined) {
+    return { error: "Repository must be in owner/repo form." };
+  }
+  return { repoFullName: `${owner}/${repo}` };
+}
+
+export function parsePurgeArgs(args) {
+  const options = { json: false, dryRun: false, repoFullName: null };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === "--repo") {
+      const repoArg = args[index + 1];
+      // Only the flag-look-alike case is checked here ("--repo --json") -- a genuinely missing value (repoArg
+      // undefined) falls through to parseRepoArg's own `!value` guard below, the single source of truth for that.
+      if (repoArg !== undefined && repoArg.startsWith("-")) return { error: PURGE_USAGE };
+      const repo = parseRepoArg(repoArg, PURGE_USAGE);
+      if ("error" in repo) return repo;
+      options.repoFullName = repo.repoFullName;
+      index += 1;
+      continue;
+    }
+    return { error: `Unknown option: ${token}` };
+  }
+
+  if (!options.repoFullName) return { error: PURGE_USAGE };
+  return options;
+}
+
+/** Read-only row count against an on-disk store file, for --dry-run. `{ readOnly: true }` (camelCase) is the
+ *  only option node:sqlite recognizes for a driver-enforced read-only connection -- the lowercase `readonly`
+ *  key is silently ignored. Never touches a store that doesn't exist yet (opening one -- even read-only --
+ *  requires the file to already be there; a dry run must make zero writes). */
+function countExistingRows(dbPath, countFn) {
+  if (!existsSync(dbPath)) return 0;
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
+    return countFn(db);
+  } finally {
+    db.close();
+  }
+}
+
+function renderDryRunSummary(result) {
+  const purgeableLine = result.stores
+    .map((entry) => `${entry.store}=${entry.wouldPurge}`)
+    .join(", ");
+  return [
+    `DRY RUN: would purge ${result.repoFullName} from: ${purgeableLine}. No writes were made.`,
+    `${ATTEMPT_LOG_NOT_PURGEABLE_NOTE} (${result.attemptLogTotalRows} total row(s) currently in attempt-log, all repos).`,
+  ].join("\n");
+}
+
+export function runPurgeDryRun(parsed, options = {}) {
+  const resolveDbPaths = options.resolveDbPaths ?? {};
+  const stores = REAL_PURGE_TARGETS.map((target) => {
+    const dbPath = (resolveDbPaths[target.name] ?? target.resolveDbPath)();
+    try {
+      const wouldPurge = countExistingRows(dbPath, (db) => countStoreByRepo(db, target.spec, parsed.repoFullName));
+      return { store: target.name, wouldPurge };
+    } catch (error) {
+      return { store: target.name, wouldPurge: null, error: describeError(error) };
+    }
+  });
+
+  const attemptLogDbPath = (resolveDbPaths["attempt-log"] ?? resolveAttemptLogDbPath)();
+  const attemptLogTotalRows = countExistingRows(attemptLogDbPath, (db) =>
+    Number(db.prepare("SELECT COUNT(*) AS count FROM attempt_log_events").get().count),
+  );
+
+  const result = {
+    outcome: "dry_run",
+    repoFullName: parsed.repoFullName,
+    stores,
+    attemptLogNote: ATTEMPT_LOG_NOT_PURGEABLE_NOTE,
+    attemptLogTotalRows,
+  };
+
+  if (parsed.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(renderDryRunSummary(result));
+  }
+  return 0;
+}
+
+function purgeOneStore(target, options, repoFullName) {
+  const ownsStore = options[target.optionKey] === undefined;
+  let store;
+  try {
+    store = (options[target.optionKey] ?? target.opener)();
+    const purged = store.purgeByRepo(repoFullName);
+    return { store: target.name, purged };
+  } catch (error) {
+    return { store: target.name, purged: null, error: describeError(error) };
+  } finally {
+    if (ownsStore) store?.close();
+  }
+}
+
+function renderPurgeSummary(summary) {
+  const perStore = summary.stores
+    .map((entry) => {
+      if ("error" in entry) return `${entry.store}=ERROR(${entry.error})`;
+      if (entry.purged === null) return `${entry.store}=skipped`;
+      return `${entry.store}=${entry.purged}`;
+    })
+    .join(", ");
+  return [
+    `Purged ${summary.totalPurged} row(s) for ${summary.repoFullName} at ${summary.purgedAt}: ${perStore}.`,
+    ATTEMPT_LOG_NOT_PURGEABLE_NOTE,
+  ].join(" ");
+}
+
+export function runPurge(args, options = {}) {
+  const parsed = parsePurgeArgs(args);
+  if ("error" in parsed) {
+    console.error(parsed.error);
+    return 2;
+  }
+
+  if (parsed.dryRun) {
+    return runPurgeDryRun(parsed, options);
+  }
+
+  const perStoreResults = REAL_PURGE_TARGETS.map((target) => purgeOneStore(target, options, parsed.repoFullName));
+  perStoreResults.push({ store: "attempt-log", purged: null, note: ATTEMPT_LOG_NOT_PURGEABLE_NOTE });
+
+  const totalPurged = perStoreResults.reduce((sum, entry) => sum + (entry.purged ?? 0), 0);
+  const hadError = perStoreResults.some((entry) => "error" in entry);
+  const summary = {
+    outcome: hadError ? "partial" : "purged",
+    repoFullName: parsed.repoFullName,
+    totalPurged,
+    stores: perStoreResults,
+    purgedAt: new Date().toISOString(),
+  };
+
+  // Audit-observable by design (#5564): print the summary in BOTH the success and partial-failure case, so a
+  // purge -- or a purge that only partly succeeded -- is never silent.
+  if (parsed.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(renderPurgeSummary(summary));
+  }
+  return hadError ? 2 : 0;
+}

package/lib/rejection-signal.d.ts

@@ -0,0 +1,6 @@
+import type { SelfReviewContextFetch } from "./self-review-context.js";
+
+export function resolveRejectionSignaled(
+  repoFullName: string,
+  options?: { rawContentBaseUrl?: string; fetchImpl?: SelfReviewContextFetch },
+): Promise<boolean>;

package/lib/rejection-signal.js

@@ -0,0 +1,101 @@
+import { resolveAiPolicyVerdict } from "@loopover/engine";
+
+// Real rejectionSignaled resolver (#5132, Wave 3.5 follow-up). iterate-policy.ts's own doc comment: "True
+// when the target repo (or this contributor's history with it) has signaled it does not want automated/
+// AI-authored contributions -- an explicit AI-usage-policy ban, or a prior submission from this same miner
+// was closed/rejected on this exact repo. The caller resolves this ... and passes it in; this policy does
+// not compute it itself." This module resolves the FIRST trigger: a real AI-USAGE.md/CONTRIBUTING.md ban,
+// fetched live and scanned via the engine's own resolveAiPolicyVerdict -- the same check
+// opportunity-fanout.js already runs during discovery, applied here at attempt time instead.
+//
+// The SECOND trigger (a prior submission from this same miner was closed/rejected on this exact repo) is
+// DELIBERATELY not resolved here: it would need each of this miner's recorded own-submissions
+// (governor-state.js's listRecentOwnSubmissions, #5134) checked against its live PR outcome via
+// rejection-state-machine.js's resolveRejection -- a second, separately-scoped fetch-and-classify pipeline.
+// Not fabricated as "no rejection history" -- explicitly left as a known, documented gap for a follow-up,
+// same discipline as SelfReviewContext's bounties/issueQuality (#5145) and this file's own callers should
+// not assume a false result here means "no rejection signal of any kind."
+
+const DEFAULT_RAW_CONTENT_BASE_URL = "https://raw.githubusercontent.com";
+const MAX_POLICY_DOC_BYTES = 128 * 1024;
+
+function parseRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") return null;
+  const [owner, repo, extra] = repoFullName.split("/");
+  if (!owner || !repo || extra !== undefined) return null;
+  return { owner, repo };
+}
+
+function normalizeOptions(options = {}) {
+  return {
+    rawContentBaseUrl:
+      typeof options.rawContentBaseUrl === "string" && options.rawContentBaseUrl.trim() ? options.rawContentBaseUrl.trim() : DEFAULT_RAW_CONTENT_BASE_URL,
+    fetchImpl: options.fetchImpl ?? fetch,
+  };
+}
+
+async function readBoundedPolicyDoc(response) {
+  const contentLength = response.headers?.get?.("content-length");
+  if (contentLength !== undefined && contentLength !== null) {
+    const parsedLength = Number.parseInt(contentLength, 10);
+    if (Number.isFinite(parsedLength) && parsedLength > MAX_POLICY_DOC_BYTES) return null;
+  }
+
+  if (!response.body?.getReader) {
+    const text = await response.text();
+    return typeof text === "string" && Buffer.byteLength(text, "utf8") <= MAX_POLICY_DOC_BYTES ? text : null;
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let totalBytes = 0;
+  let text = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      totalBytes += value.byteLength;
+      if (totalBytes > MAX_POLICY_DOC_BYTES) {
+        await reader.cancel();
+        return null;
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+    text += decoder.decode();
+    return text;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function fetchPolicyDoc(target, path, resolved) {
+  const url = `${resolved.rawContentBaseUrl}/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.repo)}/HEAD/${path}`;
+  try {
+    const response = await resolved.fetchImpl(url, { method: "GET", headers: { accept: "application/json", "user-agent": "loopover-miner" } });
+    if (!response.ok) return null;
+    return await readBoundedPolicyDoc(response);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve whether the target repo has an explicit, live AI-usage-policy ban -- the first of
+ * `rejectionSignaled`'s two documented triggers. Returns `false` (never throws) on any fetch/parse failure,
+ * matching resolveAiPolicyVerdict's own fail-open default for an absent/unreadable policy doc.
+ *
+ * @param {string} repoFullName
+ * @param {{ rawContentBaseUrl?: string, fetchImpl?: import("./self-review-context.js").SelfReviewContextFetch }} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function resolveRejectionSignaled(repoFullName, options = {}) {
+  const target = parseRepoFullName(repoFullName);
+  if (!target) return false;
+  const resolved = normalizeOptions(options);
+
+  const aiUsage = await fetchPolicyDoc(target, "AI-USAGE.md", resolved);
+  const contributing = aiUsage && aiUsage.trim() ? null : await fetchPolicyDoc(target, "CONTRIBUTING.md", resolved);
+
+  const verdict = resolveAiPolicyVerdict({ aiUsage, contributing });
+  return !verdict.allowed;
+}

package/lib/rejection-state-machine.d.ts

@@ -0,0 +1,37 @@
+import type { RejectionReason, RejectionContext } from "./rejection-templates.js";
+
+export type PrOutcomeFields = {
+  state: string | null;
+  merged: boolean;
+  mergedAt: string | null;
+  closedAt: string | null;
+};
+
+export type RejectionSignal = {
+  gateClosed?: boolean;
+  supersededByDuplicate?: boolean;
+};
+
+export type RejectionTransition = {
+  outcome: "disengaged";
+  reason: RejectionReason;
+  note: string;
+  fields: PrOutcomeFields;
+};
+
+/** Per-PR terminal outcome for a rejected (closed-without-merge) PR. */
+export const DISENGAGED_OUTCOME: "disengaged";
+
+export function extractPrOutcomeFields(prPayload: unknown): PrOutcomeFields;
+
+export function isRejectedPr(
+  fields: { state?: string | null; merged?: boolean } | null | undefined,
+): boolean;
+
+export function classifyRejectionReason(signal?: RejectionSignal): RejectionReason;
+
+export function resolveRejection(
+  prPayload: unknown,
+  signal: RejectionSignal | undefined,
+  context: RejectionContext,
+): RejectionTransition | null;