dev-loops 0.7.2 → 0.8.0

package/agents/review.agent.md

@@ -29,18 +29,15 @@ You are a focused pull request review agent. You review an implementation for co
 
 ## Scoped angle-review mode
 
-This agent has two modes. The default mode is the full-PR review described in the rest of this file. The **scoped angle-review mode** is the per-angle reviewer of the gate-review fan-out ([Gate Review Sub-Loop Contract](../docs/gate-review-sub-loop-contract.md)): the gate skill builds ONE deterministic, neutral context bundle (diff + adjacent code) and seeds each independent `review` agent with that identical bundle, each scoped to exactly one review concern. You receive only the neutral artifact + your angle — never the main (orchestrating) agent's conversation, opinions, or state.
-
-You are in scoped angle-review mode when the invocation supplies a single review `<angle>` plus a gate-context artifact path (`tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json`, written by `scripts/github/write-gate-context.mjs`). Review like an external code reviewer hunting real bugs, not a process auditor: your job is to find concrete defects in the changed code and its call paths, not to remark that "there is no test" or that a doc section is thin. In that mode:
-
-- **No worktree isolation (mandatory):** you review in the PR's actual worktree/head — the same checkout the gate-context preamble ran in — never a fresh isolated worktree. You are read-only and never mutate files, so isolation buys nothing; a fresh worktree would also be checked out from `main` (not the PR head) and would lack the gitignored, worktree-local gate-context bundle below, so you'd silently review the wrong stale tree (#1135).
-- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle> --context-path <gate-context-artifact-path>` at startup. If it reports `fresh: false` (exit 1) or any error — including a missing gate-context artifact (`gateContextPresent: false`), which is the fail-closed signal that you're not in the right worktree/head — refuse to proceed and report the failure; do not review on inherited context or without seeded context. "Fresh" here means your context is the **neutral builder artifact + your angle**, and explicitly NOT the main agent's conversation/state or a prior reviewer session's state. The injected neutral bundle is the INTENDED seed (allowed); main-agent or cross-session state bleed still fails closed.
-- **Use the PROVIDED neutral bundle as your base; do NOT re-derive it from scratch:** the gate-context artifact carries the diff (`scope.diffPath`) and a deterministic, neutral adjacent-code bundle in `adjacentCode` (each changed file plus its 1-hop import in/out-edges, with a `stripped`/`truncated`/`missing` manifest). Start from this bundle — it is the build-once, work-deduped seed shared verbatim across all reviewers. Only widen (load more files) per-angle when the bundle genuinely lacks something your angle needs; do not re-build the whole diff/adjacent-code graph yourself.
-- **Single-angle scope:** review ONLY the supplied angle's concern. Read the gate-context artifact for the resolved angle set, change scope (branch, head SHA, touched files), acceptance-criteria pointer, and validation posture. Do not review other angles; the fan-in pass consolidates across angles.
-- **Read the FULL diff, not just hunks:** the gate-context artifact records `scope.diffPath` (a repo-relative path to the complete captured diff) and `scope.changedFiles` (full repo-relative paths). Read the entire diff from `scope.diffPath`; if it is `null` or missing, reconstruct it yourself with `git diff` against the change's base (e.g. `git diff origin/main...HEAD` or the branch/head SHA in `scope`). Do not review off a partial or summarized hunk list — you MUST see every changed line for your angle.
-- **Reason about ADJACENT related code from the bundle first:** the `adjacentCode` bundle already includes the changed files' callers, callees, and imports (1-hop). Read those entries before opening anything else. For each changed function, trace the real call paths a defect would flow through, and confirm that caller and callee contracts still match (argument shapes, return shapes, error/null conventions, units). If the bundle truncated or stripped a file you need (see its `truncated`/`stripped` manifest), open that file directly to widen.
-- **Review ADVERSARIALLY — hunt concrete defects:** actively try to break the changed code. Hunt for edge cases, missing or wrong input validation, numeric coercion bugs (NaN, Infinity, floats where integers are assumed, negative values, string-to-number coercion), null/undefined handling, off-by-one and boundary conditions, mismatched caller/callee contracts, and dedup/identity bugs (wrong key, reference vs. value equality, unstable ordering). For every finding, give the concrete `file:line` plus the specific failing scenario or input that triggers the defect — not high-altitude "is there a test?" commentary.
-- **Strictly read-only, but WIDEN SCOPE when needed:** never edit files, stage, commit, push, request reviews, resolve threads, or post PR comments. Findings are returned via the output artifact only; fixes are applied later by the fix cycle, not by this agent. Because you are read-only, you MAY open any additional repository files required to judge your angle (callers, callees, contracts, sibling modules, configs, tests) — widening to read adjacent code is expected and safe. Record every file/module you consulted beyond the briefing's `changedFiles`/`diffPath` in the optional `contextWidened` field on your output artifact.
+This agent has two modes. The default mode is the full-PR review described in the rest of this file. In **scoped angle-review mode** you are one per-angle reviewer of the gate-review fan-out. You are in this mode when the invocation supplies a single review `<angle>` plus a gate-context artifact path (`tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json`, written by `scripts/github/write-gate-context.mjs`).
+
+Its full execution shape is owned elsewhere — read those owners before reviewing and do not re-derive their rules here:
+
+- The build-once neutral bundle seeding, fresh-context guard (`verify-fresh-review-context.mjs`), no-worktree-isolation prohibition (#1135), single-angle read-only scope, and briefing composition are owned by the [Gate Review Sub-Loop Contract](../docs/gate-review-sub-loop-contract.md) (`GATE-EXEC-BUILD-ONCE-SEED`, `GATE-EXEC-BRIEFING-PREFIX`) — you receive only the neutral artifact + your angle, never the orchestrating agent's conversation, opinions, or state.
+- The adversarial reviewing behavior is owned by `COPILOT-FOLLOWUP-ADVERSARIAL-BRIEFING` in the [Copilot PR Follow-up Skill](../skills/copilot-pr-followup/SKILL.md): read the FULL diff (from `scope.diffPath`, or reconstruct it with `git diff` against the change base when `scope.diffPath` is null/missing — never a hunk-only review) plus the bundled adjacent code rather than re-deriving them, then hunt concrete `file:line` defects (edge cases, input validation, numeric coercion incl. NaN/Infinity/floats/negatives, null/undefined, boundary conditions, mismatched caller/callee contracts, dedup/identity bugs) over process nits, recording any scope-widening in the optional `contextWidened` field on your findings artifact.
+
+Follow those owners, then return your findings via the structured artifact below (this agent's canonical output contract):
+
 - **Structured findings artifact:** return a single JSON object the fan-in consolidator (`@dev-loops/core/loop/gate-fanin`) can parse, written to the deterministic per-angle path `tmp/gate-reviews/<repo-slug>/pr-<N>/<gate>-<headSha>/<angle>.json`:
 
   ```json

package/extension/README.md

@@ -101,7 +101,7 @@ The messaging distinguishes between local loop readiness and remote GitHub/Copil
 
 ## Configuration
 
-The dev-loop workflow is driven by a YAML config at `.pi/dev-loop/defaults.yaml` (shipped with the package) and an optional consumer settings file at `.devloops` at repo root (the loader also accepts `.devloops.yaml`, `.devloops.yml`, and `.devloops.json`; legacy `.pi/dev-loop/settings.*` and `overrides.*` still load as fallbacks with a deprecation warning).
+The dev-loop workflow is driven by the shipped defaults in `packages/core/src/config/extension-defaults.yaml`, an optional repo-local `.pi/dev-loop/defaults.*` layer that merges on top of them, and an optional consumer settings file at `.devloops` at repo root (the loader also accepts `.devloops.yaml`, `.devloops.yml`, and `.devloops.json`; legacy `.pi/dev-loop/settings.*` and `.pi/dev-loop/overrides.*` load only as a fallback when no `.devloops` is present, and are ignored when `.devloops` exists — a deprecation warning still fires).
 
 ### How consumers customize config
 
@@ -191,8 +191,9 @@ workflow:
 ### Config precedence
 
 1. Built-in defaults (`packages/core/src/config/config.mjs` `BUILT_IN_DEFAULTS`)
-2. Shipped defaults (`.pi/dev-loop/defaults.yaml` — committed in source repo)
-3. Consumer settings (`.devloops` at repo root — preferred; `.devloops.yaml`/`.devloops.yml`/`.devloops.json` also load; legacy `.pi/dev-loop/settings.*` and `overrides.*` still load as fallbacks with deprecation warning)
+2. Shipped defaults (`packages/core/src/config/extension-defaults.yaml`)
+3. Repo-local override layer (`.pi/dev-loop/defaults.*` — merges on top of the shipped defaults when present)
+4. Consumer settings (`.devloops` at repo root — preferred and authoritative when present; `.devloops.yaml`/`.devloops.yml`/`.devloops.json` also load; legacy `.pi/dev-loop/settings.*` and `.pi/dev-loop/overrides.*` load only as a fallback when no `.devloops` is present; when `.devloops` exists they are ignored, with a deprecation warning)
 
 ### Adding custom review angles
 
@@ -221,7 +222,7 @@ Current Phase 3+ contract:
 - this phase does not require a separate compiled build or `dist/` pipeline
 
 Root verification and test commands are intentionally explicit:
-- `npm run verify` is the canonical root verification path (`npm test` + `npm run test:dev-loop`)
+- `npm run verify` is the canonical root verification path; it runs every suite in parallel via `run-p` as a single aggregated command, and any suite failing fails verify
 - `npm test` runs the current root test suite (`test:assets`, `test:extension`, `test:scripts`, `test:core`, and `test:docs`)
 - `npm run test:extension`
 - `npm run test:extension` currently expands to one `node --import tsx --test ...` invocation in `package.json`; prefer the script entrypoint over copying the file list into downstream docs or runbooks

package/package.json

@@ -21,8 +21,8 @@
     "packages/*"
   ],
   "scripts": {
-    "verify": "npm test && npm run test:dev-loop",
-    "test": "npm run test:assets && npm run test:extension && npm run test:scripts && npm run test:core && npm run test:docs && npm run test:pack",
+    "verify": "run-p --aggregate-output --continue-on-error test:assets test:extension test:scripts test:core test:docs test:pack test:dev-loop",
+    "test": "run-p --aggregate-output --continue-on-error test:assets test:extension test:scripts test:core test:docs test:pack",
     "test:assets": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/dev-loop-init-phase-smoke.test.mjs test/contracts/*.test.mjs test/workflow-handoff-contract.test.mjs",
     "test:extension": "node --import tsx --test --test-reporter ./test/failure-summary-reporter.mjs test/extension-checks.test.mjs test/extension-post-merge-update.test.mjs test/extension-command-contract.test.mjs test/extension-package-contract.test.mjs test/extension-pi-adapter.test.mjs test/dev-loops-core.test.mjs test/dev-loops-cli.test.mjs",
     "test:scripts": "GIT_CONFIG_COUNT=2 GIT_CONFIG_KEY_0=core.fsync GIT_CONFIG_VALUE_0=none GIT_CONFIG_KEY_1=core.fsyncObjectFiles GIT_CONFIG_VALUE_1=false node --test --test-reporter ./test/failure-summary-reporter.mjs test/github/*.test.mjs test/loop/*.test.mjs test/docs/*.test.mjs test/projects/*.test.mjs test/pages/*.test.mjs",
@@ -58,6 +58,7 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
+    "npm-run-all2": "^9.0.2",
     "tsx": "^4.22.0"
   },
   "pi": {
@@ -72,7 +73,7 @@
     ]
   },
   "dependencies": {
-    "@dev-loops/core": "^0.7.2"
+    "@dev-loops/core": "^0.8.0"
   },
   "repository": {
     "type": "git",
@@ -82,7 +83,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "files": [
     "cli/",
     "lib/",

package/scripts/docs/validate-state-machine-conformance.mjs

@@ -63,6 +63,7 @@ import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from
 import { DISPOSITION, interpretLoopState, STATE, TRANSITIONS } from "@dev-loops/core/loop/copilot-loop-state";
 import { evaluateConductorRouting, getAllowedOuterTransitions, OUTER_STATE, OUTER_TERMINAL_STATES } from "@dev-loops/core/loop/conductor-routing";
 import { interpretReviewerLoopState, REVIEWER_STATE, REVIEWER_TRANSITIONS } from "@dev-loops/core/loop/reviewer-loop-state";
+import { interpretRefinementGrillState, GRILL_STATE, GRILL_TRANSITIONS } from "@dev-loops/core/loop/refinement-grill-state";
 import { PR_LIFECYCLE_STATES, PR_LIFECYCLE_TERMINAL_STATES, PR_LIFECYCLE_TRANSITIONS } from "@dev-loops/core/loop/pr-lifecycle";
 import { DEV_LOOP_GATE, DEV_LOOP_ROUTE_KIND, PUBLIC_DEV_LOOP_GATE_CONTRACT, DEV_LOOP_PUBLIC_INTENT, DEV_LOOP_TARGET_KIND, DEV_LOOP_ACTOR, DEV_LOOP_STATUS, DEV_LOOP_AUTHORIZATION, DEV_LOOP_TARGET_PREFERENCE, INTERNAL_DEV_LOOP_STRATEGY, evaluatePublicDevLoopRouting } from "@dev-loops/core/loop/public-dev-loop-routing";
 
@@ -939,7 +940,83 @@ const REVIEWER_LOOP_STATE_MACHINE = {
 registerMachine(REVIEWER_LOOP_STATE_MACHINE);
 
 // ---------------------------------------------------------------------------
-// Fifth machine (issue #1233): public-dev-loop-routing.
+// Fifth machine (issue #1267): refinement-grill-state.
+//
+// Doc side: docs/refinement-grill-state-graph.md's "## Required transitions" bullets, with
+// one abstract row expanded via REFINEMENT_GRILL_ABSTRACT_ROWS below (the fail-closed
+// load/parse failure edge fires from every non-terminal state into
+// blocked_needs_user_decision). The interpreter checks loadFailed first (fail closed), then
+// the unresolvedGapCount handoff (honest handoff outranks synthesis), then the
+// iterate-to-clean branches.
+//
+// Code side: packages/core/src/loop/refinement-grill-state.mjs exports GRILL_STATE,
+// GRILL_TRANSITIONS, and interpretRefinementGrillState. Checked the same two ways as
+// copilot-loop-state / reviewer-loop-state above: structurally (the edge exists in the real
+// GRILL_TRANSITIONS table) and behaviorally (a fixture reaching `to` lands on `to`).
+// ---------------------------------------------------------------------------
+
+const REFINEMENT_GRILL_ABSTRACT_ROWS = new Map([
+  ["any non-terminal grill state->`blocked_needs_user_decision`", [
+    [GRILL_STATE.LOAD_TARGET, GRILL_STATE.BLOCKED_NEEDS_USER_DECISION],
+    [GRILL_STATE.DETECT_GAPS, GRILL_STATE.BLOCKED_NEEDS_USER_DECISION],
+    [GRILL_STATE.AWAIT_ANSWERS, GRILL_STATE.BLOCKED_NEEDS_USER_DECISION],
+    [GRILL_STATE.SYNTHESIZE, GRILL_STATE.BLOCKED_NEEDS_USER_DECISION],
+    [GRILL_STATE.RE_GRILL, GRILL_STATE.BLOCKED_NEEDS_USER_DECISION],
+  ]],
+]);
+
+const REFINEMENT_GRILL_DOC_TRANSITIONS = parseRequiredTransitions(
+  readFileSync(path.join(REPO_ROOT, "docs", "refinement-grill-state-graph.md"), "utf8"),
+  { abstractRows: REFINEMENT_GRILL_ABSTRACT_ROWS },
+);
+
+bindDocToCodeTable("refinement-grill-state", REFINEMENT_GRILL_DOC_TRANSITIONS, tableEdges(GRILL_TRANSITIONS));
+
+const REFINEMENT_GRILL_TO_FIXTURE = new Map([
+  [GRILL_STATE.DETECT_GAPS, () => ({ loaded: true, detectRan: false })],
+  [GRILL_STATE.AWAIT_ANSWERS, () => ({ loaded: true, detectRan: true, openGapCount: 2 })],
+  [GRILL_STATE.SYNTHESIZE, () => ({ loaded: true, detectRan: true, answersReady: true })],
+  [GRILL_STATE.RE_GRILL, () => ({ loaded: true, synthesized: true, reGrillRan: false })],
+  [GRILL_STATE.GRILL_CLEAN, () => ({ loaded: true, detectRan: true, openGapCount: 0 })],
+  [GRILL_STATE.NEEDS_HUMAN_HANDOFF, () => ({ loaded: true, detectRan: true, unresolvedGapCount: 1 })],
+  [GRILL_STATE.BLOCKED_NEEDS_USER_DECISION, () => ({ loadFailed: true })],
+]);
+
+const REFINEMENT_GRILL_TRANSITION_CHECKS = new Map();
+for (const [from, to] of realEdges(REFINEMENT_GRILL_DOC_TRANSITIONS)) {
+  const buildFixture = REFINEMENT_GRILL_TO_FIXTURE.get(to);
+  if (!buildFixture) throw new Error(`refinement-grill-state: no fixture registered for reachable state "${to}"`);
+  REFINEMENT_GRILL_TRANSITION_CHECKS.set(`${from}->${to}`, {
+    status: "verified",
+    verify: () => {
+      const f = buildFixture();
+      const i = interpretRefinementGrillState(f);
+      return {
+        ok: i.state === to && (GRILL_TRANSITIONS[from] || []).includes(to),
+        detail: i,
+        result: { state: i.state, loadFailed: Boolean(f.loadFailed), hasUnresolved: (f.unresolvedGapCount || 0) > 0 },
+      };
+    },
+  });
+}
+
+const REFINEMENT_GRILL_STATE_MACHINE = {
+  name: "refinement-grill-state",
+  states: Object.values(GRILL_STATE),
+  terminalStates: tableTerminalStates(GRILL_TRANSITIONS),
+  transitions: tableEdges(GRILL_TRANSITIONS),
+  docTransitions: REFINEMENT_GRILL_DOC_TRANSITIONS,
+  transitionChecks: REFINEMENT_GRILL_TRANSITION_CHECKS,
+  safetyRules: [
+    { name: "grill-load-failure-fails-closed", check: (o) => !o.loadFailed || o.state === GRILL_STATE.BLOCKED_NEEDS_USER_DECISION },
+    { name: "grill-unresolved-gap-hands-off", check: (o) => !o.hasUnresolved || o.loadFailed || o.state === GRILL_STATE.NEEDS_HUMAN_HANDOFF },
+  ],
+};
+
+registerMachine(REFINEMENT_GRILL_STATE_MACHINE);
+
+// ---------------------------------------------------------------------------
+// Sixth machine (issue #1233): public-dev-loop-routing.
 //
 // Doc side: skills/docs/public-dev-loop-contract.md's "## Required transitions" bullets,
 // parsed at load time. Like conductor-routing, the gate graph is stateless per cycle, so each

package/scripts/github/_gate-names.mjs

@@ -0,0 +1,5 @@
+// Canonical gate vocabulary — the single source of truth for gate names shared
+// across the gate-review tooling. Imported by write-gate-context.mjs (artifact
+// gate validation) and verify-briefing-prefixes.mjs (wrong-gate scope check) so
+// the two can never drift.
+export const GATE_NAMES = ["draft_gate", "pre_approval_gate"];

package/scripts/github/capture-review-threads.mjs

@@ -9,7 +9,7 @@ import {
   readInput,
 } from "../_core-helpers.mjs";
 import { parseArgs } from "node:util";
-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 { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 export const REVIEW_THREADS_QUERY = [
@@ -118,7 +118,7 @@ export function parseCaptureCliArgs(argv) {
 }
 export async function fetchGithubReviewThreadsPayload(
   { repo, pr },
-  { env = process.env, ghCommand = "gh" } = {},
+  { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {},
 ) {
   const { owner, name } = parseRepoSlug(repo);
   const result = await runChild(

package/scripts/github/detect-checkpoint-evidence.mjs

@@ -11,7 +11,7 @@ import {
 } from "../_core-helpers.mjs";
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
 import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { FANOUT_PROVENANCE_MIN_REVIEWERS, GATE_FULL_LABEL, loadDevLoopConfig, resolveGateAngleContract, resolveGateConfig, resolveLightMode, resolveRejectForeignAngles, resolveRequireFanoutEvidence, resolveRequireFanoutProvenance } from "@dev-loops/core/config";
@@ -148,7 +148,7 @@ export function parseDetectCheckpointEvidenceCliArgs(argv) {
   }
   return options;
 }
-async function runGhJson(args, { env, ghCommand }) {
+async function runGhJson(args, { env, ghCommand, runChild = defaultRunChild }) {
   const result = await runChild(ghCommand, args, env);
   if (result.code !== 0) {
     const detail = result.stderr.trim() || `exit code ${result.code}`;
@@ -534,7 +534,7 @@ export async function buildFanoutEnforcement({ repo, pr, currentHeadSha, draftGa
   }
   return { required: true, requireProvenance, rejectForeignAngles, lightMode, hasFullLabel, gates };
 }
-export async function detectCheckpointEvidence(options, { env = process.env, ghCommand = "gh", cwd = process.cwd() } = {}) {
+export async function detectCheckpointEvidence(options, { env = process.env, ghCommand = "gh", runChild = defaultRunChild, cwd = process.cwd() } = {}) {
   const runnerOwnership = await ensureAsyncRunnerOwnership({
     repo: options.repo,
     pr: options.pr,
@@ -558,8 +558,8 @@ export async function detectCheckpointEvidence(options, { env = process.env, ghC
     error.staleRunner = staleRunnerDetection;
     throw error;
   }
-  const prPayload = await runGhJson(["pr", "view", String(options.pr), "--repo", options.repo, "--json", "headRefOid"], { env, ghCommand });
-  const commentsPayload = normalizeIssueCommentsPayload(await runGhJson(["api", "--paginate", "--slurp", `repos/${options.repo}/issues/${options.pr}/comments?per_page=100`], { env, ghCommand }));
+  const prPayload = await runGhJson(["pr", "view", String(options.pr), "--repo", options.repo, "--json", "headRefOid"], { env, ghCommand, runChild });
+  const commentsPayload = normalizeIssueCommentsPayload(await runGhJson(["api", "--paginate", "--slurp", `repos/${options.repo}/issues/${options.pr}/comments?per_page=100`], { env, ghCommand, runChild }));
   const currentHeadSha = typeof prPayload?.headRefOid === "string" && prPayload.headRefOid.trim().length > 0
     ? prPayload.headRefOid.trim()
     : null;
@@ -571,7 +571,7 @@ export async function detectCheckpointEvidence(options, { env = process.env, ghC
   // as a PR review rather than an issue comment (root cause 3 from issue #692).
   let prReviews = [];
   try {
-    const reviewsRaw = await runGhJson(["api", "--paginate", "--slurp", `repos/${options.repo}/pulls/${options.pr}/reviews?per_page=100`], { env, ghCommand });
+    const reviewsRaw = await runGhJson(["api", "--paginate", "--slurp", `repos/${options.repo}/pulls/${options.pr}/reviews?per_page=100`], { env, ghCommand, runChild });
     prReviews = normalizePrReviewsPayload(reviewsRaw);
   } catch {
     // Graceful fallback: PR reviews fetch failure is non-fatal.
@@ -601,7 +601,7 @@ export async function detectCheckpointEvidence(options, { env = process.env, ghC
   );
   if (config != null && resolveRequireFanoutEvidence(config) && resolveLightMode(config) != null && anyInlineVerdict) {
     try {
-      const lightFacts = await runGhJson(["pr", "view", String(options.pr), "--repo", options.repo, "--json", "baseRefOid,labels"], { env, ghCommand });
+      const lightFacts = await runGhJson(["pr", "view", String(options.pr), "--repo", options.repo, "--json", "baseRefOid,labels"], { env, ghCommand, runChild });
       baseRef = typeof lightFacts?.baseRefOid === "string" && lightFacts.baseRefOid.trim().length > 0
         ? lightFacts.baseRefOid.trim()
         : null;

package/scripts/github/edit-issue.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseIssueNumber, requireTokenValue, runChild } 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";
+
+const USAGE = `Usage: edit-issue.mjs --repo <owner/name> --issue <number> [--title <t>] [--body <b> | --body-file <path>] [--add-assignee <u>] [--remove-assignee <u>] [--milestone <m>]
+Edit issue title/body/assignees/milestone. Thin wrapper over \`gh issue edit\` — use this
+instead of an agent-level raw \`gh issue edit\` so the loop's internal-tooling record
+stays clean (siblings: edit-pr.mjs, comment-issue.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --issue <number>              Issue number
+At least one edit:
+  --title <t>                   New issue title
+  --body <b>                    New issue body as a single argument
+  --body-file <path>            Read the new body from a file (- reads stdin)
+  --add-assignee <u>            Assignee to add (repeatable)
+  --remove-assignee <u>         Assignee to remove (repeatable)
+  --milestone <m>               Milestone to set (empty string clears it)
+                                (--title/--body/--body-file reject empty or
+                                whitespace-only values; use --milestone "" only
+                                to clear the milestone)
+Output (stdout, JSON):
+  { "ok": true, "repo": "owner/repo", "issue": 17, "edited": ["title", "body", ...] }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseEditIssueCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+      title: { type: "string" },
+      body: { type: "string" },
+      "body-file": { type: "string" },
+      "add-assignee": { type: "string", multiple: true },
+      "remove-assignee": { type: "string", multiple: true },
+      milestone: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    issue: undefined,
+    title: undefined,
+    body: undefined,
+    bodyFile: undefined,
+    addAssignees: [],
+    removeAssignees: [],
+    milestone: undefined,
+    jq: undefined,
+    silent: false,
+  };
+  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.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
+      continue;
+    }
+    if (token.name === "title") {
+      const title = requireTokenValue(token, parseError);
+      if (title.trim().length === 0) {
+        throw parseError("--title must not be empty or whitespace-only");
+      }
+      options.title = title;
+      continue;
+    }
+    if (token.name === "body") {
+      const body = requireTokenValue(token, parseError);
+      if (body.trim().length === 0) {
+        throw parseError("--body must not be empty or whitespace-only");
+      }
+      options.body = body;
+      continue;
+    }
+    if (token.name === "body-file") {
+      const rawPath = requireTokenValue(token, parseError).trim();
+      if (rawPath.length === 0) {
+        throw parseError("--body-file must be a non-empty path");
+      }
+      options.bodyFile = rawPath;
+      continue;
+    }
+    if (token.name === "add-assignee") {
+      const u = requireTokenValue(token, parseError).trim();
+      if (u.length === 0) throw parseError("--add-assignee must be a non-empty login");
+      options.addAssignees.push(u);
+      continue;
+    }
+    if (token.name === "remove-assignee") {
+      const u = requireTokenValue(token, parseError).trim();
+      if (u.length === 0) throw parseError("--remove-assignee must be a non-empty login");
+      options.removeAssignees.push(u);
+      continue;
+    }
+    if (token.name === "milestone") {
+      // Read the raw token value: an empty string is a valid milestone value
+      // (`gh issue edit --milestone ""` clears it), so this deliberately does NOT
+      // go through requireTokenValue (which rejects empty). Guard only a truly
+      // missing value (`--milestone` with no following token). A whitespace-only
+      // value is neither a clear nor a real milestone name — fail closed rather
+      // than forwarding it to gh for a less actionable error.
+      if (typeof token.value !== "string") {
+        throw parseError("--milestone requires a value (use an empty string to clear)");
+      }
+      if (token.value.length > 0 && token.value.trim().length === 0) {
+        throw parseError('--milestone must be a milestone name or "" to clear (whitespace-only is not allowed)');
+      }
+      options.milestone = token.value;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined || options.issue === undefined) {
+    throw parseError("Editing an issue requires both --repo <owner/name> and --issue <number>");
+  }
+  if (options.body !== undefined && options.bodyFile !== undefined) {
+    throw parseError("--body and --body-file are mutually exclusive; pass only one");
+  }
+  const hasEdit =
+    options.title !== undefined ||
+    options.body !== undefined ||
+    options.bodyFile !== undefined ||
+    options.addAssignees.length > 0 ||
+    options.removeAssignees.length > 0 ||
+    options.milestone !== undefined;
+  if (!hasEdit) {
+    throw parseError("Editing an issue requires at least one of --title/--body/--body-file/--add-assignee/--remove-assignee/--milestone");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+async function resolveBody(options) {
+  if (options.bodyFile === undefined) return options.body;
+  // Stdin (fd 0): the fs/promises readFile does NOT accept an integer fd, so read
+  // it synchronously via the callback-style API (which does). A real path stays on
+  // the async promise read.
+  const body =
+    options.bodyFile === "-" ? readFileSync(0, "utf8") : await readFile(options.bodyFile, "utf8");
+  // Fail closed on an empty / whitespace-only file so a blank --body-file cannot
+  // silently clear the issue body (USAGE promises --body/--title reject empties).
+  if (body.trim().length === 0) {
+    throw new Error(`--body-file ${options.bodyFile} is empty`);
+  }
+  return body;
+}
+
+// Build the `gh issue edit` args and the parallel `edited` list (which fields were
+// touched) so callers get a stable summary without re-reading the issue.
+async function buildEditArgs(options) {
+  const args = ["issue", "edit", String(options.issue), "--repo", options.repo];
+  const edited = [];
+  if (options.title !== undefined) {
+    args.push("--title", options.title);
+    edited.push("title");
+  }
+  // resolveBody still runs for validation (reads the file, throws on empty /
+  // whitespace-only). A REAL --body-file path is handed straight to gh so large
+  // bodies avoid command-length limits. But `--body-file -` (stdin) was already
+  // consumed by resolveBody reading fd 0; re-emitting `--body-file -` makes gh
+  // re-read an exhausted stdin and clear the body, so pass the resolved string
+  // inline via --body instead.
+  const body = await resolveBody(options);
+  if (body !== undefined) {
+    if (options.bodyFile !== undefined && options.bodyFile !== "-") {
+      args.push("--body-file", options.bodyFile);
+    } else {
+      args.push("--body", body);
+    }
+    edited.push("body");
+  }
+  for (const u of options.addAssignees) {
+    args.push("--add-assignee", u);
+  }
+  if (options.addAssignees.length > 0) edited.push("add-assignee");
+  for (const u of options.removeAssignees) {
+    args.push("--remove-assignee", u);
+  }
+  if (options.removeAssignees.length > 0) edited.push("remove-assignee");
+  if (options.milestone !== undefined) {
+    args.push("--milestone", options.milestone);
+    edited.push("milestone");
+  }
+  return { args, edited };
+}
+
+export async function editIssue(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const { args, edited } = await buildEditArgs(options);
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue edit failed: ${detail}`);
+  }
+  return { ok: true, repo: options.repo, issue: options.issue, edited };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild } = {},
+) {
+  let options;
+  try {
+    options = parseEditIssueCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await editIssue(options, { env, ghCommand, run });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => { process.exitCode = code; });
+}

package/scripts/github/probe-ci-status.mjs

@@ -14,6 +14,8 @@ import {
   DEFAULT_POLL_INTERVAL_MS,
   COPILOT_REVIEW_WAIT_TIMEOUT_MS,
 } from "@dev-loops/core/loop/policy-constants";
+import { ensureAsyncRunnerOwnership } from "../loop/_pr-runner-coordination.mjs";
+import { resolveRepoRoot } from "../loop/_repo-root-resolver.mjs";
 
 /** Maximum interval between heartbeat outputs during watch delays.
  *  Must be shorter than pi-subagents default needsAttentionAfterMs (60s). */
@@ -341,8 +343,10 @@ export async function watchCiStatus(
     ghCommand = "gh",
     delayImpl = delay,
     now = Date.now,
+    ensureOwnershipImpl = ensureAsyncRunnerOwnership,
   } = {},
 ) {
+  const leaseCwd = resolveRepoRoot(process.cwd());
   const { headSha: baselineSha, prVisibleCheckNames } = await fetchPrHeadSha(
     { repo: options.repo, pr: options.pr },
     { env, ghCommand },
@@ -382,6 +386,20 @@ export async function watchCiStatus(
               maxPolls: attemptBudget,
             }) + "\n",
           );
+          // The blocking CI wait can span the full watch budget, which equals the
+          // runner-coordination stale window; refresh the lease alongside each
+          // heartbeat so the claim stays fresh for every caller of this engine.
+          // No-ops without DEVLOOPS_RUN_ID; best-effort, never affects the watch.
+          try {
+            await ensureOwnershipImpl({
+              repo: options.repo,
+              pr: options.pr,
+              env,
+              cwd: leaseCwd,
+              claimIfMissing: true,
+              requireExisting: false,
+            });
+          } catch { /* best-effort: never affect the watch */ }
         }
       }
     }