dev-loops 0.5.0 → 0.7.1

package/scripts/github/upsert-checkpoint-verdict.mjs

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig } from "@dev-loops/core/config";
 import { parseArgs } from "node:util";
-import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { truncateText } from "@dev-loops/core/bash-exit-one";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
@@ -391,14 +391,7 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       options.inlineReason = smartTruncate(reason, MAX_GATE_COMMENT_EXCERPT_LENGTH);
       continue;
     }
-    if (token.name === "jq") {
-      options.jq = requireTokenValue(token, parseError);
-      continue;
-    }
-    if (token.name === "silent") {
-      options.silent = true;
-      continue;
-    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   // Default execution mode to inline_single_agent when omitted. inlineReason is
@@ -897,7 +890,14 @@ async function postDraftGateViaDraftTransition(options, { env, ghCommand, repoRo
   try {
     // The PR is now a draft, so RUN_DRAFT_GATE is the legal action. Re-enter with
     // the caller's full options; prIsDraft is now true so this branch is skipped.
-    result = await upsertCheckpointVerdict(options, { env, ghCommand, repoRoot });
+    // `_draftTransitionInProgress` guards against unbounded recursion: if GitHub's
+    // draft-state read still lags the conversion mutation on re-entry (isDraft reads
+    // false again), the reconcile branch must NOT fire a second time — it fails closed
+    // with a clear error instead of recursing indefinitely (exit 13). (#1020)
+    result = await upsertCheckpointVerdict(
+      { ...options, _draftTransitionInProgress: true },
+      { env, ghCommand, repoRoot },
+    );
   } catch (error) {
     if (conversion.alreadyDraft !== true) {
       try {
@@ -1060,11 +1060,32 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   if (
     options.gate === "draft_gate"
     && !prIsDraft
+    && !options._draftTransitionInProgress
     && !coordination.draftGateAlreadySatisfied
     && coordination.allowedNextActions.includes(PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_GATE)
   ) {
     return await postDraftGateViaDraftTransition(options, { env, ghCommand, repoRoot });
   }
+  // Fail closed on a lagged draft-state read: we are re-entering FROM
+  // postDraftGateViaDraftTransition (which just converted the PR to draft) yet the
+  // coordination context still reports the PR as non-draft. Recursing would loop
+  // indefinitely (the original #1020 hang → exit 13, error swallowed). Surface a
+  // clear, actionable error instead so the operator knows the draft conversion did
+  // not take (or GitHub's read lags the mutation) and can retry. (#1020)
+  if (
+    options.gate === "draft_gate"
+    && !prIsDraft
+    && options._draftTransitionInProgress
+  ) {
+    throw new Error(
+      `draft_gate self-heal for ${options.repo}#${options.pr} failed: the PR was converted to draft ` +
+      `to post the verdict, but GitHub still reports it as non-draft on re-entry (draft-state read lagged ` +
+      `the conversion mutation, or the conversion did not take). Not recursing. Re-run the draft_gate post ` +
+      `once the PR reflects the draft state, or reconcile manually with ` +
+      `\`gh pr ready ${options.pr} --repo ${options.repo}\` / ` +
+      `\`node scripts/github/reconcile-draft-gate.mjs --repo ${options.repo} --pr ${options.pr}\`.`,
+    );
+  }
   if (gateActionForbidden) {
     throw new Error(buildGateEntryRefusalError({ options, coordination }));
   }

package/scripts/github/verify-fresh-review-context.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { mkdir, stat, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { buildParseError, isDirectCliRun, formatCliError } from "../_core-helpers.mjs";
-const USAGE = `Usage: verify-fresh-review-context.mjs [--help] [--scope <name>]
+import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+const USAGE = `Usage: verify-fresh-review-context.mjs [--help] [--scope <name>] [--context-path <path>]
 Verify that the current scoped-reviewer session has fresh context.
 
 "Fresh" means the reviewer's context is the neutral gate-context builder
@@ -10,30 +12,60 @@ artifact (the build-once diff + adjacent-code bundle) plus its single review
 angle, and explicitly NOT the main (orchestrating) agent's conversation/state
 or a prior reviewer session's state. The injected neutral bundle is the
 INTENDED seed and is NOT contamination; this guard detects main-agent /
-cross-session state bleed by way of a per-(cwd, scope) sentinel: a first run in
-a fresh session creates the sentinel and passes, a re-entry that finds an
-existing sentinel fails closed. Seeding a reviewer with the neutral bundle (a
-path/prompt, not a sentinel) never creates a sentinel, so it never
-false-positives as contaminated.
+cross-session state bleed by way of a per-(cwd, scope, round) sentinel: a first
+run in a fresh session creates the sentinel and passes, a re-entry that finds an
+existing sentinel for the same round fails closed. Seeding a reviewer with the
+neutral bundle (a path/prompt, not a sentinel) never creates a sentinel, so it
+never false-positives as contaminated.
+
+Sentinels are per review ROUND, keyed by the current head SHA (\`git rev-parse
+HEAD\`). A retry at a new head naturally gets a fresh sentinel (no manual clear
+step), while a same-scope + same-head re-entry still fails closed. When git is
+unavailable the sentinel is keyed by scope only (legacy behavior).
 Options:
   --scope <name>  Unique reviewer scope (e.g. "draft-gate-coverage").
                   Must be non-empty, containing only alphanumeric
                   characters and hyphens. When provided, the sentinel
                   is scoped so parallel reviewers in the same working
                   directory do not trigger false contamination.
+  --context-path <path>  Path to the seeded gate-context artifact this
+                  reviewer must be reading from (the build-once bundle
+                  written by write-gate-context.mjs, e.g.
+                  tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json).
+                  Must resolve to a path within the reviewer's working
+                  directory; a path that resolves OUTSIDE cwd (an absolute
+                  or ..-escaping path pointing at another worktree's bundle,
+                  which would defeat the worktree-locality guard) fails
+                  closed (exit 1).
+                  When provided, also fails closed (exit 1) if the artifact
+                  is missing (ENOENT) from the reviewer's cwd. Per-angle
+                  gate reviewers must run in the PR's actual worktree/head
+                  (never an isolated worktree) so this gitignored,
+                  worktree-local artifact is present; a missing artifact
+                  means either a stale/isolated checkout or a skipped
+                  preamble, and the reviewer must refuse to proceed
+                  rather than silently reviewing without seeded context.
 Output (stdout, JSON):
-  { "ok": true, "fresh": true, "sentinelCreated": true }
-  { "ok": true, "fresh": false, "sentinelCreated": false, "reason": "..." }
+  { "ok": true, "fresh": true, "sentinelCreated": true, "round": "<headSha|null>" }
+  { "ok": true, "fresh": true, "sentinelCreated": true, "round": "...", "gateContextPath": "...", "gateContextPresent": true }
+  { "ok": true, "fresh": false, "sentinelCreated": false, "round": "...", "reason": "..." }
+  { "ok": true, "fresh": false, "sentinelCreated": false, "round": "...", "gateContextPath": "...", "gateContextPresent": false, "reason": "..." }
   On error (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Clean (first run)
-  1  Contaminated (prior session detected)
-  2  Usage or internal error`.trim();
+  1  Refuse to review: contaminated (prior session detected), OR (with
+     --context-path) the seeded gate-context artifact is missing or resolves
+     outside the reviewer's working directory
+  2  Usage or internal error, or invalid --jq filter`.trim();
 const VALID_SCOPE_RE = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
 const parseError = buildParseError(USAGE);
-function resolveScope(argv) {
-  const idx = argv.indexOf("--scope");
+// Resolve a `--flag <value>` argument. Returns null when the flag is absent,
+// "" when it is present but the value is missing/empty/flag-like (a following
+// `-`-prefixed token, which must not be silently consumed), else the value.
+function resolveFlagValue(argv, flag) {
+  const idx = argv.indexOf(flag);
   if (idx === -1) return null;
   const val = argv[idx + 1];
   if (val === undefined || val === "" || (val.length > 0 && val[0] === "-")) {
@@ -41,6 +73,9 @@ function resolveScope(argv) {
   }
   return val;
 }
+function resolveScope(argv) {
+  return resolveFlagValue(argv, "--scope");
+}
 function resolveValidatedScope(argv) {
   const raw = resolveScope(argv);
   if (raw === null) return null;
@@ -52,22 +87,47 @@ function resolveValidatedScope(argv) {
   }
   return raw;
 }
-function sentinelRelative(scope) {
-  const suffix = scope ? `-${scope}` : "";
-  return path.join("tmp", `checkpoint-context-sentinel${suffix}.json`);
+function resolveContextPath(argv) {
+  return resolveFlagValue(argv, "--context-path");
+}
+// Round = the current head SHA, so a retry on a new head gets a fresh key while
+// a same-head re-entry collides and fails closed. `git rev-parse HEAD` yields the
+// same full SHA on every invocation for a given head, so the key is deterministic
+// with no user input to spell it inconsistently. Returns null when git is
+// unavailable (falls back to the legacy scope-only key).
+function resolveHeadRound(cwd = process.cwd()) {
+  try {
+    const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return VALID_SCOPE_RE.test(sha) ? sha : null;
+  } catch {
+    return null; // not a git repo / git unavailable
+  }
+}
+function sentinelRelative(scope, round) {
+  const scopeSuffix = scope ? `-${scope}` : "";
+  const roundSuffix = round ? `-${round}` : "";
+  return path.join("tmp", `checkpoint-context-sentinel${scopeSuffix}${roundSuffix}.json`);
 }
 function legacySentinelRelative(scope) {
   const suffix = scope ? `-${scope}` : "";
   return path.join("tmp", `gate-review-context-sentinel${suffix}.json`);
 }
-async function checkSentinelExists(scope, cwd = process.cwd()) {
-  const sentinelPath = path.resolve(cwd, sentinelRelative(scope));
+async function checkSentinelExists(scope, round, cwd = process.cwd()) {
+  const sentinelPath = path.resolve(cwd, sentinelRelative(scope, round));
   try { await stat(sentinelPath); return { exists: true, path: sentinelPath, legacy: false }; } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
-  const legacyPath = path.resolve(cwd, legacySentinelRelative(scope));
-  try { await stat(legacyPath); return { exists: true, path: legacyPath, legacy: true }; } catch (err) {
-    if (err.code !== "ENOENT") throw err;
+  // Legacy names predate head-keyed rounds; only consult them for the
+  // scope-only key so a stale pre-round sentinel never blocks a new round.
+  if (!round) {
+    const legacyPath = path.resolve(cwd, legacySentinelRelative(scope));
+    try { await stat(legacyPath); return { exists: true, path: legacyPath, legacy: true }; } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
   }
   return { exists: false, path: sentinelPath, legacy: false };
 }
@@ -78,27 +138,85 @@ async function main(argv = process.argv.slice(2)) {
   }
   const scope = resolveValidatedScope(argv);
   if (scope === undefined) return 2;
-  const sentinelPath = path.resolve(process.cwd(), sentinelRelative(scope));
+  const contextPathArg = resolveContextPath(argv);
+  if (contextPathArg === "") {
+    process.stderr.write(`${formatCliError(
+      parseError("Invalid --context-path value: must be non-empty.")
+    )}\n`);
+    return 2;
+  }
+  const jqArg = resolveFlagValue(argv, "--jq");
+  if (jqArg === "") {
+    process.stderr.write(`${formatCliError(
+      parseError("Invalid --jq value: must be non-empty.")
+    )}\n`);
+    return 2;
+  }
+  const jq = jqArg === null ? undefined : jqArg;
+  const silent = argv.includes("--silent") || argv.includes("-s");
+  // Every branch below reports ok:true (the tool ran successfully); the
+  // fresh/contaminated verdict maps to the exit code via `ok` here so the
+  // shared --jq/--silent contract composes with the existing 0=fresh/1=refuse
+  // signal instead of always reading ok:true as success.
+  const finish = (payload, freshLike) => emitResult(payload, { jq, silent, ok: freshLike });
+  const round = resolveHeadRound();
+  if (contextPathArg !== null) {
+    const cwd = process.cwd();
+    const resolvedContextPath = path.resolve(cwd, contextPathArg);
+    // The guard proves the reviewer is in the working tree where the gitignored
+    // tmp/gate-context bundle was written. An absolute or ..-escaping path could
+    // stat the real bundle in ANOTHER (stale/isolated) worktree and pass — so a
+    // path resolving outside cwd fails closed, defeating that bypass.
+    const withinCwd =
+      resolvedContextPath === cwd || resolvedContextPath.startsWith(cwd + path.sep);
+    if (!withinCwd) {
+      return finish({
+        ok: true,
+        fresh: false,
+        sentinelCreated: false,
+        round: round ?? null,
+        gateContextPath: contextPathArg,
+        gateContextPresent: false,
+        reason: `Seeded gate-context artifact path "${contextPathArg}" resolves outside the reviewer's working directory — refusing. --context-path must be a cwd-relative path to the worktree-local bundle; an absolute or ..-escaping path could point at another (stale/isolated) worktree's bundle and defeat the worktree-locality guard.`,
+      }, false);
+    }
+    try {
+      await stat(resolvedContextPath);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      return finish({
+        ok: true,
+        fresh: false,
+        sentinelCreated: false,
+        round: round ?? null,
+        gateContextPath: contextPathArg,
+        gateContextPresent: false,
+        reason: `Seeded gate-context artifact missing at "${contextPathArg}" — refusing to review without the build-once neutral context bundle. Per-angle gate reviewers must run in the PR's actual worktree/head (never an isolated worktree checked out from stale main), which is where the context-builder preamble wrote this gitignored artifact.`,
+      }, false);
+    }
+  }
+  const sentinelPath = path.resolve(process.cwd(), sentinelRelative(scope, round));
   try {
     await mkdir(path.dirname(sentinelPath), { recursive: true });
   } catch (err) {
     process.stderr.write(`${formatCliError(err)}\n`);
     return 2;
   }
-  const existing = await checkSentinelExists(scope);
+  const existing = await checkSentinelExists(scope, round);
   if (existing.exists) {
-    process.stdout.write(JSON.stringify({
+    return finish({
       ok: true,
       fresh: false,
       sentinelCreated: false,
+      round: round ?? null,
       reason: `Checkpoint context sentinel already exists${existing.legacy ? " (legacy name)" : ""} — inherited session context detected. Restart the subagent with fresh context (subagent({context:\"fresh\"})).`,
-    }) + "\n");
-    return 1;
+    }, false);
   }
   const sentinel = {
     createdAt: new Date().toISOString(),
     pid: process.pid,
     ...(scope ? { scope } : {}),
+    ...(round ? { round } : {}),
   };
   try {
     await writeFile(sentinelPath, JSON.stringify(sentinel, null, 2) + "\n", {
@@ -107,23 +225,24 @@ async function main(argv = process.argv.slice(2)) {
     });
   } catch (err) {
     if (err.code === "EEXIST") {
-      process.stdout.write(JSON.stringify({
+      return finish({
         ok: true,
         fresh: false,
         sentinelCreated: false,
+        round: round ?? null,
         reason: "Checkpoint context sentinel already exists (detected on atomic create) — inherited session context detected. Restart the subagent with fresh context (subagent({context:\"fresh\"})).",
-      }) + "\n");
-      return 1;
+      }, false);
     }
     process.stderr.write(`${formatCliError(err)}\n`);
     return 2;
   }
-  process.stdout.write(JSON.stringify({
+  return finish({
     ok: true,
     fresh: true,
     sentinelCreated: true,
-  }) + "\n");
-  return 0;
+    round: round ?? null,
+    ...(contextPathArg !== null ? { gateContextPath: contextPathArg, gateContextPresent: true } : {}),
+  }, true);
 }
 if (isDirectCliRun(import.meta.url)) {
   try {

package/scripts/github/view-pr.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { parsePrNumber, 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";
+
+// Default PR facts a follow-up run reads: the fields loop info surfaces plus the
+// head SHA. Callers needing a different set pass --json <fields> (a comma list,
+// same vocabulary as `gh pr view --json`).
+const DEFAULT_FIELDS =
+  "number,title,body,state,isDraft,headRefName,baseRefName,headRefOid,author,mergedAt,mergeable,mergeStateStatus,url";
+
+const USAGE = `Usage: view-pr.mjs --repo <owner/name> --pr <number> [--json <fields>]
+Read PR facts (branch/state/mergeStateStatus/head SHA/etc.). Thin wrapper over
+\`gh pr view --json …\` — use this instead of an agent-level raw \`gh pr view\` so the
+loop's internal-tooling record stays clean (siblings: list-issues.mjs,
+comment-issue.mjs, fetch-ci-logs.mjs; #1057). For composite loop routing/CI facts
+prefer \`dev-loops loop info --pr\`; this is the thin field-read counterpart.
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --pr <number>                 Pull request number
+Optional:
+  --json <fields>               Comma-separated gh pr view field list
+                                (default: ${DEFAULT_FIELDS})
+Output (stdout, JSON):
+  { "ok": true, "pr": { <requested fields> } }
+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 parseViewPrCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      json: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    fields: DEFAULT_FIELDS,
+    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 === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
+      continue;
+    }
+    if (token.name === "json") {
+      const fields = requireTokenValue(token, parseError)
+        .split(",")
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+      if (fields.length === 0) {
+        throw parseError("--json must list at least one field");
+      }
+      if (fields.some((f) => !/^[A-Za-z][A-Za-z0-9]*$/.test(f))) {
+        throw parseError("--json fields must be gh pr view field names (letters/digits)");
+      }
+      options.fields = fields.join(",");
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("Viewing a PR requires both --repo <owner/name> and --pr <number>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+export async function viewPr(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const result = await run(
+    ghCommand,
+    ["pr", "view", String(options.pr), "--repo", options.repo, "--json", options.fields],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh pr view failed: ${detail}`);
+  }
+  const pr = parseJsonText(result.stdout, { label: "gh pr view" });
+  if (pr === null || typeof pr !== "object" || Array.isArray(pr)) {
+    throw new Error("gh pr view did not return a JSON object");
+  }
+  return { ok: true, pr };
+}
+
+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 = parseViewPrCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await viewPr(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; });
+}