@loopover/miner 0.1.0

package/lib/loop-reentry.d.ts

@@ -0,0 +1,51 @@
+export const LOOP_REENTRY_DECISION_EVENT: "loop_reentry_decision";
+
+export type LoopReentryOutcome = "merged" | "disengaged" | "other";
+export type LoopReentryKillSwitchScope = "global" | "repo" | "none";
+
+export type LoopReentryCandidateInput = {
+  /** Checked FIRST by the pure `shouldReenter` policy, before any other logic. */
+  killSwitchScope: LoopReentryKillSwitchScope;
+  repoFullName: string;
+  outcome: LoopReentryOutcome;
+  maxConsecutiveDisengagements?: number;
+  maxReentriesPerHour?: number;
+  maxReentriesPerSession?: number;
+};
+
+export interface LoopReentryEventLedger {
+  appendEvent(event: { type: string; repoFullName?: string; payload: Record<string, unknown> }): { id: number; seq: number; type: string; repoFullName: string | null; payload: Record<string, unknown>; createdAt: string };
+  readEvents(filter?: { since?: number; repoFullName?: string }): Array<{ type: string; repoFullName?: string | null; payload?: Record<string, unknown>; createdAt: string }>;
+}
+
+export interface LoopReentryPortfolioQueue {
+  dequeueNext(): { repoFullName: string; identifier: string; priority: number; status: string; enqueuedAt: string } | null;
+}
+
+export interface LoopReentryRunState {
+  setRunState(repoFullName: string, state: string): unknown;
+}
+
+export type LoopReentryDeps = {
+  eventLedger: LoopReentryEventLedger;
+  portfolioQueue: LoopReentryPortfolioQueue;
+  runState?: LoopReentryRunState;
+  nowMs?: number;
+  sessionStartMs?: number;
+  /** The just-completed cycle's read-only summary (loop-closure.js's `buildLoopClosureSummary`), threaded
+   *  through verbatim into the audit event's payload for traceability. Not used to compute the circuit-
+   *  breaker/rate-cap tallies -- see loop-reentry.js's own comment on why. */
+  loopSummary?: unknown;
+};
+
+export type LoopReentryResult = {
+  decision: { reenter: boolean; reasons: string[] };
+  dequeued: { repoFullName: string; identifier: string; priority: number; status: string; enqueuedAt: string } | null;
+  event: { id: number; seq: number; type: string; repoFullName: string | null; payload: Record<string, unknown>; createdAt: string };
+};
+
+export function countConsecutiveDisengagements(eventLedger: LoopReentryEventLedger, repoFullName: string): number;
+
+export function countReentriesSince(eventLedger: LoopReentryEventLedger, sinceMs: number): number;
+
+export function attemptLoopReentry(candidate: LoopReentryCandidateInput, deps: LoopReentryDeps): LoopReentryResult;

package/lib/loop-reentry.js

