@loopover/miner 0.1.0

package/lib/store-maintenance.js

@@ -0,0 +1,183 @@
+// Local-store maintenance for the miner (#4834): SQLite integrity checks + append-only ledger retention.
+//
+// Three independent, side-effect-light helpers used by `doctor`, the ledgers, and `purge-cli.js`:
+//   1. checkStoreIntegrity — run `PRAGMA integrity_check` on one store file and report health, so `doctor` can
+//      flag a corrupted store instead of only probing a single one with `SELECT 1`.
+//   2. resolveLedgerRetentionPolicy / pruneLedgerByRetention — an opt-in, age- and/or size-based retention
+//      policy for the unbounded append-only ledgers (event, governor, prediction), which otherwise grow forever.
+//      OFF by default: retention only runs when an operator sets the env opt-in.
+//   3. purgeStoreByRepo — an explicit, operator-invoked delete of every row for one repo (#5564, right-to-be-
+//      forgotten). Distinct from retention pruning: never runs automatically, always caller-initiated via
+//      `purge-cli.js`, and always reports how many rows it removed so a purge is never silent.
+// Pure control flow over injected inputs (a DB handle, an env object, a caller-supplied clock) — no network, and
+// no internal clock read in the prune path so it stays deterministic and unit-testable.
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+
+/** Env opt-ins for ledger retention (unset ⇒ retention disabled). */
+export const LEDGER_RETENTION_DAYS_ENV = "GITTENSORY_MINER_LEDGER_RETENTION_DAYS";
+export const LEDGER_RETENTION_MAX_ROWS_ENV = "GITTENSORY_MINER_LEDGER_RETENTION_MAX_ROWS";
+
+/** Fixed retention specs for the three append-only ledgers. These identifiers are INTERNAL constants — never
+ *  caller/user text — and are validated as plain identifiers before interpolation as defence in depth. */
+export const EVENT_LEDGER_RETENTION_SPEC = { table: "miner_event_ledger", timestampColumn: "created_at", orderColumn: "id" };
+export const GOVERNOR_LEDGER_RETENTION_SPEC = { table: "governor_events", timestampColumn: "ts", orderColumn: "id" };
+export const PREDICTION_LEDGER_RETENTION_SPEC = { table: "predictions", timestampColumn: "ts", orderColumn: "id" };
+
+/** Fixed purge specs (#5564) for the four stores whose rows are directly scoped by a `repoColumn`. Same
+ *  internal-constant-only discipline as the retention specs above. `attempt-log.js` is deliberately absent: its
+ *  payload is a free-form `Record<string, unknown>` with no dedicated repo column, so a precise per-repo purge
+ *  isn't possible there without risking false matches — `purge-cli.js` reports it as not-purgeable instead. */
+export const CLAIM_LEDGER_PURGE_SPEC = { table: "miner_claims", repoColumn: "repo_full_name" };
+export const EVENT_LEDGER_PURGE_SPEC = { table: "miner_event_ledger", repoColumn: "repo_full_name" };
+export const GOVERNOR_LEDGER_PURGE_SPEC = { table: "governor_events", repoColumn: "repo_full_name" };
+export const PREDICTION_LEDGER_PURGE_SPEC = { table: "predictions", repoColumn: "repo_full_name" };
+
+const SQL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** A readable message for a caught value, whether or not it is an Error. */
+export function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Classify raw `PRAGMA integrity_check` rows. A healthy database yields a single `"ok"` row; a corrupt one yields
+ * one row per problem. Pure — extracted so both the healthy and problem paths are testable without a genuinely
+ * corrupt file (which SQLite typically refuses to open at all, i.e. the catch path below).
+ * @param {Array<{ integrity_check?: unknown }>} rows
+ * @returns {{ ok: boolean, note: string }}
+ */
+export function classifyIntegrityRows(rows) {
+  const problems = rows.map((row) => String(row.integrity_check)).filter((value) => value !== "ok");
+  return problems.length === 0 ? { ok: true, note: "ok" } : { ok: false, note: problems.join("; ") };
+}
+
+/**
+ * Run `PRAGMA integrity_check` on a single store file. A store that does not exist yet is healthy by absence
+ * (nothing to corrupt). Never throws: a store that cannot be opened or read is reported as not-ok, so one bad
+ * store cannot abort the whole doctor sweep. Opens the connection driver-enforced read-only -- `readOnly`
+ * (camelCase) is the only option key node:sqlite recognizes for this; the lowercase `readonly` is silently
+ * ignored and opens read-write instead (the exact gotcha claim-ledger.js's own openClaimLedgerReadOnly already
+ * documents), which would defeat the read-only guarantee this function's own docs claim.
+ * @param {string} name - the check label (e.g. "event-ledger").
+ * @param {string} dbPath - the store file path.
+ * @returns {{ name: string, ok: boolean, detail: string }}
+ */
+export function checkStoreIntegrity(name, dbPath) {
+  if (!existsSync(dbPath)) {
+    return { name, ok: true, detail: `${dbPath}: not created yet` };
+  }
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    const { ok, note } = classifyIntegrityRows(db.prepare("PRAGMA integrity_check").all());
+    return { name, ok, detail: `${dbPath}: ${note}` };
+  } catch (error) {
+    return { name, ok: false, detail: `${dbPath}: ${describeError(error)}` };
+  } finally {
+    db?.close();
+  }
+}
+
+/** Coerce an env value to a positive integer, or null (unset/blank/zero/negative/non-finite ⇒ null ⇒ disabled).
+ *  Floors BEFORE the positivity test, so a fractional value below 1 (e.g. "0.5") floors to 0 and disables the
+ *  bound rather than becoming a dangerous 0 that would prune the whole ledger. */
+function positiveIntOrNull(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") return null;
+  const numeric = Math.floor(Number(raw));
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
+}
+
+/**
+ * Resolve the opt-in ledger retention policy from an env object. OFF by default: returns null unless at least
+ * one bound is set to a positive value. A zero/negative/non-numeric value is treated as unset. When set, returns
+ * `{ maxAgeMs? }` (from a day count) and/or `{ maxRows? }`.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ maxAgeMs?: number, maxRows?: number } | null}
+ */
+export function resolveLedgerRetentionPolicy(env = process.env) {
+  const maxAgeDays = positiveIntOrNull(env[LEDGER_RETENTION_DAYS_ENV]);
+  const maxRows = positiveIntOrNull(env[LEDGER_RETENTION_MAX_ROWS_ENV]);
+  if (maxAgeDays === null && maxRows === null) return null;
+  const policy = {};
+  if (maxAgeDays !== null) policy.maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+  if (maxRows !== null) policy.maxRows = maxRows;
+  return policy;
+}
+
+/**
+ * Prune one append-only ledger per a resolved retention policy: delete rows older than the age bound AND rows
+ * beyond the row-count bound (keeping the newest `maxRows` by `orderColumn`), atomically. A null policy is a
+ * no-op. `nowMs` is caller-supplied (no internal clock). Timestamp columns are UTC ISO-8601 strings, which sort
+ * lexicographically in chronological order, so a string comparison against the ISO cutoff selects older rows.
+ * @param {import("node:sqlite").DatabaseSync} db
+ * @param {{ table: string, timestampColumn: string, orderColumn: string }} spec
+ * @param {{ maxAgeMs?: number, maxRows?: number } | null} policy
+ * @param {number} nowMs
+ * @returns {number} rows deleted
+ */
+export function pruneLedgerByRetention(db, spec, policy, nowMs) {
+  if (!policy) return 0;
+  for (const identifier of [spec.table, spec.timestampColumn, spec.orderColumn]) {
+    if (!SQL_IDENTIFIER.test(identifier)) throw new Error(`unsafe SQL identifier: ${identifier}`);
+  }
+  let deleted = 0;
+  db.exec("BEGIN");
+  try {
+    // Both bounds are guarded to be strictly positive as defence in depth: a 0 age would prune everything older
+    // than `now`, and a 0 row-cap makes `LIMIT 0` match no rows so `NOT IN (empty)` would delete the whole ledger.
+    if (policy.maxAgeMs !== undefined && policy.maxAgeMs > 0) {
+      const cutoff = new Date(nowMs - policy.maxAgeMs).toISOString();
+      const info = db.prepare(`DELETE FROM ${spec.table} WHERE ${spec.timestampColumn} < ?`).run(cutoff);
+      deleted += Number(info.changes);
+    }
+    if (policy.maxRows !== undefined && policy.maxRows >= 1) {
+      const info = db
+        .prepare(
+          `DELETE FROM ${spec.table} WHERE ${spec.orderColumn} NOT IN ` +
+            `(SELECT ${spec.orderColumn} FROM ${spec.table} ORDER BY ${spec.orderColumn} DESC LIMIT ?)`,
+        )
+        .run(policy.maxRows);
+      deleted += Number(info.changes);
+    }
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+  return deleted;
+}
+
+/**
+ * Delete every row for one repo from a store (#5564). Unlike `pruneLedgerByRetention`, this never runs
+ * automatically — it exists solely so `purge-cli.js` can give an operator a real right-to-be-forgotten path.
+ * `repoFullName` is caller-normalized (owner/repo) before reaching here; this function only guards the SQL
+ * identifiers, matching `pruneLedgerByRetention`'s own defence-in-depth discipline.
+ * @param {import("node:sqlite").DatabaseSync} db
+ * @param {{ table: string, repoColumn: string }} spec
+ * @param {string} repoFullName
+ * @returns {number} rows deleted
+ */
+export function purgeStoreByRepo(db, spec, repoFullName) {
+  for (const identifier of [spec.table, spec.repoColumn]) {
+    if (!SQL_IDENTIFIER.test(identifier)) throw new Error(`unsafe SQL identifier: ${identifier}`);
+  }
+  const info = db.prepare(`DELETE FROM ${spec.table} WHERE ${spec.repoColumn} = ?`).run(repoFullName);
+  return Number(info.changes);
+}
+
+/**
+ * Count rows for one repo in a store without deleting anything (#5564) — the read-only counterpart to
+ * `purgeStoreByRepo`, used by `purge-cli.js --dry-run` to report what a real purge would remove.
+ * @param {import("node:sqlite").DatabaseSync} db
+ * @param {{ table: string, repoColumn: string }} spec
+ * @param {string} repoFullName
+ * @returns {number} matching row count
+ */
+export function countStoreByRepo(db, spec, repoFullName) {
+  for (const identifier of [spec.table, spec.repoColumn]) {
+    if (!SQL_IDENTIFIER.test(identifier)) throw new Error(`unsafe SQL identifier: ${identifier}`);
+  }
+  const row = db.prepare(`SELECT COUNT(*) AS count FROM ${spec.table} WHERE ${spec.repoColumn} = ?`).get(repoFullName);
+  return Number(row.count);
+}

package/lib/submission-freshness-check.d.ts

@@ -0,0 +1,32 @@
+export const SUBMISSION_FRESHNESS_ABORT_EVENT: "submission_freshness_abort";
+
+export type FreshnessAbortReason = "issue_closed" | "already_addressed" | "claim_superseded" | "live_state_unavailable";
+
+export type SubmissionFreshnessCandidate = {
+  repoFullName: string;
+  issueNumber: number;
+  minerLogin: string;
+};
+
+export type LiveIssueSnapshot = {
+  state: "open" | "closed";
+  referencingPrs: Array<{ number: number; state: "open" | "closed" | "merged"; authorLogin: string; createdAt: string | null }>;
+};
+
+export type SubmissionFreshnessClaimLedger = {
+  listClaims(filter: { repoFullName?: string; status?: string }): Array<{ repoFullName: string; issueNumber: number; status: string }>;
+};
+
+export type SubmissionFreshnessEventLedger = {
+  appendEvent(event: { type: string; repoFullName?: string; payload: Record<string, unknown> }): unknown;
+};
+
+export type SubmissionFreshnessDeps = {
+  claimLedger: SubmissionFreshnessClaimLedger;
+  fetchLiveIssueSnapshot: (repoFullName: string, issueNumber: number) => Promise<LiveIssueSnapshot | null>;
+  eventLedger: SubmissionFreshnessEventLedger;
+};
+
+export type SubmissionFreshnessResult = { fresh: true } | { fresh: false; reason: FreshnessAbortReason };
+
+export function checkSubmissionFreshness(candidate: SubmissionFreshnessCandidate, deps: SubmissionFreshnessDeps): Promise<SubmissionFreshnessResult>;

package/lib/submission-freshness-check.js

@@ -0,0 +1,93 @@
+// Late-binding freshness check before open_pr fires (#3007). A soft-claim made at the start of a long
+// create/iterate loop can go stale by the time a candidate reaches submission: the target issue may have been
+// closed, already fixed by another author, or the miner's own claim may have been released/expired in the
+// interim. This is a FINAL, read-only check immediately before open_pr spec construction -- complementing, not
+// replacing, the claim-time check (src/miner/soft-claim.ts) -- so a stale submission never reaches the Governor
+// chokepoint (governor-chokepoint.js) as a live write attempt: check freshness first, THEN prepareOpenPrSubmission
+// (harness-submission-trigger.js), THEN the Governor. These are separate, sequentially-composed units, not nested
+// calls -- a future real call site wires them together in that order.
+//
+// READ-ONLY BY CONTRACT: never writes anything except its own abort-reason audit event (on staleness only, not
+// on every check -- mirrors this issue's own "log the abort reason" wording, not a per-decision audit trail).
+// The live-state fetch is an injected dependency so this stays testable without real network I/O and agnostic
+// to HOW the caller sources issue/PR state (raw GitHub API, gittensory's own cached MCP data, etc.).
+//
+// FAIL CLOSED: an unreachable/failed live-state fetch is treated as stale (aborts), never as "no evidence of
+// staleness, so proceed" -- mirrors this package's fail-closed convention elsewhere (harness-submission-
+// trigger.js's predicted_gate_unavailable/slop_assessment_unavailable, iterate-loop.ts's ambiguous-on-error).
+//
+// NOT a rejection outcome: staleness is caught BEFORE any PR exists, so it is not the same lifecycle event as
+// rejection-state-machine.js's DISENGAGED_OUTCOME (which handles an EXISTING PR a maintainer closed). "No PR,
+// no noisy failure" here just means: return a quiet not-fresh result, same shape as any other blocked gate
+// decision in this package -- never throw, never surface anything to the target repo.
+
+export const SUBMISSION_FRESHNESS_ABORT_EVENT = "submission_freshness_abort";
+
+/**
+ * Evaluate whether a submission candidate's live repo state is still fresh enough to proceed toward open_pr.
+ * Checks the miner's own claim-ledger status first (local, free) before spending a network round-trip on the
+ * live issue/PR snapshot. Fails closed (throws) on a malformed candidate or missing dependency.
+ *
+ * @param {{ repoFullName: string, issueNumber: number, minerLogin: string }} candidate
+ * @param {{
+ *   claimLedger: { listClaims(filter: { repoFullName?: string, status?: string }): Array<{ repoFullName: string, issueNumber: number, status: string }> },
+ *   fetchLiveIssueSnapshot: (repoFullName: string, issueNumber: number) => Promise<{ state: "open"|"closed", referencingPrs: Array<{ number: number, state: "open"|"closed"|"merged", authorLogin: string }> } | null>,
+ *   eventLedger: { appendEvent(event: { type: string, repoFullName?: string, payload: Record<string, unknown> }): unknown },
+ * }} deps
+ */
+export async function checkSubmissionFreshness(candidate, deps) {
+  if (!candidate || typeof candidate !== "object") throw new Error("invalid_freshness_candidate");
+  const repoFullName = typeof candidate.repoFullName === "string" ? candidate.repoFullName.trim() : "";
+  if (!repoFullName) throw new Error("invalid_repo_full_name");
+  if (!Number.isInteger(candidate.issueNumber) || candidate.issueNumber < 1) throw new Error("invalid_issue_number");
+  const minerLogin = typeof candidate.minerLogin === "string" ? candidate.minerLogin.trim() : "";
+  if (!minerLogin) throw new Error("invalid_miner_login");
+
+  if (!deps || typeof deps !== "object") throw new Error("invalid_freshness_deps");
+  const { claimLedger, fetchLiveIssueSnapshot, eventLedger } = deps;
+  if (!claimLedger || typeof claimLedger.listClaims !== "function") throw new Error("invalid_claim_ledger");
+  if (typeof fetchLiveIssueSnapshot !== "function") throw new Error("invalid_live_state_fetcher");
+  if (!eventLedger || typeof eventLedger.appendEvent !== "function") throw new Error("invalid_event_ledger");
+
+  const claim = claimLedger.listClaims({ repoFullName }).find((c) => c.issueNumber === candidate.issueNumber);
+  if (!claim || claim.status !== "active") {
+    return abort(eventLedger, repoFullName, candidate.issueNumber, "claim_superseded");
+  }
+
+  let snapshot;
+  try {
+    snapshot = await fetchLiveIssueSnapshot(repoFullName, candidate.issueNumber);
+  } catch {
+    snapshot = null;
+  }
+  if (!snapshot || typeof snapshot !== "object") {
+    return abort(eventLedger, repoFullName, candidate.issueNumber, "live_state_unavailable");
+  }
+
+  if (snapshot.state === "closed") {
+    return abort(eventLedger, repoFullName, candidate.issueNumber, "issue_closed");
+  }
+
+  // GitHub logins are case-insensitive for identity purposes (the same account can be echoed back with
+  // different casing by different API responses), so a strict `!==` would misclassify the miner's own
+  // referencing PR as "another author" whenever the casing happens to differ -- compare case-normalized.
+  const minerLoginKey = minerLogin.toLowerCase();
+  const referencingPrs = Array.isArray(snapshot.referencingPrs) ? snapshot.referencingPrs : [];
+  const addressedByAnotherAuthor = referencingPrs.some(
+    (pr) => typeof pr.authorLogin === "string" && pr.authorLogin.trim().toLowerCase() !== minerLoginKey && (pr.state === "merged" || pr.state === "open"),
+  );
+  if (addressedByAnotherAuthor) {
+    return abort(eventLedger, repoFullName, candidate.issueNumber, "already_addressed");
+  }
+
+  return { fresh: true };
+}
+
+function abort(eventLedger, repoFullName, issueNumber, reason) {
+  eventLedger.appendEvent({
+    type: SUBMISSION_FRESHNESS_ABORT_EVENT,
+    repoFullName,
+    payload: { issueNumber, reason },
+  });
+  return { fresh: false, reason };
+}

package/lib/update-check.d.ts

@@ -0,0 +1,36 @@
+export function resolveNpmRegistryUrl(
+  env?: Record<string, string | undefined>,
+): string;
+export function resolveUpgradeCommand(packageName?: string): string;
+export function shouldSkipUpdateCheck(
+  cliArgs: string[],
+  env?: Record<string, string | undefined>,
+): boolean;
+export function compareSemver(a: string, b: string): -1 | 0 | 1 | null;
+export function fetchLatestPackageVersion(input: {
+  packageName: string;
+  npmRegistryUrl: string;
+  timeoutMs?: number;
+}): Promise<string>;
+export function maybePrintUpdateNudge(input: {
+  packageName: string;
+  packageVersion: string;
+  npmRegistryUrl: string;
+  upgradeCommand: string;
+  timeoutMs?: number;
+}): Promise<void>;
+export function startUpdateCheck(
+  cliArgs: string[],
+  input: {
+    packageName: string;
+    packageVersion: string;
+    upgradeCommand?: string;
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+  },
+): Promise<void>;
+export const updateCheckExitGraceMs: number;
+export function awaitOpportunisticUpdateCheck(
+  updateCheck: Promise<void>,
+  graceMs?: number,
+): Promise<void>;

package/lib/update-check.js

@@ -0,0 +1,161 @@
+const defaultPackageName = "@loopover/miner";
+const defaultNpmRegistryUrl = "https://registry.npmjs.org";
+
+function isLocalRegistryHost(hostname) {
+  const normalized = hostname.toLowerCase().replace(/\.$/, "");
+  return (
+    normalized === "localhost" ||
+    normalized === "127.0.0.1" ||
+    normalized === "::1" ||
+    normalized === "[::1]"
+  );
+}
+
+export function resolveNpmRegistryUrl(env = process.env) {
+  const raw = env.GITTENSORY_NPM_REGISTRY_URL?.trim();
+  if (!raw) return defaultNpmRegistryUrl;
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return defaultNpmRegistryUrl;
+  }
+
+  if (url.username || url.password || url.search || url.hash || !url.hostname) {
+    return defaultNpmRegistryUrl;
+  }
+
+  const local = isLocalRegistryHost(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+    return defaultNpmRegistryUrl;
+  }
+
+  const path = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+  return `${url.origin}${path}`;
+}
+
+export function resolveUpgradeCommand(packageName = defaultPackageName) {
+  return `npm install -g ${packageName}@latest`;
+}
+
+export function shouldSkipUpdateCheck(cliArgs, env = process.env) {
+  if (/^(1|true|yes)$/i.test(env.GITTENSORY_MINER_NO_UPDATE_CHECK ?? ""))
+    return true;
+  return cliArgs.includes("--no-update-check");
+}
+
+function parseSemver(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(
+    String(version ?? "").trim(),
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? null,
+  };
+}
+
+// Numeric identifiers are compared as decimal strings, not via Number(), which loses precision beyond
+// Number.MAX_SAFE_INTEGER (2^53-1): two distinct digit strings past that width can round to the SAME float,
+// making Number(leftId) !== Number(rightId) wrongly report them as equal (mirrors the same fix already applied
+// to compareMcpSemver's comparePrerelease in src/services/mcp-compatibility.ts, #3049). With no leading zeros
+// (semver's own numeric-identifier rule), a longer digit string is the larger number, and equal-length strings
+// compare lexicographically.
+function comparePrerelease(a, b) {
+  const left = a.split(".");
+  const right = b.split(".");
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const leftId = left[index];
+    const rightId = right[index];
+    if (leftId === undefined) return -1;
+    if (rightId === undefined) return 1;
+    const leftNumeric = /^\d+$/.test(leftId);
+    const rightNumeric = /^\d+$/.test(rightId);
+    if (leftNumeric && rightNumeric) {
+      if (leftId.length !== rightId.length) return leftId.length < rightId.length ? -1 : 1;
+      if (leftId !== rightId) return leftId < rightId ? -1 : 1;
+    } else if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    } else if (leftId !== rightId) {
+      return leftId < rightId ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+export function compareSemver(a, b) {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  if (!left || !right) return null;
+  for (const part of ["major", "minor", "patch"]) {
+    if (left[part] !== right[part]) return left[part] < right[part] ? -1 : 1;
+  }
+  if (left.prerelease === right.prerelease) return 0;
+  if (left.prerelease === null) return 1;
+  if (right.prerelease === null) return -1;
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+export async function fetchLatestPackageVersion(input) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), input.timeoutMs ?? 5000);
+  const registrySlug = input.packageName.startsWith("@")
+    ? input.packageName.replace("/", "%2F")
+    : input.packageName;
+  const registryPath = `${input.npmRegistryUrl}/${registrySlug}/latest`;
+  try {
+    const response = await fetch(registryPath, {
+      signal: controller.signal,
+      headers: { accept: "application/json" },
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok || typeof payload.version !== "string")
+      throw new Error("npm_latest_version_unavailable");
+    return payload.version;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// Non-blocking startup nudge: prints one upgrade line when local is behind npm latest.
+// Mirrors packages/gittensory-mcp/bin/gittensory-mcp.js packageVersion/npmRegistryUrl/upgradeCommand (#2331).
+export async function maybePrintUpdateNudge(input) {
+  try {
+    const latestVersion = await fetchLatestPackageVersion(input);
+    const comparison = compareSemver(input.packageVersion, latestVersion);
+    if (comparison !== null && comparison < 0) {
+      process.stderr.write(`${input.upgradeCommand}\n`);
+    }
+  } catch {
+    // Offline or unreachable registry — never block or fail the CLI.
+  }
+}
+
+export function startUpdateCheck(cliArgs, input) {
+  if (shouldSkipUpdateCheck(cliArgs, input.env)) return Promise.resolve();
+  return maybePrintUpdateNudge({
+    packageName: input.packageName,
+    packageVersion: input.packageVersion,
+    npmRegistryUrl: resolveNpmRegistryUrl(input.env),
+    upgradeCommand:
+      input.upgradeCommand ?? resolveUpgradeCommand(input.packageName),
+    timeoutMs: input.timeoutMs,
+  });
+}
+
+export const updateCheckExitGraceMs = 250;
+
+// After command output is printed, give a fast registry response time to emit the nudge
+// without waiting for the full lookup timeout on slow/offline registries.
+export async function awaitOpportunisticUpdateCheck(
+  updateCheck,
+  graceMs = updateCheckExitGraceMs,
+) {
+  await Promise.race([
+    updateCheck.catch(() => undefined),
+    new Promise((resolve) => setTimeout(resolve, graceMs)),
+  ]);
+}

package/lib/version.d.ts

@@ -0,0 +1,3 @@
+export const MINER_PACKAGE_VERSION: string;
+
+export function resolveMinerVersion(env?: Record<string, string | undefined>): string;

package/lib/version.js

@@ -0,0 +1,10 @@
+import ownPackageJson from "../package.json" with { type: "json" };
+
+/** Package.json semver at import time — the laptop npm-install default. */
+export const MINER_PACKAGE_VERSION = ownPackageJson.version;
+
+/** Resolved miner release id: `GITTENSORY_MINER_VERSION` wins when set (fleet Docker image builds). */
+export function resolveMinerVersion(env = process.env) {
+  const override = typeof env.GITTENSORY_MINER_VERSION === "string" ? env.GITTENSORY_MINER_VERSION.trim() : "";
+  return override || MINER_PACKAGE_VERSION;
+}

package/lib/worktree-allocator.d.ts

@@ -0,0 +1,39 @@
+export type WorktreeAllocation = {
+  slotIndex: number;
+  worktreePath: string;
+  attemptId: string | null;
+  repoFullName: string | null;
+  status: "free" | "active";
+  ownerPid: number | null;
+  allocatedAt: string | null;
+};
+
+export type WorktreeAllocator = {
+  dbPath: string;
+  worktreeBaseDir: string;
+  maxConcurrency: number;
+  processPid: number;
+  acquire(attemptId: string, repoFullName: string): WorktreeAllocation;
+  release(attemptId: string): WorktreeAllocation | null;
+  listSlots(): WorktreeAllocation[];
+  close(): void;
+};
+
+export function resolveWorktreeAllocatorDbPath(env?: Record<string, string | undefined>): string;
+
+export function resolveWorktreeBaseDir(env?: Record<string, string | undefined>): string;
+
+export function isProcessAlive(pid: number): boolean;
+
+export function openWorktreeAllocator(options?: {
+  dbPath?: string;
+  worktreeBaseDir?: string;
+  maxConcurrency?: number;
+  processPid?: number;
+}): WorktreeAllocator;
+
+export function acquireWorktree(attemptId: string, repoFullName: string): WorktreeAllocation;
+
+export function releaseWorktree(attemptId: string): WorktreeAllocation | null;
+
+export function closeDefaultWorktreeAllocator(): void;