@loopover/miner 0.1.0

package/lib/http-retry.js

@@ -0,0 +1,52 @@
+// Bounded retry-with-backoff around a single HTTP call (#4829). The miner's pollers (ci-poller and others)
+// previously let a single brief 5xx from GitHub kill the whole poll loop, because their own attempt loop
+// only re-polls while a conclusion is genuinely "pending", never after a server error. This wraps ONE fetch so a
+// transient SERVER error (a 5xx RESPONSE) is retried a bounded number of times, DISTINCT from that pending-
+// polling, sleeping an exponential backoff between attempts and giving up after `maxAttempts`. A 2xx/3xx/4xx
+// response is returned immediately, and a THROWN error (a network-level failure) propagates unchanged rather than
+// being retried — the pollers' existing failure-mode contract (#4281) deliberately bubbles those to the caller.
+// Pure control flow over injected `fetchFn`/`sleepFn`/`backoffMs` — no real network or timers in tests.
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BASE_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 10_000;
+
+/** Clamp `maxAttempts` to a positive integer, flooring BEFORE the positivity test so a fractional value below 1
+ *  falls back to the default rather than becoming a 0 that would skip every attempt. */
+function normalizeMaxAttempts(raw) {
+  const numeric = Math.floor(Number(raw));
+  return Number.isFinite(numeric) && numeric >= 1 ? numeric : DEFAULT_MAX_ATTEMPTS;
+}
+
+/** Exponential backoff from a base delay, capped: attempt 1 → base, 2 → 2×base, 3 → 4×base, … ≤ MAX_BACKOFF_MS. */
+export function defaultRetryBackoffMs(attempt) {
+  return Math.min(MAX_BACKOFF_MS, DEFAULT_BASE_BACKOFF_MS * 2 ** (Math.max(1, attempt) - 1));
+}
+
+const defaultSleep = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs));
+
+/**
+ * Perform `fetchFn(url, init)` with bounded retry on a transient 5xx response. A 5xx is retried (sleeping
+ * `backoffMs(attempt)` between attempts) up to `maxAttempts`; a 2xx/3xx/4xx response is returned immediately, and
+ * after the last attempt a lingering 5xx is returned as-is (the caller's own error handling still runs). A THROWN
+ * error is NOT retried — it propagates to the caller (the pollers' #4281 failure-mode contract).
+ *
+ * @param {(url: any, init?: any) => Promise<any>} fetchFn
+ * @param {any} url
+ * @param {any} [init]
+ * @param {{ maxAttempts?: number, sleepFn?: (ms: number) => Promise<unknown>, backoffMs?: (attempt: number) => number }} [options]
+ * @returns {Promise<any>} the fetch response
+ */
+export async function fetchWithRetry(fetchFn, url, init, options = {}) {
+  const maxAttempts = normalizeMaxAttempts(options.maxAttempts);
+  const sleepFn = typeof options.sleepFn === "function" ? options.sleepFn : defaultSleep;
+  const backoffMs = typeof options.backoffMs === "function" ? options.backoffMs : defaultRetryBackoffMs;
+  for (let attempt = 1; ; attempt += 1) {
+    // A thrown error is intentionally NOT caught here — it propagates to the caller unchanged.
+    const response = await fetchFn(url, init);
+    // Retry only transient SERVER errors (5xx). Return 2xx/3xx/4xx immediately; on the final attempt a lingering
+    // 5xx is returned as-is.
+    if (response.status < 500 || attempt >= maxAttempts) return response;
+    await sleepFn(backoffMs(attempt));
+  }
+}

package/lib/laptop-init.d.ts