@@ -0,0 +1,124 @@
+import { shouldReenter } from "@loopover/engine";
+
+import { readPrOutcomes } from "./pr-outcome.js";
+
+// Closed-loop discovery re-entry orchestrator (#2338): the real-IO half of "on a resolved outcome (merged, or
+// rejected-and-disengaged), automatically re-invoke discovery to select the next candidate." The DECISION
+// itself (shouldReenter, @loopover/engine) is pure; this module owns everything that decision
+// needs real state for -- reading the repo's own pr_outcome history to compute the per-repo consecutive-
+// disengagement tally, reading recent re-entry events for the hourly/session rate cap, and (only when allowed)
+// actually dequeuing the next candidate and transitioning run-state.
+//
+// NOT WIRED INTO ANY AUTOMATIC SCHEDULE: per this issue's own "manual owner sign-off before enabling by
+// default in any profile" deliverable, this is a callable function ready for that sign-off -- it is not invoked
+// by manage-poll.js or any cron/scheduler as part of this change.
+//
+// AUDITABILITY: every call appends exactly one `loop_reentry_decision` event to the ledger, whether or not the
+// decision allowed re-entry, so the full decision trail (including every suppressed re-entry and why) survives
+// independently of this function's own return value.
+
+export const LOOP_REENTRY_DECISION_EVENT = "loop_reentry_decision";
+const HOUR_MS = 60 * 60 * 1000;
+
+/** A `pr_outcome` "closed" decision is this module's practical proxy for "disengaged" -- pr-outcome.js's own
+ *  vocabulary is exactly `"merged" | "closed"` (no separate "disengaged" literal); a PR that closed without
+ *  merging IS the rejected/disengaged case rejection-state-machine.js's own `isRejectedPr` checks for. */
+function isDisengagedOutcome(outcome) {
+  return outcome?.decision === "closed";
+}
+
+/**
+ * Count a repo's CONSECUTIVE disengaged (closed-without-merge) PR outcomes, walking backward from the most
+ * recently recorded PR for that repo until a merged outcome breaks the streak (or history runs out).
+ */
+export function countConsecutiveDisengagements(eventLedger, repoFullName) {
+  const outcomes = [...readPrOutcomes(eventLedger, { repoFullName }).values()];
+  let count = 0;
+  for (let i = outcomes.length - 1; i >= 0; i -= 1) {
+    if (!isDisengagedOutcome(outcomes[i])) break;
+    count += 1;
+  }
+  return count;
+}
+
+/** Count prior re-entries (successful, i.e. `reentered: true`) recorded at or after `sinceMs`. */
+export function countReentriesSince(eventLedger, sinceMs) {
+  return eventLedger
+    .readEvents({})
+    .filter((event) => event.type === LOOP_REENTRY_DECISION_EVENT && event.payload?.reentered === true && Date.parse(event.createdAt) >= sinceMs)
+    .length;
+}
+
+/**
+ * Evaluate and (if allowed) PERFORM re-entry for one resolved outcome: reads real history to compute the
+ * circuit-breaker and rate-cap tallies, consults the pure `shouldReenter` policy, and -- only when it allows --
+ * dequeues the next candidate and transitions run-state to `"discovering"`. Always appends exactly one audit
+ * event. Fails closed (throws) on a malformed candidate or missing required dependency, mirroring
+ * `recordManagePollSnapshot`'s own validation style.
+ *
+ * @param {{ killSwitchScope: "global"|"repo"|"none", repoFullName: string, outcome: "merged"|"disengaged"|"other", maxConsecutiveDisengagements?: number, maxReentriesPerHour?: number, maxReentriesPerSession?: number }} candidate
+ * @param {{ eventLedger: object, portfolioQueue: object, runState?: object, nowMs?: number, sessionStartMs?: number }} deps
+ */
+export function attemptLoopReentry(candidate, deps) {
+  if (!candidate || typeof candidate !== "object") throw new Error("invalid_loop_reentry_candidate");
+  if (!["global", "repo", "none"].includes(candidate.killSwitchScope)) throw new Error("invalid_kill_switch_scope");
+  const repoFullName = typeof candidate.repoFullName === "string" ? candidate.repoFullName.trim() : "";
+  if (!repoFullName) throw new Error("invalid_repo_full_name");
+  if (!["merged", "disengaged", "other"].includes(candidate.outcome)) throw new Error("invalid_outcome");
+
+  if (!deps || typeof deps !== "object") throw new Error("invalid_loop_reentry_deps");
+  const { eventLedger, portfolioQueue, runState, nowMs = Date.now(), sessionStartMs = 0 } = deps;
+  if (!eventLedger || typeof eventLedger.appendEvent !== "function" || typeof eventLedger.readEvents !== "function") {
+    throw new Error("invalid_event_ledger");
+  }
+  if (!portfolioQueue || typeof portfolioQueue.dequeueNext !== "function") {
+    throw new Error("invalid_portfolio_queue");
+  }
+
+  const consecutiveDisengagements = countConsecutiveDisengagements(eventLedger, repoFullName);
+  const reentriesThisHour = countReentriesSince(eventLedger, nowMs - HOUR_MS);
+  const reentriesThisSession = countReentriesSince(eventLedger, sessionStartMs);
+
+  const decision = shouldReenter({
+    killSwitchScope: candidate.killSwitchScope,
+    repoFullName,
+    outcome: candidate.outcome,
+    consecutiveDisengagements,
+    maxConsecutiveDisengagements: candidate.maxConsecutiveDisengagements,
+    reentriesThisHour,
+    maxReentriesPerHour: candidate.maxReentriesPerHour,
+    reentriesThisSession,
+    maxReentriesPerSession: candidate.maxReentriesPerSession,
+  });
+
+  let dequeued = null;
+  if (decision.reenter) {
+    dequeued = portfolioQueue.dequeueNext();
+    if (runState && typeof runState.setRunState === "function") {
+      runState.setRunState(repoFullName, "discovering");
+    }
+  }
+
+  const event = eventLedger.appendEvent({
+    type: LOOP_REENTRY_DECISION_EVENT,
+    repoFullName,
+    payload: {
+      killSwitchScope: candidate.killSwitchScope,
+      outcome: candidate.outcome,
+      reentered: decision.reenter,
+      reasons: decision.reasons,
+      consecutiveDisengagements,
+      reentriesThisHour,
+      reentriesThisSession,
+      dequeuedIdentifier: dequeued ? dequeued.identifier : null,
+      // The just-completed cycle's read-only summary (loop-closure.js's buildLoopClosureSummary), when the
+      // caller supplies one -- threaded through verbatim for audit traceability. Optional: the circuit-breaker
+      // and rate-cap tallies above are computed directly from pr-outcome/event-ledger history (a
+      // LoopClosureSummary's own byType COUNTS aren't detailed enough to derive a per-repo consecutive-
+      // disengagement streak from), so this is context, not a computational input.
+      loopSummary: deps.loopSummary ?? null,
+    },
+  });
+
+  return { decision, dequeued, event };
+}

