@loopover/miner 0.1.0

package/lib/claim-ledger.js

@@ -0,0 +1,303 @@
+import { DatabaseSync } from "node:sqlite";
+import { DEFAULT_FORGE_CONFIG } from "./forge-config.js";
+import { normalizeLocalStoreDbPath, openLocalStoreDb, resolveLocalStoreDbPath } from "./local-store.js";
+import { applySchemaMigrations } from "./schema-version.js";
+import { CLAIM_LEDGER_PURGE_SPEC, purgeStoreByRepo } from "./store-maintenance.js";
+
+// The miner's local soft-claim ledger (#2314): a 100% client-side record of "I'm working on issue #N in repo X",
+// so Phase 2's soft-claim adjudication (sibling issues) has somewhere to persist claims. Schema + CRUD only — no
+// adjudication logic, no network calls, no autonomous writes. The database only lives on this machine; this module
+// never uploads, syncs, or phones home. Mirrors the package's existing local-store pattern (run-state.js,
+// portfolio-queue.js, event-ledger.js) — plain JS + node:sqlite, not the hosted Worker's shared D1 `migrations/`.
+
+export const CLAIM_STATUSES = Object.freeze(["active", "released", "expired"]);
+
+const defaultDbFileName = "claim-ledger.sqlite3";
+let defaultClaimLedger = null;
+
+export function resolveClaimLedgerDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_CLAIM_LEDGER_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolveClaimLedgerDbPath(), "invalid_claim_ledger_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}`;
+}
+
+function normalizeIssueNumber(issueNumber) {
+  if (!Number.isInteger(issueNumber) || issueNumber < 1) throw new Error("invalid_issue_number");
+  return issueNumber;
+}
+
+/** 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();
+}
+
+/** Optional free-text note: omitted/nullish → null; a string is kept as-is; anything else is rejected. */
+function normalizeNote(note) {
+  if (note === undefined || note === null) return null;
+  if (typeof note !== "string") throw new Error("invalid_note");
+  return note;
+}
+
+function rowToClaim(row) {
+  return {
+    id: row.id,
+    apiBaseUrl: row.api_base_url,
+    repoFullName: row.repo_full_name,
+    issueNumber: row.issue_number,
+    claimedAt: row.claimed_at,
+    status: row.status,
+    note: row.note,
+  };
+}
+
+// v1 -> v2 (#5563): scope the UNIQUE constraint by (api_base_url, repo_full_name, issue_number) instead of bare
+// (repo_full_name, issue_number) -- two different forge hosts serving a same-named repo/issue must not collide
+// in this ledger. SQLite cannot ALTER a UNIQUE constraint 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. Runs inside applySchemaMigrations' own transaction, so a mid-rebuild failure
+// leaves the file at v1 and retries cleanly on next open.
+function addApiBaseUrlScope(db) {
+  db.exec(`
+    CREATE TABLE miner_claims_v2 (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      api_base_url TEXT NOT NULL,
+      repo_full_name TEXT NOT NULL,
+      issue_number INTEGER NOT NULL,
+      claimed_at TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'released', 'expired')),
+      note TEXT,
+      UNIQUE (api_base_url, repo_full_name, issue_number)
+    )
+  `);
+  // OR IGNORE: a row this store's own read path already treats as unusable garbage (an unrecognized `status`,
+  // e.g. from a hand-edited or otherwise corrupted file) would violate the CHECK constraint above and abort the
+  // whole migration. Skipping it here is consistent with that same fail-closed posture, rather than turning one
+  // bad row into a permanently unmigratable file.
+  db.prepare(
+    `INSERT OR IGNORE INTO miner_claims_v2 (id, api_base_url, repo_full_name, issue_number, claimed_at, status, note)
+     SELECT id, ?, repo_full_name, issue_number, claimed_at, status, note FROM miner_claims`,
+  ).run(DEFAULT_FORGE_CONFIG.apiBaseUrl);
+  db.exec("DROP TABLE miner_claims");
+  db.exec("ALTER TABLE miner_claims_v2 RENAME TO miner_claims");
+}
+
+/**
+ * Opens the local claim ledger, creating the table on first use. `UNIQUE(api_base_url, repo_full_name,
+ * issue_number)` keeps ONE row per claimed issue per forge host, and `recordClaim` is a single atomic
+ * INSERT…ON CONFLICT statement (no read-then-write), so concurrent claims cannot duplicate a row. (#2314, #5563)
+ */
+export function openClaimLedger(dbPath = resolveClaimLedgerDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  const db = openLocalStoreDb(resolvedPath);
+  // LOCAL bookkeeping only: this table records which issues this miner instance has soft-claimed on this
+  // machine. It does NOT adjudicate contested duplicates — sibling miners claiming the same issue are
+  // resolved elsewhere via `isDuplicateClusterWinnerByClaim` from `@loopover/engine` (#3355).
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS miner_claims (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      repo_full_name TEXT NOT NULL,
+      issue_number INTEGER NOT NULL,
+      claimed_at TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'released', 'expired')),
+      note TEXT,
+      UNIQUE (repo_full_name, issue_number)
+    )
+  `);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations.
+  applySchemaMigrations(db, [addApiBaseUrlScope]);
+
+  // Idempotent claim in ONE atomic statement: insert a new active claim, or — only if the existing row is NOT
+  // already active — re-activate it (a released/expired claim can be re-claimed). The `WHERE status <> 'active'`
+  // guard makes re-claiming an already-active issue a true no-op (no row churn), never a duplicate row.
+  const recordStatement = db.prepare(`
+    INSERT INTO miner_claims (api_base_url, repo_full_name, issue_number, claimed_at, status, note)
+    VALUES (?, ?, ?, ?, 'active', ?)
+    ON CONFLICT(api_base_url, repo_full_name, issue_number) DO UPDATE SET
+      claimed_at = excluded.claimed_at,
+      note = excluded.note,
+      status = 'active'
+    WHERE miner_claims.status <> 'active'
+  `);
+  const getStatement = db.prepare(
+    "SELECT * FROM miner_claims WHERE api_base_url = ? AND repo_full_name = ? AND issue_number = ?",
+  );
+  // RETURNING (matching portfolio-queue.js's own claim/release statements) makes the "nothing to release/expire"
+  // case observable directly from ONE atomic statement, rather than a separate post-UPDATE SELECT whose "row
+  // went missing" branch would be structurally unreachable (nothing else runs between the UPDATE and a SELECT
+  // on the same key within one synchronous call).
+  const releaseStatement = db.prepare(
+    "UPDATE miner_claims SET status = 'released' WHERE api_base_url = ? AND repo_full_name = ? AND issue_number = ? AND status = 'active' RETURNING *",
+  );
+  const expireStatement = db.prepare(
+    "UPDATE miner_claims SET status = 'expired' WHERE api_base_url = ? AND repo_full_name = ? AND issue_number = ? AND status = 'active' RETURNING *",
+  );
+  const listAllStatement = db.prepare("SELECT * FROM miner_claims ORDER BY id ASC");
+  const listRepoStatement = db.prepare(
+    "SELECT * FROM miner_claims WHERE repo_full_name = ? ORDER BY id ASC",
+  );
+  const listStatusStatement = db.prepare(
+    "SELECT * FROM miner_claims WHERE status = ? ORDER BY id ASC",
+  );
+  const listRepoStatusStatement = db.prepare(
+    "SELECT * FROM miner_claims WHERE repo_full_name = ? AND status = ? ORDER BY id ASC",
+  );
+
+  function normalizeListRepoFilter(repoFullName) {
+    if (repoFullName === undefined || repoFullName === null) return undefined;
+    return normalizeRepoFullName(repoFullName);
+  }
+
+  function normalizeStatusFilter(status) {
+    if (status === undefined || status === null) return undefined;
+    if (!CLAIM_STATUSES.includes(status)) throw new Error("invalid_status");
+    return status;
+  }
+
+  const ledger = {
+    dbPath: resolvedPath,
+    recordClaim(claim) {
+      const apiBaseUrl = normalizeApiBaseUrl(claim?.apiBaseUrl);
+      const repoFullName = normalizeRepoFullName(claim?.repoFullName);
+      const issueNumber = normalizeIssueNumber(claim?.issueNumber);
+      const note = normalizeNote(claim?.note);
+      const claimedAt = new Date().toISOString();
+      recordStatement.run(apiBaseUrl, repoFullName, issueNumber, claimedAt, note);
+      return rowToClaim(getStatement.get(apiBaseUrl, repoFullName, issueNumber));
+    },
+    releaseClaim(repoFullName, issueNumber, apiBaseUrl) {
+      const normalizedForge = normalizeApiBaseUrl(apiBaseUrl);
+      const normalizedRepo = normalizeRepoFullName(repoFullName);
+      const normalizedIssue = normalizeIssueNumber(issueNumber);
+      const row = releaseStatement.get(normalizedForge, normalizedRepo, normalizedIssue);
+      return row ? rowToClaim(row) : null;
+    },
+    expireClaim(repoFullName, issueNumber, apiBaseUrl) {
+      const normalizedForge = normalizeApiBaseUrl(apiBaseUrl);
+      const normalizedRepo = normalizeRepoFullName(repoFullName);
+      const normalizedIssue = normalizeIssueNumber(issueNumber);
+      const row = expireStatement.get(normalizedForge, normalizedRepo, normalizedIssue);
+      return row ? rowToClaim(row) : null;
+    },
+    listClaims(filter = {}) {
+      const repoFullName = normalizeListRepoFilter(filter.repoFullName);
+      const status = normalizeStatusFilter(filter.status);
+
+      let rows;
+      if (repoFullName !== undefined && status !== undefined) {
+        rows = listRepoStatusStatement.all(repoFullName, status);
+      } else if (repoFullName !== undefined) {
+        rows = listRepoStatement.all(repoFullName);
+      } else if (status !== undefined) {
+        rows = listStatusStatement.all(status);
+      } else {
+        rows = listAllStatement.all();
+      }
+      return rows.map(rowToClaim);
+    },
+    claimIssue(repoFullName, issueNumber, note, apiBaseUrl) {
+      return ledger.recordClaim({ repoFullName, issueNumber, note, apiBaseUrl });
+    },
+    listActiveClaims(repoFullName) {
+      const filter = { status: "active" };
+      if (repoFullName !== undefined) filter.repoFullName = repoFullName;
+      return ledger.listClaims(filter);
+    },
+    // Explicit, operator-invoked right-to-be-forgotten purge (#5564) — never runs automatically. Distinct from
+    // this store's normal claim/release/expire lifecycle: deletes every row for a repo outright.
+    purgeByRepo(repoFullName) {
+      return purgeStoreByRepo(db, CLAIM_LEDGER_PURGE_SPEC, normalizeRepoFullName(repoFullName));
+    },
+    close() {
+      db.close();
+    },
+  };
+  return ledger;
+}
+
+/**
+ * Strictly read-only ledger access for advisory-only callers (#5157) that must never write anything --
+ * not even the schema-creation DDL and schema-version stamp {@link openClaimLedger} always runs on open.
+ * Opens the DB file in SQLite's own `readonly` mode (driver-enforced: an attempted write throws, this isn't
+ * just a by-convention guarantee) and touches the filesystem in no other way -- no `mkdirSync`/`chmodSync`,
+ * no `CREATE TABLE IF NOT EXISTS`, no migrations. The caller MUST only call this against a path it has
+ * already confirmed exists (e.g. via `existsSync`); a read-only connection to a nonexistent file throws.
+ * Throws if the expected table is missing too (a file exists at this path but isn't a real claim ledger) --
+ * callers should treat that identically to any other open/query failure.
+ */
+export function openClaimLedgerReadOnly(dbPath) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  // `readOnly` (camelCase) -- node:sqlite silently IGNORES `readonly` (lowercase) as an unrecognized option
+  // and opens read-write anyway, defeating the entire point of this function. Verified empirically: a write
+  // via a `{ readonly: true }` connection succeeds with no error.
+  const db = new DatabaseSync(resolvedPath, { readOnly: true });
+  let listActiveStatement;
+  try {
+    listActiveStatement = db.prepare(
+      "SELECT * FROM miner_claims WHERE repo_full_name = ? AND status = 'active' ORDER BY id ASC",
+    );
+  } catch (error) {
+    // The table doesn't exist (a file exists at this path but isn't a real claim ledger) -- close the
+    // connection we already opened before rethrowing, so this never leaks a file handle.
+    db.close();
+    throw error;
+  }
+  return {
+    dbPath: resolvedPath,
+    listActiveClaims(repoFullName) {
+      const normalizedRepo = normalizeRepoFullName(repoFullName);
+      return listActiveStatement.all(normalizedRepo).map(rowToClaim);
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+function getDefaultClaimLedger() {
+  defaultClaimLedger ??= openClaimLedger();
+  return defaultClaimLedger;
+}
+
+export function recordClaim(claim) {
+  return getDefaultClaimLedger().recordClaim(claim);
+}
+
+export function releaseClaim(repoFullName, issueNumber, apiBaseUrl) {
+  return getDefaultClaimLedger().releaseClaim(repoFullName, issueNumber, apiBaseUrl);
+}
+
+export function expireClaim(repoFullName, issueNumber, apiBaseUrl) {
+  return getDefaultClaimLedger().expireClaim(repoFullName, issueNumber, apiBaseUrl);
+}
+
+export function listClaims(filter) {
+  return getDefaultClaimLedger().listClaims(filter);
+}
+
+/** Foundation-phase alias for `recordClaim({ repoFullName, issueNumber, note, apiBaseUrl })`. (#3351) */
+export function claimIssue(repoFullName, issueNumber, note, apiBaseUrl) {
+  return getDefaultClaimLedger().claimIssue(repoFullName, issueNumber, note, apiBaseUrl);
+}
+
+/** List only `active` claims, optionally scoped to one repo. (#3351) */
+export function listActiveClaims(repoFullName) {
+  return getDefaultClaimLedger().listActiveClaims(repoFullName);
+}
+
+export function closeDefaultClaimLedger() {
+  if (!defaultClaimLedger) return;
+  defaultClaimLedger.close();
+  defaultClaimLedger = null;
+}

package/lib/cli-error.d.ts

@@ -0,0 +1,3 @@
+export function reportCliFailure(wantsJson: boolean, message: string, exitCode?: number): number;
+export function argsWantJson(args: readonly string[]): boolean;
+export function describeCliError(error: unknown): string;

package/lib/cli-error.js

@@ -0,0 +1,27 @@
+/** Shared CLI failure output (#4836): when `--json` is set, emit a parseable `{ ok: false, error }` object on
+ *  stdout (matching each command's success-path JSON stream); otherwise log plain text to stderr. */
+
+/**
+ * @param {boolean} wantsJson
+ * @param {string} message
+ * @param {number} [exitCode]
+ * @returns {number}
+ */
+export function reportCliFailure(wantsJson, message, exitCode = 2) {
+  if (wantsJson) {
+    console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+  } else {
+    console.error(message);
+  }
+  return exitCode;
+}
+
+/** True when argv includes `--json` (used on parse-error paths before a full parse result exists). */
+export function argsWantJson(args) {
+  return args.includes("--json");
+}
+
+/** Normalize a thrown value to a safe error string for CLI output. */
+export function describeCliError(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/lib/cli.d.ts

@@ -0,0 +1,3 @@
+export function printVersion(input: { packageName: string; packageVersion: string }): void;
+export function printHelp(input: { packageName: string }): void;
+export function runCli(cliArgs: string[], input: { packageName: string }): number;

package/lib/cli.js

@@ -0,0 +1,72 @@
+import { argsWantJson, reportCliFailure } from "./cli-error.js";
+
+export function printVersion(input) {
+  console.log(`${input.packageName}/${input.packageVersion} (node ${process.version})`);
+}
+
+export function printHelp(input) {
+  console.log(
+    [
+      input.packageName,
+      "",
+      "Foundation CLI for the local Gittensory miner runtime.",
+      "",
+      "Usage:",
+      "  gittensory-miner --help",
+      "  gittensory-miner --version",
+      "  gittensory-miner help",
+      "  gittensory-miner version",
+      "  gittensory-miner init [--json] [--verify-token]              Bootstrap laptop-mode local SQLite state",
+      "  gittensory-miner status [--json]                              Show installed versions + local state paths",
+      "  gittensory-miner doctor [--json]                              Check this laptop is set up correctly",
+      "  gittensory-miner migrate [--json]                             Apply pending schema migrations to existing local stores",
+      "  gittensory-miner metrics                                      Print prediction-calibration counters in Prometheus text format",
+      "  gittensory-miner manage status [--json]                       Show managed PR rows from local portfolio + ledger",
+      "  gittensory-miner manage poll <owner/repo> <pr#> [--branch <name>] [--dry-run] [--json]",
+      "  gittensory-miner discover <owner/repo> [<owner/repo>...] [--dry-run] [--json]",
+      "  gittensory-miner discover --search <query> [--dry-run] [--json]  Fan out, rank, and enqueue candidates",
+      "  gittensory-miner attempt <owner/repo> <issue#> --miner-login <login> [--base <branch>] [--live] [--dry-run] [--json]",
+      "  gittensory-miner loop <owner/repo> [<owner/repo>...] --miner-login <login> [--base <branch>] [--live] [--dry-run]",
+      "  gittensory-miner loop --search <query> --miner-login <login> [--max-cycles <n>] [--cycle-delay-ms <ms>] [--dry-run] [--json]",
+      "                                                                 Autonomous discover->claim->attempt->reenter loop",
+      "  gittensory-miner queue list [--repo <owner/repo>] [--json]    List portfolio backlog rows",
+      "  gittensory-miner queue next [--global-wip <n>] [--per-repo-wip <n>] [--dry-run] [--json]",
+      "                                                                 Claim the highest-priority queued item, optionally WIP-cap-aware",
+      "  gittensory-miner queue claim-batch [--global-wip <n>] [--per-repo-wip <n>] [--dry-run] [--json]",
+      "  gittensory-miner queue done <owner/repo> <identifier> [--dry-run] [--json]",
+      "  gittensory-miner queue release <owner/repo> <identifier> [--dry-run] [--json]  Return a claimed item to the queue",
+      "  gittensory-miner queue requeue <owner/repo> <identifier> [--dry-run] [--json]  Put a completed item back on the queue",
+      "  gittensory-miner claim claim <owner/repo> <issue#> [--note <text>] [--dry-run] [--json]",
+      "  gittensory-miner claim release <owner/repo> <issue#> [--dry-run] [--json]",
+      "  gittensory-miner claim list [--repo <owner/repo>] [--status active|released|expired] [--json]",
+      "  gittensory-miner ledger list [--repo <owner/repo>] [--since <seq>] [--type <eventType>] [--json]",
+      "  gittensory-miner ledger metrics                               Print event-ledger counters in Prometheus text format",
+      "  gittensory-miner plan list [--status pending|running|completed|failed] [--json]",
+      "  gittensory-miner plan show <planId> [--json]",
+      "  gittensory-miner governor list [--repo <owner/repo>] [--type allowed|denied|throttled|kill_switch] [--json]",
+      "  gittensory-miner governor pause [--reason <text>] [--dry-run] [--json]  Stop the loop before its next cycle",
+      "  gittensory-miner governor resume [--dry-run] [--json]         Let a paused loop continue",
+      "  gittensory-miner governor status [--json]                     Show whether the governor is paused",
+      "  gittensory-miner calibration [--json]                         Report predicted-vs-realized gate accuracy",
+      "  gittensory-miner feasibility <claimStatus> <duplicateClusterRisk> <issueStatus> [--not-found] [--json]",
+      "  gittensory-miner hooks check --tool <name> --input <json> [--json]",
+      "  gittensory-miner state get <owner/repo> [--json]",
+      "  gittensory-miner state set <owner/repo> <idle|discovering|planning|preparing> [--dry-run] [--json]",
+      "  gittensory-miner orb export [--enable] [--dry-run] [--json]   Build the opt-in anonymized telemetry batch",
+      "  gittensory-miner purge --repo <owner/repo> [--dry-run] [--json]",
+      "                                                                 Right-to-be-forgotten: delete a repo's rows from every local store",
+      "",
+      "Options:",
+      "  --no-update-check  Skip the npm registry version nudge (also GITTENSORY_MINER_NO_UPDATE_CHECK=1)",
+      "  --quiet            Log only warnings and errors (also GITTENSORY_MINER_LOG_LEVEL=error)",
+      "  --verbose          Log debug-level diagnostics (also GITTENSORY_MINER_LOG_LEVEL=debug)",
+      "  --log-level <lvl>  Set the log level explicitly: silent|error|warn|info|debug",
+    ].join("\n"),
+  );
+}
+
+export function runCli(cliArgs, input) {
+  const command = cliArgs[0] ?? "";
+  const message = `Unknown command: ${command}. Run ${input.packageName} --help.`;
+  return reportCliFailure(argsWantJson(cliArgs), message, 1);
+}

package/lib/coding-agent-construction.d.ts

@@ -0,0 +1,17 @@
+import type { AgentSdkHooks, AgentSdkQueryFn, CliSubprocessSpawnFn, CodingAgentDriver } from "@loopover/engine";
+
+export function createRealCliSubprocessSpawn(): CliSubprocessSpawnFn;
+
+export type ConstructProductionCodingAgentDriverOptions = {
+  spawn?: CliSubprocessSpawnFn;
+  query?: AgentSdkQueryFn;
+  hooks?: AgentSdkHooks;
+  listChangedFiles?: (cwd: string) => Promise<string[]>;
+  houseRulesConfig?: unknown;
+  houseRulesOptions?: unknown;
+};
+
+export function constructProductionCodingAgentDriver(
+  env: Record<string, string | undefined>,
+  options?: ConstructProductionCodingAgentDriverOptions,
+): CodingAgentDriver;

package/lib/coding-agent-construction.js

@@ -0,0 +1,103 @@
+// Production coding-agent driver construction (#5131, Wave 3.5 follow-up to #2337/#2343). Closes the gap
+// coding-agent-house-rules.js's own header names explicitly: "nothing in this package constructs a
+// coding-agent driver in production yet ... that is separate, larger follow-up work." This module IS that
+// call site -- it provides a real `child_process`-backed spawn (mirroring src/selfhost/ai.ts's `defaultSpawn`,
+// simplified to the engine's smaller `CliSubprocessSpawnFn` contract: no `firstOutputTimeoutMs`/`input`, since
+// those are reviewer-CLI-specific concerns this driver doesn't share) and resolves + constructs a real
+// `CodingAgentDriver` from `MINER_CODING_AGENT_PROVIDER`, with house-rule enforcement (#2343) wired in by
+// default via `buildHouseRulesAgentSdkHooks` -- a caller never has to remember to attach it by hand.
+
+import { spawn as nodeSpawn } from "node:child_process";
+import { createCodingAgentDriver, resolveFirstConfiguredCodingAgentDriverName } from "@loopover/engine";
+import { buildHouseRulesAgentSdkHooks } from "./coding-agent-house-rules.js";
+
+/**
+ * Real `child_process.spawn`-backed implementation of the engine's `CliSubprocessSpawnFn` contract. Captures
+ * stdout/stderr and RESOLVES (never rejects) on timeout or spawn error, so the caller always sees whatever
+ * output accumulated rather than an unhandled rejection -- mirrors `src/selfhost/ai.ts`'s `defaultSpawn`'s own
+ * resolve-not-reject rationale (a killed/errored subprocess's partial output may hold the real diagnosable
+ * error, e.g. an auth failure line on stderr).
+ *
+ * @returns {import("@loopover/engine").CliSubprocessSpawnFn}
+ */
+export function createRealCliSubprocessSpawn() {
+  return (cmd, args, opts) =>
+    new Promise((resolve) => {
+      const child = nodeSpawn(cmd, args, { cwd: opts.cwd, env: opts.env, stdio: ["ignore", "pipe", "pipe"] });
+      let stdout = "";
+      let stderr = "";
+      // Unlike src/selfhost/ai.ts's defaultSpawn (a fixed ~120s default, genuinely untestable without a real
+      // wait), `opts.timeoutMs` here is always CALLER-supplied per CliSubprocessSpawnFn's contract -- a test can
+      // pass a short value against a genuinely long-lived child, so this path is exercised directly rather than
+      // v8-ignored. No "already settled" guard is needed: Promise resolution is idempotent (a second `resolve()`
+      // is a no-op) and clearing an already-fired timer is a harmless no-op too, so `close`/`error` firing after
+      // the timeout already resolved is safe without extra bookkeeping.
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        resolve({ stdout, code: null, stderr, timedOut: true });
+      }, opts.timeoutMs);
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString("utf8");
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+      });
+      child.on("error", (err) => {
+        // A spawn-level error (e.g. ENOENT) fires before the child ever produces output, so `stderr` is always
+        // "" here in practice; Node guarantees this listener receives a real Error with `.message` (the
+        // documented contract for ChildProcess's own "error" event), so no optional chaining/fallback is needed.
+        clearTimeout(timer);
+        resolve({ stdout, code: null, stderr: err.message });
+      });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        resolve({ stdout, code, stderr });
+      });
+    });
+}
+
+/**
+ * Resolve `MINER_CODING_AGENT_PROVIDER` from `env` and construct a REAL, production `CodingAgentDriver` —
+ * house-rule-enforced by default (#2343) via `buildHouseRulesAgentSdkHooks`, matching the same
+ * automatic-enforcement guarantee `runHouseRulesEnforcedCodingAgentAttempt` gives task-level callers, but at
+ * the raw driver-construction level `attempt-runner.js`'s `deps.driver` actually needs.
+ *
+ * The default only applies to `agent-sdk`, the one provider with a real hook-registration surface. CLI
+ * subprocess providers (`claude-cli`/`codex-cli`) have none, and the engine's `createCliProvider` fails closed
+ * if `hooks` is supplied at all (driver-factory.ts) -- filling the default for them here would make every CLI
+ * construction throw. An explicitly-supplied `options.hooks` always wins and is forwarded as-is, so a caller
+ * that deliberately asks a CLI provider to enforce hooks still gets that same fail-closed rejection.
+ *
+ * Fails closed (throws) when no provider is configured, or when a CLI provider is selected without a real
+ * spawn available — never silently falls back to a driver that can never run.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @param {{
+ *   spawn?: import("@loopover/engine").CliSubprocessSpawnFn,
+ *   query?: import("@loopover/engine").AgentSdkQueryFn,
+ *   hooks?: import("@loopover/engine").AgentSdkHooks,
+ *   listChangedFiles?: (cwd: string) => Promise<string[]>,
+ *   houseRulesConfig?: unknown,
+ *   houseRulesOptions?: unknown,
+ * }} [options]
+ * @returns {import("@loopover/engine").CodingAgentDriver}
+ */
+export function constructProductionCodingAgentDriver(env, options = {}) {
+  const providerName = resolveFirstConfiguredCodingAgentDriverName(env);
+  if (!providerName) {
+    throw new Error("unconfigured_coding_agent_driver:no_provider_in_MINER_CODING_AGENT_PROVIDER");
+  }
+  const hooks =
+    options.hooks ??
+    (providerName.trim().toLowerCase() === "agent-sdk"
+      ? buildHouseRulesAgentSdkHooks(options.houseRulesConfig, options.houseRulesOptions)
+      : undefined);
+  return createCodingAgentDriver({
+    providerName,
+    env,
+    spawn: options.spawn ?? createRealCliSubprocessSpawn(),
+    ...(options.query !== undefined ? { query: options.query } : {}),
+    ...(hooks !== undefined ? { hooks } : {}),
+    ...(options.listChangedFiles !== undefined ? { listChangedFiles: options.listChangedFiles } : {}),
+  });
+}

package/lib/coding-agent-house-rules.d.ts

@@ -0,0 +1,24 @@
+import type { AgentSdkHooks, CodingAgentDriverResult, CodingAgentExecutionMode, LintGuardResult, RunCodingAgentAttemptOptions } from "@loopover/engine";
+import type { DenyRule } from "./deny-hooks.js";
+import type { appendGovernorEvent } from "./governor-ledger.js";
+
+export type HouseRulesConfig = {
+  rules?: readonly DenyRule[];
+  repoFullName?: string;
+};
+
+export type HouseRulesOptions = {
+  append?: typeof appendGovernorEvent;
+};
+
+/** The concrete shape {@link buildHouseRulesAgentSdkHooks} returns -- a single PreToolUse matcher group
+ *  holding the one house-rules callback. Structurally assignable to the engine's opaque `AgentSdkHooks`. */
+export type HouseRulesAgentSdkHooks = AgentSdkHooks & {
+  PreToolUse: Array<{ hooks: Array<(input: unknown, toolUseId?: string, context?: unknown) => Promise<Record<string, unknown>>> }>;
+};
+
+export function buildHouseRulesAgentSdkHooks(config?: HouseRulesConfig, options?: HouseRulesOptions): HouseRulesAgentSdkHooks;
+
+export function runHouseRulesEnforcedCodingAgentAttempt(
+  options: RunCodingAgentAttemptOptions & { houseRulesConfig?: HouseRulesConfig; houseRulesOptions?: HouseRulesOptions },
+): Promise<{ mode: CodingAgentExecutionMode; result: CodingAgentDriverResult & { lintGuard?: LintGuardResult } }>;

package/lib/coding-agent-house-rules.js

@@ -0,0 +1,64 @@
+// House-rules-enforced coding-agent construction (#2343 follow-up). buildHouseRulesPreToolUseHook
+// (pretooluse-hook.js) is the LIVE PreToolUse interception point, but the engine package's
+// createCodingAgentDriver / runCodingAgentAttempt (driver-factory.ts) cannot import it directly -- the
+// dependency only ever flows gittensory-miner -> @loopover/engine, never the reverse (the engine
+// package is portable and cannot depend on the miner CLI package). This module is the missing miner-side
+// glue: it wraps runCodingAgentAttempt so the `agent-sdk` provider gets house-rule enforcement by DEFAULT --
+// a future real call site does not need to remember to attach it itself, closing the exact gap
+// buildHouseRulesPreToolUseHook's own doc comment already anticipated ("the live interception wiring itself").
+//
+// This does not build a CLI entrypoint. UPDATE (#5135/#5396): a real production call site now exists --
+// packages/gittensory-miner/lib/coding-agent-construction.js's `constructProductionCodingAgentDriver` calls
+// `createCodingAgentDriver` directly -- but it does NOT go through `runCodingAgentAttempt` or this module's
+// own `runHouseRulesEnforcedCodingAgentAttempt` wrapper below; the real invocation path is
+// `constructProductionCodingAgentDriver` -> the resulting driver becomes `IterateLoopDeps.driver` -> consumed
+// by `runIterateLoop` (packages/gittensory-engine/src/miner/iterate-loop.ts). House-rule enforcement for the
+// live `agent-sdk` provider is instead attached directly there, via this module's own
+// `buildHouseRulesAgentSdkHooks` export (called from `constructProductionCodingAgentDriver` -- so the
+// DEFAULT-attachment guarantee below still holds, just through a different real call site than originally
+// anticipated). `runHouseRulesEnforcedCodingAgentAttempt` itself remains real, tested, and callable, but has
+// no production caller today -- it's a lower-level composable for a hypothetical caller that wants the
+// non-iterate-loop path, not something this package currently needs.
+
+import { runCodingAgentAttempt } from "@loopover/engine";
+import { buildHouseRulesPreToolUseHook } from "./pretooluse-hook.js";
+
+/**
+ * Wrap {@link buildHouseRulesPreToolUseHook}'s callback into the Claude Agent SDK's own `hooks.PreToolUse`
+ * registration shape (an array of matcher groups, each holding an array of hook callbacks) -- the exact
+ * contract `agent-sdk-driver.ts`'s own doc comment names as "#2343's stated attachment point", and the shape
+ * `packages/gittensory-engine/test/agent-sdk-driver.test.ts` asserts is forwarded to the SDK verbatim.
+ *
+ * @param {Parameters<typeof buildHouseRulesPreToolUseHook>[0]} [config]
+ * @param {Parameters<typeof buildHouseRulesPreToolUseHook>[1]} [options]
+ * @returns {{ PreToolUse: Array<{ hooks: Array<ReturnType<typeof buildHouseRulesPreToolUseHook>> }> }}
+ */
+export function buildHouseRulesAgentSdkHooks(config = {}, options = {}) {
+  return { PreToolUse: [{ hooks: [buildHouseRulesPreToolUseHook(config, options)] }] };
+}
+
+/**
+ * Drop-in replacement for the engine's `runCodingAgentAttempt` that defaults `hooks` to
+ * {@link buildHouseRulesAgentSdkHooks} for the `agent-sdk` provider, so house-rule enforcement (#2343) is ON
+ * by default rather than opt-in. An explicitly-supplied `hooks` option always wins (e.g. a test injecting its
+ * own hook double, or a caller composing additional hooks of its own) -- this only fills the gap when the
+ * caller omitted it entirely. CLI providers (`claude-cli`, `codex-cli`) have no hook-registration surface, and
+ * the engine fails closed if `hooks` is supplied to them at all -- so the default is scoped to `agent-sdk`
+ * only; a CLI attempt with no explicit `hooks` gets none (today's inert no-op), while one that explicitly
+ * supplies `hooks` still gets the engine's real fail-closed rejection instead of a silently unenforced run.
+ *
+ * @param {Parameters<typeof runCodingAgentAttempt>[0] & {
+ *   houseRulesConfig?: Parameters<typeof buildHouseRulesPreToolUseHook>[0],
+ *   houseRulesOptions?: Parameters<typeof buildHouseRulesPreToolUseHook>[1],
+ * }} options
+ * @returns {ReturnType<typeof runCodingAgentAttempt>}
+ */
+export function runHouseRulesEnforcedCodingAgentAttempt(options) {
+  const { houseRulesConfig, houseRulesOptions, ...attemptOptions } = options;
+  const hooks =
+    attemptOptions.hooks ??
+    (attemptOptions.providerName.trim().toLowerCase() === "agent-sdk"
+      ? buildHouseRulesAgentSdkHooks(houseRulesConfig, houseRulesOptions)
+      : undefined);
+  return runCodingAgentAttempt({ ...attemptOptions, ...(hooks !== undefined ? { hooks } : {}) });
+}