@@ -0,0 +1,53 @@
+export type LaptopInitResult = {
+  stateDir: string;
+  dbPath: string;
+  created: boolean;
+};
+
+export type DoctorCheck = {
+  name: string;
+  ok: boolean;
+  detail: string;
+};
+
+export type GithubTokenVerification = {
+  ok: boolean;
+  login: string | null;
+  scopes: string[];
+  detail: string;
+};
+
+export function resolveLaptopStateDbPath(env?: Record<string, string | undefined>): string;
+
+export function initLaptopState(env?: Record<string, string | undefined>): LaptopInitResult;
+
+export function checkLaptopStateSqlite(env?: Record<string, string | undefined>): DoctorCheck;
+
+export function findExecutableOnPath(name: string, env?: Record<string, string | undefined>): string | null;
+
+export function checkDockerPresent(options?: {
+  env?: Record<string, string | undefined>;
+  resolveDockerPath?: () => string | null;
+}): DoctorCheck;
+
+export function checkClaudeCliPresent(options?: {
+  env?: Record<string, string | undefined>;
+  resolveClaudePath?: () => string | null;
+}): DoctorCheck;
+
+export function checkCodexCliPresent(options?: {
+  env?: Record<string, string | undefined>;
+  resolveCodexPath?: () => string | null;
+  resolveCodexAuthPath?: () => string;
+}): DoctorCheck;
+
+export function resolveCodexAuthPath(env?: Record<string, string | undefined>): string;
+
+export function verifyGithubToken(options?: {
+  githubToken?: string;
+  fetchImpl?: typeof fetch;
+  apiBaseUrl?: string;
+  timeoutMs?: number;
+}): Promise<GithubTokenVerification>;
+
+export function runInit(args?: string[], env?: Record<string, string | undefined>): Promise<number>;

package/lib/laptop-init.js