package/lib/manage-poll.d.ts

@@ -0,0 +1,79 @@
+import type { PollCheckRunsOptions, PollCheckRunsResult } from "./ci-poller.js";
+import type { EventLedger, LedgerEntry } from "./event-ledger.js";
+import type { PortfolioQueueStore } from "./portfolio-queue.js";
+
+export type ManagePollInput = {
+  repoFullName: string;
+  prNumber: number;
+  branch?: string | null;
+};
+
+export type ManagePollEventPayload = {
+  prNumber: number;
+  branch: string | null;
+  ciState: PollCheckRunsResult["conclusion"];
+  gateVerdict: string;
+  outcome: string;
+  lastPolledAt: string;
+};
+
+export type ManagePollRecordResult = {
+  pollResult: PollCheckRunsResult;
+  payload: ManagePollEventPayload;
+  event: LedgerEntry;
+};
+
+export type ParsedManagePollArgs =
+  | {
+      repoFullName: string;
+      prNumber: number;
+      branch: string | null;
+      dryRun: boolean;
+      json: boolean;
+    }
+  | { error: string };
+
+export function mapPollConclusionToGateVerdict(
+  conclusion: PollCheckRunsResult["conclusion"],
+): string;
+
+export function mapPollConclusionToOutcome(conclusion: PollCheckRunsResult["conclusion"]): string;
+
+export function buildManagePollEventPayload(
+  prNumber: number,
+  pollResult: PollCheckRunsResult,
+  options?: { branch?: string | null; lastPolledAt?: string },
+): ManagePollEventPayload;
+
+export function parseManagePollArgs(args?: string[]): ParsedManagePollArgs;
+
+export function recordManagePollSnapshot(
+  input: ManagePollInput,
+  options: {
+    eventLedger: EventLedger;
+    portfolioQueue?: PortfolioQueueStore;
+    ensurePortfolioRow?: boolean;
+    pollCheckRuns?: (
+      repoFullName: string,
+      prNumber: number,
+      options?: PollCheckRunsOptions,
+    ) => Promise<PollCheckRunsResult>;
+    lastPolledAt?: string;
+  } & PollCheckRunsOptions,
+): Promise<ManagePollRecordResult>;
+
+export function runManagePoll(
+  args?: string[],
+  options?: {
+    initEventLedger?: () => EventLedger;
+    initPortfolioQueue?: () => PortfolioQueueStore;
+    ensurePortfolioRow?: boolean;
+    pollCheckRuns?: (
+      repoFullName: string,
+      prNumber: number,
+      options?: PollCheckRunsOptions,
+    ) => Promise<PollCheckRunsResult>;
+    githubToken?: string;
+    lastPolledAt?: string;
+  } & PollCheckRunsOptions,
+): Promise<number>;

