@loopover/miner 0.1.0

package/lib/event-ledger-cli.js

@@ -0,0 +1,266 @@
+import { initEventLedger } from "./event-ledger.js";
+import { argsWantJson, describeCliError, reportCliFailure } from "./cli-error.js";
+
+const LEDGER_LIST_USAGE =
+  "Usage: gittensory-miner ledger list [--repo <owner/repo>] [--since <seq>] [--type <eventType>] [--json]";
+
+function parseRepoArg(value, usage) {
+  if (!value) return { error: usage };
+  const trimmed = value.trim();
+  const [owner, repo, extra] = trimmed.split("/");
+  if (!owner || !repo || extra !== undefined) {
+    return { error: "Repository must be in owner/repo form." };
+  }
+  return { repoFullName: `${owner}/${repo}` };
+}
+
+function parseSinceArg(value) {
+  const since = Number(value);
+  if (!Number.isInteger(since) || since < 0) {
+    return { error: "since must be a non-negative integer seq cursor." };
+  }
+  return { since };
+}
+
+export function parseLedgerListArgs(args) {
+  const options = { json: false, repoFullName: null, since: null, type: null };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--repo") {
+      const repoArg = args[index + 1];
+      if (!repoArg || repoArg.startsWith("-")) return { error: LEDGER_LIST_USAGE };
+      const repo = parseRepoArg(repoArg, LEDGER_LIST_USAGE);
+      if ("error" in repo) return repo;
+      options.repoFullName = repo.repoFullName;
+      index += 1;
+      continue;
+    }
+    if (token === "--since") {
+      const sinceArg = args[index + 1];
+      if (!sinceArg || sinceArg.startsWith("--")) return { error: LEDGER_LIST_USAGE };
+      const parsedSince = parseSinceArg(sinceArg);
+      if ("error" in parsedSince) return parsedSince;
+      options.since = parsedSince.since;
+      index += 1;
+      continue;
+    }
+    if (token === "--type") {
+      const type = args[index + 1];
+      if (!type || type.startsWith("-")) return { error: LEDGER_LIST_USAGE };
+      options.type = type.trim();
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) return { error: `Unknown option: ${token}` };
+    positional.push(token);
+  }
+
+  if (positional.length > 0) return { error: LEDGER_LIST_USAGE };
+  return options;
+}
+
+export function filterLedgerEvents(events, options = {}) {
+  if (!Array.isArray(events)) return [];
+  const type = typeof options.type === "string" && options.type.trim() ? options.type.trim() : null;
+  if (!type) return events;
+  return events.filter((entry) => entry.type === type);
+}
+
+/** Metadata-only audit-feed columns exposed by the MCP tool (#5158). */
+export const AUDIT_FEED_ENTRY_FIELDS = Object.freeze([
+  "eventType",
+  "repoFullName",
+  "outcome",
+  "actor",
+  "detail",
+  "createdAt",
+]);
+
+function optionalMetadataString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+/** Project one ledger row to the public, metadata-only audit-feed shape — never returns payload_json. */
+export function projectLedgerEventToAuditFeedEntry(entry) {
+  const payload =
+    entry?.payload && typeof entry.payload === "object" && !Array.isArray(entry.payload) ? entry.payload : {};
+  return {
+    eventType: entry.type,
+    repoFullName: entry.repoFullName,
+    outcome: optionalMetadataString(payload.outcome),
+    actor: optionalMetadataString(payload.actor),
+    detail: optionalMetadataString(payload.detail),
+    createdAt: entry.createdAt,
+  };
+}
+
+/** Normalize optional MCP/JSON filter args into the shape `ledger list` already uses (#5158). */
+export function normalizeAuditFeedMcpFilter(input = {}) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("filter must be an object");
+  }
+  const filter = { repoFullName: null, since: null, type: null };
+  if (input.repoFullName !== undefined && input.repoFullName !== null) {
+    const repo = parseRepoArg(String(input.repoFullName), "repoFullName must be in owner/repo form.");
+    if ("error" in repo) throw new Error(repo.error);
+    filter.repoFullName = repo.repoFullName;
+  }
+  if (input.since !== undefined && input.since !== null) {
+    const parsedSince = parseSinceArg(String(input.since));
+    if ("error" in parsedSince) throw new Error(parsedSince.error);
+    filter.since = parsedSince.since;
+  }
+  if (input.type !== undefined && input.type !== null) {
+    const trimmed = String(input.type).trim();
+    if (!trimmed) throw new Error("type must be a non-empty string.");
+    filter.type = trimmed;
+  }
+  return filter;
+}
+
+/** Read-only audit feed shared by the MCP audit-feed tool (#5158). */
+export function collectEventLedgerAuditFeed(eventLedger, filter = {}) {
+  const events = filterLedgerEvents(
+    eventLedger.readEvents({
+      repoFullName: filter.repoFullName,
+      since: filter.since,
+    }),
+    { type: filter.type },
+  );
+  return {
+    ...(filter.repoFullName ? { repoFullName: filter.repoFullName } : {}),
+    events: events.map(projectLedgerEventToAuditFeedEntry),
+  };
+}
+
+function display(value) {
+  if (value === null || value === undefined) return "-";
+  return String(value);
+}
+
+export function renderLedgerTable(events) {
+  if (!Array.isArray(events) || events.length === 0) return "no event ledger entries";
+  const header = [
+    "seq".padStart(4),
+    "type".padEnd(20),
+    "repo".padEnd(24),
+    "created-at".padEnd(24),
+  ].join(" ");
+  const lines = events.map((entry) =>
+    [
+      String(entry.seq).padStart(4),
+      entry.type.padEnd(20),
+      display(entry.repoFullName).padEnd(24),
+      display(entry.createdAt).padEnd(24),
+    ].join(" "),
+  );
+  return [header, ...lines].join("\n");
+}
+
+const EVENT_LEDGER_METRICS_USAGE = "Usage: gittensory-miner ledger metrics";
+
+// Prometheus metric name for the per-type event-ledger counter. Mirrors the `gittensory_miner_*_total` naming and
+// the HELP/TYPE/label conventions of the engine's renderMinerPredictionMetrics
+// (packages/gittensory-engine/src/miner-prediction-metrics.ts) rather than importing across the package boundary.
+const MINER_EVENTS_TOTAL = "gittensory_miner_events_total";
+
+/** HELP-text escaping — backslash + newline (mirrors miner-prediction-metrics.ts's escapeHelpText). */
+function escapeHelpText(help) {
+  return help.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+}
+
+/** Prometheus label-value escaping — backslash, double-quote, newline — so an arbitrary event `type` string can
+ *  never break the metric line (mirrors miner-prediction-metrics.ts's escapeLabelValue). */
+function escapeLabelValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+
+/**
+ * Render event-ledger activity as Prometheus text-exposition counters: one `gittensory_miner_events_total{type}`
+ * series per event type, so a self-hoster's own Grafana/alerting can scrape ledger activity instead of polling
+ * `ledger list --json` (#4841). Pure + side-effect-free — the caller supplies the rows and prints the result;
+ * deterministic (series emitted in sorted type order); always emits HELP/TYPE so an empty ledger is still a
+ * well-formed exposition document.
+ */
+export function renderEventLedgerMetrics(events) {
+  const totalByType = new Map();
+  for (const entry of events) {
+    totalByType.set(entry.type, (totalByType.get(entry.type) ?? 0) + 1);
+  }
+  const lines = [
+    `# HELP ${MINER_EVENTS_TOTAL} ${escapeHelpText("Event-ledger entries the miner has recorded, by event type.")}`,
+    `# TYPE ${MINER_EVENTS_TOTAL} counter`,
+  ];
+  for (const [type, count] of [...totalByType.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    lines.push(`${MINER_EVENTS_TOTAL}{type="${escapeLabelValue(type)}"} ${count}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function withEventLedger(options, run) {
+  const ownsLedger = options.initEventLedger === undefined;
+  const eventLedger = (options.initEventLedger ?? initEventLedger)();
+  try {
+    return run(eventLedger);
+  } finally {
+    if (ownsLedger) eventLedger.close();
+  }
+}
+
+export function runLedgerList(args, options = {}) {
+  const parsed = parseLedgerListArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  try {
+    return withEventLedger(options, (eventLedger) => {
+      const events = filterLedgerEvents(
+        eventLedger.readEvents({
+          repoFullName: parsed.repoFullName,
+          since: parsed.since,
+        }),
+        { type: parsed.type },
+      );
+      if (parsed.json) {
+        console.log(JSON.stringify({ events }, null, 2));
+      } else {
+        console.log(renderLedgerTable(events));
+      }
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+export function runLedgerMetrics(args, options = {}) {
+  if (args.length > 0) {
+    return reportCliFailure(argsWantJson(args), EVENT_LEDGER_METRICS_USAGE);
+  }
+
+  try {
+    return withEventLedger(options, (eventLedger) => {
+      // renderEventLedgerMetrics returns a newline-terminated document; console.log re-adds the terminator, so
+      // trim it to emit exactly one trailing newline (mirrors metrics-cli.js's runMetrics).
+      console.log(renderEventLedgerMetrics(eventLedger.readEvents()).trimEnd());
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(argsWantJson(args), describeCliError(error));
+  }
+}
+
+export function runLedgerCli(subcommand, args, options = {}) {
+  if (subcommand === "list") return runLedgerList(args, options);
+  if (subcommand === "metrics") return runLedgerMetrics(args, options);
+  return reportCliFailure(argsWantJson(args), `Unknown ledger subcommand: ${subcommand ?? ""}. ${LEDGER_LIST_USAGE}`);
+}

package/lib/event-ledger.d.ts

@@ -0,0 +1,37 @@
+export type LedgerEntry = {
+  id: number;
+  seq: number;
+  type: string;
+  repoFullName: string | null;
+  payload: Record<string, unknown>;
+  createdAt: string;
+};
+
+export type AppendEventInput = {
+  type: string;
+  repoFullName?: string;
+  payload: Record<string, unknown>;
+};
+
+export type ReadEventsFilter = {
+  repoFullName?: string | null;
+  since?: number | null;
+};
+
+export type EventLedger = {
+  dbPath: string;
+  appendEvent(event: AppendEventInput): LedgerEntry;
+  readEvents(filter?: ReadEventsFilter): LedgerEntry[];
+  purgeByRepo(repoFullName: string): number;
+  close(): void;
+};
+
+export function resolveEventLedgerDbPath(env?: Record<string, string | undefined>): string;
+
+export function initEventLedger(dbPath?: string): EventLedger;
+
+export function appendEvent(event: AppendEventInput): LedgerEntry;
+
+export function readEvents(filter?: ReadEventsFilter): LedgerEntry[];
+
+export function closeDefaultEventLedger(): void;

package/lib/event-ledger.js

@@ -0,0 +1,210 @@
+import { isDeepStrictEqual } from "node:util";
+import { normalizeLocalStoreDbPath, openLocalStoreDb, resolveLocalStoreDbPath } from "./local-store.js";
+import { applySchemaMigrations } from "./schema-version.js";
+import {
+  EVENT_LEDGER_PURGE_SPEC,
+  EVENT_LEDGER_RETENTION_SPEC,
+  purgeStoreByRepo,
+  pruneLedgerByRetention,
+  resolveLedgerRetentionPolicy,
+} from "./store-maintenance.js";
+
+// The miner's local, append-only event ledger (#2290): an immutable audit trail of every significant miner-loop
+// event (discovered_issue, plan_built, plan_step_completed, pr_prepared, … — a small fixed vocabulary for this
+// foundation phase that grows in later phases), each stamped with a module-maintained monotonic `seq` and a
+// timestamp. IMMUTABILITY INVARIANT: `appendEvent`/`readEvents` only ever issue INSERT and SELECT — they NEVER
+// rewrite or remove a row, so a contributor auditing the miner's history later can trust it was not retroactively
+// edited. Keep it that way: do not add mutation to the day-to-day append/read path. The two documented exceptions
+// are opt-in retention pruning (#4834, automatic, age/size-bounded) and `purgeByRepo` (#5564, always explicit and
+// operator-invoked, never automatic) — both are separate, clearly-labeled maintenance operations, not part of the
+// ledger's normal operation. The database is 100% local; this module never uploads, syncs, or phones home with
+// its contents. Mirrors the local-store pattern of run-state.js.
+
+const defaultDbFileName = "event-ledger.sqlite3";
+let defaultEventLedger = null;
+
+export function resolveEventLedgerDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_EVENT_LEDGER_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolveEventLedgerDbPath(), "invalid_event_ledger_db_path");
+}
+
+function normalizeEventType(type) {
+  if (typeof type !== "string") throw new Error("invalid_event_type");
+  const trimmed = type.trim();
+  if (!trimmed) throw new Error("invalid_event_type");
+  return trimmed;
+}
+
+/** Optional repo scope: omitted/nullish → null; otherwise a validated `owner/repo`. */
+function normalizeOptionalRepoFullName(repoFullName) {
+  if (repoFullName === undefined || repoFullName === null) return null;
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const [owner, repo, extra] = repoFullName.trim().split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  return `${owner}/${repo}`;
+}
+
+/** Optional seq cursor for polling: omitted → undefined; otherwise a non-negative integer last-seen seq. */
+function normalizeOptionalSince(since) {
+  if (since === undefined || since === null) return undefined;
+  if (typeof since !== "number" || !Number.isInteger(since) || since < 0) {
+    throw new Error("invalid_since");
+  }
+  return since;
+}
+
+/** Read-filter repo scope: omitted/nullish → unscoped (all events); otherwise a validated `owner/repo`. */
+function normalizeReadRepoFilter(repoFullName) {
+  if (repoFullName === undefined || repoFullName === null) return undefined;
+  return normalizeOptionalRepoFullName(repoFullName);
+}
+
+// Serialize an audit payload, enforcing that it round-trips through JSON VERBATIM. A plain JSON.stringify would
+// silently drop `undefined`/function/symbol values and coerce `NaN`/`Infinity` to `null` (and throw on BigInt or a
+// cycle), so a read-back would not equal the appended event. We reject any such lossy payload outright — an audit
+// ledger must return exactly what was recorded.
+function serializePayload(payload) {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("invalid_payload");
+  }
+  let json;
+  try {
+    json = JSON.stringify(payload);
+  } catch {
+    throw new Error("invalid_payload"); // BigInt value or circular reference
+  }
+  if (!isDeepStrictEqual(JSON.parse(json), payload)) {
+    throw new Error("invalid_payload"); // a value JSON would drop or coerce (undefined/NaN/function/symbol/Date/…)
+  }
+  return json;
+}
+
+function rowToEntry(row) {
+  return {
+    id: row.id,
+    seq: row.seq,
+    type: row.event_type,
+    repoFullName: row.repo_full_name,
+    payload: JSON.parse(row.payload_json),
+    createdAt: row.created_at,
+  };
+}
+
+/**
+ * Opens the local append-only event ledger, creating the table on first use. `seq` is a monotonically increasing
+ * counter maintained by this module (next = current MAX(seq) + 1) rather than relying on `AUTOINCREMENT`'s
+ * reuse-after-vacuum behavior, so consumers get a stable ordering guarantee. Rows read back in `seq ASC` order.
+ * (#2290)
+ */
+export function initEventLedger(dbPath = resolveEventLedgerDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  const db = openLocalStoreDb(resolvedPath);
+  // `UNIQUE(seq)` makes the monotonic-ordering guarantee an enforced invariant: a duplicate seq can never persist,
+  // even if the append path were ever changed.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS miner_event_ledger (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      seq INTEGER NOT NULL UNIQUE,
+      event_type TEXT NOT NULL,
+      repo_full_name TEXT,
+      payload_json TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    )
+  `);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations (none yet).
+  applySchemaMigrations(db, []);
+  // Opt-in retention (#4834): prune aged/excess rows when an operator has enabled it; a no-op by default.
+  pruneLedgerByRetention(db, EVENT_LEDGER_RETENTION_SPEC, resolveLedgerRetentionPolicy(), Date.now());
+
+  const nextSeqStatement = db.prepare("SELECT COALESCE(MAX(seq), 0) + 1 AS nextSeq FROM miner_event_ledger");
+  const appendStatement = db.prepare(`
+    INSERT INTO miner_event_ledger (seq, event_type, repo_full_name, payload_json, created_at)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+  const getByIdStatement = db.prepare("SELECT * FROM miner_event_ledger WHERE id = ?");
+  const readAllStatement = db.prepare("SELECT * FROM miner_event_ledger ORDER BY seq ASC");
+  const readByRepoStatement = db.prepare(
+    "SELECT * FROM miner_event_ledger WHERE repo_full_name = ? ORDER BY seq ASC",
+  );
+  const readSinceStatement = db.prepare(
+    "SELECT * FROM miner_event_ledger WHERE seq > ? ORDER BY seq ASC",
+  );
+  const readByRepoSinceStatement = db.prepare(
+    "SELECT * FROM miner_event_ledger WHERE repo_full_name = ? AND seq > ? ORDER BY seq ASC",
+  );
+
+  return {
+    dbPath: resolvedPath,
+    appendEvent(event) {
+      const type = normalizeEventType(event?.type);
+      const repoFullName = normalizeOptionalRepoFullName(event?.repoFullName);
+      const payloadJson = serializePayload(event?.payload);
+      const createdAt = new Date().toISOString();
+      // Serialize the read-then-write: BEGIN IMMEDIATE takes the write lock BEFORE reading MAX(seq), so two ledger
+      // instances on the same file cannot both compute the same next seq and corrupt the ordering guarantee.
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const { nextSeq } = nextSeqStatement.get();
+        const result = appendStatement.run(nextSeq, type, repoFullName, payloadJson, createdAt);
+        const entry = rowToEntry(getByIdStatement.get(Number(result.lastInsertRowid)));
+        db.exec("COMMIT");
+        return entry;
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
+    },
+    readEvents(filter = {}) {
+      const repoFullName = normalizeReadRepoFilter(filter.repoFullName);
+      // `since` returns events with a seq STRICTLY greater than it — the "give me everything after the last seq I
+      // saw" polling shape.
+      const since = normalizeOptionalSince(filter.since);
+
+      let rows;
+      if (repoFullName !== undefined && since !== undefined) {
+        rows = readByRepoSinceStatement.all(repoFullName, since);
+      } else if (repoFullName !== undefined) {
+        rows = readByRepoStatement.all(repoFullName);
+      } else if (since !== undefined) {
+        rows = readSinceStatement.all(since);
+      } else {
+        rows = readAllStatement.all();
+      }
+      return rows.map(rowToEntry);
+    },
+    // Explicit, operator-invoked right-to-be-forgotten purge (#5564) — never runs automatically. See the
+    // IMMUTABILITY INVARIANT note above: this is a deliberate, separate exception, not a normal ledger write.
+    // Requires a real repoFullName (unlike the optional filter above): a purge must never silently no-op on a
+    // missing/blank argument.
+    purgeByRepo(repoFullName) {
+      const normalized = normalizeOptionalRepoFullName(repoFullName);
+      if (normalized === null) throw new Error("invalid_repo_full_name");
+      return purgeStoreByRepo(db, EVENT_LEDGER_PURGE_SPEC, normalized);
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+function getDefaultEventLedger() {
+  defaultEventLedger ??= initEventLedger();
+  return defaultEventLedger;
+}
+
+export function appendEvent(event) {
+  return getDefaultEventLedger().appendEvent(event);
+}
+
+export function readEvents(filter) {
+  return getDefaultEventLedger().readEvents(filter);
+}
+
+export function closeDefaultEventLedger() {
+  if (!defaultEventLedger) return;
+  defaultEventLedger.close();
+  defaultEventLedger = null;
+}

package/lib/execute-local-write.d.ts

@@ -0,0 +1,14 @@
+import type { LocalWriteActionSpec } from "@loopover/engine";
+
+export type ExecuteLocalWriteResult = {
+  action: string;
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  timedOut: boolean;
+};
+
+export function executeLocalWrite(
+  spec: LocalWriteActionSpec,
+  options?: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number },
+): Promise<ExecuteLocalWriteResult>;

package/lib/execute-local-write.js

@@ -0,0 +1,50 @@
+// Real executeLocalWrite implementation (#5132, Wave 3.5). Mirrors coding-agent-construction.js's
+// createRealCliSubprocessSpawn pattern (real child_process, resolve-not-reject on error/timeout so a
+// killed/errored process's partial output -- e.g. an auth failure line on stderr -- is never lost to an
+// unhandled rejection) but for LocalWriteActionSpec.command: a single shell-safe string (built with
+// packages/gittensory-engine/src/miner/local-write-tools.ts's own single-quote escaping), not the
+// cmd/args-array CliSubprocessSpawnFn contract the coding-agent driver itself uses. Runs it via `sh -c` in
+// the given working directory. Per local-write-tools.ts's own boundary comment, this always runs with
+// whatever `gh`/`git` credentials are already configured in that environment -- gittensory never performs
+// the write itself.
+
+import { spawn } from "node:child_process";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * @param {import("@loopover/engine").LocalWriteActionSpec} spec
+ * @param {{ cwd?: string, env?: NodeJS.ProcessEnv, timeoutMs?: number }} [options]
+ * @returns {Promise<{ action: string, stdout: string, stderr: string, code: number | null, timedOut: boolean }>}
+ */
+export function executeLocalWrite(spec, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  return new Promise((resolve) => {
+    const child = spawn("sh", ["-c", spec.command], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve({ action: spec.action, stdout, stderr, code: null, timedOut: true });
+    }, 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. no `sh` on PATH) fires before the child ever produces output -- mirrors
+      // createRealCliSubprocessSpawn's own identical handling.
+      clearTimeout(timer);
+      resolve({ action: spec.action, stdout, stderr: err.message, code: null, timedOut: false });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ action: spec.action, stdout, stderr, code, timedOut: false });
+    });
+  });
+}

package/lib/feasibility-cli.d.ts

@@ -0,0 +1,25 @@
+import type {
+  FeasibilityClaimStatus,
+  FeasibilityDuplicateClusterRisk,
+  FeasibilityGateInput,
+  FeasibilityGateResult,
+  FeasibilityIssueStatus,
+} from "@loopover/engine";
+
+export type ParsedFeasibilityArgs =
+  | {
+      claimStatus: FeasibilityClaimStatus;
+      duplicateClusterRisk: FeasibilityDuplicateClusterRisk;
+      issueStatus: FeasibilityIssueStatus;
+      found: boolean;
+      json: boolean;
+    }
+  | { error: string };
+
+export type RunFeasibilityCliOptions = {
+  buildFeasibilityVerdict?: (input: FeasibilityGateInput) => FeasibilityGateResult;
+};
+
+export function parseFeasibilityArgs(args: string[]): ParsedFeasibilityArgs;
+
+export function runFeasibilityCli(args: string[], options?: RunFeasibilityCliOptions): number;

package/lib/feasibility-cli.js

@@ -0,0 +1,80 @@
+/** `feasibility` CLI command (#4270): a thin parse -> execute -> render wrapper around the engine's pure
+ * `buildFeasibilityVerdict` composer. Purely local — no network, no filesystem — so it never needs the
+ * npm-registry update check other subcommands opt into. */
+import { buildFeasibilityVerdict } from "@loopover/engine";
+import { argsWantJson, reportCliFailure } from "./cli-error.js";
+
+const CLAIM_STATUSES = ["unclaimed", "claimed", "solved", "unknown"];
+const DUPLICATE_CLUSTER_RISKS = ["none", "low", "medium", "high"];
+const ISSUE_STATUSES = ["ready", "needs_proof", "hold", "do_not_use", "duplicate", "invalid", "missing"];
+
+const FEASIBILITY_USAGE =
+  "Usage: gittensory-miner feasibility <claimStatus> <duplicateClusterRisk> <issueStatus> [--not-found] [--json]\n" +
+  `  claimStatus: ${CLAIM_STATUSES.join("|")}\n` +
+  `  duplicateClusterRisk: ${DUPLICATE_CLUSTER_RISKS.join("|")}\n` +
+  `  issueStatus: ${ISSUE_STATUSES.join("|")}`;
+
+export function parseFeasibilityArgs(args) {
+  const options = { json: false, found: true };
+  const positional = [];
+
+  for (const token of args) {
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--not-found") {
+      options.found = false;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    positional.push(token);
+  }
+
+  if (positional.length !== 3) {
+    return { error: FEASIBILITY_USAGE };
+  }
+
+  const [claimStatus, duplicateClusterRisk, issueStatus] = positional;
+  if (!CLAIM_STATUSES.includes(claimStatus)) {
+    return { error: `claimStatus must be one of: ${CLAIM_STATUSES.join(", ")}.` };
+  }
+  if (!DUPLICATE_CLUSTER_RISKS.includes(duplicateClusterRisk)) {
+    return { error: `duplicateClusterRisk must be one of: ${DUPLICATE_CLUSTER_RISKS.join(", ")}.` };
+  }
+  if (!ISSUE_STATUSES.includes(issueStatus)) {
+    return { error: `issueStatus must be one of: ${ISSUE_STATUSES.join(", ")}.` };
+  }
+
+  return {
+    claimStatus,
+    duplicateClusterRisk,
+    issueStatus,
+    found: options.found,
+    json: options.json,
+  };
+}
+
+export function runFeasibilityCli(args, options = {}) {
+  const parsed = parseFeasibilityArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  const buildVerdict = options.buildFeasibilityVerdict ?? buildFeasibilityVerdict;
+  const verdict = buildVerdict({
+    found: parsed.found,
+    claimStatus: parsed.claimStatus,
+    duplicateClusterRisk: parsed.duplicateClusterRisk,
+    issueStatus: parsed.issueStatus,
+  });
+
+  if (parsed.json) {
+    console.log(JSON.stringify(verdict, null, 2));
+  } else {
+    console.log(`${verdict.verdict}: ${verdict.summary}`);
+  }
+  return 0;
+}