@@ -0,0 +1,332 @@
+import { accessSync, chmodSync, constants, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { applySchemaMigrations } from "./schema-version.js";
+import { reportCliFailure } from "./cli-error.js";
+
+const githubApiBaseUrl = "https://api.github.com";
+const githubApiVersion = "2022-11-28";
+const classicRepoScopes = new Set(["repo", "public_repo"]);
+const defaultDbFileName = "laptop-state.sqlite3";
+
+/** Local state directory (mirrors `resolveMinerStateDir` in status.js — kept local to avoid import cycles). */
+function resolveMinerStateDir(env = process.env) {
+  const explicitConfigDir = typeof env.GITTENSORY_MINER_CONFIG_DIR === "string"
+    ? env.GITTENSORY_MINER_CONFIG_DIR.trim()
+    : "";
+  if (explicitConfigDir) return explicitConfigDir;
+
+  const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()
+    ? env.XDG_CONFIG_HOME.trim()
+    : join(homedir(), ".config");
+  return join(configHome, "gittensory-miner");
+}
+
+/** Path to the laptop-mode SQLite bootstrap file inside the miner state directory. */
+export function resolveLaptopStateDbPath(env = process.env) {
+  return join(resolveMinerStateDir(env), defaultDbFileName);
+}
+
+/** Create the state dir and SQLite file. Re-running is idempotent and never clobbers existing rows. */
+export function initLaptopState(env = process.env) {
+  const stateDir = resolveMinerStateDir(env);
+  const dbPath = resolveLaptopStateDbPath(env);
+  mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const created = !existsSync(dbPath);
+  const db = new DatabaseSync(dbPath);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS laptop_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations (none yet).
+  applySchemaMigrations(db, []);
+  if (created) {
+    db.prepare("INSERT INTO laptop_meta (key, value) VALUES ('initialized_at', ?)")
+      .run(new Date().toISOString());
+  }
+  chmodSync(dbPath, 0o600);
+  db.close();
+  return { stateDir, dbPath, created };
+}
+
+export function checkLaptopStateSqlite(env = process.env) {
+  const dbPath = resolveLaptopStateDbPath(env);
+  if (!existsSync(dbPath)) {
+    return {
+      name: "laptop-state-sqlite",
+      ok: false,
+      detail: `${dbPath}: not found (run gittensory-miner init)`,
+    };
+  }
+  try {
+    const db = new DatabaseSync(dbPath, { readonly: true });
+    db.prepare("SELECT 1").get();
+    db.close();
+    return { name: "laptop-state-sqlite", ok: true, detail: dbPath };
+  } catch (error) {
+    return {
+      name: "laptop-state-sqlite",
+      ok: false,
+      detail: `${dbPath}: ${error instanceof Error ? error.message : "not readable"}`,
+    };
+  }
+}
+
+/** Exported so callers that only need a presence boolean (e.g. status.js's `driver` section, #5164) can reuse
+ *  this PATH scan directly instead of duplicating it or parsing a DoctorCheck's detail string. */
+export function findExecutableOnPath(name, env = process.env) {
+  const pathValue = typeof env.PATH === "string" ? env.PATH : "";
+  for (const pathEntry of pathValue.split(delimiter)) {
+    if (!pathEntry) continue;
+    const candidate = join(pathEntry, name);
+    try {
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Keep scanning: PATH often contains missing or unreadable entries.
+    }
+  }
+  return null;
+}
+
+/** Informational only — Docker is never required for laptop mode. */
+export function checkDockerPresent(options = {}) {
+  const resolveDockerPath = options.resolveDockerPath
+    ?? (() => findExecutableOnPath("docker", options.env));
+  const dockerPath = resolveDockerPath();
+  return {
+    name: "docker-present",
+    ok: true,
+    detail: dockerPath ? `found at ${dockerPath}` : "not installed (optional for laptop mode)",
+  };
+}
+
+// Codex stores credentials at `$CODEX_HOME/auth.json`, else `$HOME/.codex/auth.json` — mirrors
+// resolveCodexAuthPath in src/selfhost/ai.ts, kept local so the offline miner package never imports the
+// Worker AI module. Exported so `doctor`'s provider-credential check (status.js, #5170) resolves the SAME
+// path this file's own codex auth probe uses, instead of duplicating the location logic.
+export function resolveCodexAuthPath(env = process.env) {
+  const base = env.CODEX_HOME ?? join(env.HOME ?? homedir(), ".codex");
+  return join(base, "auth.json");
+}
+
+function githubHeaders(githubToken) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "loopover-miner",
+    "x-github-api-version": githubApiVersion,
+  };
+  const token = typeof githubToken === "string" ? githubToken.trim() : "";
+  if (token) headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+
+function parseScopesHeader(scopesHeader) {
+  return typeof scopesHeader === "string" && scopesHeader.trim()
+    ? scopesHeader.split(",").map((scope) => scope.trim()).filter(Boolean)
+    : [];
+}
+
+function formatScopes(scopes) {
+  return scopes.length > 0 ? scopes.join(", ") : "none reported";
+}
+
+function hasRepoAccessScope(scopes) {
+  return scopes.some((scope) => classicRepoScopes.has(scope));
+}
+
+function readGithubErrorMessage(payload, status) {
+  if (payload && typeof payload === "object" && typeof payload.message === "string" && payload.message.trim()) {
+    return payload.message.trim();
+  }
+  return `GitHub returned HTTP ${status}`;
+}
+
+/**
+ * Validate a GitHub token with one authenticated API call.
+ *
+ * The classic OAuth scope header is advisory when GitHub reports it: if GitHub returns `repo` or
+ * `public_repo`, we treat the token as sufficiently scoped for miner setup. If GitHub omits the classic
+ * scope header altogether, the token is still considered valid and the response is reported as "scopes not
+ * reported" — that keeps fine-grained tokens usable while still surfacing the scopes GitHub did return.
+ */
+export async function verifyGithubToken(options = {}) {
+  const githubToken = typeof options.githubToken === "string" ? options.githubToken.trim() : "";
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const apiBaseUrl =
+    typeof options.apiBaseUrl === "string" && options.apiBaseUrl.trim()
+      ? options.apiBaseUrl.trim().replace(/\/+$/, "") || githubApiBaseUrl
+      : githubApiBaseUrl;
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 5000;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetchImpl(`${apiBaseUrl}/user`, {
+      method: "GET",
+      headers: githubHeaders(githubToken),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    const detail = controller.signal.aborted
+      ? `timed out after ${timeoutMs}ms`
+      : error instanceof Error
+        ? error.message
+        : "request failed";
+    return {
+      ok: false,
+      login: null,
+      scopes: [],
+      detail: `GITHUB_TOKEN verification failed: ${detail}`,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  const payload = await response.json().catch(() => null);
+  const scopesHeader = response.headers.get("x-oauth-scopes");
+  const scopesHeaderPresent = response.headers.has("x-oauth-scopes");
+  const scopes = parseScopesHeader(scopesHeader);
+  const login = payload && typeof payload === "object" && typeof payload.login === "string" ? payload.login.trim() : "";
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      login: null,
+      scopes,
+      detail: `GITHUB_TOKEN verification failed: ${readGithubErrorMessage(payload, response.status)}`,
+    };
+  }
+
+  if (scopesHeaderPresent && scopes.length === 0) {
+    return {
+      ok: false,
+      login: login || null,
+      scopes,
+      detail: "GITHUB_TOKEN is valid, but GitHub returned an empty x-oauth-scopes header; reissue it with repo access for miner setup.",
+    };
+  }
+
+  if (scopes.length > 0 && !hasRepoAccessScope(scopes)) {
+    return {
+      ok: false,
+      login: login || null,
+      scopes,
+      detail: `GITHUB_TOKEN is valid, but GitHub reported only ${formatScopes(scopes)}; reissue it with repo access for miner setup.`,
+    };
+  }
+
+  return {
+    ok: true,
+    login: login || null,
+    scopes,
+    detail:
+      scopes.length > 0
+        ? `validated GitHub token for ${login || "unknown user"}; scopes: ${formatScopes(scopes)}`
+        : `validated GitHub token for ${login || "unknown user"}; GitHub did not report classic OAuth scopes`,
+  };
+}
+
+/** A coding-agent CLI is only needed once a driver provider is configured (#4289) — gated by
+ *  `MINER_CODING_AGENT_PROVIDER` (#5165). When that provider is NOT the CLI being checked, absence is
+ *  advisory (`ok: true`), mirroring checkDockerPresent's optional tone. When it IS configured and the CLI is
+ *  missing, `ok: false` — every attempt will fail without it. The auth probe (once found) stays advisory
+ *  either way, since an unauthenticated-but-installed CLI is a separate, already-visible warning. */
+function codingAgentProviderConfiguredFor(env, providerName) {
+  return env.MINER_CODING_AGENT_PROVIDER === providerName;
+}
+
+/** Informational unless `MINER_CODING_AGENT_PROVIDER=claude-cli` (#5165), in which case a missing CLI fails
+ *  doctor. The auth probe is read-only and never spawns the CLI: it surfaces, proactively, the SAME condition
+ *  claude checks at call time — `CLAUDE_CODE_OAUTH_TOKEN` present (see createClaudeCodeAi, src/selfhost/ai.ts). */
+export function checkClaudeCliPresent(options = {}) {
+  const env = options.env ?? process.env;
+  const claudePath = (options.resolveClaudePath ?? (() => findExecutableOnPath("claude", env)))();
+  if (!claudePath) {
+    const configured = codingAgentProviderConfiguredFor(env, "claude-cli");
+    return {
+      name: "claude-cli-present",
+      ok: !configured,
+      detail: configured
+        ? "not installed — MINER_CODING_AGENT_PROVIDER is set to claude-cli, every attempt will fail without it"
+        : "not installed (optional until a coding-agent driver is configured)",
+    };
+  }
+  const authed = typeof env.CLAUDE_CODE_OAUTH_TOKEN === "string" && env.CLAUDE_CODE_OAUTH_TOKEN.length > 0;
+  return {
+    name: "claude-cli-present",
+    ok: true,
+    detail: authed ? `found at ${claudePath} (authenticated)` : `found at ${claudePath} (not authenticated: set CLAUDE_CODE_OAUTH_TOKEN)`,
+  };
+}
+
+/** Informational unless `MINER_CODING_AGENT_PROVIDER=codex-cli` (#5165), in which case a missing CLI fails
+ *  doctor — mirrors {@link checkClaudeCliPresent}. The auth probe checks the same read-only condition
+ *  assertCodexAuthConfigured uses at call time: codex's `auth.json` is readable. */
+export function checkCodexCliPresent(options = {}) {
+  const env = options.env ?? process.env;
+  const codexPath = (options.resolveCodexPath ?? (() => findExecutableOnPath("codex", env)))();
+  if (!codexPath) {
+    const configured = codingAgentProviderConfiguredFor(env, "codex-cli");
+    return {
+      name: "codex-cli-present",
+      ok: !configured,
+      detail: configured
+        ? "not installed — MINER_CODING_AGENT_PROVIDER is set to codex-cli, every attempt will fail without it"
+        : "not installed (optional until a coding-agent driver is configured)",
+    };
+  }
+  const authPath = (options.resolveCodexAuthPath ?? (() => resolveCodexAuthPath(env)))();
+  let authed = false;
+  try {
+    accessSync(authPath, constants.R_OK);
+    authed = true;
+  } catch {
+    // auth.json missing or unreadable — codex would fail for lack of credentials at call time.
+  }
+  if (authed) {
+    return { name: "codex-cli-present", ok: true, detail: `found at ${codexPath} (authenticated)` };
+  }
+  // codex-cli IS the configured driver but auth.json is missing/expired: a more specific, actionable remediation
+  // than the generic advisory below, mirroring ORB's codexAuthReadinessProbe/assertCodexAuthConfigured wording
+  // (#5166). `ok` stays true either way (unchanged by this issue, see #5165) since the CLI itself IS present --
+  // only the CLI-absent case is a hard doctor failure.
+  const detail = codingAgentProviderConfiguredFor(env, "codex-cli")
+    ? `found at ${codexPath} but auth.json is missing or expired — run \`codex auth\` to authenticate before attempts run`
+    : `found at ${codexPath} (not authenticated: run \`codex auth\`)`;
+  return { name: "codex-cli-present", ok: true, detail };
+}
+
+export async function runInit(args = [], env = process.env) {
+  const verifyToken = args.includes("--verify-token");
+  const jsonOutput = args.includes("--json");
+  let verification = null;
+  if (verifyToken) {
+    verification = await verifyGithubToken({ githubToken: env.GITHUB_TOKEN ?? "" });
+    if (!verification.ok) {
+      return reportCliFailure(jsonOutput, verification.detail, 1);
+    }
+  }
+
+  const result = initLaptopState(env);
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify(
+        verification ? { ...result, tokenVerification: verification } : result,
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log(`initialized ${result.stateDir}`);
+    console.log(`sqlite: ${result.dbPath}${result.created ? "" : " (already existed)"}`);
+    if (verification) {
+      console.log(`token: ${verification.detail}`);
+    }
+  }
+  return 0;
+}

package/lib/live-issue-snapshot.d.ts

@@ -0,0 +1,16 @@
+import type { LiveIssueSnapshot } from "./submission-freshness-check.js";
+
+// A narrower shape than `typeof fetch` on purpose: this module only ever calls it with a string URL and a
+// plain POST init, and the ambient `fetch` type in this repo's TS program is Cloudflare-Workers-flavored
+// (RequestInfo<CfProperties> | URL), which is both irrelevant here (this package runs under plain Node) and
+// stricter than any real caller needs.
+export type LiveIssueSnapshotFetch = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body: string },
+) => Promise<{ ok: boolean; status: number; json: () => Promise<unknown> }>;
+
+export function fetchLiveIssueSnapshot(
+  repoFullName: string,
+  issueNumber: number,
+  options?: { githubToken?: string; graphqlUrl?: string; fetchImpl?: LiveIssueSnapshotFetch },
+): Promise<LiveIssueSnapshot | null>;