package/lib/manage-poll.js

@@ -0,0 +1,254 @@
+import { pollCheckRuns } from "./ci-poller.js";
+import { initEventLedger } from "./event-ledger.js";
+import {
+  MANAGE_PR_UPDATE_EVENT,
+  formatManagedPrIdentifier,
+} from "./manage-status.js";
+import { initPortfolioQueueStore } from "./portfolio-queue.js";
+import { argsWantJson, describeCliError, reportCliFailure } from "./cli-error.js";
+
+const MANAGE_POLL_USAGE =
+  "Usage: gittensory-miner manage poll <owner/repo> <pr#> [--branch <name>] [--dry-run] [--json]";
+
+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 mapPollConclusionToGateVerdict(conclusion) {
+  switch (conclusion) {
+    case "success":
+      return "pass";
+    case "failure":
+      return "block";
+    default:
+      return "advisory";
+  }
+}
+
+export function mapPollConclusionToOutcome(conclusion) {
+  switch (conclusion) {
+    case "success":
+      return "ready";
+    case "failure":
+      return "needs-work";
+    default:
+      return "open";
+  }
+}
+
+export function buildManagePollEventPayload(prNumber, pollResult, options = {}) {
+  if (!Number.isInteger(prNumber) || prNumber <= 0) throw new Error("invalid_pr_number");
+  if (!pollResult || typeof pollResult !== "object") throw new Error("invalid_poll_result");
+  const branch = typeof options.branch === "string" && options.branch.trim() ? options.branch.trim() : null;
+  const lastPolledAt =
+    typeof options.lastPolledAt === "string" && options.lastPolledAt.trim()
+      ? options.lastPolledAt.trim()
+      : new Date().toISOString();
+  return {
+    prNumber,
+    branch,
+    ciState: pollResult.conclusion,
+    gateVerdict: mapPollConclusionToGateVerdict(pollResult.conclusion),
+    outcome: mapPollConclusionToOutcome(pollResult.conclusion),
+    lastPolledAt,
+  };
+}
+
+export function parseManagePollArgs(args = []) {
+  const options = { json: false, branch: null, dryRun: false };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    // #4847: still runs the real (read-only) CI-check-run poll, but skips the event-ledger append and
+    // portfolio-queue enqueue.
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === "--branch") {
+      const branch = args[index + 1];
+      if (!branch || branch.startsWith("-")) return { error: MANAGE_POLL_USAGE };
+      options.branch = branch;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) return { error: `Unknown option: ${token}` };
+    positional.push(token);
+  }
+
+  if (positional.length !== 2) return { error: MANAGE_POLL_USAGE };
+
+  const repo = parseRepoArg(positional[0], MANAGE_POLL_USAGE);
+  if ("error" in repo) return repo;
+
+  const prNumber = Number(positional[1]);
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    return { error: "Pull request number must be a positive integer." };
+  }
+
+  return {
+    repoFullName: repo.repoFullName,
+    prNumber,
+    ...options,
+  };
+}
+
+function ensureManagedPrRow(portfolioQueue, repoFullName, prNumber) {
+  const identifier = formatManagedPrIdentifier(prNumber);
+  const exists = portfolioQueue
+    .listQueue(repoFullName)
+    .some((entry) => entry.identifier === identifier);
+  if (!exists) {
+    portfolioQueue.enqueue({ repoFullName, identifier, priority: 0 });
+  }
+}
+
+/**
+ * Poll GitHub check runs for a managed PR and append a `manage_pr_update` snapshot to the local event ledger.
+ * Completes the manage-status data path introduced in #2325 / #3070 using the CI poller from #2323.
+ */
+export async function recordManagePollSnapshot(input, options = {}) {
+  if (!input || typeof input !== "object") throw new Error("invalid_manage_poll_input");
+  const repoFullName = typeof input.repoFullName === "string" ? input.repoFullName.trim() : "";
+  const [owner, repo, extra] = repoFullName.split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  if (!Number.isInteger(input.prNumber) || input.prNumber <= 0) throw new Error("invalid_pr_number");
+
+  const eventLedger = options.eventLedger;
+  if (!eventLedger || typeof eventLedger.appendEvent !== "function") {
+    throw new Error("invalid_event_ledger");
+  }
+
+  const portfolioQueue = options.portfolioQueue;
+  if (options.portfolioQueue !== undefined) {
+    if (!portfolioQueue || typeof portfolioQueue.enqueue !== "function") {
+      throw new Error("invalid_portfolio_queue");
+    }
+  }
+
+  const pollCheckRunsFn = options.pollCheckRuns ?? pollCheckRuns;
+  const pollResult = await pollCheckRunsFn(repoFullName, input.prNumber, {
+    apiBaseUrl: options.apiBaseUrl,
+    fetchFn: options.fetchFn,
+    githubToken: options.githubToken ?? "",
+    maxAttempts: options.maxAttempts,
+    minIntervalMs: options.minIntervalMs,
+    maxIntervalMs: options.maxIntervalMs,
+    sleepFn: options.sleepFn,
+  });
+
+  const payload = buildManagePollEventPayload(input.prNumber, pollResult, {
+    branch: input.branch,
+    lastPolledAt: options.lastPolledAt,
+  });
+
+  if ((options.ensurePortfolioRow ?? true) && portfolioQueue) {
+    ensureManagedPrRow(portfolioQueue, repoFullName, input.prNumber);
+  }
+
+  const event = eventLedger.appendEvent({
+    type: MANAGE_PR_UPDATE_EVENT,
+    repoFullName,
+    payload,
+  });
+
+  return { pollResult, payload, event };
+}
+
+export async function runManagePoll(args = [], options = {}) {
+  const parsed = parseManagePollArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  // #4847: the CI-check-run poll itself is a real, read-only GitHub signal -- the useful "what would this
+  // record?" output -- so a dry run still performs it for real. It never opens the event ledger or portfolio
+  // queue, though: a no-op event ledger is fed through recordManagePollSnapshot so its own real payload-building
+  // logic still runs, just without ever writing to local storage (ensurePortfolioRow: false skips the queue
+  // enqueue the same way).
+  if (parsed.dryRun) {
+    const noopEventLedger = { appendEvent: () => null };
+    try {
+      const result = await recordManagePollSnapshot(
+        { repoFullName: parsed.repoFullName, prNumber: parsed.prNumber, branch: parsed.branch },
+        {
+          eventLedger: noopEventLedger,
+          ensurePortfolioRow: false,
+          pollCheckRuns: options.pollCheckRuns,
+          fetchFn: options.fetchFn,
+          githubToken: options.githubToken ?? process.env.GITHUB_TOKEN ?? "",
+          apiBaseUrl: options.apiBaseUrl,
+          maxAttempts: options.maxAttempts,
+          minIntervalMs: options.minIntervalMs,
+          maxIntervalMs: options.maxIntervalMs,
+          sleepFn: options.sleepFn,
+          lastPolledAt: options.lastPolledAt,
+        },
+      );
+      const dryRunResult = { outcome: "dry_run", pollResult: result.pollResult, payload: result.payload };
+      if (parsed.json) {
+        console.log(JSON.stringify(dryRunResult, null, 2));
+      } else {
+        console.log(
+          `DRY RUN: ${result.payload.ciState} (${result.payload.gateVerdict}/${result.payload.outcome}). No event-ledger or portfolio-queue write was made.`,
+        );
+      }
+      return 0;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 2;
+    }
+  }
+
+  const ownsEventLedger = options.initEventLedger === undefined;
+  const ownsPortfolioQueue = options.initPortfolioQueue === undefined;
+  const eventLedger = (options.initEventLedger ?? initEventLedger)();
+  const portfolioQueue = (options.initPortfolioQueue ?? initPortfolioQueueStore)();
+
+  try {
+    const result = await recordManagePollSnapshot(
+      {
+        repoFullName: parsed.repoFullName,
+        prNumber: parsed.prNumber,
+        branch: parsed.branch,
+      },
+      {
+        eventLedger,
+        portfolioQueue,
+        ensurePortfolioRow: options.ensurePortfolioRow ?? true,
+        pollCheckRuns: options.pollCheckRuns,
+        fetchFn: options.fetchFn,
+        githubToken: options.githubToken ?? process.env.GITHUB_TOKEN ?? "",
+        apiBaseUrl: options.apiBaseUrl,
+        maxAttempts: options.maxAttempts,
+        minIntervalMs: options.minIntervalMs,
+        maxIntervalMs: options.maxIntervalMs,
+        sleepFn: options.sleepFn,
+        lastPolledAt: options.lastPolledAt,
+      },
+    );
+
+    if (parsed.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`${result.payload.ciState} (${result.payload.gateVerdict}/${result.payload.outcome})`);
+    }
+    return 0;
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  } finally {
+    if (ownsEventLedger) eventLedger.close();
+    if (ownsPortfolioQueue) portfolioQueue.close();
+  }
+}

