dev-loops 0.2.6 → 0.3.0

package/scripts/loop/detect-copilot-session-activity.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
 const USAGE = `Usage: detect-copilot-session-activity.mjs --repo <owner/name> --branch <name> [--limit <number>]
 Detect Copilot GitHub Actions session activity on a branch.
 Required:
@@ -41,32 +42,48 @@ const COPILOT_RUN_NAME_PATTERNS = Object.freeze([
 ]);
 const parseError = buildParseError(USAGE);
 export function parseDetectCopilotSessionActivityCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     branch: undefined,
     limit: DEFAULT_LIMIT,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      branch: { type: "string" },
+      limit: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--branch") {
-      options.branch = requireOptionValue(args, "--branch", parseError).trim();
+    if (token.name === "branch") {
+      options.branch = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--limit") {
-      options.limit = parsePositiveInteger(requireOptionValue(args, "--limit", parseError), "--limit", parseError);
+    if (token.name === "limit") {
+      options.limit = parsePositiveInteger(requireTokenValue(token, parseError), "--limit", parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.branch === undefined || options.branch.length === 0) {
     throw parseError("detect-copilot-session-activity requires both --repo <owner/name> and --branch <name>");

package/scripts/loop/detect-initial-copilot-pr-state.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parseIssueNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { detectLinkedIssuePr } from "../github/detect-linked-issue-pr.mjs";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
+import { parseArgs } from "node:util";
 const USAGE = `Usage: detect-initial-copilot-pr-state.mjs --repo <owner/name> --issue <number>
 Detect whether an assigned issue is still on the bootstrap-only Copilot draft PR
 or has moved into normal linked-PR follow-up.
@@ -79,27 +80,42 @@ const INITIAL_COPILOT_PR_FACTS_QUERY = [
 ].join("\n");
 const parseError = buildParseError(USAGE);
 export function parseDetectInitialCopilotPrStateCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     issue: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--issue") {
