@loopover/miner 0.1.0

package/lib/portfolio-discovery.js

@@ -0,0 +1,100 @@
+/** Local orchestration: materialize ranked fan-out rows into the portfolio queue (#2292). */
+
+function normalizeMinRankScore(minRankScore) {
+  if (minRankScore === undefined || minRankScore === null) return 0;
+  if (typeof minRankScore !== "number" || !Number.isFinite(minRankScore) || minRankScore < 0) {
+    throw new Error("invalid_min_rank_score");
+  }
+  return minRankScore;
+}
+
+function normalizeRankedIssue(issue) {
+  if (!issue || typeof issue !== "object") return null;
+  const repoFullName = typeof issue.repoFullName === "string" ? issue.repoFullName.trim() : "";
+  const [owner, repo, extra] = repoFullName.split("/");
+  if (!owner || !repo || extra !== undefined) return null;
+  if (!Number.isInteger(issue.issueNumber) || issue.issueNumber <= 0) return null;
+  if (typeof issue.rankScore !== "number" || !Number.isFinite(issue.rankScore) || issue.rankScore < 0) {
+    return null;
+  }
+  const title = typeof issue.title === "string" ? issue.title.trim() : "";
+  if (!title) return null;
+  const labels = Array.isArray(issue.labels)
+    ? issue.labels.filter((label) => typeof label === "string" && label.trim()).map((label) => label.trim())
+    : [];
+  return {
+    repoFullName: `${owner}/${repo}`,
+    issueNumber: issue.issueNumber,
+    title,
+    labels,
+    rankScore: issue.rankScore,
+  };
+}
+
+/**
+ * Enqueue ranked discovery rows into the local portfolio backlog. Uses each row's `rankScore` as queue priority
+ * (the #2292 placeholder field). Optionally appends `discovered_issue` audit events when an event ledger is supplied.
+ * Never calls GitHub — callers rank locally first via `rankCandidateIssues`.
+ */
+export function enqueueRankedDiscovery(rankedIssues, options = {}) {
+  if (!Array.isArray(rankedIssues)) throw new Error("invalid_ranked_issues");
+  const queueStore = options.queueStore;
+  if (!queueStore || typeof queueStore.enqueue !== "function") throw new Error("invalid_queue_store");
+
+  let eventLedger = null;
+  if (options.eventLedger !== undefined) {
+    eventLedger = options.eventLedger;
+    if (!eventLedger || typeof eventLedger.appendEvent !== "function") {
+      throw new Error("invalid_event_ledger");
+    }
+  }
+
+  const minRankScore = normalizeMinRankScore(options.minRankScore);
+  // #5563: threaded through from the caller's already-resolved forge host, so a non-default (GitHub Enterprise)
+  // tenant's ranked issues land in the queue scoped to their own host instead of colliding with a same-named
+  // owner/repo on github.com. Omitted/nullish falls through to the queue store's own github.com default.
+  const apiBaseUrl = options.apiBaseUrl;
+
+  const summary = {
+    enqueued: 0,
+    skippedBelowMinRank: 0,
+    skippedInvalid: 0,
+    eventsAppended: 0,
+  };
+
+  for (const issue of rankedIssues) {
+    const normalized = normalizeRankedIssue(issue);
+    if (!normalized) {
+      summary.skippedInvalid += 1;
+      continue;
+    }
+    if (normalized.rankScore < minRankScore) {
+      summary.skippedBelowMinRank += 1;
+      continue;
+    }
+
+    queueStore.enqueue({
+      repoFullName: normalized.repoFullName,
+      identifier: `issue:${normalized.issueNumber}`,
+      priority: normalized.rankScore,
+      apiBaseUrl,
+    });
+    summary.enqueued += 1;
+
+    if (eventLedger) {
+      eventLedger.appendEvent({
+        type: "discovered_issue",
+        repoFullName: normalized.repoFullName,
+        payload: {
+          issueNumber: normalized.issueNumber,
+          rankScore: normalized.rankScore,
+          title: normalized.title,
+          labels: normalized.labels,
+        },
+      });
+      summary.eventsAppended += 1;
+    }
+  }
+
+  return summary;
+}

