dev-loops 0.7.1 → 0.8.0

package/scripts/loop/_pr-runner-coordination.mjs

@@ -1,3 +1,5 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { parseRepoSlugParts } from "@dev-loops/core/github/repo-slug";
@@ -9,6 +11,7 @@ import {
 } from "./_steering-state-file.mjs";
 export const RUNNER_COORDINATION_SCHEMA_VERSION = 2;
 export const RUNNER_COORDINATION_SUPPORTED_SCHEMA_VERSIONS = Object.freeze([1, 2]);
+export const RUNNER_COORDINATION_HISTORY_LIMIT = 50; // cap audit trail; heartbeats append per-round, keep the most recent 50 events
 export const RUNNER_OWNERSHIP_ERROR = Object.freeze({
   ACTIVE_RUN_EXISTS: "active_run_exists",
   OWNERSHIP_LOST: "ownership_lost",
@@ -50,7 +53,10 @@ async function loadRunnerStateFile(filePath) {
 }
 async function saveRunnerStateFile(filePath, state) {
   try {
-    return await saveSharedStateFile(filePath, state);
+    const capped = Array.isArray(state.history) && state.history.length > RUNNER_COORDINATION_HISTORY_LIMIT
+      ? { ...state, history: state.history.slice(-RUNNER_COORDINATION_HISTORY_LIMIT) }
+      : state;
+    return await saveSharedStateFile(filePath, capped);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Failed to write runner coordination state file '${filePath}': ${message}`);
@@ -64,13 +70,62 @@ async function withRunnerStateFileLock(filePath, callback) {
     throw new Error(`Failed to acquire runner coordination state lock for '${filePath}': ${message}`);
   }
 }
+const coordinationRootCache = new Map();
+/**
+ * Resolve the single stable coordination root for a checkout, independent of CWD.
+ *
+ * `git rev-parse --git-common-dir` yields the shared git dir that is identical for
+ * a repo and all its linked worktrees, so its parent is the one main-checkout root
+ * that a worktree runner and a repo-root detector both anchor to — eliminating the
+ * split-copy false-stale stall where each read a different `.pi/runner-coordination`
+ * file. Falls back to the canonicalized (realpath'd) `cwd` when git is
+ * unavailable or the dir is not a checkout, so symlinked and realpath'd
+ * spellings of the same non-git dir still converge on one coordination path.
+ *
+ * `cwd` is realpath'd once at entry: git returns a relative `--git-common-dir` from
+ * a main checkout but an already-realpath'd absolute one from a linked worktree, so
+ * resolving against a symlinked cwd (e.g. macOS /tmp -> /private/tmp) would make the
+ * two sides compute different roots for the same physical repo. Canonicalizing first
+ * makes both sides converge, and doubles as the cache key so symlink-variant cwd
+ * spellings share one cache entry. Cached per canonical cwd for the process.
+ */
+function resolveRepoCoordinationRoot(cwd) {
+  let canonicalCwd = cwd;
+  try {
+    canonicalCwd = fs.realpathSync(cwd);
+  } catch (err) {
+    // realpathSync on an existing checkout dir virtually never fails;
+    // warn (don't throw) so the rare transient failure — which can desync the
+    // coordination path across worktrees — is diagnosable instead of silent.
+    console.warn(
+      `[runner-coordination] realpathSync(${cwd}) failed; using raw cwd, coordination path may diverge across worktrees: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (coordinationRootCache.has(canonicalCwd)) return coordinationRootCache.get(canonicalCwd);
+  let root = canonicalCwd;
+  try {
+    const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd: canonicalCwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (commonDir) {
+      root = path.dirname(path.resolve(canonicalCwd, commonDir));
+    }
+  } catch {
+    // not a git checkout / git unavailable — anchor at the canonical (realpath'd) cwd
+  }
+  coordinationRootCache.set(canonicalCwd, root);
+  return root;
+}
 export function defaultRunnerCoordinationFilePathForTarget({ repo, pr }, cwd = process.cwd()) {
   const { owner, name } = parseRepoSlugParts(repo, {
     errorMessage: `Invalid repo slug for coordination target path: ${JSON.stringify(repo)}`,
     lowercase: true,
   });
   const normalizedPr = normalizePr(pr);
-  return path.join(cwd, ".pi", "runner-coordination", owner, name, `pr-${normalizedPr}.json`);
+  const root = resolveRepoCoordinationRoot(cwd);
+  return path.join(root, ".pi", "runner-coordination", owner, name, `pr-${normalizedPr}.json`);
 }
 export function createRunnerCoordinationState({ repo, pr, runId = null, now = new Date().toISOString() }) {
   const normalizedRepo = normalizeRepoSlug(repo);
@@ -324,6 +379,18 @@ export async function claimRunnerOwnership({
     };
   });
 }
+/**
+ * Verify the caller still owns the PR's runner claim.
+ *
+ * A successful owner-confirmed assert (the active owner's runId matches the
+ * caller's) refreshes `activeRun.updatedAt` — it acts as a heartbeat. Every
+ * other outcome (no record, no active run, ownership lost, missing run id)
+ * is a pure lock-free read with no write. Long-running loops must assert (or
+ * claim) at least once within the stale-max-age window
+ * (`STALE_RUNNER_DEFAULT_MAX_AGE_MS`, 30 minutes by default, overridable via
+ * `DEVLOOPS_STALE_RUNNER_MAX_AGE_MS`; see `_stale-runner-detection.mjs`) to
+ * avoid being seen as stale during a long multi-round gate cycle.
+ */
 export async function assertRunnerOwnership({
   repo,
   pr,
@@ -331,6 +398,7 @@ export async function assertRunnerOwnership({
   cwd = process.cwd(),
   filePath = null,
   requireExisting = false,
+  now = new Date().toISOString(),
 } = {}) {
   const normalizedRepo = normalizeRepoSlug(repo);
   const normalizedPr = normalizePr(pr);
@@ -397,17 +465,48 @@ export async function assertRunnerOwnership({
     });
   }
   if (state.activeRun.runId === normalizedRunId) {
-    return {
-      ok: true,
-      status: "owner_confirmed",
-      repo: normalizedRepo,
-      pr: normalizedPr,
-      runId: normalizedRunId,
-      activeRun: state.activeRun,
-      previousRun: state.previousRun,
-      exitSignals: state.exitSignals,
-      filePath: resolvedPath,
-    };
+    return withRunnerStateFileLock(resolvedPath, async () => {
+      const lockedRaw = await loadRunnerStateFile(resolvedPath);
+      const lockedState = lockedRaw === null
+        ? null
+        : normalizeRunnerCoordinationState(lockedRaw, { repo: normalizedRepo, pr: normalizedPr });
+      if (lockedState?.activeRun?.runId !== normalizedRunId) {
+        // Ownership changed hands between the lockless read above and acquiring
+        // the lock (a concurrent takeover) — don't write; report the new owner.
+        return buildConflict({
+          error: RUNNER_OWNERSHIP_ERROR.OWNERSHIP_LOST,
+          repo: normalizedRepo,
+          pr: normalizedPr,
+          runId: normalizedRunId,
+          activeRun: lockedState?.activeRun ?? null,
+          filePath: resolvedPath,
+          exitSignals: lockedState?.exitSignals ?? [],
+          message: lockedState?.activeRun?.runId
+            ? `PR ${normalizedRepo}#${normalizedPr} is now owned by run ${lockedState.activeRun.runId}; run ${normalizedRunId} must stop.`
+            : `PR ${normalizedRepo}#${normalizedPr} no longer has an active runner ownership record; run ${normalizedRunId} must stop.`,
+        });
+      }
+      const nextState = {
+        ...lockedState,
+        activeRun: {
+          ...lockedState.activeRun,
+          updatedAt: now,
+        },
+        history: [...lockedState.history, { type: "heartbeat", runId: normalizedRunId, at: now }],
+      };
+      await saveRunnerStateFile(resolvedPath, nextState);
+      return {
+        ok: true,
+        status: "owner_confirmed",
+        repo: normalizedRepo,
+        pr: normalizedPr,
+        runId: normalizedRunId,
+        activeRun: nextState.activeRun,
+        previousRun: nextState.previousRun,
+        exitSignals: nextState.exitSignals,
+        filePath: resolvedPath,
+      };
+    });
   }
   return buildConflict({
     error: RUNNER_OWNERSHIP_ERROR.OWNERSHIP_LOST,

package/scripts/loop/check-retro-tooling.mjs

@@ -24,10 +24,13 @@
  *   - dev-loops subcommands and `node scripts/....mjs` invocations. Those scripts
  *     legitimately call gh/GraphQL/etc. internally — that IS the tooling.
  *   - A small explicit allowlist of write-ops that have no internal wrapper today:
- *     `gh pr merge`, `gh pr ready`, `gh issue create`, `gh issue edit`. These are
- *     recorded as `allowedWriteOps` rather than violations so the gate is not
+ *     `gh pr merge`, `gh pr ready`, `gh issue create`. Plus belt-and-suspenders
+ *     entries that DO have wrappers — `gh issue edit` (scripts/github/edit-issue.mjs)
+ *     and `gh label create` (scripts/github/create-label.mjs) — kept so a bare
+ *     invocation surfaced from the wrapper's own subprocess is not a false violation.
+ *     All are recorded as `allowedWriteOps` rather than violations so the gate is not
  *     blocked forever on an unavoidable gap. Document/close the gap with a wrapper
- *     to remove them from the allowlist.
+ *     to remove the no-wrapper entries from the allowlist.
  *
  * VIOLATION (agent-level raw call):
  *   - `gh ...` at the start of a command segment (start of line, or after
@@ -75,19 +78,21 @@ Exit codes:
   2  Argument/runtime error, or invalid --jq filter`;
 
 /**
- * Write-ops that currently have no internal dev-loops wrapper. Recorded
- * distinctly so the gate is not blocked forever on an unavoidable gap.
- * Keep this set SMALL and explicit; remove an entry once a wrapper exists.
+ * Write-ops recorded distinctly (as allowedWriteOps, not violations) so the gate
+ * is not blocked forever on an unavoidable gap. Most have no internal wrapper yet;
+ * a couple DO have wrappers and are kept belt-and-suspenders (see below).
+ * Keep this set SMALL and explicit; remove a no-wrapper entry once a wrapper exists.
  * @type {ReadonlyArray<RegExp>}
  */
 const ALLOWED_WRITE_OPS = Object.freeze([
   /^gh\s+pr\s+merge\b/,
   /^gh\s+pr\s+ready\b/,
   /^gh\s+issue\s+create\b/,
+  // `gh issue edit` (scripts/github/edit-issue.mjs) and `gh label create`
+  // (scripts/github/create-label.mjs) both HAVE wrappers; these entries are
+  // belt-and-suspenders so a bare invocation (e.g. surfaced from the wrapper's
+  // own subprocess) classifies as an allowed write-op, not a violation.
   /^gh\s+issue\s+edit\b/,
-  // `gh label create` HAS a wrapper (scripts/github/create-label.mjs); this
-  // entry is belt-and-suspenders so a bare invocation (e.g. surfaced from the
-  // wrapper's own subprocess) classifies as an allowed write-op, not a violation.
   /^gh\s+label\s+create\b/,
 ]);
 

package/scripts/loop/copilot-pr-handoff.mjs

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, normalizeTimestamp, parseJsonText } from "../_core-helpers.mjs";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import { detectPostConvergenceSignificantChange } from "./_post-convergence-change.mjs";
 import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId } from "@dev-loops/core/loop/run-context";
-import { loadDevLoopConfig, resolveRefinement } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, resolveRefinement } from "@dev-loops/core/config";
 import { autoDetectSnapshot } from "./detect-copilot-loop-state.mjs";
 import { performCopilotReviewRequest } from "../github/request-copilot-review.mjs";
 import { detectInternalOnly as detectPrInternalOnly } from "./detect-internal-only-pr.mjs";
 import { applyConfirmedReviewRequest, interpretLoopState, NEXT_ACTIONS, STATE, summarizeLoopInterpretation, TRANSITIONS } from "@dev-loops/core/loop/copilot-loop-state";
+import { PR_LIFECYCLE_STATE } from "@dev-loops/core/loop/pr-lifecycle";
 import { ensureAsyncRunnerOwnership, releaseAsyncRunnerOwnership } from "./_pr-runner-coordination.mjs";
 import { resolveRepoRoot } from "./_repo-root-resolver.mjs";
 
@@ -38,6 +39,13 @@ Optional:
   --watch-status <status>   Refresh deterministic loop state after a prior
                            watcher result (changed|timeout|idle). This mode
                            never requests review; it only re-detects state.
+  --lightweight         This PR is light-dispatched (#1210): compose the
+                        Copilot round cap with localImplementation.lightMode.
+                        maxCopilotRounds (default 1) via
+                        min(lightMode.maxCopilotRounds, refinement.maxCopilotRounds)
+                        instead of using refinement.maxCopilotRounds alone.
+                        refinement.maxCopilotRounds: 0 still disables Copilot
+                        rounds even with --lightweight.
 Output (stdout, JSON):
   { "ok": true, "action": "watch"|"fix"|"stop", "state": "...",
     "allowedTransitions": [...], "nextAction": "...", "snapshot": {...},
@@ -100,7 +108,7 @@ function summarizeRequestWatchContract({
     || interpretation.state === STATE.READY_TO_REREQUEST_REVIEW
     && interpretation.sameHeadCleanConverged !== true
   ) {
-    routingState = "ready_state_needs_copilot_request";
+    routingState = PR_LIFECYCLE_STATE.READY_STATE_NEEDS_COPILOT_REQUEST;
   } else if (interpretation.state === STATE.INTERNAL_TOOLING_DIRECT_GATE) {
     routingState = "internal_tooling_skip_copilot";
   }
@@ -138,6 +146,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
     repo: undefined,
     pr: undefined,
     watchStatus: undefined,
+    lightweight: false,
     jq: undefined,
     silent: false,
   };
@@ -148,6 +157,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       repo: { type: "string" },
       pr: { type: "string" },
       "watch-status": { type: "string" },
+      lightweight: { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
@@ -184,6 +194,10 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       options.watchStatus = watchStatus;
       continue;
     }
+    if (token.name === "lightweight") {
+      options.lightweight = true;
+      continue;
+    }
     if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
@@ -213,7 +227,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
  * loop should pause for operator review.
  * Returns { paused: true, humanComments: [...] } when human comments need attention.
  */
-export async function detectRecentHumanComments({ repo, pr, claimedAtMs }, { env = process.env, ghCommand = "gh" } = {}) {
+export async function detectRecentHumanComments({ repo, pr, claimedAtMs }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   try {
     const result = await runChild(
       ghCommand,
@@ -298,7 +312,7 @@ export async function detectRecentHumanComments({ repo, pr, claimedAtMs }, { env
 // (#1103, #1126): the current head, the Copilot reviews (to find the last
 // reviewed head), and the PR's changed files. Fetched only when the interpreter
 // already resolved ROUND_CAP_CLEAN_FALLBACK, so this extra call is off the hot path.
-async function fetchReopenCycleFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchReopenCycleFacts({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "headRefOid,reviews,files"],
@@ -314,12 +328,16 @@ async function fetchReopenCycleFacts({ repo, pr }, { env = process.env, ghComman
   }
 }
 
-export async function runHandoff(options, { env = process.env, ghCommand = "gh" } = {}) {
+export async function runHandoff(options, { env = process.env, ghCommand = "gh", runChild = defaultRunChild, repoRoot } = {}) {
+  // Single resolved repo root for config + runner-coordination reads/writes.
+  // Defaults to the checkout's git toplevel (production); an injected repoRoot
+  // keeps the whole cascade hermetic when driven in-process.
+  const resolvedRepoRoot = repoRoot ?? resolveRepoRoot(process.cwd());
   const runnerOwnership = await ensureAsyncRunnerOwnership({
     repo: options.repo,
     pr: options.pr,
     env,
-    cwd: resolveRepoRoot(process.cwd()),
+    cwd: resolvedRepoRoot,
     claimIfMissing: true,
   });
   if (!runnerOwnership.ok) {
@@ -349,15 +367,24 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   }
   let snapshot = await autoDetectSnapshot(
     { repo: options.repo, pr: options.pr },
-    { env, ghCommand },
+    { env, ghCommand, runChild },
   );
-  const config = await loadDevLoopConfig({ repoRoot: resolveRepoRoot(process.cwd()) });
+  const config = await loadDevLoopConfig({ repoRoot: resolvedRepoRoot });
   if (config.errors?.length > 0) {
     console.error("[copilot-pr-handoff] config warnings:", JSON.stringify(config.errors));
   }
   const refinementConfig = config.errors?.length > 0
     ? resolveRefinement({ version: 1 })
     : resolveRefinement(config.config);
+  if (options.lightweight) {
+    // Compose (not replace) the round cap for light-dispatched PRs (#1210):
+    // min(lightMode.maxCopilotRounds ?? 1, refinement.maxCopilotRounds), so
+    // maxCopilotRounds: 0 still disables Copilot rounds everywhere.
+    refinementConfig.maxCopilotRounds = resolveEffectiveCopilotRoundCap(
+      config.errors?.length > 0 ? { version: 1 } : config.config,
+      { lightweight: true },
+    );
+  }
   let interpretation = interpretLoopState(snapshot, refinementConfig);
 
   // Check for human comments since last subagent action
@@ -366,7 +393,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   if (resolveRunId(env)) {
     humanCommentCheck = await detectRecentHumanComments(
       { repo: options.repo, pr: options.pr, claimedAtMs: runnerOwnership?.activeRun?.claimedAt ? new Date(runnerOwnership.activeRun.claimedAt).getTime() : undefined },
-      { env, ghCommand },
+      { env, ghCommand, runChild },
     );
   }
   const TERMINAL_STATES = new Set([STATE.NO_PR, STATE.DONE, STATE.BLOCKED_NEEDS_USER_DECISION]);
@@ -376,7 +403,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
       repo: options.repo,
       pr: options.pr,
       env,
-      cwd: resolveRepoRoot(process.cwd()),
+      cwd: resolvedRepoRoot,
     });
     return {
       ok: true,
@@ -444,7 +471,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
       interpretation.state === STATE.READY_TO_REREQUEST_REVIEW)
   ) {
     try {
-      const internalCheck = await detectPrInternalOnly(options, { env, ghCommand });
+      const internalCheck = await detectPrInternalOnly(options, { env, ghCommand, runChild });
       if (internalCheck.ok && internalCheck.internalOnly) {
         internalOnlySkipCopilot = true;
         interpretation = {
@@ -503,7 +530,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   if (!internalOnlySkipCopilot
       && options.watchStatus === undefined
       && interpretation.state === STATE.ROUND_CAP_CLEAN_FALLBACK) {
-    const reopenFacts = await fetchReopenCycleFacts(options, { env, ghCommand });
+    const reopenFacts = await fetchReopenCycleFacts(options, { env, ghCommand, runChild });
     const significant = await detectPostConvergenceSignificantChange(
       {
         repo: options.repo,
@@ -514,7 +541,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
         roundCapReached: true,
         regularCopilotRounds: (snapshot.copilotReviewRoundCount ?? 0) > 0,
       },
-      { env, ghCommand },
+      { env, ghCommand, runChild },
     );
     if (significant) {
       reopenedCapCycle = true;
@@ -545,8 +572,12 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
         // still refuses unless the head actually advanced past the last review
         // (its hasNewCommits guard), so this cannot force an over-cap same-head request.
         forceRerequestReview: reopenedCapCycle,
+        // Thread the light-dispatch signal so the requester enforces the same
+        // composed round cap this handoff resolved (#1210) — the enforcement
+        // backstop must never permit rounds the interpreter already forbids.
+        lightweight: options.lightweight,
       },
-      { env, ghCommand },
+      { env, ghCommand, runChild },
     );
     reviewRequestStatus = requestResult.status;
     snapshot = applyConfirmedReviewRequest(snapshot, reviewRequestStatus);
@@ -632,7 +663,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
       repo: options.repo,
       pr: options.pr,
       env,
-      cwd: resolveRepoRoot(process.cwd()),
+      cwd: resolvedRepoRoot,
     });
     if (runnerRelease.status !== "skipped_no_async_run_id") {
       result.runnerRelease = runnerRelease;

package/scripts/loop/detect-change-scope.mjs

@@ -75,7 +75,7 @@ export function parseGitDiffStat(output) {
   }
   return { filesChanged: fileCount, linesChanged: insertions + deletions };
 }
-function detectScope({ base, head } = {}) {
+function detectScope({ base, head, cwd } = {}) {
   let diffArgs = ["diff", "--stat"];
   if (base && head) {
     diffArgs.push(`${base}..${head}`);
@@ -86,7 +86,7 @@ function detectScope({ base, head } = {}) {
   }
   let output;
   try {
-    output = execFileSync("git", diffArgs, { encoding: "utf8", maxBuffer: 1_000_000 });
+    output = execFileSync("git", diffArgs, { encoding: "utf8", maxBuffer: 1_000_000, cwd: cwd || undefined });
   } catch (err) {
     return { ok: false, filesChanged: 0, linesChanged: 0, error: err instanceof Error ? err.message : String(err) };
   }

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import {
   buildParseError,
   formatCliError,
@@ -14,7 +14,7 @@ import {
 } from "../_core-helpers.mjs";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
-import { loadDevLoopConfig, resolveRefinement } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, resolveRefinement } from "@dev-loops/core/config";
 import {
   buildSnapshotFromPrFacts,
   interpretLoopState,
@@ -43,8 +43,13 @@ Required (auto-detect mode):
   --pr <number>                              Pull request number
 Required (snapshot mode):
   --input <path>                             Path to snapshot JSON file
-Optional (auto-detect mode only):
-Optional (auto-detect mode only):
+Optional (either mode):
+  --lightweight   This PR is light-dispatched (#1210): compose the Copilot
+                  round cap with localImplementation.lightMode.maxCopilotRounds
+                  (default 1) via min(lightMode.maxCopilotRounds,
+                  refinement.maxCopilotRounds) instead of using
+                  refinement.maxCopilotRounds alone. refinement.maxCopilotRounds:
+                  0 still disables Copilot rounds even with --lightweight.
 Output (stdout, JSON):
   { "ok": true, "snapshot": {..., "copilotReviewRoundCount": N}, "state": "...", "allowedTransitions": [...], "nextAction": "...",
     "autoRerequestEligible": true|false, "sameHeadCleanConverged": true|false,
@@ -67,6 +72,7 @@ export function parseDetectCliArgs(argv) {
     inputPath: undefined,
     repo: undefined,
     pr: undefined,
+    lightweight: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -75,6 +81,7 @@ export function parseDetectCliArgs(argv) {
       input: { type: "string" },
       repo: { type: "string" },
       pr: { type: "string" },
+      lightweight: { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
@@ -104,6 +111,10 @@ export function parseDetectCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (token.name === "lightweight") {
+      options.lightweight = true;
+      continue;
+    }
     if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
@@ -129,7 +140,7 @@ export function parseDetectCliArgs(argv) {
   }
   return options;
 }
-async function fetchPrView({ repo, pr }, { env, ghCommand }) {
+async function fetchPrView({ repo, pr }, { env, ghCommand, runChild = defaultRunChild }) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "headRefOid,isDraft,state,number,reviews,statusCheckRollup"],
@@ -150,7 +161,7 @@ async function fetchPrView({ repo, pr }, { env, ghCommand }) {
   }
   return payload;
 }
-async function fetchCopilotRequested({ repo, pr }, { env, ghCommand }) {
+async function fetchCopilotRequested({ repo, pr }, { env, ghCommand, runChild = defaultRunChild }) {
   const result = await runChild(
     ghCommand,
     ["api", `repos/${repo}/pulls/${pr}/requested_reviewers`],
@@ -169,7 +180,7 @@ async function fetchCopilotRequested({ repo, pr }, { env, ghCommand }) {
   const users = Array.isArray(payload?.users) ? payload.users : [];
   return users.some((user) => isCopilotLogin(user?.login));
 }
-async function fetchLatestCopilotReviewRequestAt({ repo, pr }, { env, ghCommand }) {
+async function fetchLatestCopilotReviewRequestAt({ repo, pr }, { env, ghCommand, runChild = defaultRunChild }) {
   const result = await runChild(
     ghCommand,
     ["api", `repos/${repo}/issues/${pr}/timeline`, "--paginate", "--jq",
@@ -201,7 +212,7 @@ function extractPrVisibleCheckNames(statusCheckRollup) {
     .filter((name) => typeof name === "string" && name.length > 0);
 }
 
-async function fetchCurrentHeadCiEvidence({ repo, headSha, prVisibleCheckNames }, { env, ghCommand }) {
+async function fetchCurrentHeadCiEvidence({ repo, headSha, prVisibleCheckNames }, { env, ghCommand, runChild = defaultRunChild }) {
   const [checkRunsResult, statusesResult] = await Promise.all([
     runChild(
       ghCommand,
@@ -317,8 +328,8 @@ function hasSubmittedCopilotReviewOffCurrentHead(reviewSummary, currentHeadSha)
 }
 
 
-export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride, localValidationHeadSha, draftGateResetAtMs }, { env = process.env, ghCommand = "gh" } = {}) {
-  const prData = await fetchPrView({ repo, pr }, { env, ghCommand });
+export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride, localValidationHeadSha, draftGateResetAtMs }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
+  const prData = await fetchPrView({ repo, pr }, { env, ghCommand, runChild });
   if (prData === null) {
     return normalizeSnapshot({ prExists: false });
   }
@@ -344,13 +355,13 @@ export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride
   } else if (reviewSummary.hasPendingReviewOnCurrentHead) {
     copilotReviewRequestStatus = "requested";
   } else {
-    const copilotRequested = await fetchCopilotRequested({ repo, pr }, { env, ghCommand });
+    const copilotRequested = await fetchCopilotRequested({ repo, pr }, { env, ghCommand, runChild });
     if (!copilotRequested) {
       copilotReviewRequestStatus = "none";
     } else if (!reviewSummary.hasSubmittedReviewOnCurrentHead) {
       copilotReviewRequestStatus = "requested";
     } else {
-      const latestRequestAt = await fetchLatestCopilotReviewRequestAt({ repo, pr }, { env, ghCommand });
+      const latestRequestAt = await fetchLatestCopilotReviewRequestAt({ repo, pr }, { env, ghCommand, runChild });
       const latestReviewAt = reviewSummary.latestSubmittedReviewOnCurrentHeadAt;
       if (latestRequestAt !== null && latestReviewAt !== null && latestRequestAt > latestReviewAt) {
         copilotReviewRequestStatus = "requested";
@@ -365,7 +376,7 @@ export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride
   let actionableThreadCount = 0;
   let lastCopilotRoundMaxSignal = null;
   try {
-    const threadsPayload = await fetchGithubReviewThreadsPayload({ repo, pr }, { env, ghCommand });
+    const threadsPayload = await fetchGithubReviewThreadsPayload({ repo, pr }, { env, ghCommand, runChild });
     const parsed = parseReviewThreads(threadsPayload);
     unresolvedThreadCount = parsed.summary.unresolvedThreads;
     actionableThreadCount = parsed.summary.actionableThreads;
@@ -389,7 +400,7 @@ export async function autoDetectSnapshot({ repo, pr, reviewRequestStatusOverride
   let failureDetails = [];
   let excludedFailureDetails = [];
   if (shouldRefreshCurrentHeadCi) {
-    const refreshed = await fetchCurrentHeadCiEvidence({ repo, headSha: prHeadSha, prVisibleCheckNames }, { env, ghCommand });
+    const refreshed = await fetchCurrentHeadCiEvidence({ repo, headSha: prHeadSha, prVisibleCheckNames }, { env, ghCommand, runChild });
     currentHeadCiStatus = refreshed?.status ?? "none";
     failureDetails = refreshed?.failureDetails ?? [];
     excludedFailureDetails = refreshed?.excludedFailureDetails ?? [];
@@ -455,6 +466,15 @@ export async function runCli(
   const refinementConfig = config.errors.length > 0
     ? resolveRefinement({ version: 1 })
     : resolveRefinement(config.config);
+  if (options.lightweight) {
+    // Compose (not replace) the round cap for light-dispatched PRs (#1210):
+    // min(lightMode.maxCopilotRounds ?? 1, refinement.maxCopilotRounds), so
+    // maxCopilotRounds: 0 still disables Copilot rounds everywhere.
+    refinementConfig.maxCopilotRounds = resolveEffectiveCopilotRoundCap(
+      config.errors.length > 0 ? { version: 1 } : config.config,
+      { lightweight: true },
+    );
+  }
   interpretation = interpretLoopState(interpretationInput, refinementConfig);
   const interpretationSummary = summarizeLoopInterpretation(interpretation);
   process.exitCode = emitResult({

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

@@ -3,7 +3,7 @@ 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, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { parseArgs } from "node:util";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
@@ -184,7 +184,7 @@ export function parseCliArgs(argv) {
   return options;
 }
 
-async function fetchPrFiles({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchPrFiles({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "files", "--jq", ".files[].path"],
@@ -198,7 +198,7 @@ async function fetchPrFiles({ repo, pr }, { env = process.env, ghCommand = "gh"
   return paths;
 }
 
-async function fetchPrLabels({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchPrLabels({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "labels", "--jq", ".labels[].name"],
@@ -219,10 +219,10 @@ async function fetchPrLabels({ repo, pr }, { env = process.env, ghCommand = "gh"
  * - If ANY changed file doesn't match any pattern → internalOnly=false
  * - No blacklist needed — a non-matching file is consumer-facing by definition.
  */
-export async function detectInternalOnly(options, { env = process.env, ghCommand = "gh" } = {}) {
+export async function detectInternalOnly(options, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const patterns = loadInternalPathPatterns(options.config);
   const matchers = buildPatternMatchers(patterns);
-  const files = await fetchPrFiles(options, { env, ghCommand });
+  const files = await fetchPrFiles(options, { env, ghCommand, runChild });
 
   if (files.length === 0) {
     return {
@@ -250,7 +250,7 @@ export async function detectInternalOnly(options, { env = process.env, ghCommand
 
   // Check for explicit internal_only label if requested (confirmation only)
   if (options.labelCheck) {
-    const labels = await fetchPrLabels(options, { env, ghCommand });
+    const labels = await fetchPrLabels(options, { env, ghCommand, runChild });
     if (labels.includes("internal_only")) {
       // Label confirms — path check already passed
     }