-      options.issue = parseIssueNumber(requireOptionValue(args, "--issue", parseError), parseError);
+    if (token.name === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
     throw parseError("detect-initial-copilot-pr-state requires both --repo <owner/name> and --issue <number>");

package/scripts/loop/detect-internal-only-pr.mjs

@@ -3,8 +3,9 @@ import { statSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
 
 const USAGE = `Usage: detect-internal-only-pr.mjs --repo <owner/name> --pr <number> [--config <path>]
 Detect whether a PR only touches internal tooling files (scripts, docs, tests, config)
@@ -118,7 +119,6 @@ function buildPatternMatchers(patterns) {
 }
 
 export function parseCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -126,29 +126,47 @@ export function parseCliArgs(argv) {
     config: undefined,
     labelCheck: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      config: { type: "string" },
+      "label-check": { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    if (token === "--config") {
-      options.config = requireOptionValue(args, "--config", parseError).trim();
+    if (token.name === "config") {
+      options.config = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--label-check") {
+    if (token.name === "label-check") {
       options.labelCheck = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("detect-internal-only-pr requires both --repo <owner/name> and --pr <number>");

package/scripts/loop/detect-issue-refinement-artifact.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
 import {
   detectIssueRefinementArtifact,
   REFINEMENT_SOURCE,
@@ -33,36 +34,52 @@ Error output (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectIssueRefinementArtifactCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     issue: undefined,
     input: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+      input: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--issue") {
-      const value = requireOptionValue(args, "--issue", parseError);
+    if (token.name === "issue") {
+      const value = requireTokenValue(token, parseError);
       if (!/^\d+$/.test(value) || Number(value) === 0) {
         throw parseError("--issue must be a positive integer");
       }
       options.issue = Number(value);
       continue;
     }
-    if (token === "--input") {
-      options.input = requireOptionValue(args, "--input", parseError).trim();
+    if (token.name === "input") {
+      options.input = requireTokenValue(token, parseError).trim();
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const hasInput = typeof options.input === "string" && options.input.length > 0;
   const hasRemote = typeof options.repo === "string" && options.repo.length > 0 && Number.isInteger(options.issue);

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -6,19 +6,20 @@ import {
   formatCliError,
   isCopilotLogin,
   isDirectCliRun,
-  normalizeTimestamp,
   parseJsonText,
   parseReviewThreads,
+  resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
 } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
-import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { loadDevLoopConfig, resolveGateConfig, resolveRefinement, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
 import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
 import { shouldGuardCopilotReviewRequest } from "@dev-loops/core/loop/pr-gate-coordination";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
 import { detectCheckpointEvidence } from "../github/detect-checkpoint-evidence.mjs";
+import { parseArgs } from "node:util";
 const UNMERGED_GIT_STATUS_CODES = new Set(["DD", "AU", "UD", "UA", "DU", "AA", "UU"]);
 const USAGE = `Usage: detect-pr-gate-coordination-state.mjs --repo <owner/name> --pr <number>
 Determine which PR gate/transition is legal next for a pull request.
@@ -70,27 +71,42 @@ Exit codes:
   1  Argument error or gh/runtime failure`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectPrGateCoordinationCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     pr: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("detect-pr-gate-coordination-state requires both --repo <owner/name> and --pr <number>");
@@ -287,18 +303,13 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   const gateEvidence = await detectCheckpointEvidence(options, runtime);
   // When draft gate was re-passed on a different head, use its timestamp
   // to reset the Copilot round count — only reviews after the re-pass count.
-  // Use prefix matching for the head SHA comparison so shortened SHAs (7+)
-  // from gate comments match the full headRefOid.
-  const draftGateHeadSha = gateEvidence.draftGate?.headSha;
-  const draftGateOnCurrentHead = typeof draftGateHeadSha === "string"
-    && typeof currentHeadSha === "string"
-    && currentHeadSha.startsWith(draftGateHeadSha);
-  const draftGateResetAtMs = gateEvidence.draftGate?.verdict === "clean"
-    && typeof draftGateHeadSha === "string"
-    && !draftGateOnCurrentHead
-    && typeof gateEvidence.draftGate?.updatedAt === "string"
-    ? normalizeTimestamp(gateEvidence.draftGate.updatedAt)
-    : null;
+  // Shared with request-copilot-review so both scripts compute the same
+  // completed round count / cap (#896). Prefix matching for the head SHA lets
+  // shortened SHAs (7+) from gate comments match the full headRefOid.
+  const draftGateResetAtMs = resolveDraftGateRoundResetMs({
+    draftGate: gateEvidence.draftGate,
+    currentHeadSha,
+  });
   const reviewSummary = summarizeCopilotReviews(prData?.reviews, { headSha: currentHeadSha, draftGateResetAtMs });
   const reviewRequestStatus = requestedReviewers.requested
     ? "requested"
@@ -322,8 +333,19 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   if (gateEvidence.currentHeadSha !== currentHeadSha) {
     throw new Error(`PR head changed while loading gate coordination facts for ${options.repo}#${options.pr}; refuse to evaluate mixed-head gate state.`);
   }
-  const interpretation = interpretLoopState(snapshot);
-  const disposition = summarizeLoopInterpretation(interpretation);
+  // Resolve the refinement config (round cap, low-signal heuristic) and feed it to
+  // the interpreter. Without it, the interpreter cannot see maxCopilotRounds and so
+  // never resolves ROUND_CAP_CLEAN_FALLBACK — a post-cap clean head would fall to
+  // READY_TO_REREQUEST_REVIEW, dead-ending the loop at the round cap (#896). This
+  // keeps the gate-coordination interpretation consistent with the standalone
+  // detect-copilot-loop-state path and with request-copilot-review's cap logic.
+  const interpreterRepoRoot = runtime.repoRoot ?? process.cwd();
+  const interpreterConfigResult = await loadDevLoopConfig({ repoRoot: interpreterRepoRoot });
+  const interpreterRefinementConfig = (Array.isArray(interpreterConfigResult.errors) && interpreterConfigResult.errors.length > 0)
+    ? resolveRefinement({ version: 1 })
+    : resolveRefinement(interpreterConfigResult.config ?? { version: 1 });
+  const interpretation = interpretLoopState(snapshot, interpreterRefinementConfig);
+  const disposition = summarizeLoopInterpretation(interpretation, interpreterRefinementConfig);
   const mergeStateStatus = typeof prData?.mergeStateStatus === "string" && prData.mergeStateStatus.trim().length > 0
     ? prData.mergeStateStatus.trim().toUpperCase()
     : null;
@@ -346,6 +368,7 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
     interpretation,
     disposition,
     refinementArtifact,
+    refinementConfig: interpreterRefinementConfig,
   };
 }
 
