@loopover/miner 0.1.0

package/lib/deployment-docs-audit.js

@@ -0,0 +1,115 @@
+// Docs-accuracy audit for the miner's DEPLOYMENT.md (#5180). Mirrors the self-host docs audit
+// (apps/gittensory-ui/src/lib/selfhost-docs-audit.ts): parse the deployment doc, then assert every
+// GITTENSORY_MINER_* / MINER_* env var, repo-relative file path, and `gittensory-miner <subcommand>`
+// it documents still exists under packages/gittensory-miner/**. A rename or move that leaves the doc
+// stale then fails CI with a message naming the exact stale claim, instead of misleading operators.
+
+/** The miner's own env-var namespace: GITTENSORY_MINER_* and the shorter MINER_* aliases it reads. */
+const ENV_VAR_PATTERN = /\b(?:GITTENSORY_MINER|MINER)_[A-Z0-9_]+\b/g;
+
+/** `gittensory-miner <subcommand>` CLI invocations, excluding the `@loopover/miner` package spelling. */
+const SUBCOMMAND_PATTERN = /(?<![\w./@-])gittensory-miner\s+([a-z][a-z0-9-]*)/g;
+
+/** Markdown inline-link targets: the `target` in `](target)`. */
+const MARKDOWN_LINK_PATTERN = /\]\(([^)]+)\)/g;
+
+/** Link targets the audit ignores: URLs, in-page anchors, and runtime-generated (~ or absolute) paths. */
+const NON_REPO_LINK_PATTERN = /^(?:https?:\/\/|mailto:|#|~|\/)/;
+
+/** `cliArgs[0] === "<name>"` guards in the miner bin — the CLI's registered top-level command table. */
+const CLI_DISPATCH_PATTERN = /cliArgs\[0\]\s*===\s*"([a-z][a-z0-9-]*)"/g;
+
+/** Collect every GITTENSORY_MINER_* / MINER_* token that appears in `text` (doc prose/code or source). */
+export function scanEnvVarTokens(text) {
+  const tokens = new Set();
+  for (const match of text.matchAll(ENV_VAR_PATTERN)) {
+    tokens.add(match[0]);
+  }
+  return tokens;
+}
+
+/** Sorted, de-duplicated env-var names DEPLOYMENT.md claims the miner honors. */
+export function extractEnvVarClaims(markdown) {
+  return [...scanEnvVarTokens(markdown)].sort();
+}
+
+/** Sorted, de-duplicated `gittensory-miner <subcommand>` subcommands DEPLOYMENT.md documents. */
+export function extractSubcommandClaims(markdown) {
+  const commands = new Set();
+  for (const match of markdown.matchAll(SUBCOMMAND_PATTERN)) {
+    commands.add(match[1]);
+  }
+  return [...commands].sort();
+}
+
+/** True when a markdown link target is an on-disk repo path (not a URL, anchor, or runtime path). */
+export function isRepoRelativePath(target) {
+  return !NON_REPO_LINK_PATTERN.test(target);
+}
+
+/** Sorted, de-duplicated repo-relative file paths DEPLOYMENT.md links to (external issue links excluded).
+ *  An in-file anchor fragment (`file.md#heading`) is stripped before the path is recorded -- the fragment
+ *  names a heading inside the target file, not a filesystem entry, so checking it against `pathExists`
+ *  verbatim would always fail even when the linked file (and heading) both genuinely exist. */
+export function extractFilePathClaims(markdown) {
+  const paths = new Set();
+  for (const match of markdown.matchAll(MARKDOWN_LINK_PATTERN)) {
+    const target = match[1].trim();
+    if (isRepoRelativePath(target)) {
+      const [pathOnly] = target.split("#");
+      paths.add(pathOnly);
+    }
+  }
+  return [...paths].sort();
+}
+
+/** The set of top-level subcommands the miner CLI dispatches, parsed from its bin entry source. */
+export function scanRegisteredCommands(binSource) {
+  const commands = new Set();
+  for (const match of binSource.matchAll(CLI_DISPATCH_PATTERN)) {
+    commands.add(match[1]);
+  }
+  return commands;
+}
+
+/**
+ * Cross-check parsed DEPLOYMENT.md claims against reality. `reality` supplies three predicates so this
+ * comparison stays pure and filesystem-independent: `hasEnvRead(name)` (a read of that env var exists
+ * under packages/gittensory-miner/**), `pathExists(relativePath)` (the doc-relative path is on disk),
+ * and `isRegisteredCommand(name)` (the subcommand is dispatched by the CLI). Returns the drift findings,
+ * each failure naming the specific stale claim rather than a generic mismatch.
+ */
+export function auditDeploymentDocs(claims, reality) {
+  const failures = [];
+  for (const name of claims.envVars) {
+    if (!reality.hasEnvRead(name)) {
+      failures.push(
+        `env var "${name}" is documented in DEPLOYMENT.md but no read of it exists under packages/gittensory-miner/**`,
+      );
+    }
+  }
+  for (const path of claims.filePaths) {
+    if (!reality.pathExists(path)) {
+      failures.push(`file path "${path}" is linked from DEPLOYMENT.md but no longer exists on disk`);
+    }
+  }
+  for (const command of claims.subcommands) {
+    if (!reality.isRegisteredCommand(command)) {
+      failures.push(
+        `CLI subcommand "gittensory-miner ${command}" is documented in DEPLOYMENT.md but is not registered in the CLI command table`,
+      );
+    }
+  }
+  return { ok: failures.length === 0, failures };
+}
+
+/** Run the audit and throw a build-failing error naming every stale claim; returns the result when in sync. */
+export function assertDeploymentDocsInSync(claims, reality) {
+  const result = auditDeploymentDocs(claims, reality);
+  if (!result.ok) {
+    throw new Error(
+      `DEPLOYMENT.md is out of sync with packages/gittensory-miner/**:\n- ${result.failures.join("\n- ")}`,
+    );
+  }
+  return result;
+}

package/lib/discover-cli.d.ts

@@ -0,0 +1,94 @@
+import type { ForgeConfig } from "./forge-config.js";
+import type {
+  CandidateIssueWarning,
+  FanoutOptions,
+  FanoutTarget,
+  RawCandidateIssue,
+} from "./opportunity-fanout.js";
+import type {
+  RankCandidateIssuesOptions,
+  RankedCandidateIssue,
+  RankedCandidateSummary,
+} from "./opportunity-ranker.js";
+import type { PolicyDocCacheStore } from "./policy-doc-cache.js";
+import type { PolicyVerdictCacheStore } from "./policy-verdict-cache.js";
+import type { EnqueueRankedDiscoverySummary } from "./portfolio-discovery.js";
+import type { PortfolioQueueStore } from "./portfolio-queue.js";
+
+export type ParsedDiscoverArgs =
+  | {
+      targets: FanoutTarget[];
+      search: string | null;
+      dryRun: boolean;
+      json: boolean;
+      /** Present only when `--api-base-url` is supplied (#4784); threads the tenant's forge host to the fan-out. */
+      apiBaseUrl?: string;
+      /** Present only when `--token-env` is supplied (#4784); names the credential env var to read. */
+      tokenEnv?: string;
+    }
+  | { error: string };
+
+/** The subset of `CandidateIssueSummary` runDiscover actually reads. It surfaces the rate-limit telemetry (#4837),
+ * so a fake must supply it. A real `fetchCandidateIssuesWithSummary` result satisfies this, since it is a superset. */
+export type DiscoverFanOutSummary = {
+  issues: RawCandidateIssue[];
+  warnings: CandidateIssueWarning[];
+  rateLimitRemaining: number | null;
+  rateLimitResetAt: string | null;
+};
+
+/** The subset of a ranked entry that `renderDiscoverSummary` reads for its top-candidates listing. */
+export type DiscoverRankedEntry = Pick<RankedCandidateIssue, "repoFullName" | "issueNumber" | "title" | "rankScore">;
+
+export type DiscoverResult = {
+  fanOutCount: number;
+  warnings: CandidateIssueWarning[];
+  rateLimitRemaining: number | null;
+  rateLimitResetAt: string | null;
+  ranked: DiscoverRankedEntry[];
+  /** True when ranking fell back to the built-in default goal spec because no per-tenant spec was supplied (#4784). */
+  usedDefaultGoalSpec?: boolean;
+  enqueueSummary: EnqueueRankedDiscoverySummary;
+};
+
+export type RunDiscoverOptions = {
+  githubToken?: string;
+  apiBaseUrl?: string;
+  /** Per-tenant credential env var name (#4784); defaults to GITHUB_TOKEN. Overridden by a `--token-env` flag. */
+  tokenEnv?: string;
+  /** Per-tenant forge knobs beyond the host (#4784), forwarded to the fan-out. */
+  forge?: Partial<ForgeConfig>;
+  nowMs?: number;
+  /** Per-tenant goal specs threaded to the ranker so lane fit uses the tenant's conventions, not the defaults (#4784). */
+  goalSpecsByRepo?: RankCandidateIssuesOptions["goalSpecsByRepo"];
+  goalSpecContentByRepo?: RankCandidateIssuesOptions["goalSpecContentByRepo"];
+  initPortfolioQueue?: () => PortfolioQueueStore;
+  initPolicyDocCache?: () => PolicyDocCacheStore;
+  initPolicyVerdictCache?: () => PolicyVerdictCacheStore;
+  fetchCandidateIssuesWithSummary?: (
+    targets: FanoutTarget[],
+    githubToken: string,
+    options?: FanoutOptions,
+  ) => Promise<DiscoverFanOutSummary>;
+  searchCandidateIssuesWithSummary?: (
+    searchQuery: string,
+    githubToken: string,
+    options?: FanoutOptions,
+  ) => Promise<DiscoverFanOutSummary>;
+  rankCandidateIssuesWithSummary?: (
+    candidates: RawCandidateIssue[],
+    options?: RankCandidateIssuesOptions,
+  ) => RankedCandidateSummary;
+  enqueueRankedDiscovery?: (
+    rankedIssues: RankedCandidateIssue[],
+    options: { queueStore: PortfolioQueueStore },
+  ) => EnqueueRankedDiscoverySummary;
+};
+
+export function parseDiscoverArgs(args: string[]): ParsedDiscoverArgs;
+
+export function sanitizeDiscoverDisplayText(value: unknown): string;
+
+export function renderDiscoverSummary(result: DiscoverResult): string;
+
+export function runDiscover(args: string[], options?: RunDiscoverOptions): Promise<number>;

package/lib/discover-cli.js

@@ -0,0 +1,284 @@
+/** `discover` CLI command (#4247): wires the existing fanout -> rank -> enqueue pipeline together so a miner
+ * can actually run it. Every piece already exists and is independently tested; this module only composes them. */
+import { resolveForgeConfig } from "./forge-config.js";
+import {
+  fetchCandidateIssuesWithSummary,
+  searchCandidateIssuesWithSummary,
+} from "./opportunity-fanout.js";
+import { rankCandidateIssuesWithSummary } from "./opportunity-ranker.js";
+import { initPolicyDocCacheStore } from "./policy-doc-cache.js";
+import { initPolicyVerdictCacheStore } from "./policy-verdict-cache.js";
+import { enqueueRankedDiscovery } from "./portfolio-discovery.js";
+import { initPortfolioQueueStore } from "./portfolio-queue.js";
+import { argsWantJson, describeCliError, reportCliFailure } from "./cli-error.js";
+
+const DISCOVER_USAGE =
+  "Usage: gittensory-miner discover <owner/repo> [<owner/repo>...] | --search <query> [--dry-run] [--json] [--api-base-url <url>] [--token-env <VAR>]";
+
+const MAX_DISCOVER_TITLE_DISPLAY_LENGTH = 240;
+const OSC_SEQUENCE_PATTERN = /\u001b\][\s\S]*?(?:\u0007|\u001b\\)/g;
+const ANSI_ESCAPE_PATTERN = /\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f-\u009f]/g;
+const BIDI_CONTROL_PATTERN = /[\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+
+export function sanitizeDiscoverDisplayText(value) {
+  return String(value ?? "")
+    .replace(OSC_SEQUENCE_PATTERN, "")
+    .replace(ANSI_ESCAPE_PATTERN, "")
+    .replace(CONTROL_CHARACTER_PATTERN, " ")
+    .replace(BIDI_CONTROL_PATTERN, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, MAX_DISCOVER_TITLE_DISPLAY_LENGTH);
+}
+
+function parseRepoTarget(value) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  const [owner, repo, extra] = trimmed.split("/");
+  if (!owner || !repo || extra !== undefined) return null;
+  return { owner, repo };
+}
+
+export function parseDiscoverArgs(args) {
+  // `--api-base-url` and `--token-env` (#4784) thread the tenant's forge host and credential env var into the
+  // fan-out; they are kept off the parsed result unless supplied, so callers that pass neither see the exact
+  // pre-#4784 `{ targets, search, json }` shape.
+  const options = { json: false, dryRun: false, search: null, apiBaseUrl: null, tokenEnv: null };
+  const targets = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    // #4847: fetches + ranks exactly as a real run, but skips opening any local store and makes zero writes.
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === "--search") {
+      const query = args[index + 1];
+      if (!query || query.startsWith("-")) return { error: DISCOVER_USAGE };
+      options.search = query;
+      index += 1;
+      continue;
+    }
+    if (token === "--api-base-url") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) return { error: DISCOVER_USAGE };
+      options.apiBaseUrl = value;
+      index += 1;
+      continue;
+    }
+    if (token === "--token-env") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) return { error: DISCOVER_USAGE };
+      options.tokenEnv = value;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    const target = parseRepoTarget(token);
+    if (!target) return { error: `Repository must be in owner/repo form: ${token}` };
+    targets.push(target);
+  }
+
+  if (options.search === null && targets.length === 0) {
+    return { error: DISCOVER_USAGE };
+  }
+  if (options.search !== null && targets.length > 0) {
+    return { error: "Pass either repository targets or --search, not both." };
+  }
+
+  return {
+    targets,
+    search: options.search,
+    dryRun: options.dryRun,
+    json: options.json,
+    ...(options.apiBaseUrl !== null ? { apiBaseUrl: options.apiBaseUrl } : {}),
+    ...(options.tokenEnv !== null ? { tokenEnv: options.tokenEnv } : {}),
+  };
+}
+
+// The rate-limit line surfaces the telemetry the fanout already records (#4837) so an operator sees how close a
+// `discover` run is to being throttled without running a separate command. `unknown` covers the no-fetch/no-header
+// case where the fanout captured no remaining count.
+function renderRateLimitLine(result) {
+  const remaining = result.rateLimitRemaining === null ? "unknown" : String(result.rateLimitRemaining);
+  const resetSuffix = result.rateLimitResetAt === null ? "" : ` (resets ${result.rateLimitResetAt})`;
+  return `rate-limit remaining: ${remaining}${resetSuffix}`;
+}
+
+export function renderDiscoverSummary(result) {
+  const lines = [
+    `fanned out: ${result.fanOutCount} candidate issue(s)`,
+    `ai-policy warnings: ${result.warnings.length}`,
+    `ranked: ${result.ranked.length}`,
+    `enqueued: ${result.enqueueSummary.enqueued}`,
+    renderRateLimitLine(result),
+  ];
+  if (result.enqueueSummary.skippedBelowMinRank > 0) {
+    lines.push(`skipped (below min rank): ${result.enqueueSummary.skippedBelowMinRank}`);
+  }
+  // Make the fall-back to gittensory's built-in rubric explicit instead of silent (#4784): when no per-tenant goal
+  // spec is supplied, lane fit reflects gittensory's defaults, not the target repo's own conventions.
+  if (result.usedDefaultGoalSpec) {
+    lines.push(
+      "note: ranked with the built-in default goal spec (no per-tenant .gittensory-miner.yml supplied)",
+    );
+  }
+  if (result.ranked.length === 0) {
+    lines.push("", "no candidates found.");
+    return lines.join("\n");
+  }
+  lines.push("", "top candidates:");
+  for (const entry of result.ranked.slice(0, 10)) {
+    const title = sanitizeDiscoverDisplayText(entry.title);
+    lines.push(`  ${entry.repoFullName}#${entry.issueNumber}  score=${entry.rankScore.toFixed(4)}  ${title}`);
+  }
+  return lines.join("\n");
+}
+
+export async function runDiscover(args, options = {}) {
+  const parsed = parseDiscoverArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  // Credential env var is per-tenant (#4784): a `--token-env FORGE_PAT` flag (or `options.tokenEnv`) reads a
+  // non-`GITHUB_TOKEN` variable so a non-github.com forge's token is reachable. The default falls through to the
+  // forge adapter's own `tokenEnvVar` (github.com's `GITHUB_TOKEN`), so there's a single source of truth for the
+  // default credential env instead of a second hardcoded literal that could drift from `DEFAULT_FORGE_CONFIG`.
+  const tokenEnv = parsed.tokenEnv ?? options.tokenEnv ?? resolveForgeConfig(options.forge).tokenEnvVar;
+  const githubToken = options.githubToken ?? process.env[tokenEnv] ?? "";
+  // A `--api-base-url` flag (or `options.apiBaseUrl`) surfaces the fan-out's existing forge-host override at the CLI
+  // (#4784); `options.forge` carries any remaining per-tenant forge knobs for a programmatic caller.
+  const apiBaseUrl = parsed.apiBaseUrl ?? options.apiBaseUrl;
+  const fetchTargets = options.fetchCandidateIssuesWithSummary ?? fetchCandidateIssuesWithSummary;
+  const searchTargets = options.searchCandidateIssuesWithSummary ?? searchCandidateIssuesWithSummary;
+  const rankIssues = options.rankCandidateIssuesWithSummary ?? rankCandidateIssuesWithSummary;
+  const enqueue = options.enqueueRankedDiscovery ?? enqueueRankedDiscovery;
+
+  // #4847: fetch + rank are read-only GitHub GETs and pure local computation, so a dry run still does them for
+  // real (that's the useful "what would this discover?" output) -- but it never opens any local store (portfolio
+  // queue, policy-doc cache, policy-verdict cache), since opening a not-yet-existing SQLite store file is itself
+  // a write. The ranked issues are fed through a no-op queue stub so enqueueRankedDiscovery's own classification
+  // logic (valid/invalid, below-min-rank) still runs for real, just without ever touching the real queue.
+  if (parsed.dryRun) {
+    const fanOutOptions = { apiBaseUrl, forge: options.forge, policyDocCache: null, policyVerdictCache: null };
+    try {
+      const fanOut =
+        parsed.search !== null
+          ? await searchTargets(parsed.search, githubToken, fanOutOptions)
+          : await fetchTargets(parsed.targets, githubToken, fanOutOptions);
+      const rankedSummary = rankIssues(fanOut.issues, {
+        nowMs: options.nowMs,
+        goalSpecsByRepo: options.goalSpecsByRepo,
+        goalSpecContentByRepo: options.goalSpecContentByRepo,
+      });
+      const noopQueueStore = { enqueue: () => {} };
+      const enqueueSummary = enqueue(rankedSummary.issues, { queueStore: noopQueueStore });
+      const result = {
+        outcome: "dry_run",
+        fanOutCount: fanOut.issues.length,
+        warnings: fanOut.warnings,
+        rateLimitRemaining: fanOut.rateLimitRemaining,
+        rateLimitResetAt: fanOut.rateLimitResetAt,
+        ranked: rankedSummary.issues,
+        usedDefaultGoalSpec: rankedSummary.usedDefaultGoalSpec,
+        enqueueSummary,
+      };
+      if (parsed.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(renderDiscoverSummary(result));
+        console.log("\nDRY RUN: no portfolio-queue write was made.");
+      }
+      return 0;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 2;
+    }
+  }
+
+  const ownsPortfolioQueue = options.initPortfolioQueue === undefined;
+  let portfolioQueue;
+  try {
+    portfolioQueue = (options.initPortfolioQueue ?? initPortfolioQueueStore)();
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+
+  // Local ETag cache so a repeated discover revalidates each repo's policy docs with a conditional GET instead of
+  // re-downloading them (#4842). Opened inside its OWN try/catch, separate from the portfolio queue above: the
+  // queue is required infrastructure (discovery genuinely cannot enqueue anything without it, so a real open
+  // failure should abort the run), but the policy-doc cache is a pure performance optimization -- a corrupt or
+  // unwritable cache DB must degrade to "no cache" (every doc fetched in full, exactly as before #4842) rather
+  // than fail discovery outright.
+  let policyDocCache = null;
+  let ownsPolicyDocCache = false;
+  try {
+    ownsPolicyDocCache = options.initPolicyDocCache === undefined;
+    policyDocCache = (options.initPolicyDocCache ?? initPolicyDocCacheStore)();
+  } catch {
+    policyDocCache = null;
+    ownsPolicyDocCache = false;
+  }
+
+  // Persisted cache of resolved policy verdicts (#4843), same "own try/catch, degrade to null" discipline as the
+  // doc cache above and for the same reason: purely a performance optimization the feature is inert without, so a
+  // corrupt/unwritable cache DB must never abort a run.
+  let policyVerdictCache = null;
+  let ownsPolicyVerdictCache = false;
+  try {
+    ownsPolicyVerdictCache = options.initPolicyVerdictCache === undefined;
+    policyVerdictCache = (options.initPolicyVerdictCache ?? initPolicyVerdictCacheStore)();
+  } catch {
+    policyVerdictCache = null;
+    ownsPolicyVerdictCache = false;
+  }
+  const fanOutOptions = { apiBaseUrl, forge: options.forge, policyDocCache, policyVerdictCache };
+
+  try {
+    const fanOut =
+      parsed.search !== null
+        ? await searchTargets(parsed.search, githubToken, fanOutOptions)
+        : await fetchTargets(parsed.targets, githubToken, fanOutOptions);
+
+    // Pass any caller-supplied per-tenant goal specs through to the ranker so lane fit uses the tenant's
+    // conventions instead of silently falling back to gittensory's defaults (#4784); the fallback is surfaced via
+    // `usedDefaultGoalSpec` below rather than hidden.
+    const rankedSummary = rankIssues(fanOut.issues, {
+      nowMs: options.nowMs,
+      goalSpecsByRepo: options.goalSpecsByRepo,
+      goalSpecContentByRepo: options.goalSpecContentByRepo,
+    });
+    const enqueueSummary = enqueue(rankedSummary.issues, { queueStore: portfolioQueue, apiBaseUrl });
+
+    const result = {
+      fanOutCount: fanOut.issues.length,
+      warnings: fanOut.warnings,
+      rateLimitRemaining: fanOut.rateLimitRemaining,
+      rateLimitResetAt: fanOut.rateLimitResetAt,
+      ranked: rankedSummary.issues,
+      usedDefaultGoalSpec: rankedSummary.usedDefaultGoalSpec,
+      enqueueSummary,
+    };
+
+    if (parsed.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(renderDiscoverSummary(result));
+    }
+    return 0;
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  } finally {
+    if (ownsPortfolioQueue && portfolioQueue) portfolioQueue.close();
+    if (ownsPolicyDocCache && policyDocCache) policyDocCache.close();
+    if (ownsPolicyVerdictCache && policyVerdictCache) policyVerdictCache.close();
+  }
+}

package/lib/discovery-throttle.d.ts

@@ -0,0 +1,8 @@
+export const DEFAULT_RATE_LIMIT_LOW_WATER_MARK: number;
+export const DEFAULT_RATE_LIMIT_HIGH_WATER_MARK: number;
+export function resolveThrottledConcurrency(
+  baseConcurrency: number,
+  rateLimitRemaining: number | null,
+  lowWaterMark: number,
+  highWaterMark: number,
+): number;

package/lib/discovery-throttle.js

@@ -0,0 +1,33 @@
+// Dynamic discovery back-off (#4844): the fanout already records GitHub's `x-ratelimit-remaining`, but nothing
+// slowed its own concurrent fetching in response — a `discover` run could sprint at full concurrency straight
+// into a 403. This pure helper maps the recorded remaining budget to an allowed in-flight concurrency so the
+// fanout tapers off as the budget approaches zero. It only decides *how many* requests may run; it never changes
+// which docs are fetched or how a policy verdict is derived from them.
+
+/** At or below this remaining budget, serialize discovery to a single in-flight request. */
+export const DEFAULT_RATE_LIMIT_LOW_WATER_MARK = 50;
+/** At or above this remaining budget, run at the full configured concurrency. */
+export const DEFAULT_RATE_LIMIT_HIGH_WATER_MARK = 250;
+
+/**
+ * Resolve the concurrency the fanout may run at for the currently-recorded rate-limit budget. Returns an integer
+ * in `[1, baseConcurrency]`:
+ *  - an unknown budget (`null`/non-finite — nothing recorded yet) runs at full `baseConcurrency`;
+ *  - at or below `lowWaterMark` it clamps to a single in-flight request;
+ *  - at or above `highWaterMark` it runs at full `baseConcurrency`;
+ *  - in between it scales linearly with the remaining fraction of the low→high band.
+ * @param {number} baseConcurrency
+ * @param {number|null} rateLimitRemaining
+ * @param {number} lowWaterMark
+ * @param {number} highWaterMark
+ * @returns {number}
+ */
+export function resolveThrottledConcurrency(baseConcurrency, rateLimitRemaining, lowWaterMark, highWaterMark) {
+  if (!Number.isFinite(rateLimitRemaining)) return baseConcurrency;
+  if (rateLimitRemaining <= lowWaterMark) return 1;
+  if (rateLimitRemaining >= highWaterMark) return baseConcurrency;
+  // remaining is strictly inside the (low, high) band, so the fraction is in (0, 1) and the ceil lands in
+  // [1, baseConcurrency] without any further clamping.
+  const fraction = (rateLimitRemaining - lowWaterMark) / (highWaterMark - lowWaterMark);
+  return Math.ceil(fraction * baseConcurrency);
+}

package/lib/env-file-indirection.d.ts

@@ -0,0 +1,4 @@
+export function loadMinerFileSecrets(
+  env?: Record<string, string | undefined>,
+  readFile?: (path: string) => string,
+): void;

package/lib/env-file-indirection.js

@@ -0,0 +1,45 @@
+// Resolve `<NAME>_FILE` env vars (Docker/Swarm/K8s secret mounts) into `<NAME>` at miner startup (#5178).
+// Ports src/selfhost/load-file-secrets.ts's pattern into the miner package -- the miner is a separate
+// deployable (its own process/container per DEPLOYMENT.md's fleet mode), so it never runs through ORB's own
+// server-startup resolver. Deliberately diverges from that analogue in one way: an unreadable/missing
+// `<NAME>_FILE` here THROWS rather than logging and continuing, so a broken secret mount fails a miner
+// container fast and loud (never silently proceeds with an unset/empty credential the next real GitHub call
+// would then fail on anyway, with a far less specific error).
+import { readFileSync } from "node:fs";
+
+// Docker Compose's OWN reserved `_FILE`-suffixed environment variables -- never gittensory's secret-file
+// convention, so they must never be dereferenced below (mirrors src/selfhost/load-file-secrets.ts's own
+// exclusion and rationale: `COMPOSE_FILE` is a colon-delimited list of compose file paths, never a single
+// readable file itself, and `COMPOSE_ENV_FILE` points at an operator's own .env file, not a secret).
+const COMPOSE_RESERVED_FILE_VARS = new Set(["COMPOSE_FILE", "COMPOSE_ENV_FILE"]);
+
+/**
+ * Scan `env` for `<NAME>_FILE` vars and resolve each into `<NAME>` in place, reading the referenced file's
+ * contents (trimmed). An explicit `<NAME>` value always wins over `<NAME>_FILE` (mirrors the ORB analogue's
+ * precedence rule exactly) -- a `_FILE` var is only consulted when its plain counterpart is unset. Throws a
+ * clear, actionable error identifying the offending `<NAME>_FILE` var and its file path when the file is
+ * missing or unreadable -- this never silently leaves a credential empty/undefined. Never logs or returns any
+ * resolved secret value itself; only the (non-secret) var name and file path ever appear in a thrown message.
+ *
+ * `env` and `readFile` are injectable purely for testability -- every real caller uses the defaults
+ * (`process.env`, `node:fs`'s `readFileSync`), so this is byte-identical to a hardcoded version at runtime.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @param {(path: string) => string} [readFile]
+ */
+export function loadMinerFileSecrets(env = process.env, readFile = (path) => readFileSync(path, "utf8")) {
+  for (const key of Object.keys(env)) {
+    if (!key.endsWith("_FILE") || !env[key] || COMPOSE_RESERVED_FILE_VARS.has(key)) continue;
+    const target = key.slice(0, -"_FILE".length);
+    if (env[target]) continue; // an explicit <NAME> value always wins over <NAME>_FILE
+    try {
+      env[target] = readFile(env[key]).trim();
+    } catch (error) {
+      throw new Error(
+        `Failed to read secret file for ${key} (${env[key]}): ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+}

package/lib/event-ledger-cli.d.ts

@@ -0,0 +1,82 @@
+import type { EventLedger, LedgerEntry } from "./event-ledger.js";
+
+export type ParsedLedgerListArgs =
+  | {
+      json: boolean;
+      repoFullName: string | null;
+      since: number | null;
+      type: string | null;
+    }
+  | { error: string };
+
+export function parseLedgerListArgs(args: string[]): ParsedLedgerListArgs;
+
+export function filterLedgerEvents(
+  events: LedgerEntry[],
+  options?: { type?: string | null },
+): LedgerEntry[];
+
+export const AUDIT_FEED_ENTRY_FIELDS: readonly [
+  "eventType",
+  "repoFullName",
+  "outcome",
+  "actor",
+  "detail",
+  "createdAt",
+];
+
+export function projectLedgerEventToAuditFeedEntry(entry: LedgerEntry): {
+  eventType: string;
+  repoFullName: string | null;
+  outcome: string | null;
+  actor: string | null;
+  detail: string | null;
+  createdAt: string;
+};
+
+export type AuditFeedMcpFilterInput = {
+  repoFullName?: string | null;
+  since?: number | null;
+  type?: string | null;
+};
+
+export function normalizeAuditFeedMcpFilter(input?: AuditFeedMcpFilterInput): {
+  repoFullName: string | null;
+  since: number | null;
+  type: string | null;
+};
+
+export function collectEventLedgerAuditFeed(
+  eventLedger: EventLedger,
+  filter?: { repoFullName?: string | null; since?: number | null; type?: string | null },
+): {
+  repoFullName?: string;
+  events: Array<{
+    eventType: string;
+    repoFullName: string | null;
+    outcome: string | null;
+    actor: string | null;
+    detail: string | null;
+    createdAt: string;
+  }>;
+};
+
+export function renderLedgerTable(events: LedgerEntry[]): string;
+
+export function renderEventLedgerMetrics(events: readonly LedgerEntry[]): string;
+
+export function runLedgerList(
+  args: string[],
+  options?: { initEventLedger?: () => EventLedger },
+): number;
+
+export function runLedgerMetrics(
+  args: string[],
+  options?: { initEventLedger?: () => EventLedger },
+): number;
+
+export function runLedgerCli(
+  subcommand: string | undefined,
+  args: string[],
+  options?: { initEventLedger?: () => EventLedger },
+): number;