@loopover/miner 0.1.0

package/bin/gittensory-miner-mcp.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CLAIM_STATUSES, openClaimLedger } from "../lib/claim-ledger.js";
+import {
+  collectEventLedgerAuditFeed,
+  normalizeAuditFeedMcpFilter,
+} from "../lib/event-ledger-cli.js";
+import { initEventLedger } from "../lib/event-ledger.js";
+import { collectPortfolioDashboard } from "../lib/portfolio-dashboard.js";
+import { initPortfolioQueueStore } from "../lib/portfolio-queue.js";
+import { initRunStateStore } from "../lib/run-state.js";
+import { PLAN_STATUSES, openPlanStore } from "../lib/plan-store.js";
+import { initGovernorLedger } from "../lib/governor-ledger.js";
+import { collectStatus, runDoctorChecks } from "../lib/status.js";
+
+// MCP stdio server for @loopover/miner (scaffold #5153). Mirrors the packages/gittensory-mcp
+// harness (MCP SDK server + stdio transport). Tools:
+//   - gittensory_miner_ping (#5153): trivial static health check, reads no AMS state.
+//   - gittensory_miner_get_portfolio_dashboard (#5155): read-only per-repo backlog dashboard, wrapping the
+//     existing collectPortfolioDashboard aggregator (no new logic; same data as `queue dashboard --json`).
+//   - gittensory_miner_list_claims (#5156): read-only listing of the local claim ledger (optional repo/status
+//     filter passed through to listClaims); exposes no claim/release mutation.
+//   - gittensory_miner_get_audit_feed (#5158): read-only metadata-only event-ledger audit feed via
+//     collectEventLedgerAuditFeed() (same filters as `ledger list`; never returns payload_json).
+//   - gittensory_miner_get_run_state (#5160): read-only per-repo run-state via run-state.js's getRunState/
+//     listRunStates (read-only analog of ORB's gittensory_get_automation_state; no state-set mutation).
+//   - gittensory_miner_list_plans / gittensory_miner_get_plan (#5161): read-only access to the persisted
+//     plan store via plan-store.js's listPlans/loadPlan (distinct from ORB's stateless gittensory_plan_status).
+//   - gittensory_miner_get_governor_decisions (#5159): read-only governor decision-log projection via
+//     governor-ledger.js's readGovernorDecisions -- an explicit named-column read that excludes payload_json.
+//   - gittensory_miner_status (#5154): read-only status + doctor diagnostics via status.js's collectStatus/
+//     runDoctorChecks (names/booleans/paths only -- never any env-var value, token, key, or credential).
+
+// Read the version from this package's own package.json (always shipped) rather than a hand-synced
+// literal, so a release bump never has a second place to forget -- same approach as the mcp harness.
+const ownPackageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+/** Optional filters accepted by gittensory_miner_get_audit_feed (#5158). */
+const auditFeedInputSchema = {
+  repoFullName: z.string().min(1).optional(),
+  since: z.number().int().nonnegative().optional(),
+  type: z.string().min(1).optional(),
+};
+
+/** The static, non-secret payload the ping tool always returns, independent of any input or AMS state. */
+export const MINER_PING_STATUS = { status: "ok", tool: "gittensory_miner_ping" };
+
+/**
+ * Build the miner MCP server with its tools registered. `options.initPortfolioQueue`, `options.openClaimLedger`,
+ * `options.initEventLedger`, `options.initRunStateStore`, `options.openPlanStore`, `options.initGovernorLedger`,
+ * `options.collectStatus`, `options.runDoctorChecks`, and `options.nowMs` are injection seams for tests (default
+ * to the real stores/readers and the wall clock); the ping tool needs none. Each store-backed tool opens its
+ * store only when invoked and closes any store it opened.
+ */
+export function createMinerMcpServer(options = {}) {
+  const server = new McpServer({ name: "gittensory-miner", version: ownPackageJson.version });
+  server.registerTool(
+    "gittensory_miner_ping",
+    {
+      description:
+        "Health check for the gittensory-miner MCP server. Returns a static status object confirming the " +
+        "server is reachable. Reads no AMS state and takes no arguments.",
+      inputSchema: {},
+    },
+    async () => ({ content: [{ type: "text", text: JSON.stringify(MINER_PING_STATUS) }] }),
+  );
+  server.registerTool(
+    "gittensory_miner_get_portfolio_dashboard",
+    {
+      description:
+        "Read-only per-repo portfolio-queue backlog dashboard: status counts (queued/in_progress/done), totals, " +
+        "and the oldest-queued age in ms. Wraps the existing collectPortfolioDashboard aggregator (no new logic) " +
+        "-- the same data `gittensory-miner queue dashboard --json` prints locally. Takes no arguments; mutates nothing.",
+      inputSchema: {},
+    },
+    async () => {
+      const ownsQueue = options.initPortfolioQueue === undefined;
+      const portfolioQueue = (options.initPortfolioQueue ?? initPortfolioQueueStore)();
+      try {
+        const summary = collectPortfolioDashboard({ portfolioQueue }, { nowMs: options.nowMs ?? Date.now() });
+        return { content: [{ type: "text", text: JSON.stringify(summary) }] };
+      } finally {
+        if (ownsQueue) portfolioQueue.close();
+      }
+    },
+  );
+  server.registerTool(
+    "gittensory_miner_list_claims",
+    {
+      description:
+        "Read-only listing of the local claim ledger: which issues this miner has claimed (repo, issue number, " +
+        "status, claimed-at, note). Optional repoFullName/status filters pass through to the existing listClaims " +
+        "query. Exposes no claim/release mutation and no conflict-resolution logic.",
+      inputSchema: {
+        repoFullName: z.string().optional(),
+        status: z.enum(CLAIM_STATUSES).optional(),
+      },
+    },
+    async ({ repoFullName, status }) => {
+      const ownsLedger = options.openClaimLedger === undefined;
+      const ledger = (options.openClaimLedger ?? openClaimLedger)();
+      try {
+        const filter = {};
+        if (repoFullName !== undefined) filter.repoFullName = repoFullName;
+        if (status !== undefined) filter.status = status;
+        return { content: [{ type: "text", text: JSON.stringify(ledger.listClaims(filter)) }] };
+      } finally {
+        if (ownsLedger) ledger.close();
+      }
+    },
+  );
+  server.registerTool(
+    "gittensory_miner_get_audit_feed",
+    {
+      description:
+        "Read-only, metadata-only audit feed from the local append-only event ledger: eventType, repoFullName, " +
+        "outcome, actor, detail, and createdAt per row. Wraps collectEventLedgerAuditFeed() (no new query logic) — " +
+        "the same read filters as `gittensory-miner ledger list` (--repo, --since, --type). Never returns " +
+        "payload_json or other raw ledger columns; never writes to the ledger.",
+      inputSchema: auditFeedInputSchema,
+    },
+    async (input) => {
+      const ownsLedger = options.initEventLedger === undefined;
+      const eventLedger = (options.initEventLedger ?? initEventLedger)();
+      try {
+        const filter = normalizeAuditFeedMcpFilter(input ?? {});
+        const feed = collectEventLedgerAuditFeed(eventLedger, filter);
+        return { content: [{ type: "text", text: JSON.stringify(feed) }] };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+              }),
+            },
+          ],
+          isError: true,
+        };
+      } finally {
+        if (ownsLedger) eventLedger.close();
+      }
+    },
+  );
+  server.registerTool(
+    "gittensory_miner_get_run_state",
+    {
+      description:
+        "Read-only per-repo miner run-state (idle/discovering/planning/preparing). Pass repoFullName for a single " +
+        "repo (a null state means none has been recorded for it yet), or omit it to list every repo's state. The " +
+        "read-only analog of ORB's gittensory_get_automation_state; adds no state-set or mutation capability.",
+      inputSchema: {
+        repoFullName: z.string().min(1).optional(),
+      },
+    },
+    async ({ repoFullName }) => {
+      const ownsStore = options.initRunStateStore === undefined;
+      const store = (options.initRunStateStore ?? initRunStateStore)();
+      try {
+        const result =
+          repoFullName === undefined
+            ? { states: store.listRunStates() }
+            : { repoFullName, state: store.getRunState(repoFullName) };
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } finally {
+        if (ownsStore) store.close();
+      }
+    },
+  );
+  server.registerTool(
+    "gittensory_miner_list_plans",
+    {
+      description:
+        "Read-only list of the miner's PERSISTED plan store (planId, plan DAG, status, updatedAt), optionally " +
+        "filtered by status. Wraps plan-store.js's existing listPlans query -- no new logic, no mutation. NOTE: " +
+        "this is the store-backed AMS plan store; it is distinct from ORB's stateless gittensory_plan_status " +
+        "tool, which reads the caller's in-memory plan object rather than any persisted store.",
+      inputSchema: {
+        status: z.enum(PLAN_STATUSES).optional(),
+      },
+    },
+    async ({ status }) => {
+      const ownsStore = options.openPlanStore === undefined;
+      const store = (options.openPlanStore ?? openPlanStore)();
+      try {
+        const filter = {};
+        if (status !== undefined) filter.status = status;
+        return { content: [{ type: "text", text: JSON.stringify(store.listPlans(filter)) }] };
+      } finally {
+        if (ownsStore) store.close();
+      }
+    },
+  );
+  server.registerTool(
+    "gittensory_miner_get_plan",
+    {
+      description:
+        "Read-only fetch of one persisted plan record by planId (the full plan DAG, status, updatedAt), or an " +
+        "explicit { planId, found: false } for an unknown id. Wraps plan-store.js's existing loadPlan lookup -- " +
+        "no mutation, no DAG/planning logic. Store-backed AMS plan store; distinct from ORB's stateless " +
+        "gittensory_plan_status tool.",
+      inputSchema: {
+        planId: z.string().min(1),
+      },
+    },
+    async ({ planId }) => {
+      const ownsStore = options.openPlanStore === undefined;
+      const store = (options.openPlanStore ?? openPlanStore)();
+      try {
+        const plan = store.loadPlan(planId);
+        const result = plan === null ? { planId, found: false } : { found: true, plan };
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } finally {
+        if (ownsStore) store.close();
+      }
+    },
+  );
+  server.registerTool(
+    "gittensory_miner_get_governor_decisions",
+    {
+      description:
+        "Read-only projection of the governor decision log: id, ts, eventType, repoFullName, actionClass, " +
+        "decision, reason per row. This projection INTENTIONALLY EXCLUDES the internal/sensitive payload column " +
+        "(reputation / self-plagiarism / budget state) by construction -- governor-ledger.js reads it with an " +
+        "explicit named-column SELECT, never SELECT *. Optional repoFullName filter (the only filter the ledger " +
+        "supports natively). Read-only; never writes to the ledger.",
+      inputSchema: {
+        repoFullName: z.string().min(1).optional(),
+      },
+    },
+    async ({ repoFullName }) => {
+      const ownsLedger = options.initGovernorLedger === undefined;
+      const ledger = (options.initGovernorLedger ?? initGovernorLedger)();
+      try {
+        const filter = {};
+        if (repoFullName !== undefined) filter.repoFullName = repoFullName;
+        return { content: [{ type: "text", text: JSON.stringify(ledger.readGovernorDecisions(filter)) }] };
+      } finally {
+        if (ownsLedger) ledger.close();
+      }
+    },
+  );
+  server.registerTool(
+    "gittensory_miner_status",
+    {
+      description:
+        "Read-only miner status + doctor diagnostics. Returns { status, doctor }: status = package/engine versions " +
+        "(+ skew), node version, state-dir path, config-file path, and the resolved coding-agent driver (provider " +
+        "name, the model ENV-VAR NAME -- never its value -- and a CLI-present boolean); doctor = the same checks " +
+        "`gittensory-miner doctor` runs (Docker/CLI presence, config validity, ...) as { name, ok, detail }. Reuses " +
+        "collectStatus/runDoctorChecks so it can never drift from the CLI. Only names / booleans / paths -- never " +
+        "any env-var value, token, key, or credential. Read-only; no writes or state changes.",
+      inputSchema: {},
+    },
+    async () => {
+      const status = (options.collectStatus ?? collectStatus)();
+      const doctor = (options.runDoctorChecks ?? runDoctorChecks)();
+      return { content: [{ type: "text", text: JSON.stringify({ status, doctor }) }] };
+    },
+  );
+  return server;
+}
+
+// Start the stdio transport only when executed directly as the bin, not when imported by a test.
+// realpathSync on both sides resolves the npm bin symlink so a global/npx install still matches.
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : "";
+if (invokedPath && invokedPath === realpathSync(fileURLToPath(import.meta.url))) {
+  createMinerMcpServer()
+    .connect(new StdioServerTransport())
+    .catch((error) => {
+      console.error(error);
+      process.exit(1);
+    });
+}

