@loopover/miner 0.1.0

package/lib/attempt-input-builder.js

@@ -0,0 +1,91 @@
+import { isGlobalMinerKillSwitch, isGlobalMinerLiveModeOptIn } from "@loopover/engine";
+
+// Pure composers for runMinerAttempt's real input (#5132, Wave 3.5 -- the final assembly). Everything here is
+// a plain in/out transform over already-fetched/already-computed real data (coding-task-spec, #5239;
+// self-review-context, #5145; worktree preparation, #5237/#5252; AmsPolicySpec, #5249) -- no fetching, no IO,
+// same discipline as coding-task-spec.js's own composers.
+//
+// KNOWN, DOCUMENTED GAPS (not fabricated -- explicitly left as real, narrow follow-ups):
+//   - governor.convergenceInput is a first-attempt-shaped literal ({ attempts: 0, consecutiveFailures: 0,
+//     reenqueues: 0, reachedDone: false }), not a real per-issue query. attempt-log.js's schema has no
+//     repo+issue index (attemptId embeds a timestamp, so it's not a stable group key), and reenqueue counts
+//     aren't tracked ANYWHERE yet (non-convergence.ts's own header says that belongs on the portfolio-queue
+//     table once it grows attempt-history columns -- a real, separate schema change, not something to fake
+//     here). This literal is only ever an UNDER-estimate (reads "fresh, no prior failures" even on a real
+//     Nth attempt), which fails toward LETTING an attempt through, not blocking one -- documented, not silent.
+//   - governor.reputationHistory/selfPlagiarismCandidate/selfPlagiarismRecentSubmissions are omitted, which
+//     chokepoint.ts's own design treats as "skip that stage entirely" -- an honest absence, not a fabricated
+//     "clean" verdict.
+
+/**
+ * Assemble the real Governor chokepoint context for one attempt. rateLimitBuckets/rateLimitBackoffAttempts/
+ * capUsage are deliberately omitted -- evaluateGovernorChokepointGatePersisted (#5134) auto-loads them from
+ * the persisted governor-state store when absent.
+ *
+ * `repoPaused` (#5392) is the caller's own resolved `MinerGoalSpec.killSwitch.paused` for the target repo
+ * (miner-goal-spec.js's resolveMinerGoalSpec) -- this composer stays pure and just threads whatever the
+ * caller already resolved through; passing nothing keeps the prior fails-open-on-that-axis-only behavior.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @param {import("@loopover/engine").AmsPolicySpec} amsPolicySpec
+ * @param {boolean} [repoPaused]
+ * @returns {import("./attempt-runner.js").AttemptGovernorContext}
+ */
+export function buildAttemptGovernorContext(env, amsPolicySpec, repoPaused) {
+  return {
+    killSwitchGlobal: isGlobalMinerKillSwitch(env),
+    killSwitchRepoPaused: repoPaused,
+    liveModeGlobalOptIn: isGlobalMinerLiveModeOptIn(env),
+    capLimits: amsPolicySpec.capLimits,
+    convergenceInput: { attempts: 0, consecutiveFailures: 0, reenqueues: 0, reachedDone: false },
+  };
+}
+
+/**
+ * Assemble the real IterateLoopInput for one attempt from every already-computed real dependency. Pure --
+ * throws nothing itself (callers are expected to have already validated `codingTaskSpec.ready`).
+ *
+ * @param {{
+ *   codingTaskSpec: Extract<import("./coding-task-spec.js").CodingTaskSpecResult, { ready: true }>,
+ *   reviewContext: import("@loopover/engine").SelfReviewContext,
+ *   worktreePath: string,
+ *   attemptId: string,
+ *   mode: import("@loopover/engine").CodingAgentExecutionMode,
+ *   repoFullName: string,
+ *   minerLogin: string,
+ *   rejectionSignaled: boolean,
+ *   amsPolicySpec: import("@loopover/engine").AmsPolicySpec,
+ *   branchRef?: string,
+ * }} input
+ * @returns {import("@loopover/engine").IterateLoopInput}
+ */
+export function buildAttemptLoopInput(input) {
+  return {
+    attemptId: input.attemptId,
+    workingDirectory: input.worktreePath,
+    acceptanceCriteriaPath: input.codingTaskSpec.acceptanceCriteriaPath,
+    instructions: input.codingTaskSpec.instructions,
+    mode: input.mode,
+    maxIterations: input.amsPolicySpec.maxIterations,
+    maxTurnsPerIteration: input.amsPolicySpec.maxTurnsPerIteration,
+    // Real mid-attempt budget (#5395): the SAME Governor cap ceilings that already bound cross-cycle spend
+    // (loop-cli.js's after-the-fact governorState.saveCapUsage) now also bound this ONE attempt in progress,
+    // via the engine's real accumulateAttemptUsage/evaluateAttemptBudget -- a runaway attempt can no longer
+    // burn through the entire cross-cycle budget before anything reacts. No maxTokens: no driver reports a
+    // real per-iteration token count today, so that axis has no real ceiling to set (never fabricated).
+    budget: {
+      maxTurns: input.amsPolicySpec.capLimits.turns,
+      maxWallClockMs: input.amsPolicySpec.capLimits.elapsedMs,
+      maxCostUsd: input.amsPolicySpec.capLimits.budget,
+    },
+    repoFullName: input.repoFullName,
+    contributorLogin: input.minerLogin,
+    title: input.codingTaskSpec.title,
+    body: input.codingTaskSpec.body,
+    labels: input.codingTaskSpec.labels,
+    linkedIssues: input.codingTaskSpec.linkedIssues,
+    branchRef: input.branchRef,
+    reviewContext: input.reviewContext,
+    rejectionSignaled: input.rejectionSignaled,
+  };
+}