@@ -413,9 +436,13 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     && typeof (context.snapshot?.copilotReviewRoundCount) === "number"
     && context.snapshot?.copilotReviewRoundCount >= maxCopilotRounds;
   const sameHeadCleanConverged = context.interpretation?.sameHeadCleanConverged ?? false;
+  // Round-cap clean fallback (#896): the interpreter resolved a clean post-cap head
+  // (zero unresolved threads + green CI) that Copilot will not re-review. The formal
+  // request guard must not fire here — pre_approval_gate reviews the post-cap head.
+  const roundCapCleanFallback = context.interpretation?.roundCapCleanEligible ?? false;
   const copilotReviewEverFormallyRequested = copilotReviewRequestStatus === "none"
     && guardBoundaries.has(result.gateBoundary)
-    && !(roundCapReached && sameHeadCleanConverged)
+    && !(roundCapReached && (sameHeadCleanConverged || roundCapCleanFallback))
     ? await fetchCopilotEverFormallyRequested(
         { repo: context.repo, pr: context.pr },
         runtime,
@@ -426,7 +453,8 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     copilotReviewRoundCount: context.snapshot?.copilotReviewRoundCount ?? 0,
     copilotReviewEverFormallyRequested,
     maxCopilotRounds,
-    sameHeadCleanConverged: context.interpretation?.sameHeadCleanConverged ?? false,
+    sameHeadCleanConverged,
+    roundCapCleanFallback,
     gateBoundary: result.gateBoundary,
   })) {
     result.gateBoundary = PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW;

package/scripts/loop/detect-reviewer-loop-state.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
@@ -26,7 +27,20 @@ function parseBool(value, flag) {
   throw new Error(`${flag} must be true or false`);
 }
 export function parseDetectReviewerCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      input: { type: "string" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "review-requested": { type: "string" },
+      "local-state": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     inputPath: undefined,
     repo: undefined,
@@ -35,36 +49,41 @@ export function parseDetectReviewerCliArgs(argv) {
     localStatePath: undefined,
     help: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--input") {
-      options.inputPath = requireOptionValue(args, "--input");
+    if (token.name === "input") {
+      options.inputPath = requireTokenValue(token);
       continue;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo").trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr"));
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token));
       continue;
     }
-    if (token === "--review-requested") {
+    if (token.name === "review-requested") {
       options.reviewRequestedOverride = parseBool(
-        requireOptionValue(args, "--review-requested"),
+        requireTokenValue(token),
         "--review-requested",
       );
       continue;
     }
-    if (token === "--local-state") {
-      options.localStatePath = requireOptionValue(args, "--local-state");
+    if (token.name === "local-state") {
+      options.localStatePath = requireTokenValue(token);
       continue;
     }
-    throw new Error(`Unknown argument: ${token}`);
+    throw new Error(`Unknown argument: ${token.rawName}`);
   }
   if (options.inputPath !== undefined) {
     if (options.repo !== undefined || options.pr !== undefined) {

package/scripts/loop/detect-stale-runner.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import process from "node:process";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId as resolveEnvRunId } from "@dev-loops/core/loop/run-context";
+import { parseArgs } from "node:util";
 import {
   detectStaleRunner,
   STALE_RUNNER_ERROR,
@@ -50,7 +51,6 @@ Exit codes:
   1  Argument error or stale/exit-signal condition detected`.trim();
 const parseError = buildParseError(USAGE);
 function parseCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -58,22 +58,40 @@ function parseCliArgs(argv) {
     staleRunnerMaxAgeMs: undefined,
     runId: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "stale-runner-max-age-ms": { type: "string" },
+      "run-id": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    if (token === "--stale-runner-max-age-ms") {
-      const raw = requireOptionValue(args, "--stale-runner-max-age-ms", parseError).trim();
+    if (token.name === "stale-runner-max-age-ms") {
+      const raw = requireTokenValue(token, parseError).trim();
       const parsed = Number(raw);
       if (!Number.isFinite(parsed) || parsed <= 0) {
         throw parseError(`--stale-runner-max-age-ms must be a positive integer (ms), got: ${raw}`);
@@ -81,11 +99,11 @@ function parseCliArgs(argv) {
       options.staleRunnerMaxAgeMs = Math.floor(parsed);
       continue;
     }
-    if (token === "--run-id") {
-      options.runId = requireOptionValue(args, "--run-id", parseError).trim();
+    if (token.name === "run-id") {
+      options.runId = requireTokenValue(token, parseError).trim();
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("detect-stale-runner requires both --repo <owner/name> and --pr <number>");