@loopover/miner 0.1.0

package/lib/plan-store.js

@@ -0,0 +1,231 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { applySchemaMigrations } from "./schema-version.js";
+
+// Local SQLite persistence for the stateless MCP plan DAG (#2318). `gittensory_build_plan`/`plan_status`/
+// `record_step_result` are stateless — the caller holds the plan and passes it back each call — so a miner running
+// unattended across process restarts needs somewhere to persist the plan object between calls. This is local-only
+// bookkeeping (no plan logic, no network), 100% client-side, mirroring the package's other local stores. Every
+// plan is validated against the `planDagSchema` shape (src/mcp/server.ts) on BOTH save and load, so a corrupted
+// local row fails loudly instead of feeding a malformed plan back into `gittensory_plan_status`.
+
+const PLAN_STEP_STATUSES = Object.freeze(["pending", "running", "completed", "failed", "skipped"]);
+/** Derived plan-level status used for `listPlans({ status })`. */
+export const PLAN_STATUSES = Object.freeze(["pending", "running", "completed", "failed"]);
+
+const stepStatusSet = new Set(PLAN_STEP_STATUSES);
+const planStatusSet = new Set(PLAN_STATUSES);
+const defaultDbFileName = "plan-store.sqlite3";
+let defaultPlanStore = null;
+
+export function resolvePlanStoreDbPath(env = process.env) {
+  const explicitPath = typeof env.GITTENSORY_MINER_PLAN_STORE_DB === "string"
+    ? env.GITTENSORY_MINER_PLAN_STORE_DB.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);
+}
+
+function normalizeDbPath(dbPath) {
+  const raw = dbPath ?? resolvePlanStoreDbPath();
+  if (typeof raw !== "string" || !raw.trim()) throw new Error("invalid_plan_store_db_path");
+  return raw.trim();
+}
+
+function normalizePlanId(planId) {
+  if (typeof planId !== "string" || !planId.trim()) throw new Error("invalid_plan_id");
+  return planId.trim();
+}
+
+function normalizePlanStatusFilter(status) {
+  if (status === undefined || status === null) return undefined;
+  if (!planStatusSet.has(status)) throw new Error("invalid_status");
+  return status;
+}
+
+function isBoundedString(value, min, max) {
+  return typeof value === "string" && value.length >= min && value.length <= max;
+}
+
+function isBoundedInt(value, min, max) {
+  return Number.isInteger(value) && value >= min && value <= max;
+}
+
+const STEP_KEYS = new Set(["id", "title", "actionClass", "dependsOn", "status", "attempts", "maxAttempts", "lastError"]);
+
+function isValidStep(step) {
+  if (!step || typeof step !== "object" || Array.isArray(step)) return false;
+  for (const key of Object.keys(step)) if (!STEP_KEYS.has(key)) return false; // strict: no unknown keys
+  if (!isBoundedString(step.id, 1, 100) || !isBoundedString(step.title, 1, 300)) return false;
+  if (step.actionClass !== undefined && !isBoundedString(step.actionClass, 1, 60)) return false;
+  if (!Array.isArray(step.dependsOn) || step.dependsOn.length > 50) return false;
+  if (!step.dependsOn.every((dep) => isBoundedString(dep, 1, 100))) return false;
+  if (!stepStatusSet.has(step.status)) return false;
+  if (!isBoundedInt(step.attempts, 0, Number.MAX_SAFE_INTEGER)) return false;
+  if (!isBoundedInt(step.maxAttempts, 1, 10)) return false;
+  if (step.lastError !== undefined && step.lastError !== null && !isBoundedString(step.lastError, 0, 2000)) return false;
+  return true;
+}
+
+/** Validate a plan against the `planDagSchema` shape (strict `{ steps: PlanStep[] }`, ≤100 steps). Throws on any
+ *  malformed field so a bad plan can neither be saved nor read back. */
+function validatePlanDag(plan) {
+  if (!plan || typeof plan !== "object" || Array.isArray(plan)) throw new Error("invalid_plan");
+  const keys = Object.keys(plan);
+  if (keys.length !== 1 || keys[0] !== "steps") throw new Error("invalid_plan");
+  if (!Array.isArray(plan.steps) || plan.steps.length === 0 || plan.steps.length > 100) {
+    throw new Error("invalid_plan");
+  }
+  if (!plan.steps.every(isValidStep)) throw new Error("invalid_plan");
+  const seenStepIds = new Set();
+  for (const step of plan.steps) {
+    if (seenStepIds.has(step.id)) throw new Error("invalid_plan");
+    seenStepIds.add(step.id);
+  }
+  for (const step of plan.steps) {
+    for (const dep of step.dependsOn) {
+      if (dep === step.id || !seenStepIds.has(dep)) throw new Error("invalid_plan");
+    }
+  }
+  const color = new Map();
+  const byId = new Map(plan.steps.map((step) => [step.id, step]));
+  const hasCycle = (id) => {
+    color.set(id, 1);
+    for (const dep of byId.get(id)?.dependsOn ?? []) {
+      const depColor = color.get(dep) ?? 0;
+      if (depColor === 1) return true;
+      if (depColor === 0 && byId.has(dep) && hasCycle(dep)) return true;
+    }
+    color.set(id, 2);
+    return false;
+  };
+  for (const step of plan.steps) {
+    if ((color.get(step.id) ?? 0) === 0 && hasCycle(step.id)) {
+      throw new Error("invalid_plan");
+    }
+  }
+  return plan;
+}
+
+/** Derive a plan-level status from its steps: any failed → failed; else any running → running; else all steps
+ *  finished (completed/skipped) with at least one step → completed; otherwise pending. */
+function computePlanStatus(plan) {
+  const steps = plan.steps;
+  if (steps.some((step) => step.status === "failed")) return "failed";
+  if (steps.some((step) => step.status === "running")) return "running";
+  if (steps.length > 0 && steps.every((step) => step.status === "completed" || step.status === "skipped")) {
+    return "completed";
+  }
+  return "pending";
+}
+
+function rowToRecord(row) {
+  let plan;
+  try {
+    plan = validatePlanDag(JSON.parse(row.plan_json));
+  } catch {
+    throw new Error("corrupted_plan_row"); // stored blob no longer matches the plan shape
+  }
+  // Also fail closed on the status column: a manually-edited or legacy row (predating the CHECK constraint) could
+  // hold a status outside PLAN_STATUSES, which would otherwise violate the exported PlanRecord contract on read.
+  if (!planStatusSet.has(row.status)) throw new Error("corrupted_plan_row");
+  return { planId: row.plan_id, plan, status: row.status, updatedAt: row.updated_at };
+}
+
+/**
+ * Opens the local plan store, creating the table on first use. `savePlan` is a single atomic INSERT…ON CONFLICT
+ * upsert keyed by `plan_id`; the plan JSON is validated on save AND re-validated on load, so a corrupted row is
+ * rejected rather than silently returned. (#2318)
+ */
+export function openPlanStore(dbPath = resolvePlanStoreDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  // The store is a persistent local file; the special in-memory path (':memory:') has no file to create or chmod.
+  if (resolvedPath !== ":memory:") {
+    mkdirSync(dirname(resolvedPath), { recursive: true, mode: 0o700 });
+  }
+  const db = new DatabaseSync(resolvedPath);
+  if (resolvedPath !== ":memory:") chmodSync(resolvedPath, 0o600);
+  db.exec("PRAGMA busy_timeout = 5000");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS miner_plans (
+      plan_id TEXT PRIMARY KEY,
+      plan_json TEXT NOT NULL,
+      status TEXT NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed')),
+      updated_at TEXT NOT NULL
+    )
+  `);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations (none yet).
+  applySchemaMigrations(db, []);
+
+  const saveStatement = db.prepare(`
+    INSERT INTO miner_plans (plan_id, plan_json, status, updated_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(plan_id) DO UPDATE SET
+      plan_json = excluded.plan_json,
+      status = excluded.status,
+      updated_at = excluded.updated_at
+  `);
+  const getStatement = db.prepare("SELECT * FROM miner_plans WHERE plan_id = ?");
+  const listAllStatement = db.prepare("SELECT * FROM miner_plans ORDER BY plan_id ASC");
+  const listStatusStatement = db.prepare("SELECT * FROM miner_plans WHERE status = ? ORDER BY plan_id ASC");
+
+  return {
+    dbPath: resolvedPath,
+    savePlan(planId, plan) {
+      const id = normalizePlanId(planId);
+      validatePlanDag(plan);
+      const status = computePlanStatus(plan);
+      const updatedAt = new Date().toISOString();
+      saveStatement.run(id, JSON.stringify(plan), status, updatedAt);
+      return { planId: id, plan, status, updatedAt };
+    },
+    loadPlan(planId) {
+      const row = getStatement.get(normalizePlanId(planId));
+      return row ? rowToRecord(row) : null;
+    },
+    listPlans(filter = {}) {
+      const status = normalizePlanStatusFilter(filter.status);
+      if (status !== undefined) {
+        return listStatusStatement.all(status).map(rowToRecord);
+      }
+      return listAllStatement.all().map(rowToRecord);
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+function getDefaultPlanStore() {
+  defaultPlanStore ??= openPlanStore();
+  return defaultPlanStore;
+}
+
+export function savePlan(planId, plan) {
+  return getDefaultPlanStore().savePlan(planId, plan);
+}
+
+export function loadPlan(planId) {
+  return getDefaultPlanStore().loadPlan(planId);
+}
+
+export function listPlans(filter) {
+  return getDefaultPlanStore().listPlans(filter);
+}
+
+export function closeDefaultPlanStore() {
+  if (!defaultPlanStore) return;
+  defaultPlanStore.close();
+  defaultPlanStore = null;
+}

package/lib/policy-doc-cache.d.ts

@@ -0,0 +1,25 @@
+export type PolicyDocCacheEntry = {
+  etag: string;
+  content: string;
+};
+
+export type PolicyDocCacheWrite = {
+  url: string;
+  etag: string;
+  content: string;
+  updatedAt: string;
+};
+
+export type PolicyDocCacheStore = {
+  dbPath: string;
+  get(url: string): PolicyDocCacheEntry | null;
+  put(url: string, etag: string, content: string): PolicyDocCacheWrite;
+  close(): void;
+};
+
+/** The read/write surface opportunity-fanout.js needs to inject a cache without depending on the SQLite store. */
+export type PolicyDocCache = Pick<PolicyDocCacheStore, "get" | "put">;
+
+export function resolvePolicyDocCacheDbPath(env?: Record<string, string | undefined>): string;
+
+export function initPolicyDocCacheStore(dbPath?: string): PolicyDocCacheStore;

package/lib/policy-doc-cache.js

@@ -0,0 +1,79 @@
+import { normalizeLocalStoreDbPath, openLocalStoreDb, resolveLocalStoreDbPath } from "./local-store.js";
+import { applySchemaMigrations } from "./schema-version.js";
+
+// Local ETag cache for discovery's small policy-doc fetches (#4842). `discover` refetches each target repo's
+// AI-USAGE.md/CONTRIBUTING.md on every run even though they rarely change, spending rate-limit budget on static
+// content; this store lets opportunity-fanout.js revalidate with a conditional GET (If-None-Match) instead, and
+// GitHub answers an unchanged doc with a 304 that costs no primary rate-limit budget. A 304 is a GitHub-confirmed
+// unchanged body -- the cached content is only ever served AFTER a same-run revalidation, never blindly -- so this
+// can never surface a stale policy that would wrongly permit autonomous work on an opted-out repo. Same 100%
+// local/client-side discipline (mirrors run-state.js and the other stores this package owns via local-store.js):
+// the file lives only on this machine and is never uploaded, synced, or phoned home with.
+
+const defaultDbFileName = "policy-doc-cache.sqlite3";
+
+export function resolvePolicyDocCacheDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_POLICY_DOC_CACHE_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolvePolicyDocCacheDbPath(), "invalid_policy_doc_cache_db_path");
+}
+
+function normalizeUrl(url) {
+  if (typeof url !== "string") throw new Error("invalid_policy_doc_url");
+  const trimmed = url.trim();
+  if (!trimmed) throw new Error("invalid_policy_doc_url");
+  return trimmed;
+}
+
+/**
+ * Opens the 100% local/client-side miner policy-doc ETag cache. The database only lives on this machine; this
+ * module never uploads, syncs, or phones home with its contents. (#4842)
+ */
+export function initPolicyDocCacheStore(dbPath = resolvePolicyDocCacheDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  const db = openLocalStoreDb(resolvedPath);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS policy_doc_cache (
+      url TEXT PRIMARY KEY,
+      etag TEXT NOT NULL,
+      content TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations (none yet).
+  applySchemaMigrations(db, []);
+
+  const getStatement = db.prepare("SELECT etag, content FROM policy_doc_cache WHERE url = ?");
+  const putStatement = db.prepare(`
+    INSERT INTO policy_doc_cache (url, etag, content, updated_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(url) DO UPDATE SET
+      etag = excluded.etag,
+      content = excluded.content,
+      updated_at = excluded.updated_at
+  `);
+
+  return {
+    dbPath: resolvedPath,
+    /** The last-known `{ etag, content }` for a policy-doc URL, or null when it has never been cached. Both columns
+     *  are `TEXT NOT NULL`, so a present row always carries string values. */
+    get(url) {
+      const row = getStatement.get(normalizeUrl(url));
+      return row ? { etag: row.etag, content: row.content } : null;
+    },
+    /** Record the fresh ETag + body so the next run can revalidate it with a conditional GET. */
+    put(url, etag, content) {
+      const normalizedUrl = normalizeUrl(url);
+      if (typeof etag !== "string" || !etag.trim()) throw new Error("invalid_policy_doc_etag");
+      if (typeof content !== "string") throw new Error("invalid_policy_doc_content");
+      const updatedAt = new Date().toISOString();
+      putStatement.run(normalizedUrl, etag, content, updatedAt);
+      return { url: normalizedUrl, etag, content, updatedAt };
+    },
+    close() {
+      db.close();
+    },
+  };
+}

package/lib/policy-verdict-cache.d.ts

@@ -0,0 +1,35 @@
+import type { AiPolicyVerdict } from "@loopover/engine";
+
+export type PolicyVerdictDecisiveDoc = "AI-USAGE.md" | "CONTRIBUTING.md";
+
+export type PolicyVerdictCacheEntry = {
+  decisiveDoc: PolicyVerdictDecisiveDoc;
+  etag: string;
+  verdict: AiPolicyVerdict;
+};
+
+export type PolicyVerdictCacheWrite = PolicyVerdictCacheEntry & {
+  repoScope: string;
+  updatedAt: string;
+};
+
+export type PolicyVerdictCacheStore = {
+  dbPath: string;
+  /** `repoScope` must uniquely identify a tenant forge host + repo (see `policyVerdictCacheKey` in
+   *  opportunity-fanout.js) -- a bare `owner/repo` is not safe across multiple forge hosts. */
+  get(repoScope: string): PolicyVerdictCacheEntry | null;
+  put(
+    repoScope: string,
+    decisiveDoc: PolicyVerdictDecisiveDoc,
+    etag: string,
+    verdict: AiPolicyVerdict,
+  ): PolicyVerdictCacheWrite;
+  close(): void;
+};
+
+/** The read/write surface opportunity-fanout.js needs to inject a cache without depending on the SQLite store. */
+export type PolicyVerdictCache = Pick<PolicyVerdictCacheStore, "get" | "put">;
+
+export function resolvePolicyVerdictCacheDbPath(env?: Record<string, string | undefined>): string;
+
+export function initPolicyVerdictCacheStore(dbPath?: string): PolicyVerdictCacheStore;

package/lib/policy-verdict-cache.js

@@ -0,0 +1,106 @@
+import { normalizeLocalStoreDbPath, openLocalStoreDb, resolveLocalStoreDbPath } from "./local-store.js";
+import { applySchemaMigrations } from "./schema-version.js";
+
+// Local cache of resolved AI-usage-policy verdicts (#4843). Even with #4842's conditional-GET doc cache, the small
+// but non-zero cost of resolving `resolveAiPolicyVerdict` from raw doc text was still paid on every discover run.
+// This stores the verdict itself, keyed by repo SCOPE (the tenant's `apiBaseUrl` plus `owner/repo` -- see
+// `policyVerdictCacheKey` in opportunity-fanout.js, same "the caller owns what makes a cache key" precedent as
+// policy-doc-cache.js keying on the full request URL) + the ETag of whichever doc actually decided it, so a
+// repeat run against an unchanged repo reuses the prior verdict outright once opportunity-fanout.js's same-run
+// conditional-GET confirms that doc's ETag hasn't moved -- never served blindly, exactly the same "cheaper, never
+// less correct" discipline as policy-doc-cache.js. `owner/repo` alone is NOT a safe key: two different tenant
+// forge hosts can each have their own unrelated `acme/widgets`, and without the host in the key a verdict
+// resolved against one host's docs could be served for the other's. 100% local/client-side, same as every other
+// store this package owns via local-store.js: the file lives only on this machine and is never uploaded, synced,
+// or phoned home with.
+
+const defaultDbFileName = "policy-verdict-cache.sqlite3";
+const DECISIVE_DOCS = new Set(["AI-USAGE.md", "CONTRIBUTING.md"]);
+
+export function resolvePolicyVerdictCacheDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_POLICY_VERDICT_CACHE_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolvePolicyVerdictCacheDbPath(), "invalid_policy_verdict_cache_db_path");
+}
+
+function normalizeRepoScope(repoScope) {
+  if (typeof repoScope !== "string") throw new Error("invalid_policy_verdict_repo_scope");
+  const trimmed = repoScope.trim();
+  if (!trimmed) throw new Error("invalid_policy_verdict_repo_scope");
+  return trimmed;
+}
+
+function normalizeDecisiveDoc(decisiveDoc) {
+  if (!DECISIVE_DOCS.has(decisiveDoc)) throw new Error("invalid_policy_verdict_decisive_doc");
+  return decisiveDoc;
+}
+
+function normalizeEtag(etag) {
+  if (typeof etag !== "string" || !etag.trim()) throw new Error("invalid_policy_verdict_etag");
+  return etag;
+}
+
+function serializeVerdict(verdict) {
+  if (!verdict || typeof verdict !== "object" || Array.isArray(verdict)) {
+    throw new Error("invalid_policy_verdict");
+  }
+  return JSON.stringify(verdict);
+}
+
+/**
+ * Opens the 100% local/client-side miner policy-verdict cache. The database only lives on this machine; this
+ * module never uploads, syncs, or phones home with its contents. (#4843)
+ */
+export function initPolicyVerdictCacheStore(dbPath = resolvePolicyVerdictCacheDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  const db = openLocalStoreDb(resolvedPath);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS policy_verdict_cache (
+      repo_scope TEXT PRIMARY KEY,
+      decisive_doc TEXT NOT NULL,
+      etag TEXT NOT NULL,
+      verdict TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+  // Schema-version convention (#4832): stamp the baseline and run any post-baseline migrations (none yet).
+  applySchemaMigrations(db, []);
+
+  const getStatement = db.prepare(
+    "SELECT decisive_doc, etag, verdict FROM policy_verdict_cache WHERE repo_scope = ?",
+  );
+  const putStatement = db.prepare(`
+    INSERT INTO policy_verdict_cache (repo_scope, decisive_doc, etag, verdict, updated_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(repo_scope) DO UPDATE SET
+      decisive_doc = excluded.decisive_doc,
+      etag = excluded.etag,
+      verdict = excluded.verdict,
+      updated_at = excluded.updated_at
+  `);
+
+  return {
+    dbPath: resolvedPath,
+    /** The last-known `{ decisiveDoc, etag, verdict }` for a repo scope, or null when it has never been cached. */
+    get(repoScope) {
+      const row = getStatement.get(normalizeRepoScope(repoScope));
+      if (!row) return null;
+      return { decisiveDoc: row.decisive_doc, etag: row.etag, verdict: JSON.parse(row.verdict) };
+    },
+    /** Record the resolved verdict against the ETag of the doc that decided it, so the next run can reuse it. */
+    put(repoScope, decisiveDoc, etag, verdict) {
+      const normalizedRepoScope = normalizeRepoScope(repoScope);
+      const normalizedDecisiveDoc = normalizeDecisiveDoc(decisiveDoc);
+      const normalizedEtag = normalizeEtag(etag);
+      const serializedVerdict = serializeVerdict(verdict);
+      const updatedAt = new Date().toISOString();
+      putStatement.run(normalizedRepoScope, normalizedDecisiveDoc, normalizedEtag, serializedVerdict, updatedAt);
+      return { repoScope: normalizedRepoScope, decisiveDoc: normalizedDecisiveDoc, etag: normalizedEtag, verdict, updatedAt };
+    },
+    close() {
+      db.close();
+    },
+  };
+}

package/lib/portfolio-dashboard.d.ts

@@ -0,0 +1,30 @@
+export interface PortfolioRepoSummary {
+  repoFullName: string;
+  byStatus: { queued: number; in_progress: number; done: number };
+  total: number;
+}
+
+export interface PortfolioDashboardSummary {
+  total: number;
+  byStatus: { queued: number; in_progress: number; done: number };
+  repos: PortfolioRepoSummary[];
+  oldestQueuedAgeMs: number | null;
+}
+
+export interface PortfolioDashboardSources {
+  portfolioQueue: { listQueue(repoFullName?: string | null): unknown[] };
+}
+
+export function collectPortfolioDashboard(
+  sources: PortfolioDashboardSources,
+  options?: { nowMs?: number },
+): PortfolioDashboardSummary;
+
+export function renderPortfolioDashboardTable(summary: PortfolioDashboardSummary | null | undefined): string;
+
+export function parsePortfolioDashboardArgs(args?: string[]): { json: boolean } | { error: string };
+
+export function runPortfolioDashboard(
+  args?: string[],
+  options?: { initPortfolioQueue?: () => { listQueue(repoFullName: string | null): unknown[]; close(): void }; nowMs?: number },
+): number;

package/lib/portfolio-dashboard.js

@@ -0,0 +1,105 @@
+// Read-only portfolio-queue dashboard (#4287). Aggregates the miner's OWN local portfolio-queue backlog
+// (packages/gittensory-miner/lib/portfolio-queue.js) into summary stats — counts by status globally and per repo,
+// plus the oldest queued item's age. Same three-layer shape as manage-status.js (pure collect → pure render → thin
+// CLI glue), but scoped to the backlog/queue rather than per-PR manage state. 100% client-side, read-only — it never
+// mutates queue state and never gates or enforces anything.
+//
+// The extension-panel half named in the issue is a forward dependency, not delivered here: the miner's queue is a
+// local SQLite file with no local-reachable channel a GitHub-page content script can read today. The pure
+// collector below is factored so it is directly reusable once such a channel exists.
+
+import { initPortfolioQueueStore } from "./portfolio-queue.js";
+import { argsWantJson, reportCliFailure } from "./cli-error.js";
+
+const QUEUE_STATUS_KEYS = ["queued", "in_progress", "done"];
+
+function emptyCounts() {
+  return { queued: 0, in_progress: 0, done: 0 };
+}
+
+/**
+ * Pure aggregator over an injected portfolio-queue store (mirrors manage-status.js's `collectManageStatus`).
+ * Read-only. Returns global + per-repo status counts and, when a clock is supplied via `options.nowMs`, the age in
+ * ms of the oldest still-`queued` item (null when no clock is given or nothing is queued).
+ */
+export function collectPortfolioDashboard(sources, options = {}) {
+  const portfolioQueue = sources?.portfolioQueue;
+  if (!portfolioQueue || typeof portfolioQueue.listQueue !== "function") throw new Error("invalid_portfolio_queue");
+  const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : null;
+
+  const byStatus = emptyCounts();
+  const perRepo = new Map();
+  let total = 0;
+  let oldestQueuedMs = null;
+
+  for (const entry of portfolioQueue.listQueue(null)) {
+    const status = entry?.status;
+    if (!QUEUE_STATUS_KEYS.includes(status)) continue;
+    const repoFullName = typeof entry.repoFullName === "string" ? entry.repoFullName : "";
+    total += 1;
+    byStatus[status] += 1;
+    let repo = perRepo.get(repoFullName);
+    if (!repo) {
+      repo = { repoFullName, byStatus: emptyCounts(), total: 0 };
+      perRepo.set(repoFullName, repo);
+    }
+    repo.byStatus[status] += 1;
+    repo.total += 1;
+    if (status === "queued") {
+      const ms = Date.parse(entry.enqueuedAt);
+      if (Number.isFinite(ms) && (oldestQueuedMs === null || ms < oldestQueuedMs)) oldestQueuedMs = ms;
+    }
+  }
+
+  const repos = [...perRepo.values()].sort((left, right) => left.repoFullName.localeCompare(right.repoFullName));
+  const oldestQueuedAgeMs = nowMs !== null && oldestQueuedMs !== null ? Math.max(0, nowMs - oldestQueuedMs) : null;
+  return { total, byStatus, repos, oldestQueuedAgeMs };
+}
+
+/** Plain-text render of a dashboard summary (mirrors manage-status.js's `renderManageStatusTable`). */
+export function renderPortfolioDashboardTable(summary) {
+  if (!summary || summary.total === 0) return "portfolio queue is empty";
+  const age = summary.oldestQueuedAgeMs !== null ? `  oldest-queued: ${Math.round(summary.oldestQueuedAgeMs / 60000)}m` : "";
+  const header = ["repo".padEnd(28), "queued".padStart(7), "in_prog".padStart(8), "done".padStart(6), "total".padStart(6)].join(" ");
+  const lines = summary.repos.map((repo) =>
+    [
+      repo.repoFullName.padEnd(28),
+      String(repo.byStatus.queued).padStart(7),
+      String(repo.byStatus.in_progress).padStart(8),
+      String(repo.byStatus.done).padStart(6),
+      String(repo.total).padStart(6),
+    ].join(" "),
+  );
+  return [
+    `total: ${summary.total}  queued: ${summary.byStatus.queued}  in_progress: ${summary.byStatus.in_progress}  done: ${summary.byStatus.done}${age}`,
+    "",
+    header,
+    ...lines,
+  ].join("\n");
+}
+
+export function parsePortfolioDashboardArgs(args = []) {
+  for (const token of args) {
+    if (token === "--json") continue;
+    if (token.startsWith("-")) return { error: `Unknown option: ${token}` };
+    return { error: "Usage: gittensory-miner queue dashboard [--json]" };
+  }
+  return { json: args.includes("--json") };
+}
+
+/** CLI glue for `gittensory-miner queue dashboard [--json]` (mirrors manage-status.js's `runManageStatus`). */
+export function runPortfolioDashboard(args = [], options = {}) {
+  const parsed = parsePortfolioDashboardArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+  const ownsQueue = options.initPortfolioQueue === undefined;
+  const portfolioQueue = (options.initPortfolioQueue ?? initPortfolioQueueStore)();
+  try {
+    const summary = collectPortfolioDashboard({ portfolioQueue }, { nowMs: Number.isFinite(options.nowMs) ? options.nowMs : Date.now() });
+    console.log(parsed.json ? JSON.stringify(summary, null, 2) : renderPortfolioDashboardTable(summary));
+    return 0;
+  } finally {
+    if (ownsQueue) portfolioQueue.close();
+  }
+}

package/lib/portfolio-discovery.d.ts

@@ -0,0 +1,29 @@
+import type { EventLedger } from "./event-ledger.js";
+import type { PortfolioQueueStore } from "./portfolio-queue.js";
+
+export type EnqueueRankedDiscoveryInput = {
+  repoFullName: string;
+  issueNumber: number;
+  title: string;
+  labels?: string[];
+  rankScore: number;
+};
+
+export type EnqueueRankedDiscoveryOptions = {
+  queueStore: PortfolioQueueStore;
+  eventLedger?: EventLedger;
+  minRankScore?: number | null;
+  apiBaseUrl?: string;
+};
+
+export type EnqueueRankedDiscoverySummary = {
+  enqueued: number;
+  skippedBelowMinRank: number;
+  skippedInvalid: number;
+  eventsAppended: number;
+};
+
+export function enqueueRankedDiscovery(
+  rankedIssues: readonly EnqueueRankedDiscoveryInput[],
+  options: EnqueueRankedDiscoveryOptions,
+): EnqueueRankedDiscoverySummary;