package/lib/manage-status.d.ts

@@ -0,0 +1,70 @@
+import type { EventLedger, LedgerEntry } from "./event-ledger.js";
+import type { PortfolioQueueStore, QueueStatus } from "./portfolio-queue.js";
+import type { RunState, RunStateStore } from "./run-state.js";
+
+export type ManageStatusRow = {
+  repoFullName: string;
+  prNumber: number;
+  branch: string | null;
+  ciState: string | null;
+  gateVerdict: string | null;
+  outcome: string | null;
+  lastPolledAt: string | null;
+  queueStatus: QueueStatus | null;
+  priority: number | null;
+};
+
+export type ManageStatusSources = {
+  portfolioQueue: PortfolioQueueStore;
+  eventLedger: EventLedger;
+};
+
+export type RunPortfolioSources = ManageStatusSources & {
+  runStateStore: RunStateStore;
+};
+
+export type RunPortfolioRow = {
+  repoFullName: string;
+  runState: RunState | null;
+  runStateUpdatedAt: string | null;
+  prCount: number;
+  prs: ManageStatusRow[];
+};
+
+export type ManageUpdateSnapshot = {
+  repoFullName: string;
+  prNumber: number;
+  branch: string | null;
+  ciState: string | null;
+  gateVerdict: string | null;
+  outcome: string | null;
+  lastPolledAt: string | null;
+};
+
+export const MANAGE_PR_UPDATE_EVENT: "manage_pr_update";
+export const MANAGED_PR_IDENTIFIER_PREFIX: "pr:";
+
+export function parseManagedPrIdentifier(identifier: string): number | null;
+
+export function formatManagedPrIdentifier(prNumber: number): string;
+
+export function indexLatestManageUpdates(events: LedgerEntry[]): Map<string, ManageUpdateSnapshot>;
+
+export function collectManageStatus(sources: ManageStatusSources): ManageStatusRow[];
+
+export function collectRunPortfolio(sources: RunPortfolioSources): RunPortfolioRow[];
+
+export function renderManageStatusTable(rows: ManageStatusRow[]): string;
+
+export function renderRunPortfolioTable(portfolio: RunPortfolioRow[]): string;
+
+export function parseManageStatusArgs(args?: string[]): { json: boolean } | { error: string };
+
+export function runManageStatus(
+  args?: string[],
+  options?: {
+    initPortfolioQueue?: () => PortfolioQueueStore;
+    initEventLedger?: () => EventLedger;
+    initRunStateStore?: () => RunStateStore;
+  },
+): number;