package/lib/attempt-log.d.ts

@@ -0,0 +1,37 @@
+import type { AttemptLogEvent } from "@loopover/engine";
+
+export type AttemptLogEntry = {
+  id: number;
+  seq: number;
+  eventType: string;
+  attemptId: string;
+  actionClass: string;
+  mode: string;
+  reason: string;
+  payload: Record<string, unknown>;
+  createdAt: string;
+};
+
+export type ReadAttemptLogEventsFilter = {
+  attemptId?: string | null;
+};
+
+export type AttemptLog = {
+  dbPath: string;
+  appendAttemptLogEvent(event: AttemptLogEvent): AttemptLogEntry;
+  readAttemptLogEvents(filter?: ReadAttemptLogEventsFilter): AttemptLogEntry[];
+  exportAttemptLogJsonl(attemptId: string): string;
+  close(): void;
+};
+
+export function resolveAttemptLogDbPath(env?: Record<string, string | undefined>): string;
+
+export function initAttemptLog(dbPath?: string): AttemptLog;
+
+export function appendAttemptLogEvent(event: AttemptLogEvent): AttemptLogEntry;
+
+export function readAttemptLogEvents(filter?: ReadAttemptLogEventsFilter): AttemptLogEntry[];
+
+export function exportAttemptLogJsonl(attemptId: string): string;
+
+export function closeDefaultAttemptLog(): void;

package/lib/attempt-log.js

