dev-loops 0.6.0 → 0.7.2

package/scripts/github/write-gate-findings-log.mjs

@@ -4,6 +4,9 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+import { checkFanoutAngleCoverage, provenanceConsistencyError } from "@dev-loops/core/loop/gate-fanin";
+import { loadDevLoopConfig, resolveGateAngleContract, resolveRejectForeignAngles } from "@dev-loops/core/config";
 const USAGE = `Usage: write-gate-findings-log.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --verdict <clean|findings_present|blocked> --findings <json> [--tmp-root <path>]
 Write a durable <gate>-<headSha>.json log under deterministic tmp/ paths.
 Required:
@@ -14,7 +17,11 @@ Required:
   --verdict <clean|findings_present|blocked>
   --findings <json>              JSON array of finding objects with severity, disposition, angle, and summary
 Optional:
+  --provenance <json>            Fan-out provenance object: { distinctReviewers: <int>, perAngle: [{ angle, reviewer?, dispatchId?, model? }] }
+                                 distinctReviewers must be <= the distinct reviewers recorded in perAngle (perAngle non-empty when distinctReviewers > 0)
   --tmp-root <path>              Root tmp directory (default: tmp/)
+
+${JQ_OUTPUT_USAGE}
 `.trim();
 function parseError(message) {
   return Object.assign(new Error(message), { usage: USAGE });
@@ -24,6 +31,7 @@ function normalizeGate(value) {
   const normalized = String(value).trim().toLowerCase();
   return gates.has(normalized) ? normalized : null;
 }
+const GATE_CONFIG_KEY = { draft_gate: "draft", pre_approval_gate: "preApproval" };
 function normalizeVerdict(value) {
   const verdicts = new Set(["clean", "findings_present", "blocked"]);
   const normalized = String(value).trim().toLowerCase();
@@ -89,6 +97,95 @@ function parseFindingsJson(raw) {
     return entry;
   });
 }
