@loopover/miner 0.1.0

package/lib/governor-state.js

@@ -0,0 +1,363 @@
+import { DEFAULT_FORGE_CONFIG } from "./forge-config.js";
+import { normalizeLocalStoreDbPath, openLocalStoreDb, resolveLocalStoreDbPath } from "./local-store.js";
+
+// Governor cross-attempt state persistence (#5134, Wave 3.5). Every governor-*.js wrapper
+// (governor-write-rate-limit.js, governor-chokepoint.js) is a pure in/out transform: it computes and RETURNS
+// updated rate-limit buckets/backoff attempts, but nothing writes them to disk, so they reset to zero on
+// every process start -- the mutable counters that should gate the NEXT decision never survive past one
+// process. governor-ledger.js already persists the DECISION HISTORY (an append-only audit log); this module
+// persists the DECISION INPUT state instead -- a second, distinct concern, not a duplicate of that log (see
+// its own module doc for the ledger/state split this issue's acceptance criteria requires).
+//
+// This module does not alter evaluateGovernorChokepoint's precedence ladder or any pure calculator's logic --
+// it only gives their existing, already-optional input fields (rateLimitBuckets, rateLimitBackoffAttempts,
+// capUsage, reputationHistory, recentOwnSubmissions) a real load-at-start/save-at-end home. Convergence input
+// (packages/gittensory-engine/src/portfolio/non-convergence.ts's PortfolioConvergenceInput) is NOT persisted
+// here: that module's own doc comment says its counters belong on the portfolio-queue table (a pre-existing
+// store this issue's boundaries don't touch) once that table grows attempt-history columns -- inventing a
+// second, competing store for the same concept here would violate the same non-duplication principle the
+// ledger/state split above is built on.
+
+const defaultDbFileName = "governor-state.sqlite3";
+const DEFAULT_RATE_LIMIT_BUCKETS = Object.freeze({ global: {}, perRepo: {} });
+const DEFAULT_RATE_LIMIT_BACKOFF = Object.freeze({});
+const DEFAULT_CAP_USAGE = Object.freeze({ budgetSpent: 0, turnsTaken: 0, elapsedMs: 0 });
+const DEFAULT_REPUTATION_HISTORY = Object.freeze({ decided: 0, unfavorable: 0 });
+let defaultGovernorState = null;
+
+export function resolveGovernorStateDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_GOVERNOR_STATE_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolveGovernorStateDbPath(), "invalid_governor_state_db_path");
+}
+
+function normalizeRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const [owner, repo, extra] = repoFullName.trim().split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  return `${owner}/${repo}`;
+}
+
+/** Optional forge host, scoping rows so two hosts serving the same owner/repo name never collide (#5563).
+ *  Omitted/nullish → the github.com default, so every pre-existing single-forge caller is unaffected. */
+function normalizeApiBaseUrl(apiBaseUrl) {
+  if (apiBaseUrl === undefined || apiBaseUrl === null) return DEFAULT_FORGE_CONFIG.apiBaseUrl;
+  if (typeof apiBaseUrl !== "string" || !apiBaseUrl.trim()) throw new Error("invalid_api_base_url");
+  return apiBaseUrl.trim();
+}
+
+function parseJsonColumn(value, fallback) {
+  if (typeof value !== "string") return fallback;
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" ? parsed : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+// Add the pause/resume columns (#4851) to an on-disk file created before they existed. `CREATE TABLE IF NOT
+// EXISTS` above is a no-op against an already-existing table, so a pre-#4851 file needs this explicit ALTER --
+// guarded by a per-column presence check (rather than a single `paused`-only check) so a file that somehow
+// has `paused` but not `pause_reason`/`paused_at` still gets the columns it's missing, same technique as
+// portfolio-queue.js's own post-creation column migration.
+function ensurePauseColumns(db) {
+  const existingColumns = new Set(
+    db
+      .prepare("PRAGMA table_info(governor_scalar_state)")
+      .all()
+      .map((column) => column.name),
+  );
+  if (!existingColumns.has("paused")) {
+    db.exec("ALTER TABLE governor_scalar_state ADD COLUMN paused INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!existingColumns.has("pause_reason")) {
+    db.exec("ALTER TABLE governor_scalar_state ADD COLUMN pause_reason TEXT");
+  }
+  if (!existingColumns.has("paused_at")) {
+    db.exec("ALTER TABLE governor_scalar_state ADD COLUMN paused_at TEXT");
+  }
+}
+
+// Rebuild governor_reputation_history's bare `repo_full_name` PRIMARY KEY into a (api_base_url, repo_full_name)
+// composite (#5563) -- two forge hosts serving a same-named owner/repo must not share one reputation row.
+// SQLite cannot ALTER a PRIMARY KEY in place, so this rebuilds the table: create the new shape, copy every
+// existing row with the pre-#4784 implicit single-forge default backfilled, drop the old table, rename the new
+// one in. Guarded by a column-presence check (matching ensurePauseColumns' idempotence) so this only runs once
+// per file, same technique as portfolio-queue.js's own post-creation migration.
+function ensureReputationHistoryForgeScope(db) {
+  const hasApiBaseUrlColumn = db
+    .prepare("PRAGMA table_info(governor_reputation_history)")
+    .all()
+    .some((column) => column.name === "api_base_url");
+  if (hasApiBaseUrlColumn) return;
+  db.exec(`
+    CREATE TABLE governor_reputation_history_v2 (
+      api_base_url TEXT NOT NULL,
+      repo_full_name TEXT NOT NULL,
+      decided INTEGER NOT NULL,
+      unfavorable INTEGER NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (api_base_url, repo_full_name)
+    )
+  `);
+  // OR IGNORE: a source row that somehow violates the rebuilt table's NOT NULL columns (a hand-edited or
+  // otherwise corrupted file) is skipped rather than aborting the whole migration -- same fail-closed posture
+  // as run-state.js's own #5563 migration.
+  db.prepare(
+    `INSERT OR IGNORE INTO governor_reputation_history_v2 (api_base_url, repo_full_name, decided, unfavorable, updated_at)
+     SELECT ?, repo_full_name, decided, unfavorable, updated_at FROM governor_reputation_history`,
+  ).run(DEFAULT_FORGE_CONFIG.apiBaseUrl);
+  db.exec("DROP TABLE governor_reputation_history");
+  db.exec("ALTER TABLE governor_reputation_history_v2 RENAME TO governor_reputation_history");
+}
+
+/** Opens the local governor-state store, creating tables on first use. */
+export function openGovernorState(dbPath = resolveGovernorStateDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  const db = openLocalStoreDb(resolvedPath);
+
+  // ONE row (id=1) holding the whole-run scalar state: rate-limit buckets/backoff and budget/turn/termination
+  // usage have no natural per-repo key of their own beyond what's already encoded inside the JSON blob
+  // (WriteRateLimitBucketStore.perRepo is itself keyed by `${actionClass}:${repoFullName}`), so a single
+  // UPSERTed row is simpler and more honest than inventing a relational key that doesn't exist upstream.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS governor_scalar_state (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      rate_limit_buckets_json TEXT NOT NULL,
+      rate_limit_backoff_json TEXT NOT NULL,
+      cap_usage_json TEXT NOT NULL,
+      paused INTEGER NOT NULL DEFAULT 0,
+      pause_reason TEXT,
+      paused_at TEXT,
+      updated_at TEXT NOT NULL
+    )
+  `);
+  ensurePauseColumns(db);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS governor_reputation_history (
+      repo_full_name TEXT PRIMARY KEY,
+      decided INTEGER NOT NULL,
+      unfavorable INTEGER NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+  ensureReputationHistoryForgeScope(db);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS governor_own_submissions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      repo_full_name TEXT NOT NULL,
+      fingerprint TEXT NOT NULL,
+      submitted_at TEXT,
+      pull_request_number INTEGER,
+      issue_number INTEGER
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_governor_own_submissions_repo ON governor_own_submissions (repo_full_name, id)");
+
+  const getScalarStatement = db.prepare("SELECT * FROM governor_scalar_state WHERE id = 1");
+  const upsertScalarStatement = db.prepare(`
+    INSERT INTO governor_scalar_state
+      (id, rate_limit_buckets_json, rate_limit_backoff_json, cap_usage_json, paused, pause_reason, paused_at, updated_at)
+    VALUES (1, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      rate_limit_buckets_json = excluded.rate_limit_buckets_json,
+      rate_limit_backoff_json = excluded.rate_limit_backoff_json,
+      cap_usage_json = excluded.cap_usage_json,
+      paused = excluded.paused,
+      pause_reason = excluded.pause_reason,
+      paused_at = excluded.paused_at,
+      updated_at = excluded.updated_at
+  `);
+  const getReputationStatement = db.prepare(
+    "SELECT * FROM governor_reputation_history WHERE api_base_url = ? AND repo_full_name = ?",
+  );
+  const upsertReputationStatement = db.prepare(`
+    INSERT INTO governor_reputation_history (api_base_url, repo_full_name, decided, unfavorable, updated_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(api_base_url, repo_full_name) DO UPDATE SET
+      decided = excluded.decided,
+      unfavorable = excluded.unfavorable,
+      updated_at = excluded.updated_at
+  `);
+  const insertSubmissionStatement = db.prepare(`
+    INSERT INTO governor_own_submissions (repo_full_name, fingerprint, submitted_at, pull_request_number, issue_number)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+  const listSubmissionsAllStatement = db.prepare(
+    "SELECT * FROM governor_own_submissions ORDER BY id DESC LIMIT ?",
+  );
+  const listSubmissionsByRepoStatement = db.prepare(
+    "SELECT * FROM governor_own_submissions WHERE repo_full_name = ? ORDER BY id DESC LIMIT ?",
+  );
+
+  function rowToSubmission(row) {
+    return {
+      repoFullName: row.repo_full_name,
+      fingerprint: row.fingerprint,
+      submittedAt: row.submitted_at,
+      pullRequestNumber: row.pull_request_number,
+      issueNumber: row.issue_number,
+    };
+  }
+
+  const state = {
+    dbPath: resolvedPath,
+    loadRateLimitState() {
+      const row = getScalarStatement.get();
+      return {
+        buckets: parseJsonColumn(row?.rate_limit_buckets_json, DEFAULT_RATE_LIMIT_BUCKETS),
+        backoffAttempts: parseJsonColumn(row?.rate_limit_backoff_json, DEFAULT_RATE_LIMIT_BACKOFF),
+      };
+    },
+    saveRateLimitState(rateLimitState) {
+      const row = getScalarStatement.get();
+      upsertScalarStatement.run(
+        JSON.stringify(rateLimitState?.buckets ?? DEFAULT_RATE_LIMIT_BUCKETS),
+        JSON.stringify(rateLimitState?.backoffAttempts ?? DEFAULT_RATE_LIMIT_BACKOFF),
+        row ? row.cap_usage_json : JSON.stringify(DEFAULT_CAP_USAGE),
+        row ? row.paused : 0,
+        row ? row.pause_reason : null,
+        row ? row.paused_at : null,
+        new Date().toISOString(),
+      );
+    },
+    loadCapUsage() {
+      const row = getScalarStatement.get();
+      return parseJsonColumn(row?.cap_usage_json, DEFAULT_CAP_USAGE);
+    },
+    saveCapUsage(capUsage) {
+      const row = getScalarStatement.get();
+      upsertScalarStatement.run(
+        row ? row.rate_limit_buckets_json : JSON.stringify(DEFAULT_RATE_LIMIT_BUCKETS),
+        row ? row.rate_limit_backoff_json : JSON.stringify(DEFAULT_RATE_LIMIT_BACKOFF),
+        JSON.stringify(capUsage ?? DEFAULT_CAP_USAGE),
+        row ? row.paused : 0,
+        row ? row.pause_reason : null,
+        row ? row.paused_at : null,
+        new Date().toISOString(),
+      );
+    },
+    // The governor pause/resume control surface (#4851): a real, persisted, operator/governor-writable flag the
+    // loop checks before each cycle -- distinct from governor-kill-switch.js (a read-only resolver over env/YAML
+    // inputs the miner does not itself write) and governor-run-halt.js (a one-way, run-scoped terminal breaker).
+    // `pausedAt` is stamped fresh on every transition INTO paused, and cleared on resume, so a status query can
+    // report how long a pause has been in effect without needing a separate history table.
+    loadPauseState() {
+      const row = getScalarStatement.get();
+      return {
+        paused: row ? Boolean(row.paused) : false,
+        reason: row?.pause_reason ?? null,
+        pausedAt: row?.paused_at ?? null,
+      };
+    },
+    savePauseState(pauseState) {
+      const row = getScalarStatement.get();
+      const paused = Boolean(pauseState?.paused);
+      const reason =
+        typeof pauseState?.reason === "string" && pauseState.reason.trim() ? pauseState.reason.trim() : null;
+      const pausedAt = paused ? new Date().toISOString() : null;
+      upsertScalarStatement.run(
+        row ? row.rate_limit_buckets_json : JSON.stringify(DEFAULT_RATE_LIMIT_BUCKETS),
+        row ? row.rate_limit_backoff_json : JSON.stringify(DEFAULT_RATE_LIMIT_BACKOFF),
+        row ? row.cap_usage_json : JSON.stringify(DEFAULT_CAP_USAGE),
+        paused ? 1 : 0,
+        reason,
+        pausedAt,
+        new Date().toISOString(),
+      );
+      return { paused, reason, pausedAt };
+    },
+    loadReputationHistory(repoFullName, apiBaseUrl) {
+      const normalizedForge = normalizeApiBaseUrl(apiBaseUrl);
+      const normalizedRepo = normalizeRepoFullName(repoFullName);
+      const row = getReputationStatement.get(normalizedForge, normalizedRepo);
+      if (!row) return { ...DEFAULT_REPUTATION_HISTORY };
+      return { decided: row.decided, unfavorable: row.unfavorable };
+    },
+    saveReputationHistory(repoFullName, history, apiBaseUrl) {
+      const normalizedForge = normalizeApiBaseUrl(apiBaseUrl);
+      const normalizedRepo = normalizeRepoFullName(repoFullName);
+      const decided = Number.isInteger(history?.decided) ? history.decided : 0;
+      const unfavorable = Number.isInteger(history?.unfavorable) ? history.unfavorable : 0;
+      upsertReputationStatement.run(normalizedForge, normalizedRepo, decided, unfavorable, new Date().toISOString());
+      return { decided, unfavorable };
+    },
+    recordOwnSubmission(record) {
+      const normalized = normalizeRepoFullName(record?.repoFullName);
+      if (typeof record?.fingerprint !== "string" || !record.fingerprint.trim()) {
+        throw new Error("invalid_fingerprint");
+      }
+      const submittedAt = typeof record.submittedAt === "string" ? record.submittedAt : new Date().toISOString();
+      const pullRequestNumber = Number.isInteger(record.pullRequestNumber) ? record.pullRequestNumber : null;
+      const issueNumber = Number.isInteger(record.issueNumber) ? record.issueNumber : null;
+      insertSubmissionStatement.run(normalized, record.fingerprint, submittedAt, pullRequestNumber, issueNumber);
+      return { repoFullName: normalized, fingerprint: record.fingerprint, submittedAt, pullRequestNumber, issueNumber };
+    },
+    listRecentOwnSubmissions(filter = {}) {
+      const limit = Number.isInteger(filter.limit) && filter.limit > 0 ? filter.limit : 200;
+      const rows =
+        filter.repoFullName === undefined
+          ? listSubmissionsAllStatement.all(limit)
+          : listSubmissionsByRepoStatement.all(normalizeRepoFullName(filter.repoFullName), limit);
+      return rows.map(rowToSubmission);
+    },
+    close() {
+      db.close();
+    },
+  };
+  return state;
+}
+
+function getDefaultGovernorState() {
+  defaultGovernorState ??= openGovernorState();
+  return defaultGovernorState;
+}
+
+export function loadRateLimitState() {
+  return getDefaultGovernorState().loadRateLimitState();
+}
+
+export function saveRateLimitState(rateLimitState) {
+  return getDefaultGovernorState().saveRateLimitState(rateLimitState);
+}
+
+export function loadCapUsage() {
+  return getDefaultGovernorState().loadCapUsage();
+}
+
+export function saveCapUsage(capUsage) {
+  return getDefaultGovernorState().saveCapUsage(capUsage);
+}
+
+export function loadPauseState() {
+  return getDefaultGovernorState().loadPauseState();
+}
+
+export function savePauseState(pauseState) {
+  return getDefaultGovernorState().savePauseState(pauseState);
+}
+
+export function loadReputationHistory(repoFullName, apiBaseUrl) {
+  return getDefaultGovernorState().loadReputationHistory(repoFullName, apiBaseUrl);
+}
+
+export function saveReputationHistory(repoFullName, history, apiBaseUrl) {
+  return getDefaultGovernorState().saveReputationHistory(repoFullName, history, apiBaseUrl);
+}
+
+export function recordOwnSubmission(record) {
+  return getDefaultGovernorState().recordOwnSubmission(record);
+}
+
+export function listRecentOwnSubmissions(filter) {
+  return getDefaultGovernorState().listRecentOwnSubmissions(filter);
+}
+
+export function closeDefaultGovernorState() {
+  if (!defaultGovernorState) return;
+  defaultGovernorState.close();
+  defaultGovernorState = null;
+}

package/lib/governor-write-rate-limit.d.ts

@@ -0,0 +1,30 @@
+import type {
+  WriteRateLimitBackoffStore,
+  WriteRateLimitBucketStore,
+  WriteRateLimitPolicies,
+  WriteRateLimitVerdict,
+} from "@loopover/engine";
+import type { AppendGovernorEventInput, GovernorLedgerEntry } from "./governor-ledger.js";
+
+export type EvaluateWriteRateLimitGateInput = {
+  actionClass: string;
+  repoFullName: string;
+  buckets: WriteRateLimitBucketStore;
+  backoffAttempts: WriteRateLimitBackoffStore;
+  nowMs: number;
+  policies?: WriteRateLimitPolicies;
+  randomFn?: () => number;
+};
+
+export type EvaluateWriteRateLimitGateResult = {
+  verdict: WriteRateLimitVerdict;
+  recorded: GovernorLedgerEntry;
+  buckets: WriteRateLimitBucketStore;
+  backoffAttempts: WriteRateLimitBackoffStore;
+  retryAtMs: number | null;
+};
+
+export function evaluateWriteRateLimitGate(
+  input: EvaluateWriteRateLimitGateInput,
+  options?: { append?: (event: AppendGovernorEventInput) => GovernorLedgerEntry },
+): EvaluateWriteRateLimitGateResult;

package/lib/governor-write-rate-limit.js

@@ -0,0 +1,64 @@
+// Governor write-rate-limit gate (#2344). Consults global + per-repo buckets before a write action, schedules
+// jittered retries on throttle, and records outcomes to the append-only governor ledger.
+
+import {
+  buildWriteRateLimitGovernorLedgerEvent,
+  clearWriteRateLimitBackoff,
+  evaluateWriteRateLimit,
+  recordWriteRateLimitAllowed,
+  recordWriteRateLimitDenied,
+} from "@loopover/engine";
+import { appendGovernorEvent } from "./governor-ledger.js";
+
+/**
+ * Evaluate write-rate limits for a governor write action and persist the decision.
+ *
+ * @param {object} input
+ * @param {string} input.actionClass governor write class (e.g. open_pr, comment)
+ * @param {string} input.repoFullName target repo
+ * @param {import("@loopover/engine").WriteRateLimitBucketStore} input.buckets
+ * @param {import("@loopover/engine").WriteRateLimitBackoffStore} input.backoffAttempts
+ * @param {number} input.nowMs clock reading in epoch ms
+ * @param {import("@loopover/engine").WriteRateLimitPolicies} [input.policies]
+ * @param {() => number} [input.randomFn] injected jitter source (defaults to mid-band draw)
+ * @param {{ append?: typeof appendGovernorEvent }} [options]
+ */
+export function evaluateWriteRateLimitGate(input, options = {}) {
+  const append = options.append ?? appendGovernorEvent;
+  const verdict = evaluateWriteRateLimit(input);
+  const recorded = append(
+    buildWriteRateLimitGovernorLedgerEvent(input.repoFullName, input.actionClass, verdict),
+  );
+
+  if (verdict.allowed) {
+    return {
+      verdict,
+      recorded,
+      buckets: recordWriteRateLimitAllowed(
+        input.buckets,
+        input.actionClass,
+        input.repoFullName,
+        input.nowMs,
+        input.policies,
+      ),
+      backoffAttempts: clearWriteRateLimitBackoff(
+        input.backoffAttempts,
+        input.actionClass,
+        input.repoFullName,
+      ),
+      retryAtMs: null,
+    };
+  }
+
+  return {
+    verdict,
+    recorded,
+    buckets: input.buckets,
+    backoffAttempts: recordWriteRateLimitDenied(
+      input.backoffAttempts,
+      input.actionClass,
+      input.repoFullName,
+    ),
+    retryAtMs: input.nowMs + verdict.retryAfterMs,
+  };
+}

package/lib/harness-submission-trigger.d.ts

@@ -0,0 +1,69 @@
+export const HARNESS_SUBMISSION_TRIGGER_DECISION_EVENT: "harness_submission_trigger_decision";
+
+export type HarnessSubmissionSlopBand = "clean" | "low" | "elevated" | "high";
+export type HarnessSubmissionMode = "observe" | "enforce";
+export type HarnessSubmissionKillSwitchScope = "global" | "repo" | "none";
+
+export type HarnessSubmissionCandidateInput = {
+  /** Forwarded to shouldSubmit's own kill-switch check (#2339). */
+  killSwitchScope: HarnessSubmissionKillSwitchScope;
+  repoFullName: string;
+  handoffPacket: {
+    worktreePath: string;
+    branchRef?: string;
+    diffSummary: string;
+    selfReviewVerdict: unknown;
+    attemptLogReference: string;
+  };
+  slopThreshold: HarnessSubmissionSlopBand;
+  mode: HarnessSubmissionMode;
+  maxConsecutiveGateBlocks?: number;
+};
+
+export interface HarnessSubmissionEventLedger {
+  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 type HarnessSubmissionDeps = {
+  eventLedger: HarnessSubmissionEventLedger;
+  sessionStartMs?: number;
+};
+
+export type HarnessSubmissionDecision = {
+  allow: boolean;
+  reasons: string[];
+  circuitBreakerTripped: boolean;
+};
+
+export type HarnessSubmissionResult = {
+  decision: HarnessSubmissionDecision;
+  event: { id: number; seq: number; type: string; repoFullName: string | null; payload: Record<string, unknown>; createdAt: string };
+};
+
+export function countConsecutiveGateBlocks(eventLedger: HarnessSubmissionEventLedger, sinceMs: number): number;
+
+export function evaluateAndRecordHarnessSubmissionTrigger(candidate: HarnessSubmissionCandidateInput, deps: HarnessSubmissionDeps): HarnessSubmissionResult;
+
+/** The exact input shape buildOpenPrSpec (root src/mcp/local-write-tools.ts) expects. */
+export type OpenPrInput = {
+  repoFullName: string;
+  base: string;
+  head: string;
+  title: string;
+  body: string;
+  draft: boolean;
+};
+
+export type PrepareOpenPrSubmissionCandidate = HarnessSubmissionCandidateInput & {
+  base: string;
+  title: string;
+  body?: string;
+  draft?: boolean;
+};
+
+export type PrepareOpenPrSubmissionResult =
+  | { ready: true; decision: HarnessSubmissionDecision; event: HarnessSubmissionResult["event"]; openPrInput: OpenPrInput }
+  | { ready: false; decision: HarnessSubmissionDecision; event: HarnessSubmissionResult["event"] };
+
+export function prepareOpenPrSubmission(candidate: PrepareOpenPrSubmissionCandidate, deps: HarnessSubmissionDeps): PrepareOpenPrSubmissionResult;

package/lib/harness-submission-trigger.js

@@ -0,0 +1,138 @@
+import { evaluateHarnessSubmissionTrigger } from "@loopover/engine";
+
+// Harness submission-gate wiring orchestrator (#2337): the real-IO half of connecting the gated-submission
+// decision (`shouldSubmit`, wrapped by `evaluateHarnessSubmissionTrigger`, @loopover/engine) to a
+// real driving loop's own handoff signal. Reads the session's recent decision history to compute the
+// consecutive-block circuit-breaker tally, consults the pure decision, and always records exactly one audit
+// event -- regardless of outcome, so a paused-pending-human-review session leaves a full trail of why.
+//
+// NOT WIRED INTO ANY AUTOMATIC SCHEDULE: per this issue's own "manual owner sign-off on the wiring before this
+// ships to any default-on profile" deliverable. `prepareOpenPrSubmission` below is the call site up to the
+// cross-package boundary: on `allow: true` it shapes the exact input `buildOpenPrSpec` (root
+// `src/mcp/local-write-tools.ts`) needs -- but does not, and cannot, call that function itself, since the spec
+// builder lives in the private root `src/` tree, unreachable from this package (same cross-package-boundary
+// reason self-review-adapter.ts's slop injection exists). A real root-side/MCP call site (e.g. the existing
+// `gittensory_open_pr` tool, src/mcp/server.ts) takes `openPrInput` from a `ready: true` result and passes it
+// to `buildOpenPrSpec` (or the equivalent tool call) to actually produce the runnable local-write spec. The
+// CLI/driver entrypoint that instantiates a real `CodingAgentDriver` and calls `runIterateLoop` end to end with
+// live credentials does not exist yet in this package -- that is separate, larger scope from this decision-to-
+// payload bridge.
+//
+// SESSION-SCOPED, NOT PER-REPO: the circuit breaker's own "pauses the run entirely" wording means the tally is
+// counted across EVERY repo's decisions this session, not scoped to one repo -- distinct from #2338's loop-
+// reentry circuit breaker, which is deliberately per-repo (a rejection streak on one repo must not pause
+// unrelated repos).
+
+export const HARNESS_SUBMISSION_TRIGGER_DECISION_EVENT = "harness_submission_trigger_decision";
+
+/** Count consecutive `allow: false` decisions recorded at or after `sinceMs`, walking backward from the most
+ *  recent decision until an `allow: true` breaks the streak (or history runs out). Session-scoped (not
+ *  filtered by repo) to match the circuit breaker's own "pauses the run entirely" semantics. */
+export function countConsecutiveGateBlocks(eventLedger, sinceMs) {
+  const decisions = eventLedger
+    .readEvents({})
+    .filter((event) => event.type === HARNESS_SUBMISSION_TRIGGER_DECISION_EVENT && Date.parse(event.createdAt) >= sinceMs);
+  let count = 0;
+  for (let i = decisions.length - 1; i >= 0; i -= 1) {
+    if (decisions[i].payload?.allow === true) break;
+    count += 1;
+  }
+  return count;
+}
+
+/**
+ * Evaluate the harness submission trigger for one candidate handoff, reading real session history to compute
+ * the circuit-breaker tally, and always appending exactly one audit event. Fails closed (throws) on a
+ * malformed candidate or missing required dependency.
+ *
+ * @param {{ killSwitchScope: "global"|"repo"|"none", repoFullName: string, handoffPacket: object, slopThreshold: "clean"|"low"|"elevated"|"high", mode: "observe"|"enforce", maxConsecutiveGateBlocks?: number }} candidate
+ * @param {{ eventLedger: object, sessionStartMs?: number }} deps
+ */
+export function evaluateAndRecordHarnessSubmissionTrigger(candidate, deps) {
+  if (!candidate || typeof candidate !== "object") throw new Error("invalid_harness_submission_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 (!candidate.handoffPacket || typeof candidate.handoffPacket !== "object") throw new Error("invalid_handoff_packet");
+
+  if (!deps || typeof deps !== "object") throw new Error("invalid_harness_submission_deps");
+  const { eventLedger, sessionStartMs = 0 } = deps;
+  if (!eventLedger || typeof eventLedger.appendEvent !== "function" || typeof eventLedger.readEvents !== "function") {
+    throw new Error("invalid_event_ledger");
+  }
+
+  const consecutiveGateBlocks = countConsecutiveGateBlocks(eventLedger, sessionStartMs);
+
+  const decision = evaluateHarnessSubmissionTrigger({
+    killSwitchScope: candidate.killSwitchScope,
+    handoffPacket: candidate.handoffPacket,
+    slopThreshold: candidate.slopThreshold,
+    mode: candidate.mode,
+    consecutiveGateBlocks,
+    maxConsecutiveGateBlocks: candidate.maxConsecutiveGateBlocks,
+  });
+
+  const event = eventLedger.appendEvent({
+    type: HARNESS_SUBMISSION_TRIGGER_DECISION_EVENT,
+    repoFullName,
+    payload: {
+      killSwitchScope: candidate.killSwitchScope,
+      allow: decision.allow,
+      reasons: decision.reasons,
+      circuitBreakerTripped: decision.circuitBreakerTripped,
+      consecutiveGateBlocks,
+      attemptLogReference: candidate.handoffPacket.attemptLogReference ?? null,
+    },
+  });
+
+  return { decision, event };
+}
+
+/**
+ * Bridge one completed handoff through the submission gate to a submission-READY payload -- the exact input
+ * shape `buildOpenPrSpec` expects (repoFullName/base/head/title/body/draft). On `allow: true` returns
+ * `{ ready: true, decision, event, openPrInput }`; otherwise `{ ready: false, decision, event }` -- the block
+ * reasons are on `decision.reasons` and already on the ledger via the wrapped call either way. Does NOT call
+ * `buildOpenPrSpec` itself (see this module's own doc comment for why it cannot) -- a real root-side/MCP call
+ * site takes `openPrInput` from a `ready: true` result and passes it to that function or the equivalent
+ * `gittensory_open_pr` MCP tool.
+ *
+ * Fails closed (throws) on a malformed candidate, mirroring evaluateAndRecordHarnessSubmissionTrigger's own
+ * validation -- a missing PR title/base is a caller bug that must never silently degrade into a garbage spec.
+ * The one field evaluateAndRecordHarnessSubmissionTrigger does NOT itself require -- handoffPacket.branchRef,
+ * optional there because iterate-loop.ts deliberately does not manage worktrees/branches -- IS required here,
+ * but only once the decision is known to be `allow: true`: a PR cannot be opened without a source branch, but a
+ * blocked candidate needs no branch at all, and must not throw for a reason unrelated to why it was blocked.
+ *
+ * @param {{ killSwitchScope: "global"|"repo"|"none", repoFullName: string, handoffPacket: { branchRef?: string, [key: string]: unknown }, slopThreshold: "clean"|"low"|"elevated"|"high", mode: "observe"|"enforce", maxConsecutiveGateBlocks?: number, base: string, title: string, body?: string, draft?: boolean }} candidate
+ * @param {{ eventLedger: object, sessionStartMs?: number }} deps
+ */
+export function prepareOpenPrSubmission(candidate, deps) {
+  if (!candidate || typeof candidate !== "object") throw new Error("invalid_harness_submission_candidate");
+  const base = typeof candidate.base === "string" ? candidate.base.trim() : "";
+  if (!base) throw new Error("invalid_pr_base");
+  const title = typeof candidate.title === "string" ? candidate.title.trim() : "";
+  if (!title) throw new Error("invalid_pr_title");
+
+  const { decision, event } = evaluateAndRecordHarnessSubmissionTrigger(candidate, deps);
+  if (!decision.allow) return { ready: false, decision, event };
+
+  // Only reached once evaluateAndRecordHarnessSubmissionTrigger has already validated handoffPacket is a
+  // well-formed object -- safe to read .branchRef directly.
+  const head = typeof candidate.handoffPacket.branchRef === "string" ? candidate.handoffPacket.branchRef.trim() : "";
+  if (!head) throw new Error("invalid_pr_head_branch");
+
+  return {
+    ready: true,
+    decision,
+    event,
+    openPrInput: {
+      repoFullName: candidate.repoFullName.trim(),
+      base,
+      head,
+      title,
+      body: typeof candidate.body === "string" ? candidate.body : "",
+      draft: candidate.draft === true,
+    },
+  };
+}

package/lib/http-retry.d.ts

@@ -0,0 +1,12 @@
+export function defaultRetryBackoffMs(attempt: number): number;
+
+export function fetchWithRetry<Response extends { status: number }>(
+  fetchFn: (url: unknown, init?: unknown) => Promise<Response>,
+  url: unknown,
+  init?: unknown,
+  options?: {
+    maxAttempts?: number;
+    sleepFn?: (ms: number) => Promise<unknown>;
+    backoffMs?: (attempt: number) => number;
+  },
+): Promise<Response>;