package/bin/gittensory-miner.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { runAttempt } from "../lib/attempt-cli.js";
+import { printHelp, printVersion, runCli } from "../lib/cli.js";
+import { configureLogger, extractLogOptions } from "../lib/logger.js";
+import { runDenyCheck } from "../lib/deny-check.js";
+import { runDiscover } from "../lib/discover-cli.js";
+import { runFeasibilityCli } from "../lib/feasibility-cli.js";
+import { runGovernorCli } from "../lib/governor-ledger-cli.js";
+import { runLedgerCli } from "../lib/event-ledger-cli.js";
+import { runCalibrationCli } from "../lib/calibration-cli.js";
+import { runLoop } from "../lib/loop-cli.js";
+import { runManagePoll } from "../lib/manage-poll.js";
+import { runManageStatus } from "../lib/manage-status.js";
+import { runMetrics } from "../lib/metrics-cli.js";
+import { runPlanCli } from "../lib/plan-store-cli.js";
+import { runClaimCli } from "../lib/claim-ledger-cli.js";
+import { runPurge } from "../lib/purge-cli.js";
+import { runQueueCli } from "../lib/portfolio-queue-cli.js";
+import { runOrbExportCli } from "../lib/orb-export.js";
+import { installCliSignalHandlers } from "../lib/process-lifecycle.js";
+import { runStateCli } from "../lib/run-state-cli.js";
+import { runInit } from "../lib/laptop-init.js";
+import { loadMinerFileSecrets } from "../lib/env-file-indirection.js";
+import { runMigrate } from "../lib/migrate-cli.js";
+import { runDoctor, runStatus } from "../lib/status.js";
+import {
+  awaitOpportunisticUpdateCheck,
+  resolveUpgradeCommand,
+  startUpdateCheck,
+} from "../lib/update-check.js";
+import { resolveMinerVersion } from "../lib/version.js";
+
+// Resolve any `<NAME>_FILE` secret-mount vars (GITHUB_TOKEN_FILE, etc.) into their plain counterparts FIRST,
+// before anything else reads process.env -- every subcommand below (and the coding-agent driver construction
+// deeper in the call graph) reads plain env vars, so this single early pass is all that's needed for the whole
+// CLI (#5178). A broken secret mount fails the process fast and loud with a clear message, instead of an
+// uncaught-exception stack trace or a silent empty credential surfacing as a confusing GitHub 401 later.
+try {
+  loadMinerFileSecrets();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+// Register signal + crash handlers once, before any command runs, so an interrupted run closes its open ledgers
+// cleanly instead of dying mid-write (#4826). Covers every subcommand below, including the local ones.
+installCliSignalHandlers();
+
+// Peel the global logging flags (--quiet/--verbose/--log-level) off the front of argv and configure the
+// process-wide logger once (#4835), so every command below shares one level-aware logger without re-parsing
+// them; the stripped `cliArgs` is what the command dispatch sees.
+const { options: logOptions, rest: cliArgs } = extractLogOptions(process.argv.slice(2));
+configureLogger({ ...logOptions, env: process.env });
+
+// `status` and `doctor` are strictly local, offline commands — their contract is to make NO network calls.
+// `init` stays local by default and only makes a network call when the operator explicitly passes
+// `--verify-token`.
+// Dispatch the local commands BEFORE the opportunistic npm-registry update check is even started, so they can
+// never reach that network path (the update check runs for the remaining commands below).
+if (cliArgs[0] === "init") {
+  process.exit(await runInit(cliArgs.slice(1)));
+}
+
+if (cliArgs[0] === "status") {
+  process.exit(runStatus(cliArgs.slice(1)));
+}
+
+if (cliArgs[0] === "doctor") {
+  process.exit(runDoctor(cliArgs.slice(1)));
+}
+
+// `migrate` is strictly local + offline like `status`/`doctor` (it only opens the local SQLite stores), so it is
+// dispatched here too, before the opportunistic npm-registry update check is ever started.
+if (cliArgs[0] === "migrate") {
+  process.exit(runMigrate(cliArgs.slice(1)));
+}
+
+// `metrics` is strictly local + offline like `status`/`doctor` (it reads only the local prediction ledger), so it
+// is dispatched here, before the opportunistic npm-registry update check is ever started.
+if (cliArgs[0] === "metrics") {
+  process.exit(runMetrics(cliArgs.slice(1)));
+}
+
+if (cliArgs[0] === "manage" && cliArgs[1] === "status") {
+  process.exit(runManageStatus(cliArgs.slice(2)));
+}
+
+if (cliArgs[0] === "queue") {
+  process.exit(runQueueCli(cliArgs[1], cliArgs.slice(2)));
+}
+
+if (cliArgs[0] === "orb" && cliArgs[1] === "export") {
+  process.exit(runOrbExportCli(cliArgs.slice(2)));
+}
+
+if (cliArgs[0] === "claim") {
+  process.exit(runClaimCli(cliArgs[1], cliArgs.slice(2)));
+}
+
+if (cliArgs[0] === "ledger") {
+  process.exit(runLedgerCli(cliArgs[1], cliArgs.slice(2)));
+}
+
+if (cliArgs[0] === "calibration") {
+  process.exit(runCalibrationCli(cliArgs.slice(1)));
+}
+
+if (cliArgs[0] === "plan") {
+  process.exit(runPlanCli(cliArgs[1], cliArgs.slice(2)));
+}
+
+if (cliArgs[0] === "governor") {
+  process.exit(await runGovernorCli(cliArgs[1], cliArgs.slice(2)));
+}
+
+if (cliArgs[0] === "feasibility") {
+  process.exit(runFeasibilityCli(cliArgs.slice(1)));
+}
+
+// `purge` (#5564) is strictly local + offline like `queue`/`claim`/`governor` above -- it only opens the local
+// SQLite stores, so it is dispatched here too, before the opportunistic npm-registry update check ever starts.
+if (cliArgs[0] === "purge") {
+  process.exit(runPurge(cliArgs.slice(1)));
+}
+
+const packageName = "@loopover/miner";
+const packageVersion = resolveMinerVersion(process.env);
+const upgradeCommand = resolveUpgradeCommand(packageName);
+
+const updateCheck = startUpdateCheck(cliArgs, {
+  packageName,
+  packageVersion,
+  upgradeCommand,
+  env: process.env,
+});
+
+if (
+  cliArgs.length === 0 ||
+  cliArgs.includes("--help") ||
+  cliArgs.includes("-h") ||
+  cliArgs[0] === "help"
+) {
+  printHelp({ packageName });
+  await awaitOpportunisticUpdateCheck(updateCheck);
+  process.exit(0);
+}
+
+if (
+  cliArgs.includes("--version") ||
+  cliArgs.includes("-v") ||
+  cliArgs[0] === "version"
+) {
+  printVersion({ packageName, packageVersion });
+  await awaitOpportunisticUpdateCheck(updateCheck);
+  process.exit(0);
+}
+
+if (cliArgs[0] === "hooks" && cliArgs[1] === "check") {
+  const exitCode = runDenyCheck(cliArgs.slice(2));
+  await awaitOpportunisticUpdateCheck(updateCheck);
+  process.exit(exitCode);
+}
+
+if (cliArgs[0] === "state") {
+  const exitCode = runStateCli(cliArgs[1], cliArgs.slice(2));
+  await awaitOpportunisticUpdateCheck(updateCheck);
+  process.exit(exitCode);
+}
+
+if (cliArgs[0] === "manage" && cliArgs[1] === "poll") {
+  const exitCode = await runManagePoll(cliArgs.slice(2));
+  await awaitOpportunisticUpdateCheck(updateCheck);
+  process.exit(exitCode);
+}
+
+if (cliArgs[0] === "discover") {
+  const exitCode = await runDiscover(cliArgs.slice(1));
+  await awaitOpportunisticUpdateCheck(updateCheck);
+  process.exit(exitCode);
+}
+
+if (cliArgs[0] === "attempt") {
+  const exitCode = await runAttempt(cliArgs.slice(1));
+  await awaitOpportunisticUpdateCheck(updateCheck);
+  process.exit(exitCode);
+}
+
+if (cliArgs[0] === "loop") {
+  const exitCode = await runLoop(cliArgs.slice(1));
+  await awaitOpportunisticUpdateCheck(updateCheck);
+  process.exit(exitCode);
+}
+
+const exitCode = runCli(cliArgs, { packageName });
+await awaitOpportunisticUpdateCheck(updateCheck);
+process.exit(exitCode);

package/docs/coding-agent-driver.md

@@ -0,0 +1,140 @@
+# CodingAgentDriver — the miner's coding-agent seam
+
+`CodingAgentDriver` is the single interface a Gittensory miner runs a coding agent through. It lets the miner drive
+**either** a local CLI subprocess (e.g. `claude` / `codex`) **or** an in-process Agent SDK `query()` loop behind one
+provider-agnostic contract, so the rest of the miner — planning, attempt logging, metering, gate polling — never
+has to know which backend actually did the work.
+
+The interface itself lives in `@loopover/engine`
+([`packages/gittensory-engine/src/miner/coding-agent-driver.ts`](../../gittensory-engine/src/miner/coding-agent-driver.ts));
+the orchestration around it (mode gating, invocation, the factory) lives in the sibling modules described below.
+
+> **See also:** [Observing your miner](observability.md) — point Grafana at the miner's local SQLite ledgers
+> (attempt log, prediction ledger) to see what the driver actually did.
+
+## Why a seam, and why this shape
+
+The design deliberately mirrors the review stack's `SelfHostAi` (`src/selfhost/ai.ts`) rather than inventing a new
+pattern: a single `run()` method, provider-agnostic task/result types, and **injected dependencies** (spawn fn,
+clock, filesystem) on the concrete implementations rather than hardcoded globals. That injection is what keeps every
+driver unit-testable without real IO — the same reason `SelfHostAi` takes an injected `SpawnFn`.
+
+The interface defines only the contract. Implementations MAY perform real IO; they never make GitHub writes or
+autonomous continue/stop decisions — the task handed to a driver is already scoped.
+
+## The contract
+
+```ts
+type CodingAgentDriverTask = {
+  attemptId: string; // stable id for this attempt (keys the attempt log)
+  workingDirectory: string; // the ONLY directory a driver may edit (see worktree isolation below)
+  acceptanceCriteriaPath: string; // path to the immutable acceptance-criteria file written before the run
+  instructions: string; // the metadata-only prompt (no source contents)
+  maxTurns: number; // hard cap on agent iterations for this attempt
+};
+
+type CodingAgentDriverResult = {
+  ok: boolean;
+  changedFiles: readonly string[];
+  summary: string;
+  transcript?: string; // opaque provider transcript for operator inspection
+  turnsUsed?: number;
+  error?: string;
+};
+
+interface CodingAgentDriver {
+  run(task: CodingAgentDriverTask): Promise<CodingAgentDriverResult>;
+}
+```
+
+Two reference implementations ship today for tests: `createFakeCodingAgentDriver` (records the last task, no IO) and
+`createNoopCodingAgentDriver` (default-OFF stub). The two real backends — a CLI-subprocess driver (#4266) and an
+Agent-SDK driver (#4267) — register in `createCodingAgentDriver` as `claude-cli`, `codex-cli`, and `agent-sdk`
+(`CODING_AGENT_DRIVER_NAMES`: `["noop", "claude-cli", "codex-cli", "agent-sdk"]`).
+
+## The surrounding primitives
+
+A driver never runs in isolation. The neighborhood it plugs into:
+
+| Concern             | Module                        | What it provides                                                                                                                                                                                                                                                                                                                               |
+| ------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Execution mode      | `coding-agent-mode.ts`        | `paused` / `dry_run` / `live` with deny-toward-safety precedence; `codingAgentModeExecutes(mode)` is the single "should this attempt actually spawn?" boolean. A `dry_run` is a pure no-op at the driver boundary.                                                                                                                             |
+| Invocation          | `coding-agent-invoke.ts`      | `invokeCodingAgentDriver(driver, task, mode?, log?)` — gates on the mode, calls `driver.run`, and streams lifecycle events to an `AttemptLogSink`.                                                                                                                                                                                             |
+| Factory             | `driver-factory.ts`           | `createCodingAgentDriver(options)` resolves a driver by configured name; `resolveConfiguredCodingAgentDriverNames` / `isConfiguredCodingAgentDriver` deny unknown names by default; `runCodingAgentAttempt(options)` is the top-level "resolve + invoke" convenience.                                                                          |
+| Attempt log         | `attempt-log.ts` (#4294)      | `ATTEMPT_LOG_EVENT_TYPES` + `normalizeAttemptLogEvent` + `createAttemptLogBuffer` + `formatAttemptLogJsonl` — an append-only, JSONL-exportable event trace per attempt, independent of any driver's own transcript. Durable persistence: `packages/gittensory-miner/lib/attempt-log.js` (sibling SQLite store; imports the engine normalizer). |
+| Metering            | `attempt-metering.ts` (#4311) | `accumulateAttemptUsage` / `meterAttemptUsage` / `evaluateAttemptBudget` over `AttemptBudgetAxis` (`tokens` / `turns` / `wallClockMs` / `costUsd`).                                                                                                                                                                                            |
+| Acceptance criteria | (#4271)                       | The immutable criteria file at `task.acceptanceCriteriaPath`, written before the driver starts.                                                                                                                                                                                                                                                |
+| Worktree isolation  | (#4269)                       | Each attempt's `task.workingDirectory` is a dedicated git worktree; a driver must never edit outside it.                                                                                                                                                                                                                                       |
+
+## Authoring a third driver
+
+To add a driver beyond the CLI-subprocess and Agent-SDK backends:
+
+1. **Implement the interface.** Export a `create<Name>CodingAgentDriver(deps)` factory returning a `CodingAgentDriver`.
+   Take every side-effecting dependency (spawn fn, `query()` client, clock, fs) as an **injected argument** — do not
+   reach for globals — so the contract suite can drive it with fakes (mirrors `SpawnFn` injection in `SelfHostAi`).
+2. **Honor the task scoping.** Only edit inside `task.workingDirectory`; stop at `task.maxTurns`; read the acceptance
+   criteria from `task.acceptanceCriteriaPath`; never make a GitHub write.
+3. **Return the result shape faithfully.** Set `ok` from whether acceptance was met, list `changedFiles`, and surface
+   failures via `error` (a clean failure) rather than throwing — the invoker records either outcome.
+4. **Register it in the factory.** Add the name to `CODING_AGENT_DRIVER_NAMES` and wire `createCodingAgentDriver`, so
+   `resolveConfiguredCodingAgentDriverNames` can select it from config (unknown names stay denied by default).
+5. **Get covered by the parity/contract suite** (#4296): the suite runs the same scenario fixtures — a clean success,
+   a clean failure, a budget/timeout, and a malformed acceptance-criteria input — against every driver with an
+   injected backend, asserting identical SHAPE and edge-case handling (not identical output, which is inherently
+   non-deterministic across backends).
+
+## A worked attempt lifecycle (the real production path)
+
+`runCodingAgentAttempt`/`invokeCodingAgentDriver` (driver-factory.ts/coding-agent-invoke.ts) are real, tested,
+and remain available as a lower-level composable, but **production does not call either of them today**. The
+real construction + invocation path, as actually wired into `packages/gittensory-miner`, is:
+
+```
+constructProductionCodingAgentDriver(env)        (packages/gittensory-miner/lib/coding-agent-construction.js)
+  └─ createCodingAgentDriver({ providerName, spawn, ... })   (driver-factory.ts) → the configured CodingAgentDriver
+       │  (house-rule hooks attached by default for agent-sdk via buildHouseRulesAgentSdkHooks -- see below)
+       └─ becomes IterateLoopDeps.driver, handed to runIterateLoop (iterate-loop.ts)
+
+runIterateLoop(input, deps)                       (packages/gittensory-engine/src/miner/iterate-loop.ts)
+  └─ per iteration, runDriverSafely(input, deps, task):
+       ├─ if !codingAgentModeExecutes(input.mode):  → invokeCodingAgentDriver(deps.driver, mode, task, {...})
+       │     (paused/dry_run only -- records a shadow/no-op attempt-log event, never spawns the real driver)
+       └─ else (live):                              → deps.driver.run(task) directly, NOT via invokeCodingAgentDriver
+              → edits inside task.workingDirectory only, ≤ task.maxTurns
+       ├─ evaluateSelfReviewOutcome(...) → self-review the resulting diff
+       ├─ decideNextActionWithReason(state) → continue | handoff | abandon
+       └─ logDecision(...) records ONE attempt-log event per iteration (continue/handoff/abandon), not a
+              raw driver-start/succeed/fail pair the way invokeCodingAgentDriver's own wrapper would
+```
+
+The attempt log (JSONL) is the durable, provider-independent record of what happened, independent of whichever
+backend's own transcript, and the input to the miner's manage-phase and self-improve loops.
+
+`packages/gittensory-miner/lib/coding-agent-house-rules.js`'s `runHouseRulesEnforcedCodingAgentAttempt` (a
+drop-in wrapper over `runCodingAgentAttempt`) exists for a caller that wants the alternate, non-iterate-loop
+path with house-rule enforcement built in by default -- no such caller exists in production today either; the
+real house-rule enforcement for the live `agent-sdk` provider happens via `buildHouseRulesAgentSdkHooks`,
+attached directly in `constructProductionCodingAgentDriver`.
+
+**Metering:** `attempt-metering.ts`'s `accumulateAttemptUsage`/`evaluateAttemptBudget` are wired into
+`iterate-loop.ts` for real ([#5395](https://github.com/JSONbored/gittensory/issues/5395)) -- every iteration
+accumulates real `turns`/`costUsd`/`wallClockMs` (`tokens` stays an honest 0; no driver reports a real
+per-iteration token count today) into a running `AttemptMeterTotals`, and `runIterateLoop`'s optional
+`input.budget: AttemptBudget` is evaluated against it each iteration via the SAME `costCeilingReached` signal
+`iterate-policy.ts` already exposed for the (now-removed) turns-only `maxTotalTurns` ceiling -- a genuine
+mid-attempt abort, not just a between-cycle cap. `packages/gittensory-miner/lib/attempt-input-builder.js`'s
+`buildAttemptLoopInput` sets `budget` from the SAME `AmsPolicySpec.capLimits` the Governor's cross-cycle
+`GovernorCapUsage` already uses (`packages/gittensory-miner/lib/loop-cli.js`'s `governorState.saveCapUsage`
+between loop cycles) -- one attempt can no longer burn through the entire cross-cycle budget before anything
+reacts. `wallClockMs` uses a real injected clock (`IterateLoopDeps.nowMs`, defaulting to `Date.now`) measured
+around each iteration's driver invocation. The result's `finalMeterTotals`/`budgetBreaches` fields surface
+which axis (if any) triggered an abandon, for an operator reading the attempt log back.
+
+## Related docs
+
+- [`operations-runbook.md`](operations-runbook.md) — SQLite `busy_timeout` concurrency, corruption recovery, multi-process collisions, post-upgrade migration ([#4875](https://github.com/JSONbored/gittensory/issues/4875)).
+- [`env-reference.md`](env-reference.md) — env vars including ledger path overrides.
+- [`../DEPLOYMENT.md`](../DEPLOYMENT.md) — laptop vs fleet deployment and state directory layout.
+- [`miner-goal-spec.md`](miner-goal-spec.md) — per-repo `.gittensory-miner.yml` targeting policy.
+- [`../README.md#mcp-server`](../README.md#mcp-server) — the `gittensory-miner-mcp` read-only tool surface for querying this driver's resolved status (provider, model env-var name, CLI presence) and the rest of AMS's local state over MCP.