package/lib/live-issue-snapshot.js

@@ -0,0 +1,117 @@
+// Real GitHub-backed fetchLiveIssueSnapshot (#5132, Wave 3.5). AttemptDeps.fetchLiveIssueSnapshot and
+// SubmissionFreshnessDeps.fetchLiveIssueSnapshot (submission-freshness-check.js) share this one shape:
+// "is this issue still open, and is it already addressed by another PR" -- the live-state answer
+// checkSubmissionFreshness needs before every submission. Uses GitHub's GraphQL
+// `closedByPullRequestsReferences` connection rather than a body-text/search-API heuristic: it's GitHub's
+// own authoritative, closing-keyword-aware answer to "which PRs will close this issue" -- the same signal
+// the platform itself uses to auto-close on merge, not a regex we'd have to keep in sync with GitHub's own
+// closing-keyword parsing.
+
+const DEFAULT_GRAPHQL_URL = "https://api.github.com/graphql";
+const GITHUB_API_VERSION = "2022-11-28";
+const MAX_REFERENCING_PRS = 50;
+
+const LIVE_ISSUE_SNAPSHOT_QUERY = `
+  query($owner: String!, $repo: String!, $number: Int!, $maxPrs: Int!) {
+    repository(owner: $owner, name: $repo) {
+      issue(number: $number) {
+        state
+        closedByPullRequestsReferences(first: $maxPrs) {
+          nodes {
+            number
+            state
+            author { login }
+            createdAt
+          }
+        }
+      }
+    }
+  }
+`;
+
+function githubGraphqlHeaders(githubToken) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "content-type": "application/json",
+    "user-agent": "loopover-miner",
+    "x-github-api-version": GITHUB_API_VERSION,
+  };
+  const token = typeof githubToken === "string" ? githubToken.trim() : "";
+  if (token) headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+
+function normalizeIssueOrPrState(rawState) {
+  return typeof rawState === "string" ? rawState.toLowerCase() : "";
+}
+
+function normalizeReferencingPr(node) {
+  if (!node || typeof node !== "object") return null;
+  if (!Number.isInteger(node.number) || node.number <= 0) return null;
+  const state = normalizeIssueOrPrState(node.state);
+  if (state !== "open" && state !== "closed" && state !== "merged") return null;
+  const authorLogin = typeof node.author?.login === "string" ? node.author.login : "";
+  // GitHub's real PR creation timestamp (ISO 8601), when present -- null otherwise (never fabricated). Not
+  // an ordering signal for the maintainer gate's own duplicate-cluster election (duplicate-winner.ts's own
+  // doc explains why: a PR can be backdated by editing an old placeholder to add the linked issue later), but
+  // it's the only real, publicly-observable claim-time proxy claim-conflict-resolver.js's own client-side
+  // caller has for a THIRD-PARTY PR -- unlike gittensory's own server, the miner has no continuous observation
+  // history to derive a true "first linked" timestamp from.
+  const createdAt = typeof node.createdAt === "string" ? node.createdAt : null;
+  return { number: node.number, state, authorLogin, createdAt };
+}
+
+function parseRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") return null;
+  const [owner, repo, extra] = repoFullName.split("/");
+  if (!owner || !repo || extra !== undefined) return null;
+  return { owner, repo };
+}
+
+/**
+ * Real fetchLiveIssueSnapshot implementation: the live-state answer AttemptDeps/SubmissionFreshnessDeps
+ * need, built from a single GraphQL round-trip. Returns null on any malformed input, transport failure, or
+ * unrecognized GitHub response -- callers already treat a null snapshot as "state unavailable", so this
+ * never throws.
+ *
+ * @param {string} repoFullName
+ * @param {number} issueNumber
+ * @param {{ githubToken?: string, graphqlUrl?: string, fetchImpl?: typeof fetch }} [options]
+ * @returns {Promise<import("./submission-freshness-check.js").LiveIssueSnapshot | null>}
+ */
+export async function fetchLiveIssueSnapshot(repoFullName, issueNumber, options = {}) {
+  const target = parseRepoFullName(repoFullName);
+  if (!target || !Number.isInteger(issueNumber) || issueNumber <= 0) return null;
+
+  const graphqlUrl =
+    typeof options.graphqlUrl === "string" && options.graphqlUrl.trim() ? options.graphqlUrl.trim() : DEFAULT_GRAPHQL_URL;
+  const githubToken = options.githubToken ?? process.env.GITHUB_TOKEN ?? "";
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  let response;
+  try {
+    response = await fetchImpl(graphqlUrl, {
+      method: "POST",
+      headers: githubGraphqlHeaders(githubToken),
+      body: JSON.stringify({
+        query: LIVE_ISSUE_SNAPSHOT_QUERY,
+        variables: { owner: target.owner, repo: target.repo, number: issueNumber, maxPrs: MAX_REFERENCING_PRS },
+      }),
+    });
+  } catch {
+    return null;
+  }
+  if (!response.ok) return null;
+
+  const payload = await response.json().catch(() => null);
+  if (!payload || typeof payload !== "object" || payload.errors) return null;
+
+  const issue = payload.data?.repository?.issue;
+  const state = normalizeIssueOrPrState(issue?.state);
+  if (state !== "open" && state !== "closed") return null;
+
+  const nodes = Array.isArray(issue?.closedByPullRequestsReferences?.nodes) ? issue.closedByPullRequestsReferences.nodes : [];
+  const referencingPrs = nodes.map(normalizeReferencingPr).filter((pr) => pr !== null);
+
+  return { state, referencingPrs };
+}