@@ -0,0 +1,177 @@
+import { formatAttemptLogJsonl, normalizeAttemptLogEvent } from "@loopover/engine";
+import { normalizeLocalStoreDbPath, openLocalStoreDb, resolveLocalStoreDbPath } from "./local-store.js";
+
+// Append-only driver attempt log (#4294): a structured, attempt-scoped event trace for every CodingAgentDriver run
+// (started, tool/edit, succeeded/failed/aborted). IMMUTABILITY INVARIANT: INSERT + SELECT only — rows are never
+// rewritten or removed after append.
+//
+// Why a sibling store instead of extending event-ledger.js: event-ledger is the general miner-loop audit trail
+// (discovered_issue, plan_built, pr_prepared, …) keyed by repo scope with a growing free-form type vocabulary.
+// Attempt events are keyed by attempt_id, validated against the engine's fixed ATTEMPT_LOG_EVENT_TYPES, and are
+// exported per attempt as JSONL — mixing both into one table would couple unrelated lifecycles and complicate the
+// per-attempt dump path. This module mirrors governor-ledger.js: engine holds pure normalization, miner holds SQLite.
+
+const defaultDbFileName = "attempt-log.sqlite3";
+let defaultAttemptLog = null;
+
+export function resolveAttemptLogDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_ATTEMPT_LOG_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolveAttemptLogDbPath(), "invalid_attempt_log_db_path");
+}
+
+/** Read-filter attempt scope: omitted/nullish → unscoped (all events); otherwise a non-empty attempt id. */
+function normalizeReadAttemptIdFilter(attemptId) {
+  if (attemptId === undefined || attemptId === null) return undefined;
+  if (typeof attemptId !== "string") throw new Error("invalid_attempt_id");
+  const trimmed = attemptId.trim();
+  if (!trimmed) throw new Error("invalid_attempt_id");
+  return trimmed;
+}
+
+/** Export requires an explicit attempt id — JSONL dumps are always per attempt. */
+function normalizeRequiredAttemptId(attemptId) {
+  const normalized = normalizeReadAttemptIdFilter(attemptId);
+  if (normalized === undefined) throw new Error("invalid_attempt_id");
+  return normalized;
+}
+
+function rowToEntry(row) {
+  let payload;
+  try {
+    payload = JSON.parse(row.payload_json);
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("corrupted_attempt_log_row");
+    }
+  } catch {
+    throw new Error("corrupted_attempt_log_row");
+  }
+  return {
+    id: row.id,
+    seq: row.seq,
+    eventType: row.event_type,
+    attemptId: row.attempt_id,
+    actionClass: row.action_class,
+    mode: row.mode,
+    reason: row.reason,
+    payload,
+    createdAt: row.created_at,
+  };
+}
+
+function rowToNormalized(row) {
+  return {
+    eventType: row.event_type,
+    attemptId: row.attempt_id,
+    actionClass: row.action_class,
+    mode: row.mode,
+    reason: row.reason,
+    payloadJson: row.payload_json,
+  };
+}
+
+/**
+ * Opens the append-only attempt log, creating the table on first use. `seq` is a monotonically increasing counter
+ * maintained by this module (next = current MAX(seq) + 1) with a UNIQUE(seq) constraint. Rows read back in seq ASC
+ * order. (#4294)
+ */
+export function initAttemptLog(dbPath = resolveAttemptLogDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  const db = openLocalStoreDb(resolvedPath);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS attempt_log_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      seq INTEGER NOT NULL UNIQUE,
+      attempt_id TEXT NOT NULL,
+      event_type TEXT NOT NULL,
+      action_class TEXT NOT NULL,
+      mode TEXT NOT NULL,
+      reason TEXT NOT NULL,
+      payload_json TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    )
+  `);
+  db.exec(
+    "CREATE INDEX IF NOT EXISTS idx_attempt_log_attempt ON attempt_log_events (attempt_id, seq)",
+  );
+
+  const nextSeqStatement = db.prepare("SELECT COALESCE(MAX(seq), 0) + 1 AS nextSeq FROM attempt_log_events");
+  const appendStatement = db.prepare(`
+    INSERT INTO attempt_log_events (
+      seq, attempt_id, event_type, action_class, mode, reason, payload_json, created_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const getByIdStatement = db.prepare("SELECT * FROM attempt_log_events WHERE id = ?");
+  const readAllStatement = db.prepare("SELECT * FROM attempt_log_events ORDER BY seq ASC");
+  const readByAttemptStatement = db.prepare(
+    "SELECT * FROM attempt_log_events WHERE attempt_id = ? ORDER BY seq ASC",
+  );
+
+  return {
+    dbPath: resolvedPath,
+    appendAttemptLogEvent(event) {
+      const normalized = normalizeAttemptLogEvent(event);
+      const createdAt = new Date().toISOString();
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const { nextSeq } = nextSeqStatement.get();
+        const result = appendStatement.run(
+          nextSeq,
+          normalized.attemptId,
+          normalized.eventType,
+          normalized.actionClass,
+          normalized.mode,
+          normalized.reason,
+          normalized.payloadJson,
+          createdAt,
+        );
+        const entry = rowToEntry(getByIdStatement.get(Number(result.lastInsertRowid)));
+        db.exec("COMMIT");
+        return entry;
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
+    },
+    readAttemptLogEvents(filter = {}) {
+      const attemptId = normalizeReadAttemptIdFilter(filter.attemptId);
+      const rows =
+        attemptId === undefined ? readAllStatement.all() : readByAttemptStatement.all(attemptId);
+      return rows.map(rowToEntry);
+    },
+    exportAttemptLogJsonl(attemptId) {
+      const scopedAttemptId = normalizeRequiredAttemptId(attemptId);
+      const rows = readByAttemptStatement.all(scopedAttemptId);
+      return formatAttemptLogJsonl(rows.map(rowToNormalized));
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+function getDefaultAttemptLog() {
+  defaultAttemptLog ??= initAttemptLog();
+  return defaultAttemptLog;
+}
+
+export function appendAttemptLogEvent(event) {
+  return getDefaultAttemptLog().appendAttemptLogEvent(event);
+}
+
+export function readAttemptLogEvents(filter) {
+  return getDefaultAttemptLog().readAttemptLogEvents(filter);
+}
+
+export function exportAttemptLogJsonl(attemptId) {
+  return getDefaultAttemptLog().exportAttemptLogJsonl(attemptId);
+}
+
+export function closeDefaultAttemptLog() {
+  if (!defaultAttemptLog) return;
+  defaultAttemptLog.close();
+  defaultAttemptLog = null;
+}

package/lib/attempt-runner.d.ts

@@ -0,0 +1,59 @@
+import type {
+  CodingAgentDriver,
+  GovernorDecision,
+  IterateLoopInput,
+  IterateLoopResult,
+  LocalWriteActionSpec,
+} from "@loopover/engine";
+import type { HarnessSubmissionDecision, HarnessSubmissionEventLedger } from "./harness-submission-trigger.js";
+import type { SubmissionFreshnessClaimLedger, LiveIssueSnapshot, FreshnessAbortReason } from "./submission-freshness-check.js";
+import type { GovernorChokepointInputPersisted } from "./governor-chokepoint-persisted.js";
+import type { GovernorState } from "./governor-state.js";
+
+export const ATTEMPT_OUTCOMES: readonly ["abandon", "stale", "blocked", "governed", "submitted"];
+
+// rateLimitBuckets/rateLimitBackoffAttempts/capUsage are optional here (via GovernorChokepointInputPersisted,
+// not the engine's own GovernorChokepointInput) so a caller can omit them and let evaluateGovernorChokepointGatePersisted
+// (#5134) auto-supply real persisted state -- forcing them required at this layer would make every caller
+// hand-thread honest-but-stale zero defaults on every invocation, silently defeating that persistence.
+export type AttemptGovernorContext = Omit<GovernorChokepointInputPersisted, "actionClass" | "repoFullName" | "nowMs" | "wouldBeAction">;
+
+export type AttemptInput = {
+  loopInput: IterateLoopInput;
+  issueNumber: number;
+  minerLogin: string;
+  base: string;
+  killSwitchScope: "global" | "repo" | "none";
+  slopThreshold: "clean" | "low" | "elevated" | "high";
+  submissionMode: "observe" | "enforce";
+  maxConsecutiveGateBlocks?: number;
+  draft?: boolean;
+  governor: AttemptGovernorContext;
+};
+
+export type AttemptDeps = {
+  driver: CodingAgentDriver;
+  runSlopAssessment: (input: unknown) => unknown;
+  appendAttemptLogEvent: (event: unknown) => void;
+  claimLedger: SubmissionFreshnessClaimLedger;
+  fetchLiveIssueSnapshot: (repoFullName: string, issueNumber: number) => Promise<LiveIssueSnapshot | null>;
+  eventLedger: HarnessSubmissionEventLedger;
+  /** Injected governor-ledger append (mirrors evaluateGovernorChokepointGate's own `options.append`); omitted
+   *  falls back to that function's own default (the real default governor ledger). */
+  governorLedgerAppend?: (event: unknown) => unknown;
+  /** Injected governor-state store (#5134); omitted falls back to evaluateGovernorChokepointGatePersisted's
+   *  own default (opens + closes the real default governor-state store for this one call). */
+  governorState?: GovernorState;
+  sessionStartMs?: number;
+  nowMs: number;
+  executeLocalWrite: (spec: LocalWriteActionSpec) => Promise<unknown>;
+};
+
+export type AttemptResult =
+  | { outcome: "abandon"; loopResult: IterateLoopResult }
+  | { outcome: "stale"; reason: FreshnessAbortReason; loopResult: IterateLoopResult }
+  | { outcome: "blocked"; decision: HarnessSubmissionDecision; loopResult: IterateLoopResult }
+  | { outcome: "governed"; decision: GovernorDecision; loopResult: IterateLoopResult }
+  | { outcome: "submitted"; spec: LocalWriteActionSpec; execResult: unknown; loopResult: IterateLoopResult };
+
+export function runMinerAttempt(input: AttemptInput, deps: AttemptDeps): Promise<AttemptResult>;

package/lib/attempt-runner.js

@@ -0,0 +1,164 @@
+import { buildOpenPrSpec } from "@loopover/engine";
+import { runIterateLoop } from "@loopover/engine";
+import { checkSubmissionFreshness } from "./submission-freshness-check.js";
+import { evaluateGovernorChokepointGatePersisted } from "./governor-chokepoint-persisted.js";
+import { prepareOpenPrSubmission } from "./harness-submission-trigger.js";
+
+// The real driving-loop entrypoint (#2337): the missing link between #2333's iterate-loop orchestrator and an
+// actual, executed open_pr write. Composes, in order: runIterateLoop (create -> score -> self-review -> decide,
+// #2333) -> on handoff, checkSubmissionFreshness (#3007) -> prepareOpenPrSubmission (#2336/#2337) -> the
+// Governor chokepoint (#2340, which itself composes kill-switch, dry-run, rate-limit, budget caps, non-
+// convergence, self-reputation-throttle, and self-plagiarism -- see chokepoint.ts's own module doc comment for
+// the exact precedence ladder) -> on allowed:true, builds the REAL open_pr command via the now-shared
+// buildOpenPrSpec (@loopover/engine, moved from root src/mcp/local-write-tools.ts) and executes it.
+//
+// WORKTREE LIFECYCLE IS NOT THIS MODULE'S JOB: runIterateLoop already takes a plain `workingDirectory` string
+// (packages/gittensory-engine/src/miner/iterate-loop.ts's own IterateLoopInput), deliberately agnostic about
+// where it came from. Allocating one is the caller's job, via the already-built slot allocator
+// (worktree-allocator.js, #4297) -- this module composes the create/review/gate/submit sequence #2337 is
+// actually about, not worktree allocation policy, which is a separate, already-solved concern.
+//
+// KNOWN, DELIBERATE GAP (not silently papered over -- was an injected-but-unwired seam before this module
+// existed, and remains so here):
+//   - `deps.runSlopAssessment` has no production implementation anywhere in this package. The real slop scorer
+//     (src/signals/slop.ts, 518 lines, 5 sibling src/signals/** dependencies) is far larger and more
+//     interconnected than local-write-tools.ts was, so extracting it is separate, substantial scope -- this
+//     function requires a real one be injected rather than silently stubbing a result that would either always
+//     pass (unsafe) or always fail (useless).
+//
+// `input.governor`'s cross-attempt state (rate-limit buckets, backoff attempts, budget-cap usage) DOES now
+// persist across separate process invocations (#5134, governor-state.js), via
+// evaluateGovernorChokepointGatePersisted -- callers no longer need to hand-thread honest empty/zero defaults
+// on every invocation; `capUsage` is loaded from that same store but its post-attempt save stays the caller's
+// job (see governor-chokepoint-persisted.js's own header for why: nothing computes "the next capUsage" from a
+// verdict, only the attempt's real outcome does). Reputation/self-plagiarism state also has real persistence
+// primitives (governor-state.js) but isn't auto-loaded here yet -- `input.governor.reputationHistory`/
+// `selfPlagiarismCandidate`/`selfPlagiarismRecentSubmissions` are still caller-supplied optional fields on
+// GovernorChokepointInput, same as before.
+
+/** True once the loop reaches handoff AND every downstream gate (freshness, submission, governor) allows. */
+export const ATTEMPT_OUTCOMES = Object.freeze(["abandon", "stale", "blocked", "governed", "submitted"]);
+
+function assertFn(value, name) {
+  if (typeof value !== "function") throw new Error(`invalid_${name}`);
+}
+
+function assertDeps(deps) {
+  if (!deps || typeof deps !== "object") throw new Error("invalid_attempt_deps");
+  assertFn(deps.runSlopAssessment, "run_slop_assessment");
+  assertFn(deps.appendAttemptLogEvent, "append_attempt_log_event");
+  assertFn(deps.fetchLiveIssueSnapshot, "fetch_live_issue_snapshot");
+  assertFn(deps.executeLocalWrite, "execute_local_write");
+  if (!deps.driver || typeof deps.driver.run !== "function") throw new Error("invalid_driver");
+  if (!deps.claimLedger || typeof deps.claimLedger.listClaims !== "function") throw new Error("invalid_claim_ledger");
+  if (!deps.eventLedger || typeof deps.eventLedger.appendEvent !== "function") throw new Error("invalid_event_ledger");
+  if (typeof deps.nowMs !== "number" || !Number.isFinite(deps.nowMs)) throw new Error("invalid_now_ms");
+}
+
+function assertInput(input) {
+  if (!input || typeof input !== "object") throw new Error("invalid_attempt_input");
+  if (!input.loopInput || typeof input.loopInput !== "object") throw new Error("invalid_loop_input");
+  if (!Number.isInteger(input.issueNumber) || input.issueNumber < 1) throw new Error("invalid_issue_number");
+  if (typeof input.minerLogin !== "string" || !input.minerLogin.trim()) throw new Error("invalid_miner_login");
+  if (typeof input.base !== "string" || !input.base.trim()) throw new Error("invalid_base");
+  if (!["global", "repo", "none"].includes(input.killSwitchScope)) throw new Error("invalid_kill_switch_scope");
+  if (!["clean", "low", "elevated", "high"].includes(input.slopThreshold)) throw new Error("invalid_slop_threshold");
+  if (!["observe", "enforce"].includes(input.submissionMode)) throw new Error("invalid_submission_mode");
+  if (!input.governor || typeof input.governor !== "object") throw new Error("invalid_governor_context");
+}
+
+/**
+ * Run one full attempt end to end: iterate-loop -> (on handoff) freshness -> submission-gate -> Governor
+ * chokepoint -> (on allowed:true) build + execute the real open_pr command. Fails closed (throws) on malformed
+ * input/deps, mirroring every sibling module in this pipeline.
+ *
+ * @param {{
+ *   loopInput: import("@loopover/engine").IterateLoopInput,
+ *   issueNumber: number,
+ *   minerLogin: string,
+ *   base: string,
+ *   killSwitchScope: "global"|"repo"|"none",
+ *   slopThreshold: "clean"|"low"|"elevated"|"high",
+ *   submissionMode: "observe"|"enforce",
+ *   maxConsecutiveGateBlocks?: number,
+ *   draft?: boolean,
+ *   governor: Omit<import("@loopover/engine").GovernorChokepointInput, "actionClass"|"repoFullName"|"nowMs"|"wouldBeAction">,
+ * }} input
+ * @param {{
+ *   driver: import("@loopover/engine").CodingAgentDriver,
+ *   runSlopAssessment: Function,
+ *   appendAttemptLogEvent: Function,
+ *   claimLedger: object,
+ *   fetchLiveIssueSnapshot: Function,
+ *   eventLedger: object,
+ *   governorLedgerAppend?: Function,
+ *   governorState?: import("./governor-state.js").GovernorState,
+ *   sessionStartMs?: number,
+ *   nowMs: number,
+ *   executeLocalWrite: (spec: import("@loopover/engine").LocalWriteActionSpec) => Promise<unknown>,
+ * }} deps
+ */
+export async function runMinerAttempt(input, deps) {
+  assertInput(input);
+  assertDeps(deps);
+
+  const loopResult = await runIterateLoop(input.loopInput, {
+    driver: deps.driver,
+    runSlopAssessment: deps.runSlopAssessment,
+    appendAttemptLogEvent: deps.appendAttemptLogEvent,
+  });
+
+  if (loopResult.outcome === "abandon") {
+    return { outcome: "abandon", loopResult };
+  }
+
+  const handoffPacket = loopResult.handoffPacket;
+
+  const freshness = await checkSubmissionFreshness(
+    { repoFullName: input.loopInput.repoFullName, issueNumber: input.issueNumber, minerLogin: input.minerLogin },
+    { claimLedger: deps.claimLedger, fetchLiveIssueSnapshot: deps.fetchLiveIssueSnapshot, eventLedger: deps.eventLedger },
+  );
+  if (!freshness.fresh) {
+    return { outcome: "stale", reason: freshness.reason, loopResult };
+  }
+
+  const submission = await prepareOpenPrSubmission(
+    {
+      killSwitchScope: input.killSwitchScope,
+      repoFullName: input.loopInput.repoFullName,
+      handoffPacket,
+      slopThreshold: input.slopThreshold,
+      mode: input.submissionMode,
+      maxConsecutiveGateBlocks: input.maxConsecutiveGateBlocks,
+      base: input.base,
+      title: input.loopInput.title,
+      body: input.loopInput.body ?? "",
+      draft: input.draft,
+    },
+    { eventLedger: deps.eventLedger, sessionStartMs: deps.sessionStartMs },
+  );
+  if (!submission.ready) {
+    return { outcome: "blocked", decision: submission.decision, loopResult };
+  }
+
+  const governed = evaluateGovernorChokepointGatePersisted(
+    {
+      actionClass: "open_pr",
+      repoFullName: input.loopInput.repoFullName,
+      nowMs: deps.nowMs,
+      wouldBeAction: submission.openPrInput,
+      ...input.governor,
+    },
+    {
+      ...(deps.governorLedgerAppend ? { append: deps.governorLedgerAppend } : {}),
+      ...(deps.governorState ? { governorState: deps.governorState } : {}),
+    },
+  );
+  if (!governed.decision.allowed) {
+    return { outcome: "governed", decision: governed.decision, loopResult };
+  }
+
+  const spec = buildOpenPrSpec(submission.openPrInput);
+  const execResult = await deps.executeLocalWrite(spec);
+  return { outcome: "submitted", spec, execResult, loopResult };
+}

package/lib/attempt-worktree.d.ts

@@ -0,0 +1,31 @@
+import type { WorktreeExecFn } from "@loopover/engine";
+import type { RunGitFn } from "./repo-clone.js";
+
+export function createRealWorktreeExec(timeoutMs?: number): WorktreeExecFn;
+
+export type PrepareAttemptWorktreeOptions = {
+  baseBranch?: string;
+  cloneBaseDir?: string;
+  env?: Record<string, string | undefined>;
+  exec?: WorktreeExecFn;
+  timeoutMs?: number;
+  remoteUrl?: string;
+  runGit?: RunGitFn;
+};
+
+export type PrepareAttemptWorktreeResult =
+  | { ok: true; worktreePath: string; branchName: string; repoPath: string }
+  | { ok: false; repoPath?: string; error: string };
+
+export function prepareAttemptWorktree(
+  repoFullName: string,
+  attemptId: string,
+  options?: PrepareAttemptWorktreeOptions,
+): Promise<PrepareAttemptWorktreeResult>;
+
+export function cleanupAttemptWorktree(
+  repoPath: string,
+  worktreePath: string,
+  attemptOk: boolean,
+  options?: { exec?: WorktreeExecFn; timeoutMs?: number },
+): Promise<{ ok: boolean; removed: boolean; error?: string }>;

package/lib/attempt-worktree.js

@@ -0,0 +1,94 @@
+import { spawn } from "node:child_process";
+import { addWorktree, removeWorktree, shouldRetainWorktree } from "@loopover/engine";
+import { ensureRepoCloned } from "./repo-clone.js";
+
+// Real attempt-worktree preparation (#5132, Wave 3.5 follow-up). Composes ensureRepoCloned (repo-clone.js,
+// the missing base-clone-management step) with @loopover/engine's already-built, already-tested
+// addWorktree/removeWorktree primitives -- which existed but were never called from this package, so
+// `workingDirectory` handed to runIterateLoop was always just an empty directory with no real git repo in
+// it. This is the caller that finally exercises them for real.
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * Real child_process-backed implementation of the engine's WorktreeExecFn contract. Resolves (never
+ * rejects) on error/timeout, mirroring coding-agent-construction.js's createRealCliSubprocessSpawn -- a
+ * failed `git worktree add`'s stderr is the diagnosable signal, not something to lose to an unhandled
+ * rejection.
+ *
+ * @returns {import("@loopover/engine").WorktreeExecFn}
+ */
+export function createRealWorktreeExec(timeoutMs = DEFAULT_TIMEOUT_MS) {
+  return (cmd, args, opts) =>
+    new Promise((resolve) => {
+      const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+      let stdout = "";
+      let stderr = "";
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        resolve({ code: null, stdout, stderr: `${stderr}\ntimed_out_after_${timeoutMs}ms`.trim() });
+      }, timeoutMs);
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString("utf8");
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+      });
+      child.on("error", (err) => {
+        clearTimeout(timer);
+        resolve({ code: null, stdout, stderr: err.message });
+      });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        resolve({ code, stdout, stderr });
+      });
+    });
+}
+
+/**
+ * Prepare a real, isolated git worktree for one attempt: ensure the target repo's base clone exists and is
+ * current, then create a fresh `git worktree` off it on a deterministically-named branch. Fails closed
+ * (`ok: false`) on any step's failure rather than handing back a half-prepared directory.
+ *
+ * @param {string} repoFullName
+ * @param {string} attemptId
+ * @param {{
+ *   baseBranch?: string, cloneBaseDir?: string, env?: Record<string, string | undefined>,
+ *   exec?: import("@loopover/engine").WorktreeExecFn, timeoutMs?: number,
+ *   remoteUrl?: string, runGit?: import("./repo-clone.js").RunGitFn,
+ * }} [options]
+ * @returns {Promise<{ ok: boolean, worktreePath?: string, branchName?: string, repoPath?: string, error?: string }>}
+ */
+export async function prepareAttemptWorktree(repoFullName, attemptId, options = {}) {
+  const cloneResult = await ensureRepoCloned(repoFullName, {
+    baseBranch: options.baseBranch,
+    cloneBaseDir: options.cloneBaseDir,
+    env: options.env,
+    timeoutMs: options.timeoutMs,
+    remoteUrl: options.remoteUrl,
+    runGit: options.runGit,
+  });
+  if (!cloneResult.ok) return { ok: false, error: cloneResult.error ?? "ensure_repo_cloned_failed" };
+
+  const exec = options.exec ?? createRealWorktreeExec(options.timeoutMs);
+  const baseBranch = typeof options.baseBranch === "string" && options.baseBranch.trim() ? options.baseBranch.trim() : "main";
+  const added = await addWorktree({ exec, repoPath: cloneResult.repoPath, baseBranch, attemptId });
+  if (!added.ok) return { ok: false, repoPath: cloneResult.repoPath, error: added.error ?? "git_worktree_add_failed" };
+
+  return { ok: true, worktreePath: added.plan.worktreePath, branchName: added.plan.branchName, repoPath: cloneResult.repoPath };
+}
+
+/**
+ * Tear down an attempt's worktree once the attempt concludes, per the engine's own retention policy: a
+ * failed attempt's worktree is RETAINED for post-mortem inspection, a succeeded one is removed.
+ *
+ * @param {string} repoPath
+ * @param {string} worktreePath
+ * @param {boolean} attemptOk
+ * @param {{ exec?: import("@loopover/engine").WorktreeExecFn, timeoutMs?: number }} [options]
+ * @returns {Promise<{ ok: boolean, removed: boolean, error?: string }>}
+ */
+export async function cleanupAttemptWorktree(repoPath, worktreePath, attemptOk, options = {}) {
+  const exec = options.exec ?? createRealWorktreeExec(options.timeoutMs);
+  return removeWorktree({ exec, repoPath, worktreePath, retain: shouldRetainWorktree(attemptOk) });
+}

package/lib/calibration-cli.d.ts

@@ -0,0 +1 @@
+export function runCalibrationCli(args?: string[], env?: Record<string, string | undefined>): number;