+/**
+ * Validate + normalize the fan-out provenance object. Records how many distinct
+ * reviewer agents were dispatched (distinctReviewers) and per-angle dispatch
+ * provenance (perAngle). Rejects MALFORMED or self-INCONSISTENT provenance (bad
+ * shape, or a distinctReviewers claim not backed by recorded dispatch entries).
+ * This raises the bar; it does NOT make provenance un-forgeable — a determined
+ * single agent can still write an internally-consistent blob. Un-forgeable
+ * recording is the Pi-harness bridge (subagent tool at child depth). Returns the
+ * normalized object.
+ */
+export function parseProvenanceJson(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw parseError("--provenance must be valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw parseError("--provenance must be a JSON object");
+  }
+  if (!Number.isInteger(parsed.distinctReviewers) || parsed.distinctReviewers < 0) {
+    throw parseError("--provenance.distinctReviewers must be a non-negative integer");
+  }
+  if (!Array.isArray(parsed.perAngle)) {
+    throw parseError("--provenance.perAngle must be an array");
+  }
+  const perAngle = parsed.perAngle.map((a, i) => {
+    if (!a || typeof a !== "object" || Array.isArray(a)) {
+      throw parseError(`--provenance.perAngle[${i}] must be an object`);
+    }
+    if (typeof a.angle !== "string" || a.angle.trim().length === 0) {
+      throw parseError(`--provenance.perAngle[${i}].angle is required`);
+    }
+    const entry = { angle: a.angle.trim() };
+    for (const key of ["reviewer", "dispatchId", "model"]) {
+      if (key in a) {
+        if (typeof a[key] !== "string" || a[key].trim().length === 0) {
+          throw parseError(`--provenance.perAngle[${i}].${key} must be a non-empty string`);
+        }
+        entry[key] = a[key].trim();
+      }
+    }
+    return entry;
+  });
+  const normalized = { distinctReviewers: parsed.distinctReviewers, perAngle };
+  // Internal-consistency gate: a distinctReviewers claim must be backed by that
+  // many distinct recorded reviewer identities (closes the {n, perAngle:[]} loophole).
+  const consistencyError = provenanceConsistencyError(normalized);
+  if (consistencyError) {
+    throw parseError(`--${consistencyError}`);
+  }
+  return normalized;
+}
+/**
+ * Validate recorded provenance.perAngle against the gate's configured angle
+ * contract (mandatoryAngles + pool, resolved from .devloops/defaults). A
+ * missing mandatory angle always fails the write. A foreign (out-of-pool)
+ * angle fails the write unless `gates.rejectForeignAngles: false`, in which
+ * case it is returned as a warning instead. Throws a `parseError`-shaped Error
+ * (matching this module's other validation failures) on a fail-closed
+ * rejection.
+ *
+ * @param {{ perAngle: Array<{ angle: string }> }} provenance
+ * @param {"draft_gate"|"pre_approval_gate"} gate
+ * @param {{ repoRoot?: string }} [options]
+ * @returns {Promise<{ warning: string|null }>}
+ */
+export async function checkProvenanceAngleCoverage(provenance, gate, { repoRoot = process.cwd() } = {}) {
+  const { config } = await loadDevLoopConfig({ repoRoot });
+  const gateKey = GATE_CONFIG_KEY[gate];
+  const { mandatoryAngles, pool } = resolveGateAngleContract(config, gateKey);
+  const { missingMandatory, foreignAngles } = checkFanoutAngleCoverage(provenance.perAngle, {
+    mandatoryAngles,
+    pool,
+  });
+  if (missingMandatory.length > 0) {
+    throw parseError(
+      `--provenance.perAngle is missing mandatory angle(s) for ${gate}: ${missingMandatory.join(", ")} (configured in gates.${gateKey}.mandatoryAngles)`,
+    );
+  }
+  if (foreignAngles.length > 0) {
+    const message = `--provenance.perAngle names angle(s) outside the configured pool for ${gate}: ${foreignAngles.join(", ")}`;
+    if (resolveRejectForeignAngles(config)) {
+      throw parseError(`${message} (add them to gates.${gateKey}.angles, or set gates.rejectForeignAngles: false to warn instead of fail)`);
+    }
+    return { warning: `${message} (gates.rejectForeignAngles is false; recorded as a warning)` };
+  }
+  return { warning: null };
+}
 export function parseWriteGateFindingsLogCliArgs(argv) {
   const { tokens } = parseArgs({
     args: [...argv],
@@ -100,7 +197,9 @@ export function parseWriteGateFindingsLogCliArgs(argv) {
       "head-sha": { type: "string" },
       verdict: { type: "string" },
       findings: { type: "string" },
+      provenance: { type: "string" },
       "tmp-root": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -155,10 +254,15 @@ export function parseWriteGateFindingsLogCliArgs(argv) {
       options.findings = requireTokenValue(token, parseError);
       continue;
     }
+    if (token.name === "provenance") {
+      options.provenance = requireTokenValue(token, parseError);
+      continue;
+    }
     if (token.name === "tmp-root") {
       options.tmpRoot = requireTokenValue(token, parseError).trim();
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const missing = ["repo", "pr", "gate", "headSha", "verdict", "findings"]
@@ -183,6 +287,13 @@ export function buildLogPath({ repo, pr, gate, headSha, tmpRoot }) {
 }
 export async function writeGateFindingsLog(options, { repoRoot = process.cwd() } = {}) {
   const findings = parseFindingsJson(options.findings);
+  const provenance = options.provenance === undefined ? undefined : parseProvenanceJson(options.provenance);
+  // Angle-coverage enforcement (fail-closed on missing mandatory angles / foreign
+  // angles) only applies when provenance is actually recorded — provenance
+  // remains optional and additive (inline_single_agent writes never carry it).
+  const angleCoverage = provenance !== undefined
+    ? await checkProvenanceAngleCoverage(provenance, options.gate, { repoRoot })
+    : { warning: null };
   const logPath = buildLogPath({
     repo: options.repo,
     pr: options.pr,
@@ -200,9 +311,18 @@ export async function writeGateFindingsLog(options, { repoRoot = process.cwd() }
     loggedAt: new Date().toISOString(),
     findings,
   };
+  // Provenance is optional and additive: when absent the ledger writes exactly
+  // as before (no provenance key), preserving byte-identical output for the
+  // default / Claude-Code path. When present it records fan-out provenance for
+  // gates.requireFanoutProvenance enforcement.
+  if (provenance !== undefined) {
+    log.provenance = provenance;
+  }
   await mkdir(path.dirname(fullPath), { recursive: true });
   await writeFile(fullPath, JSON.stringify(log, null, 2) + "\n", "utf8");
-  return { ok: true, path: logPath, log };
+  return angleCoverage.warning
+    ? { ok: true, path: logPath, log, warning: angleCoverage.warning }
+    : { ok: true, path: logPath, log };
 }
 async function main() {
   let options;
@@ -219,7 +339,13 @@ async function main() {
   }
   try {
     const result = await writeGateFindingsLog(options);
-    process.stdout.write(JSON.stringify(result) + "\n");
+    // rejectForeignAngles: false is WARNING mode, not silence — surface the
+    // angle-coverage warning on stderr too (the JSON result carries it as
+    // `warning`). Suppressed under --silent.
+    if (result.warning && !options.silent) {
+      process.stderr.write(`WARNING: ${result.warning}\n`);
+    }
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     process.stderr.write(JSON.stringify({
       ok: false,

package/scripts/lib/jq-output.mjs

@@ -256,6 +256,24 @@ export const JQ_OUTPUT_USAGE = `Output filtering:
   --silent, -s              Suppress stdout; map result to exit code only
                             (0 = pass/truthy, 1 = fail/falsy). Composes with --jq as a predicate.`;
 
+// Shared token-matcher for scripts that hand-roll a `parseArgs({ tokens: true })`
+// loop (rather than reading `values.jq`/`values.silent` off a strict parse).
+// Call once per `option` token: `if (matchJqOutputToken(token, options)) continue;`.
+// `requireValue` extracts the `--jq <value>` argument; pass the script's own
+// value-extraction function (e.g. `(t) => requireTokenValue(t, parseError)`) to
+// preserve its existing error semantics. Defaults to the raw token value.
+export function matchJqOutputToken(token, options, requireValue = (t) => t.value) {
+  if (token.name === "jq") {
+    options.jq = requireValue(token);
+    return true;
+  }
+  if (token.name === "silent") {
+    options.silent = true;
+    return true;
+  }
+  return false;
+}
+
 // Apply --jq / --silent to a result object and emit. Returns the exit code the
 // CLI should use (0 success / truthy, 1 falsy or non-ok, 2 invalid filter).
 // Without jq/silent the result is printed verbatim as JSON (unchanged shape).

package/scripts/loop/_post-convergence-change.mjs

@@ -0,0 +1,211 @@
+// Single source of truth (#1103, #1126) for "did a significant product/test-logic
+// change land since the last Copilot review at the round cap". Both
+// detect-pr-gate-coordination-state.mjs and copilot-pr-handoff.mjs consume this
+// so they agree on the round-cap escape hatch: at the cap, a significant
+// post-convergence change reopens a Copilot cycle (rerequest) instead of the
+// clean fallback; a doc/comment-only change stays at the clean fallback.
+//
+// It lives in scripts/loop/ (not packages/core) because significance is derived
+// from a `gh api .../compare` diff — gh I/O that does not belong in core.
+import { extractReviewCommitSha, isCopilotLogin, parseJsonText } from "../_core-helpers.mjs";
+import { runChild } from "../_cli-primitives.mjs";
+
+export function getLatestSubmittedCopilotReviewHeadSha(reviews) {
+  const copilotSubmitted = (Array.isArray(reviews) ? reviews : [])
+    .filter((review) => {
+      const login = review?.author?.login;
+      const state = String(review?.state ?? "").toUpperCase();
+      return isCopilotLogin(login) && state !== "PENDING";
+    })
+    .map((review, index) => {
+      const submittedAt = review?.submittedAt ?? review?.submitted_at;
+      const submittedAtMs = typeof submittedAt === "string" ? Date.parse(submittedAt) : Number.NaN;
+      return { review, submittedAtMs, index };
+    })
+    .sort((left, right) => {
+      const leftValid = !Number.isNaN(left.submittedAtMs);
+      const rightValid = !Number.isNaN(right.submittedAtMs);
+      if (leftValid && rightValid) {
+        return right.submittedAtMs - left.submittedAtMs;
+      }
+      if (leftValid !== rightValid) {
+        return leftValid ? -1 : 1;
+      }
+      return right.index - left.index;
+    });
+  const latest = copilotSubmitted[0]?.review;
+  const sha = extractReviewCommitSha(latest);
+  return typeof sha === "string" && sha.trim().length > 0 ? sha.trim() : null;
+}
+
+export function isTrivialDocumentationOnlyPath(filePath) {
+  if (typeof filePath !== "string") return true;
+  const normalized = filePath.trim().toLowerCase();
+  if (normalized.length === 0) return true;
+  if (normalized.startsWith("docs/")) return true;
+  return normalized.endsWith(".md")
+    || normalized.endsWith(".mdx")
+    || normalized.endsWith(".txt")
+    || normalized.endsWith(".rst")
+    || normalized.endsWith(".adoc");
+}
+
+// Extensions whose comment syntax we can classify with confidence (`//`, `/* */`).
+const JS_TS_EXTENSIONS = [".mjs", ".cjs", ".js", ".jsx", ".ts", ".tsx", ".mts", ".cts"];
+
+// Classifies one line's content given the current block-comment state.
+// Returns { code, state }: code=true when the line carries anything that is not
+// comment/blank; state = inBlockComment AFTER the line.
+// Known ceilings (both err toward significance or genuinely-trivial cases only):
+//   - a line STARTING with `//` or `/*` inside a string literal is misread as a
+//     comment — such a line still has to literally begin with the token, which
+//     real code lines almost never do;
+//   - a `/*` opener sitting AFTER code on the same line (`foo(); /* start`) is
+//     not tracked (we return code=true immediately) — follow-up `*` body lines
+//     then read as code → significant, the safe direction.
+function classifyLine(content, inBlock) {
+  let rest = content;
+  let state = inBlock;
+  while (true) {
+    if (state) {
+      const close = rest.indexOf("*/");
+      if (close === -1) return { code: false, state: true };
+      rest = rest.slice(close + 2);
+      state = false;
+      continue;
+    }
+    const trimmed = rest.trim();
+    if (trimmed.length === 0) return { code: false, state };
+    if (trimmed.startsWith("//")) return { code: false, state };
+    if (trimmed.startsWith("/*")) {
+      rest = trimmed.slice(2);
+      state = true;
+      continue;
+    }
+    // Anything else is code — including a bare `*`-leading line with NO open
+    // block observed: generator signatures (`*items() {`) and operator
+    // continuations (`* b`) start with `*` and are real code.
+    return { code: true, state };
+  }
+}
+
+// Content-level significance filter (#1137). A JS/TS file change is "comment-only"
+// when EVERY added/removed line in its patch is blank OR a comment line. Such
+// changes (JSDoc/inline-comment tweaks) must NOT reopen a Copilot round past the
+// cap. Comment rules:
+//   - a line starting with `//` is a comment;
+//   - `/*` opens block-comment state, `*/` closes it; state is tracked across
+//     ALL patch lines (changed AND context) and RESET at every `@@` hunk header
+//     — a block opened before the hunk is unobservable, so a `*`-leading line
+//     with no observed opener in the same hunk is treated as CODE (conservative:
+//     bare `*` counts as comment ONLY inside an observed open `/* ... */` block).
+// Conservative by construction — every ambiguous case returns false (= NOT
+// classifiable as comment-only; the file remains subject to the existing
+// size/count thresholds, it is NOT auto-escalated to significant):
+//   - patch missing (binary / oversized to diff)     → false
+//   - extension we cannot classify (non-JS/TS code)  → false
+//   - a changed line mixing code + comment           → false
+//   - a patch with no parseable added/removed lines  → false
+// Input contract: GitHub compare `files[].patch` starts at `@@` and never
+// contains `---`/`+++` file headers, so `+`/`-` prefixes are always content
+// (`+++counter;` is the real added line `++counter;`, not a header).
+// Note: line-scanner heuristic, upgrade to a real tokenizer only if string-literal misreads ever bite.
+export function isCommentOnlyFileChange(file) {
+  const filename = typeof file?.filename === "string" ? file.filename : "";
+  const lower = filename.toLowerCase();
+  if (!JS_TS_EXTENSIONS.some((ext) => lower.endsWith(ext))) {
+    // Not a classifiable code file (or a doc path handled elsewhere) → treat as code.
+    return false;
+  }
+  const patch = file?.patch;
+  if (typeof patch !== "string" || patch.length === 0) {
+    // No patch (binary / too large) → cannot prove trivial → treat as code.
+    return false;
+  }
+  let sawChangedLine = false;
+  let inBlock = false;
+  for (const line of patch.split("\n")) {
+    if (line.startsWith("@@")) {
+      inBlock = false; // hunk boundary: the gap is unobserved → reset state
+      continue;
+    }
+    if (line.startsWith("\\")) continue; // ""
+    const marker = line[0];
+    const content = line.slice(1);
+    if (marker === "+" || marker === "-") {
+      sawChangedLine = true;
+      const { code, state } = classifyLine(content, inBlock);
+      if (code) return false;
+      inBlock = state;
+    } else {
+      // Context line: never classified as changed content, but it advances
+      // block-comment state so an opener/closer visible in the hunk is honored.
+      inBlock = classifyLine(content, inBlock).state;
+    }
+  }
+  // A patch with zero parseable changed lines is ambiguous → treat as code.
+  return sawChangedLine;
+}
+
+export async function detectPostConvergenceSignificantChange(
+  { repo, pr, currentHeadSha, reviews, changedFiles, roundCapReached, regularCopilotRounds },
+  { env = process.env, ghCommand = "gh" } = {},
+) {
+  if (!roundCapReached || !regularCopilotRounds) {
+    return false;
+  }
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return false;
+  }
+  if (!currentHeadSha) {
+    // No usable current head → the compare call would be doomed; fail closed
+    // without issuing a wasted gh API request.
+    return false;
+  }
+  const lastReviewedHeadSha = getLatestSubmittedCopilotReviewHeadSha(reviews);
+  if (!lastReviewedHeadSha || lastReviewedHeadSha === currentHeadSha) {
+    return false;
+  }
+  const compareResult = await runChild(
+    ghCommand,
+    ["api", `repos/${repo}/compare/${lastReviewedHeadSha}...${currentHeadSha}`],
+    env,
+  );
+  if (compareResult.code !== 0) {
+    return false;
+  }
+  let payload;
+  try {
+    payload = parseJsonText(compareResult.stdout, { label: "gh compare" });
+  } catch {
+    return false;
+  }
+  const rawFiles = Array.isArray(payload?.files) ? payload.files : [];
+  if (rawFiles.length === 0) {
+    return false;
+  }
+  // Content-aware filter (#1137): drop comment/JSDoc-only JS/TS changes BEFORE the
+  // existing size/count thresholds so trivial comment fixes no longer reopen a
+  // Copilot round past the cap. Doc paths and un-classifiable files fall through
+  // unchanged (isCommentOnlyFileChange returns false for them), preserving the
+  // prior threshold behavior for everything else.
+  const files = rawFiles.filter((file) => !isCommentOnlyFileChange(file));
+  if (files.length === 0) {
+    return false;
+  }
+  const hasNonDocChanges = files.some((file) => !isTrivialDocumentationOnlyPath(file?.filename));
+  if (!hasNonDocChanges) {
+    return false;
+  }
+  const totalChangedLines = files.reduce((sum, file) => {
+    const changes = Number(file?.changes);
+    if (Number.isFinite(changes) && changes > 0) {
+      return sum + changes;
+    }
+    const additions = Number(file?.additions);
+    const deletions = Number(file?.deletions);
+    const fallback = (Number.isFinite(additions) ? additions : 0) + (Number.isFinite(deletions) ? deletions : 0);
+    return sum + (fallback > 0 ? fallback : 0);
+  }, 0);
+  return totalChangedLines >= 20 || files.length >= 2;
+}

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

@@ -610,3 +610,73 @@ export async function ensureAsyncRunnerOwnership({
   }
   return claimRunnerOwnership({ repo, pr, runId, cwd, mode: "claim" });
 }
+/**
+ * Env-aware, best-effort release for the run-completion/stop path (issue #1109).
+ *
+ * Mirrors {@link ensureAsyncRunnerOwnership}: a no-op when no async run id is
+ * present, so it is harness-agnostic — Claude Code with no DEVLOOPS_RUN_ID yields
+ * `skipped_no_async_run_id` and never touches the coordination file.
+ *
+ * Non-fatal by contract: a release conflict (the claim is owned by another run,
+ * or no record remains) is swallowed into an `ok:true` result so a failed release
+ * can never block a stop/checkpoint. Fail-closed competitor semantics are
+ * preserved — {@link releaseRunnerOwnership} only clears a claim THIS run owns, so
+ * a genuinely active competing run's claim is left intact.
+ *
+ * Resolves to one of `skipped_no_async_run_id` (no run id present),
+ * `release_skipped` (release conflict swallowed), `release_error` (release threw),
+ * or the passthrough `releaseRunnerOwnership` result — `released` when this run's
+ * claim was cleared, or `release_noop` when the target has no coordination record.
+ */
+export async function releaseAsyncRunnerOwnership({
+  repo,
+  pr,
+  env = process.env,
+  cwd = process.cwd(),
+} = {}) {
+  const filePath = defaultRunnerCoordinationFilePathForTarget({ repo, pr }, cwd);
+  const runId = normalizeRunId(resolveRunId(env));
+  if (runId === null) {
+    return {
+      ok: true,
+      status: "skipped_no_async_run_id",
+      repo: normalizeRepoSlug(repo),
+      pr: normalizePr(pr),
+      runId: null,
+      activeRun: null,
+      exitSignals: [],
+      filePath,
+    };
+  }
+  try {
+    const released = await releaseRunnerOwnership({ repo, pr, runId, cwd });
+    if (released.ok) {
+      return released;
+    }
+    return {
+      ok: true,
+      status: "release_skipped",
+      repo: released.repo ?? normalizeRepoSlug(repo),
+      pr: released.pr ?? normalizePr(pr),
+      runId,
+      activeRun: released.activeRun ?? null,
+      exitSignals: released.exitSignals ?? [],
+      skippedReason: released.error,
+      message: released.message,
+      filePath: released.filePath ?? filePath,
+    };
+  } catch (error) {
+    return {
+      ok: true,
+      status: "release_error",
+      repo: normalizeRepoSlug(repo),
+      pr: normalizePr(pr),
+      runId,
+      activeRun: null,
+      exitSignals: [],
+      skippedReason: "release_threw",
+      message: error instanceof Error ? error.message : String(error),
+      filePath,
+    };
+  }
+}

package/scripts/loop/_repo-root-resolver.mjs

@@ -0,0 +1,47 @@
+/**
+ * Shared worktree-relative repo-root / ledger-checkout resolver (issue #1052,
+ * folds #1019 and #1050). ONE shared resolver: derive repo root from the
+ * checkout under operation (git-toplevel, not ambient cwd) for config reads,
+ * and enumerate ALL checkouts (main + every worktree) for ledger reads so a
+ * ledger written in any worktree is visible regardless of which checkout runs
+ * the check.
+ *
+ * #1050: the pre-PR-worktree flow means the session cwd is a DIFFERENT checkout
+ * than the PR worktree. Ledgers get written cwd-relative in the PR worktree but
+ * read cwd-relative from the session checkout, so they diverge and clean gates
+ * false-block on "missing pre-merge gate evidence". resolveLedgerCheckouts
+ * enumerates every checkout so a ledger written in one is found from any.
+ *
+ * #1019: .devloops is read at EXACTLY <repoRoot>/.devloops with no upward walk.
+ * Reading it from process.cwd() (a subdir or sibling checkout) silently falls
+ * back to defaults (maxCopilotRounds -> 5). resolveRepoRoot derives the root
+ * from the checkout's git-toplevel so config resolves correctly.
+ */
+import { execFileSync } from "node:child_process";
+import { parseAllWorktreePaths, parseMainWorktreePath } from "@dev-loops/core/loop/worktree-guard";
+
+export function resolveRepoRoot(cwd, { gitCommand = "git" } = {}) {
+  try {
+    return execFileSync(gitCommand, ["rev-parse", "--show-toplevel"], {
+      cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || cwd;
+  } catch {
+    // git failed or cwd is not inside a git repo (or git is unavailable) -> fall back to cwd.
+    return cwd;
+  }
+}
+
+export function resolveLedgerCheckouts(cwd, { gitCommand = "git" } = {}) {
+  const roots = [];
+  const add = (p) => { if (typeof p === "string" && p.length > 0 && !roots.includes(p)) roots.push(p); };
+  add(resolveRepoRoot(cwd, { gitCommand }));
+  try {
+    const listing = execFileSync(gitCommand, ["worktree", "list"], {
+      cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+    add(parseMainWorktreePath(listing));
+    for (const p of parseAllWorktreePaths(listing)) add(p);
+  } catch { /* git failed, not inside a git repo, or git unavailable: cwd-toplevel is all we have */ }
+  if (roots.length === 0) add(cwd);
+  return roots;
+}

package/scripts/loop/build-handoff-envelope.mjs

@@ -12,7 +12,7 @@
  *   dev-loops loop build-envelope --input resolver-output.json
  *
  * Or via npx:
- *   npx dev-loops loop build-envelope --input resolver-output.json
+ *   npx dev-loops@<version> loop build-envelope --input resolver-output.json
  */
 import { readFile } from "node:fs/promises";
 import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
@@ -23,6 +23,8 @@ import { buildDevLoopHandoffEnvelope } from "@dev-loops/core/loop/handoff-envelo
 import { loadDevLoopConfig } from "@dev-loops/core/config";
 import { createPiAdapter } from "@dev-loops/core/harness";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+import { SANCTIONED_COMMANDS } from "./sanctioned-commands.mjs";
 
 const USAGE = `Usage: build-handoff-envelope.mjs --input <path>
 Build a deterministic handoff envelope from startup resolver output and settings.
@@ -30,7 +32,7 @@ Required:
   --input <path>         Path to resolver output JSON (from resolve-dev-loop-startup.mjs)
 Optional:
   --gate-state <json>    Gate state JSON string
-                           { currentHeadSha?, ciStatus?, unresolvedThreadCount?, copilotRoundCount? }
+                           { currentHeadSha?, ciStatus?, unresolvedThreadCount?, copilotRoundCount?, retrospectiveFindings? }
   --overrides <json>     Overrides JSON string
                            { mergeAuthorized?, preferLocal?, scopeConstraint?, customStopAt? }
   --repo <owner/name>    Repository slug override (falls back to bundle.repoSlug or bundle.repo)
@@ -41,9 +43,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   Runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or runtime failure`.trim();
+  1  Argument error or runtime failure
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -73,6 +77,7 @@ export function parseBuildHandoffEnvelopeCliArgs(argv) {
       "gate-state": { type: "string" },
       overrides: { type: "string" },
       repo: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -105,6 +110,7 @@ export function parseBuildHandoffEnvelopeCliArgs(argv) {
       options.repo = requireTokenValue(token, parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
 
@@ -143,6 +149,10 @@ export async function buildHandoffEnvelopeCli(
   // Build options for envelope builder
   const envelopeOptions = {};
 
+  // Carry the canonical sanctioned operation → wrapper command map (issue #1081)
+  // into every emitted envelope by DEFAULT so spawned subagents never re-derive it.
+  envelopeOptions.sanctionedCommands = SANCTIONED_COMMANDS;
+
   // Repo slug: explicit --repo, then resolver output bundle, then git remote
   const bundleSlug = resolverOutput?.bundle?.repoSlug ?? resolverOutput?.bundle?.repo ?? null;
   const repoSlug = options.repo ?? bundleSlug ?? detectRepoSlug(repoRoot);
@@ -186,7 +196,7 @@ export async function runCli(
 
   try {
     const envelope = await buildHandoffEnvelopeCli(options, { adapter });
-    stdout.write(`${JSON.stringify(envelope)}\n`);
+    process.exitCode = emitResult(envelope, { jq: options.jq, silent: options.silent, stdout, stderr });
   } catch (err) {
     const msg = formatCliError(err);
     stderr.write(`${msg}\n`);