package/lib/portfolio-queue-cli.d.ts

@@ -0,0 +1,87 @@
+import type { PortfolioQueueStore, QueueEntry } from "./portfolio-queue.js";
+import type { PortfolioQueueManager } from "./portfolio-queue-manager.js";
+
+export type ParsedQueueListArgs =
+  | {
+      json: boolean;
+      repoFullName: string | null;
+    }
+  | { error: string };
+
+export type ParsedQueueNextArgs =
+  | { json: boolean; dryRun: boolean; globalWipCap: number | undefined; perRepoWipCap: number | undefined }
+  | { error: string };
+
+export type QueueClaimTarget = { repoFullName: string; identifier: string; apiBaseUrl: string };
+
+export function selectNextEligibleTarget(
+  entries: Array<{ repoFullName: string; identifier: string; apiBaseUrl: string; status: string }>,
+  caps: { globalWipCap: number; perRepoWipCap: number } | null,
+): QueueClaimTarget[];
+
+export type ParsedQueueDoneArgs =
+  | {
+      repoFullName: string;
+      identifier: string;
+      dryRun: boolean;
+      json: boolean;
+      apiBaseUrl: string | undefined;
+    }
+  | { error: string };
+
+export function parseQueueListArgs(args: string[]): ParsedQueueListArgs;
+
+export function parseQueueNextArgs(args: string[]): ParsedQueueNextArgs;
+
+export function parseQueueDoneArgs(args: string[]): ParsedQueueDoneArgs;
+
+export function parseQueueReleaseArgs(args: string[]): ParsedQueueDoneArgs;
+
+export function parseQueueRequeueArgs(args: string[]): ParsedQueueDoneArgs;
+
+export type ParsedQueueClaimBatchArgs =
+  | { json: boolean; dryRun: boolean; globalWipCap: number; perRepoWipCap: number }
+  | { error: string };
+
+export function parseQueueClaimBatchArgs(args: string[]): ParsedQueueClaimBatchArgs;
+
+export function renderQueueTable(entries: QueueEntry[]): string;
+
+export function runQueueList(
+  args: string[],
+  options?: { initPortfolioQueue?: () => PortfolioQueueStore },
+): number;
+
+export function runQueueNext(
+  args: string[],
+  options?: { initPortfolioQueue?: () => PortfolioQueueStore },
+): number;
+
+export function runQueueDone(
+  args: string[],
+  options?: { initPortfolioQueue?: () => PortfolioQueueStore },
+): number;
+
+export function runQueueRelease(
+  args: string[],
+  options?: { initPortfolioQueue?: () => PortfolioQueueStore },
+): number;
+
+export function runQueueRequeue(
+  args: string[],
+  options?: { initPortfolioQueue?: () => PortfolioQueueStore },
+): number;
+
+export function runQueueClaimBatch(
+  args: string[],
+  options?: { initPortfolioQueueManager?: (opts: unknown) => PortfolioQueueManager },
+): number;
+
+export function runQueueCli(
+  subcommand: string | undefined,
+  args: string[],
+  options?: {
+    initPortfolioQueue?: () => PortfolioQueueStore;
+    initPortfolioQueueManager?: (opts: unknown) => PortfolioQueueManager;
+  },
+): number;

package/lib/portfolio-queue-cli.js