package/lib/local-store.d.ts

@@ -0,0 +1,18 @@
+import type { DatabaseSync } from "node:sqlite";
+
+export function resolveLocalStoreDbPath(
+  defaultDbFileName: string,
+  explicitEnvVarName: string,
+  env?: Record<string, string | undefined>,
+): string;
+
+export function normalizeLocalStoreDbPath(
+  dbPath: string | null | undefined,
+  resolvedDefault: string,
+  invalidPathError: string,
+): string;
+
+export function openLocalStoreDb(
+  resolvedPath: string,
+  options?: { busyTimeoutMs?: number },
+): DatabaseSync;

package/lib/local-store.js

@@ -0,0 +1,62 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { registerCleanupResource } from "./process-lifecycle.js";
+
+// Shared path-resolution + DB-open boilerplate for the package's local SQLite stores (#4272). This is a DRY pass
+// only, not a merge: run-state.js, claim-ledger.js, portfolio-queue.js, and event-ledger.js each keep their own
+// `.sqlite3` file, table, and env var — this module just extracts the ~15 lines each hand-duplicated
+// (env-var/config-dir/XDG path resolution, mkdirSync(0o700) + chmodSync(0o600), and `PRAGMA busy_timeout`).
+
+/**
+ * Resolve a local store's DB path from, in order: an explicit env var, `GITTENSORY_MINER_CONFIG_DIR`,
+ * `XDG_CONFIG_HOME` (falling back to `~/.config`) — mirroring every store's prior hand-written resolver.
+ */
+export function resolveLocalStoreDbPath(defaultDbFileName, explicitEnvVarName, env = process.env) {
+  const explicitPath = typeof env[explicitEnvVarName] === "string" ? env[explicitEnvVarName].trim() : "";
+  if (explicitPath) return explicitPath;
+
+  const explicitConfigDir = typeof env.GITTENSORY_MINER_CONFIG_DIR === "string"
+    ? env.GITTENSORY_MINER_CONFIG_DIR.trim()
+    : "";
+  if (explicitConfigDir) return join(explicitConfigDir, defaultDbFileName);
+
+  const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()
+    ? env.XDG_CONFIG_HOME.trim()
+    : join(homedir(), ".config");
+  return join(configHome, "gittensory-miner", defaultDbFileName);
+}
+
+/** Trim and validate a caller-supplied (or resolved-default) DB path, throwing `invalidPathError` if it is empty. */
+export function normalizeLocalStoreDbPath(dbPath, resolvedDefault, invalidPathError) {
+  const raw = dbPath ?? resolvedDefault;
+  if (typeof raw !== "string" || !raw.trim()) throw new Error(invalidPathError);
+  return raw.trim();
+}
+
+/**
+ * Open (creating parent dirs on first use) a local store's SQLite file with 0700/0600 permissions and a shared
+ * busy-timeout, so two instances of the same store on one file serialize writes instead of racing. Skips the
+ * mkdir/chmod steps for the special `:memory:` path, which has no on-disk file. `run-state.js` previously opened
+ * its DB with no busy-timeout at all (the one inconsistency among the four stores this issue found); folding it
+ * through this shared helper gives it the same wait-don't-fail behavior the other three already had.
+ */
+export function openLocalStoreDb(resolvedPath, options = {}) {
+  const busyTimeoutMs = options.busyTimeoutMs ?? 5000;
+  const isMemory = resolvedPath === ":memory:";
+  if (!isMemory) mkdirSync(dirname(resolvedPath), { recursive: true, mode: 0o700 });
+  const db = new DatabaseSync(resolvedPath);
+  if (!isMemory) chmodSync(resolvedPath, 0o600);
+  db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+  // Crash-safety (#4826): register every opened store so a SIGINT/SIGTERM/uncaught-exception handler can close it
+  // mid-run instead of leaving it half-written. The normal `close()` unregisters first, so the happy path never
+  // double-closes and a long-running `loop` doesn't accumulate stale references.
+  const unregister = registerCleanupResource(db);
+  const originalClose = db.close.bind(db);
+  db.close = () => {
+    unregister();
+    return originalClose();
+  };
+  return db;
+}