@@ -0,0 +1,509 @@
+import { initPortfolioQueueStore } from "./portfolio-queue.js";
+import { initPortfolioQueueManager } from "./portfolio-queue-manager.js";
+import { runPortfolioDashboard } from "./portfolio-dashboard.js";
+import { argsWantJson, describeCliError, reportCliFailure } from "./cli-error.js";
+
+const QUEUE_LIST_USAGE = "Usage: gittensory-miner queue list [--repo <owner/repo>] [--json]";
+const QUEUE_NEXT_USAGE =
+  "Usage: gittensory-miner queue next [--global-wip <n>] [--per-repo-wip <n>] [--dry-run] [--json]";
+const QUEUE_DONE_USAGE =
+  "Usage: gittensory-miner queue done <owner/repo> <identifier> [--api-base-url <url>] [--dry-run] [--json]";
+const QUEUE_RELEASE_USAGE =
+  "Usage: gittensory-miner queue release <owner/repo> <identifier> [--api-base-url <url>] [--dry-run] [--json]";
+const QUEUE_REQUEUE_USAGE =
+  "Usage: gittensory-miner queue requeue <owner/repo> <identifier> [--api-base-url <url>] [--dry-run] [--json]";
+const QUEUE_CLAIM_BATCH_USAGE =
+  "Usage: gittensory-miner queue claim-batch [--global-wip <n>] [--per-repo-wip <n>] [--dry-run] [--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 parseJsonFlag(args) {
+  const options = { json: false, dryRun: false };
+  const positional = [];
+
+  for (const token of args) {
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    // #4847: reports what a real mutation would do and returns before opening the portfolio queue at all.
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    positional.push(token);
+  }
+
+  return { positional, ...options };
+}
+
+export function parseQueueListArgs(args) {
+  const options = { json: false, repoFullName: 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: QUEUE_LIST_USAGE };
+      }
+      const repo = parseRepoArg(repoArg, QUEUE_LIST_USAGE);
+      if ("error" in repo) return repo;
+      options.repoFullName = repo.repoFullName;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    positional.push(token);
+  }
+
+  if (positional.length > 0) {
+    return { error: QUEUE_LIST_USAGE };
+  }
+
+  return options;
+}
+
+// #4850: --global-wip/--per-repo-wip are OMITTED (undefined) by default -- queue next stays uncapped, byte-
+// identical to its pre-#4850 behavior, unless an operator explicitly opts in. Mirrors queue claim-batch's own
+// flag names (portfolio-queue-manager.js's WIP-cap-aware claimer), but claim-batch's OWN default of 1/1 is not
+// reused here: claim-batch's whole purpose is cap enforcement, while queue next has always been a plain
+// highest-priority dequeue and must not silently start capping existing callers that never asked for it.
+export function parseQueueNextArgs(args) {
+  const options = { json: false, dryRun: false, globalWipCap: undefined, perRepoWipCap: undefined };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === "--global-wip" || token === "--per-repo-wip") {
+      const value = Number(args[index + 1]);
+      if (args[index + 1] === undefined || !Number.isFinite(value) || value < 0) {
+        return { error: QUEUE_NEXT_USAGE };
+      }
+      if (token === "--global-wip") options.globalWipCap = value;
+      else options.perRepoWipCap = value;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    positional.push(token);
+  }
+
+  if (positional.length > 0) {
+    return { error: QUEUE_NEXT_USAGE };
+  }
+  return options;
+}
+
+/**
+ * Pick at most one atomically-claimable target from the store's already-priority-ordered active rows (queued
+ * AND in_progress interleaved, exactly `batchClaim`'s own `entries` shape). `caps` of `null` replicates the
+ * pre-#4850 behavior: the single highest-priority queued row, unconditionally. When caps are set, refuses to
+ * select anything once the global or the target row's own per-repo in-progress count has reached its cap --
+ * "stops claiming once the cap is reached" (#4850), not a diversifying batch selection (that remains
+ * claim-batch's job via the engine's own `nextEligibleItems`).
+ * @param {Array<{ repoFullName: string, identifier: string, apiBaseUrl: string, status: string }>} entries
+ * @param {{ globalWipCap: number, perRepoWipCap: number } | null} caps
+ */
+export function selectNextEligibleTarget(entries, caps) {
+  const topQueued = entries.find((entry) => entry.status === "queued");
+  if (!topQueued) return [];
+  if (!caps) {
+    return [{ repoFullName: topQueued.repoFullName, identifier: topQueued.identifier, apiBaseUrl: topQueued.apiBaseUrl }];
+  }
+  const globalActiveCount = entries.filter((entry) => entry.status === "in_progress").length;
+  if (globalActiveCount >= caps.globalWipCap) return [];
+  const repoActiveCount = entries.filter(
+    (entry) => entry.status === "in_progress" && entry.repoFullName === topQueued.repoFullName,
+  ).length;
+  if (repoActiveCount >= caps.perRepoWipCap) return [];
+  return [{ repoFullName: topQueued.repoFullName, identifier: topQueued.identifier, apiBaseUrl: topQueued.apiBaseUrl }];
+}
+
+/** Shared `<owner/repo> <identifier> [--api-base-url <url>] [--json]` parse for the item-targeting subcommands
+ *  (done/release/requeue). `usage` is the command-specific message surfaced on a malformed argv. */
+function parseRepoIdentifierArgs(args, usage) {
+  const options = { json: false, dryRun: false, apiBaseUrl: undefined };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    // #4847: reports what a real mutation would do and returns before opening the portfolio queue at all.
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    // #5563: scope the target to a non-default forge host, so it doesn't collide with (or get confused for) a
+    // same-named repo on the default github.com host.
+    if (token === "--api-base-url") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        return { error: usage };
+      }
+      options.apiBaseUrl = value;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    positional.push(token);
+  }
+
+  if (positional.length !== 2) {
+    return { error: usage };
+  }
+
+  const repo = parseRepoArg(positional[0], usage);
+  if ("error" in repo) return repo;
+
+  const identifier = positional[1]?.trim();
+  if (!identifier) {
+    return { error: usage };
+  }
+
+  return {
+    repoFullName: repo.repoFullName,
+    identifier,
+    dryRun: options.dryRun,
+    json: options.json,
+    apiBaseUrl: options.apiBaseUrl,
+  };
+}
+
+export function parseQueueDoneArgs(args) {
+  return parseRepoIdentifierArgs(args, QUEUE_DONE_USAGE);
+}
+
+export function parseQueueReleaseArgs(args) {
+  return parseRepoIdentifierArgs(args, QUEUE_RELEASE_USAGE);
+}
+
+export function parseQueueRequeueArgs(args) {
+  return parseRepoIdentifierArgs(args, QUEUE_REQUEUE_USAGE);
+}
+
+function display(value) {
+  if (value === null || value === undefined) return "-";
+  return String(value);
+}
+
+export function renderQueueTable(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return "no portfolio queue entries";
+  const header = [
+    "repo".padEnd(24),
+    "identifier".padEnd(16),
+    "status".padEnd(12),
+    "pri".padStart(4),
+    "enqueued-at".padEnd(24),
+  ].join(" ");
+  const lines = entries.map((entry) =>
+    [
+      entry.repoFullName.padEnd(24),
+      entry.identifier.padEnd(16),
+      entry.status.padEnd(12),
+      display(entry.priority).padStart(4),
+      display(entry.enqueuedAt).padEnd(24),
+    ].join(" "),
+  );
+  return [header, ...lines].join("\n");
+}
+
+function withPortfolioQueue(options, run) {
+  const ownsStore = options.initPortfolioQueue === undefined;
+  const portfolioQueue = (options.initPortfolioQueue ?? initPortfolioQueueStore)();
+  try {
+    return run(portfolioQueue);
+  } finally {
+    if (ownsStore) portfolioQueue.close();
+  }
+}
+
+export function runQueueList(args, options = {}) {
+  const parsed = parseQueueListArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  try {
+    return withPortfolioQueue(options, (portfolioQueue) => {
+      const entries = portfolioQueue.listQueue(parsed.repoFullName);
+      if (parsed.json) {
+        console.log(JSON.stringify({ entries }, null, 2));
+      } else {
+        console.log(renderQueueTable(entries));
+      }
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+export function runQueueNext(args, options = {}) {
+  const parsed = parseQueueNextArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  const capsRequested = parsed.globalWipCap !== undefined || parsed.perRepoWipCap !== undefined;
+  if (parsed.dryRun) {
+    const dryRunResult = capsRequested
+      ? { outcome: "dry_run", globalWipCap: parsed.globalWipCap, perRepoWipCap: parsed.perRepoWipCap }
+      : { outcome: "dry_run" };
+    if (parsed.json) {
+      console.log(JSON.stringify(dryRunResult, null, 2));
+    } else if (capsRequested) {
+      console.log(
+        `DRY RUN: would dequeue the highest-priority queued item within WIP caps (global-wip: ${parsed.globalWipCap ?? "unset"}, per-repo-wip: ${parsed.perRepoWipCap ?? "unset"}). No portfolio-queue write was made.`,
+      );
+    } else {
+      console.log("DRY RUN: would dequeue the highest-priority queued item. No portfolio-queue write was made.");
+    }
+    return 0;
+  }
+
+  try {
+    return withPortfolioQueue(options, (portfolioQueue) => {
+      let entry;
+      if (capsRequested) {
+        // Unset dimensions stay genuinely uncapped (Infinity), not silently defaulted to 1 like claim-batch.
+        const caps = {
+          globalWipCap: parsed.globalWipCap ?? Number.POSITIVE_INFINITY,
+          perRepoWipCap: parsed.perRepoWipCap ?? Number.POSITIVE_INFINITY,
+        };
+        const claimed = portfolioQueue.batchClaim((entries) => selectNextEligibleTarget(entries, caps));
+        entry = claimed[0] ?? null;
+      } else {
+        entry = portfolioQueue.dequeueNext();
+      }
+      if (parsed.json) {
+        console.log(JSON.stringify({ entry }, null, 2));
+      } else {
+        console.log(entry ? entry.identifier : "none");
+      }
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+export function runQueueDone(args, options = {}) {
+  const parsed = parseQueueDoneArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  if (parsed.dryRun) {
+    const dryRunResult = { outcome: "dry_run", repoFullName: parsed.repoFullName, identifier: parsed.identifier };
+    if (parsed.json) {
+      console.log(JSON.stringify(dryRunResult, null, 2));
+    } else {
+      console.log(`DRY RUN: would mark ${parsed.repoFullName} ${parsed.identifier} done. No portfolio-queue write was made.`);
+    }
+    return 0;
+  }
+
+  try {
+    return withPortfolioQueue(options, (portfolioQueue) => {
+      const entry = portfolioQueue.markDone(parsed.repoFullName, parsed.identifier, parsed.apiBaseUrl);
+      if (!entry) {
+        return reportCliFailure(parsed.json, "queue_entry_not_found");
+      }
+      if (parsed.json) {
+        console.log(JSON.stringify({ entry }, null, 2));
+      } else {
+        console.log(entry.status);
+      }
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+/** `release <owner/repo> <identifier>`: manually give up a CLAIMED (in_progress) item, returning it to the queue
+ *  (the manual counterpart to the automated stuck-lease sweep). Exit 2 when there is no in-flight item to release. */
+export function runQueueRelease(args, options = {}) {
+  const parsed = parseQueueReleaseArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  if (parsed.dryRun) {
+    const dryRunResult = { outcome: "dry_run", repoFullName: parsed.repoFullName, identifier: parsed.identifier };
+    if (parsed.json) {
+      console.log(JSON.stringify(dryRunResult, null, 2));
+    } else {
+      console.log(`DRY RUN: would release ${parsed.repoFullName} ${parsed.identifier} back to the queue. No portfolio-queue write was made.`);
+    }
+    return 0;
+  }
+
+  try {
+    return withPortfolioQueue(options, (portfolioQueue) => {
+      const entry = portfolioQueue.reclaimStuckItem(parsed.repoFullName, parsed.identifier, parsed.apiBaseUrl);
+      if (!entry) {
+        return reportCliFailure(parsed.json, "queue_entry_not_in_progress");
+      }
+      if (parsed.json) {
+        console.log(JSON.stringify({ entry }, null, 2));
+      } else {
+        console.log(entry.status);
+      }
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+/** `requeue <owner/repo> <identifier>`: manually put a COMPLETED (done) item back on the queue so it is picked up
+ *  again, keeping its original FIFO position. Exit 2 when there is no done item to requeue (already queued,
+ *  in-flight — release it instead — or absent). */
+export function runQueueRequeue(args, options = {}) {
+  const parsed = parseQueueRequeueArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  if (parsed.dryRun) {
+    const dryRunResult = { outcome: "dry_run", repoFullName: parsed.repoFullName, identifier: parsed.identifier };
+    if (parsed.json) {
+      console.log(JSON.stringify(dryRunResult, null, 2));
+    } else {
+      console.log(`DRY RUN: would requeue ${parsed.repoFullName} ${parsed.identifier}. No portfolio-queue write was made.`);
+    }
+    return 0;
+  }
+
+  try {
+    return withPortfolioQueue(options, (portfolioQueue) => {
+      const entry = portfolioQueue.requeueItem(parsed.repoFullName, parsed.identifier, parsed.apiBaseUrl);
+      if (!entry) {
+        return reportCliFailure(parsed.json, "queue_entry_not_requeuable");
+      }
+      if (parsed.json) {
+        console.log(JSON.stringify({ entry }, null, 2));
+      } else {
+        console.log(entry.status);
+      }
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+export function parseQueueClaimBatchArgs(args) {
+  const options = { json: false, dryRun: false, globalWipCap: 1, perRepoWipCap: 1 };
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === "--global-wip" || token === "--per-repo-wip") {
+      const value = Number(args[index + 1]);
+      if (args[index + 1] === undefined || !Number.isFinite(value) || value < 0) {
+        return { error: QUEUE_CLAIM_BATCH_USAGE };
+      }
+      if (token === "--global-wip") options.globalWipCap = value;
+      else options.perRepoWipCap = value;
+      index += 1;
+      continue;
+    }
+    return { error: QUEUE_CLAIM_BATCH_USAGE };
+  }
+  return options;
+}
+
+/** Claim the next caps-aware batch via the WIP-cap-aware batch claimer (portfolio-queue-manager.js), which also
+ *  reclaims any leases orphaned by a crashed process first (#4833 wires the previously caller-less claimer). */
+export function runQueueClaimBatch(args, options = {}) {
+  const parsed = parseQueueClaimBatchArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  if (parsed.dryRun) {
+    const dryRunResult = { outcome: "dry_run", globalWipCap: parsed.globalWipCap, perRepoWipCap: parsed.perRepoWipCap };
+    if (parsed.json) {
+      console.log(JSON.stringify(dryRunResult, null, 2));
+    } else {
+      console.log(
+        `DRY RUN: would claim a batch (global-wip: ${parsed.globalWipCap}, per-repo-wip: ${parsed.perRepoWipCap}). No portfolio-queue write was made.`,
+      );
+    }
+    return 0;
+  }
+
+  // Open the manager INSIDE the try so a store open failure returns 2 instead of crashing; the finally guards the
+  // close with `?.` since the initializer may have thrown before assigning.
+  const ownsManager = options.initPortfolioQueueManager === undefined;
+  let manager;
+  try {
+    manager = (options.initPortfolioQueueManager ?? initPortfolioQueueManager)({
+      caps: { globalWipCap: parsed.globalWipCap, perRepoWipCap: parsed.perRepoWipCap },
+    });
+    const claimed = manager.claimNextBatch();
+    if (parsed.json) {
+      console.log(JSON.stringify({ claimed }, null, 2));
+    } else {
+      console.log(claimed.length === 0 ? "none" : claimed.map((entry) => entry.identifier).join("\n"));
+    }
+    return 0;
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  } finally {
+    if (ownsManager) manager?.close();
+  }
+}
+
+export function runQueueCli(subcommand, args, options = {}) {
+  if (subcommand === "list") return runQueueList(args, options);
+  if (subcommand === "next") return runQueueNext(args, options);
+  if (subcommand === "done") return runQueueDone(args, options);
+  if (subcommand === "release") return runQueueRelease(args, options);
+  if (subcommand === "requeue") return runQueueRequeue(args, options);
+  if (subcommand === "claim-batch") return runQueueClaimBatch(args, options);
+  if (subcommand === "dashboard") return runPortfolioDashboard(args, options);
+  return reportCliFailure(argsWantJson(args), `Unknown queue subcommand: ${subcommand ?? ""}. ${QUEUE_LIST_USAGE}`);
+}