@dev-loops/core 1.0.2 → 1.0.3

package/src/github/issue-ops.mjs

@@ -4,6 +4,7 @@ import { runChild as defaultRunChild } from "../cli/primitives.mjs";
 import { parseJsonText } from "./review-threads.mjs";
 import { parseRepoSlug } from "./repo-slug.mjs";
 import { guardCommentBodyNoIssuePrIds } from "./comment-id-guard.mjs";
+import { assertGithubWriteStubbedInTestMode } from "./test-mode-write-guard.mjs";
 
 /**
  * Core `gh issue` operations, extracted from the thin CLI wrappers under
@@ -88,6 +89,7 @@ export async function resolveCreateBody(options) {
 }
 
 export async function createIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  assertGithubWriteStubbedInTestMode(run, "issue create", { env });
   const body = await resolveCreateBody(options);
   if (typeof body !== "string" || body.trim().length === 0) {
     const source = options.bodyFile !== undefined ? `--body-file ${options.bodyFile}` : "--body";
@@ -182,6 +184,7 @@ export function buildStateChangeArgs(options) {
 }
 
 export async function editIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  assertGithubWriteStubbedInTestMode(run, "issue edit/close", { env });
   const { args, edited } = await buildEditArgs(options);
   // Skip the edit call entirely when --state is the only change requested —
   // `gh issue edit` with no field flags errors ("no changed fields").
@@ -227,6 +230,7 @@ export async function resolveCommentBody(options) {
 }
 
 export async function commentIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  assertGithubWriteStubbedInTestMode(run, "issue comment", { env });
   const body = await resolveCommentBody(options);
   // ISSUE/PR-ID GUARD (#1731): a generated comment body must never emit a raw
   // issue/PR id (fail-closed unless explicitly allowlisted). `allowedRefs` is

package/src/github/repo-slug.mjs

@@ -83,10 +83,33 @@ export function dedupeRepoSlugOptions(options) {
   }
   return uniqueOptions;
 }
+// Parses a git remote URL into an <owner/name> slug, but only for github.com
+// remotes. The URI form (scheme://[user@]host[:port]/path) is checked before
+// the scp form (host:path), because the scp regex also matches URIs like
+// https://... — checking scp first would misparse the host out of the scheme.
+function parseGitHubRemoteSlug(url) {
+  let host, path;
+  const uri = url.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+)$/);
+  const scp = url.match(/^(?:[^@/]+@)?([^/:]+):(.+)$/);
+  if (uri) {
+    host = uri[1];
+    path = uri[2];
+  } else if (scp) {
+    host = scp[1];
+    path = scp[2];
+  } else {
+    return null;
+  }
+  if (host.toLowerCase() !== "github.com") return null;
+  const seg = path.match(/([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  if (!seg) return null;
+  return `${seg[1]}/${seg[2]}`;
+}
+
 /**
  * Auto-detect <owner/name> from `git remote get-url origin`.
  * Returns the slug string on success, or null when detection fails
- * (no origin remote, not a git repo, or unparseable URL).
+ * (no origin remote, not a git repo, non-github.com host, or unparseable URL).
  * Does NOT throw — callers should add their own context-specific error messages.
  */
 export function detectRepoSlug(cwd) {
@@ -96,9 +119,7 @@ export function detectRepoSlug(cwd) {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
     }).trim();
-    const match = url.match(/[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
-    if (!match) return null;
-    return `${match[1]}/${match[2]}`;
+    return parseGitHubRemoteSlug(url);
   } catch {
     return null;
   }

package/src/github/test-mode-write-guard.mjs

@@ -0,0 +1,81 @@
+/**
+ * Fail-closed test-mode guard for GitHub WRITE helpers.
+ *
+ * A GitHub write helper (issue/PR create/edit/close/comment/merge) must never
+ * reach a live GitHub write path from a test. The real incident: an unstubbed
+ * `bun run verify` drove a dedup test's followUpDraft through
+ * applyFollowUpIssues -> ensureFollowUpIssue -> createIssue and FILED A REAL
+ * ISSUE against the repo. The DI stub seam existed; the test simply did not
+ * thread it, and nothing failed closed to stop the live write.
+ *
+ * This guard is TEST-MODE ONLY. In production (`NODE_ENV !== "test"`) it is a
+ * no-op — it never changes production write behavior (non-goal: no production
+ * behavior change; no general network sandbox). It only asserts, when a test is
+ * running, that the write is stubbed by one of the two sanctioned seams:
+ *
+ * Test mode is derived from the EXECUTING PROCESS's own env (`process.env`),
+ * never from the write-target `env` a caller passes in. A caller can build a
+ * sparse `env` (e.g. `{ GH_TOKEN }` with no `NODE_ENV`) to shape the `gh`
+ * child's environment; if that sparse env decided test mode, it could turn
+ * the guard off from under a test simply by omitting `NODE_ENV`. Reading the
+ * real process env instead makes that impossible: a caller-supplied env can
+ * never disable the guard.
+ *
+ *   (a) In-process DI seam: the helper's `run`/`runChild` was replaced with a
+ *       stub (e.g. `makeGhMock`), so it is no longer the live child-exec seam.
+ *   (b) Process-boundary seam: a subprocess test installed a fake `gh` on PATH
+ *       (`writeGhStub`) and attests it via `DEV_LOOPS_GH_STUB` in the child env.
+ *
+ * Anything else in test mode fails closed at the call site, before any network
+ * call, with an actionable error naming both seams.
+ */
+
+import { runChild as liveRunChild } from "../cli/primitives.mjs";
+
+/**
+ * Env var a process-boundary gh stub sets to attest that `gh` itself is a stub
+ * (set automatically by the `writeGhStub` test helper). Only consulted in test
+ * mode, so it is not a production escape hatch.
+ */
+export const GH_STUB_ATTESTATION_ENV = "DEV_LOOPS_GH_STUB";
+
+/**
+ * True when `run` is the live child-exec seam — i.e. NO in-process DI stub was
+ * injected. `null`/`undefined` (a helper with no run seam, e.g. the spawn-based
+ * create-pr path) is treated as live too, so it fails closed rather than open.
+ * @param {unknown} run
+ */
+export function isLiveExecutor(run) {
+  return run == null || run === liveRunChild;
+}
+
+/**
+ * Assert a GitHub write is stubbed when running under a test. No-op unless the
+ * EXECUTING PROCESS is in test mode (`processEnv.NODE_ENV === "test"`) — never
+ * decided by the caller-supplied write-target `env`, so a sparse `env` (e.g.
+ * missing `NODE_ENV`) cannot bypass the guard. Throws (code
+ * `GH_WRITE_UNSTUBBED_IN_TEST`) when the write would reach the live path with
+ * neither sanctioned stub seam present.
+ *
+ * @param {unknown} run - the helper's `run`/`runChild` seam (omit for spawn-only
+ *   helpers with no in-process seam).
+ * @param {string} op - human-readable op name, e.g. `"issue create"`.
+ * @param {{ env?: NodeJS.ProcessEnv, processEnv?: NodeJS.ProcessEnv }} [opts]
+ *   `env` is the write-target env (consulted only for the stub attestation);
+ *   `processEnv` (defaults to `process.env`, injectable for tests) is the
+ *   real executing process's env and is the sole source of test-mode.
+ */
+export function assertGithubWriteStubbedInTestMode(run, op, { env = process.env, processEnv = process.env } = {}) {
+  if (processEnv?.NODE_ENV !== "test") return; // production / non-test: never guards
+  if (!isLiveExecutor(run)) return; // (a) in-process DI stub injected
+  if (processEnv?.[GH_STUB_ATTESTATION_ENV] || env?.[GH_STUB_ATTESTATION_ENV]) return; // (b) process-boundary gh stub
+  throw Object.assign(
+    new Error(
+      `GitHub write helper "${op}" was called in test mode without an injected stub — ` +
+        `refusing to reach a live GitHub write path (a test must never mutate the real repo). ` +
+        `Inject the in-process DI seam (pass { run } / { runChild }, e.g. makeGhMock) or stub gh ` +
+        `at the process boundary (writeGhStub, which sets ${GH_STUB_ATTESTATION_ENV}). See issue 2216.`,
+    ),
+    { code: "GH_WRITE_UNSTUBBED_IN_TEST" },
+  );
+}

package/src/loop/bash-command-classify.mjs

@@ -8,9 +8,65 @@
  * Pure and side-effect free.
  */
 
-/** The repository these gate guards apply to. */
+/**
+ * The dev-loops repo itself. Retained ONLY for the Pi extension's
+ * (`extension/post-merge-update.ts`) dev-loops-repo SELF-UPDATE scoping (`markPendingUpdate` /
+ * `queueIfEligible`), which is legitimately anchored to this one repo, not to whatever repo the
+ * harness happens to run in. Both harness guard suites — the Claude PreToolUse Bash gate
+ * (`decideBashGate` in `hook-decisions.mjs`) and the Pi extension's `gh pr ready`/`gh pr merge`
+ * guards (`post-merge-update.ts`) — now resolve the managed repo dynamically via
+ * `deriveInManagedRepo` below instead of comparing against this hardcoded slug, so every guard
+ * also applies in a dev-loops-managed consumer repo.
+ */
 export const TARGET_REPO_SLUG = "mfittko/dev-loops";
 
+/** `.devloops` config file extensions checked (in order) to decide whether a repo root is
+ * dev-loops-managed. Shared by every harness that resolves `inManagedContext` from the
+ * filesystem (`fs.existsSync(path.join(repoRoot, \`.devloops${ext}\`))`). */
+export const DEVLOOPS_CONFIG_VARIANTS = ["", ".yaml", ".yml", ".json"];
+
+/**
+ * Whether the current repo counts as "managed" for guard-gating purposes: inside a
+ * dev-loops-managed context (a `.devloops` config exists at its root) AND, when the managed
+ * repo's identity resolves, the cwd repo IS that managed repo. FAIL CLOSED: inside a managed
+ * context whose identity can't be resolved (`managedRepoSlug` null), the guard suite still
+ * applies rather than silently allowing everything.
+ * @param {Object} [params]
+ * @param {boolean} [params.inManagedContext] - Whether a `.devloops` config exists at the repo root.
+ * @param {string|null} [params.managedRepoSlug] - Resolved owner/name of the managed repo, or null.
+ * @param {string|null} [params.repoSlug] - Resolved owner/name of the cwd repo, or null.
+ * @returns {boolean}
+ */
+export function deriveInManagedRepo({ inManagedContext = false, managedRepoSlug = null, repoSlug = null } = {}) {
+  const managedSlug = (managedRepoSlug ?? "").trim().toLowerCase() || null;
+  const cwdSlug = (repoSlug ?? "").trim().toLowerCase() || null;
+  return Boolean(inManagedContext) && (managedSlug === null || cwdSlug === managedSlug);
+}
+
+/**
+ * Whether an explicit `--repo`/`-R` (or `GH_REPO=`) target is PROVABLY a different repo than the
+ * managed one — both slugs must resolve and differ. An unresolvable managed slug never proves
+ * foreign-ness (fail closed: the guard stays active rather than waving an explicit flag through).
+ * @param {string|null} explicitRepo
+ * @param {string|null} managedRepoSlug
+ * @returns {boolean}
+ */
+export function explicitRepoProvenForeign(explicitRepo, managedRepoSlug) {
+  const managedSlug = (managedRepoSlug ?? "").trim().toLowerCase() || null;
+  const explicit = (explicitRepo ?? "").trim().toLowerCase() || null;
+  if (managedSlug === null || explicit === null) {
+    return false;
+  }
+  // Both sides must be clean owner/name identities before we can prove foreign: a
+  // managed slug that bypassed the normalizer (e.g. a hostile `acme/widgets;id` test
+  // double) can't be trusted to prove anything about the explicit `--repo` — fail
+  // closed (the managed-repo guard still applies) rather than wave it through.
+  if (!isCleanRepoSlug(managedSlug) || !isCleanRepoSlug(explicit)) {
+    return false;
+  }
+  return explicit !== managedSlug;
+}
+
 /** Flags known to take a value argument for `gh pr ready` (not boolean flags). */
 export const FLAGS_THAT_TAKE_VALUE = new Set(["-r", "--repo"]);
 
@@ -21,7 +77,7 @@ export const FLAGS_THAT_TAKE_VALUE = new Set(["-r", "--repo"]);
  * strings — so a segment must break on them too, else `echo hi\ngh pr create` evades
  * the gate. Used by all segment-splitting sites (DRY).
  */
-const SHELL_SEGMENT_SEPARATOR = /\s*(?:&&|\|\||;|\||\n|\r)\s*/;
+const SHELL_SEGMENT_SEPARATOR = /\s*(?:&&|\|\||;|\||&|\n|\r)\s*/;
 
 /**
  * Strip a single balanced surrounding quote pair (`'…'` or `"…"`) from a shell arg value.
@@ -67,8 +123,32 @@ export function trimToNull(value) {
   return trimmed ? trimmed : null;
 }
 
+/**
+ * Strict GitHub owner/name identity shape: each of the two path segments is
+ * `[A-Za-z0-9._-]+` — the character set GitHub itself allows in an owner or repo name. A slug
+ * outside this shape (a shell metacharacter, whitespace, path traversal, or an extra `/` segment)
+ * can never be a real GitHub identity.
+ */
+const CLEAN_REPO_SLUG_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+/**
+ * Whether `slug` is a clean `owner/name` GitHub identity (see `CLEAN_REPO_SLUG_RE`). Exported so a
+ * sink that interpolates a repo slug into a shell command string (e.g. the Pi extension's
+ * `gateCommand` in `extension/post-merge-update.ts`) can defense-in-depth guard the interpolation,
+ * on top of `normalizeGitHubRepoSlug` already enforcing this shape at the source.
+ * @param {string|null|undefined} slug @returns {boolean}
+ */
+export function isCleanRepoSlug(slug) {
+  return typeof slug === "string" && CLEAN_REPO_SLUG_RE.test(slug);
+}
+
 /**
  * Normalize a git remote URL into an `owner/name` slug (lowercased), or null.
+ * A hostile remote (e.g. `git@github.com:acme/widgets;id`) never yields a slug carrying the
+ * injected metacharacters — the extracted candidate must match `CLEAN_REPO_SLUG_RE` or this
+ * returns null instead, so every caller (both harnesses' managed-repo scope checks, and any sink
+ * that interpolates the slug into a shell command) sees either a real GitHub identity or null,
+ * never shell-metacharacter-bearing text.
  * @param {string} remoteUrl
  * @returns {string|null}
  */
@@ -91,7 +171,8 @@ export function normalizeGitHubRepoSlug(remoteUrl) {
     if (!match) {
       continue;
     }
-    return trimToNull(match[1])?.toLowerCase() ?? null;
+    const slug = trimToNull(match[1])?.toLowerCase() ?? null;
+    return isCleanRepoSlug(slug) ? slug : null;
   }
 
   return null;
@@ -486,6 +567,25 @@ export function extractRepoFlagsFromGhPrCreateSegments(command) {
   return extractRepoFlagsFromGhSubcmdVerbSegments(command, "pr", "create");
 }
 
+/**
+ * Return `{ segment, explicitRepo }` for every `gh pr merge` segment (ignoring --help/-h) —
+ * PreToolUse gate scope check use only, so a proven-foreign leading segment can't shield a later
+ * managed one. Mirrors `extractRepoFlagsFromGhPrCreateSegments`.
+ * @param {string} command @returns {{ segment: string, explicitRepo: string|null }[]}
+ */
+export function extractRepoFlagsFromGhPrMergeSegments(command) {
+  return extractRepoFlagsFromGhSubcmdVerbSegments(command, "pr", "merge");
+}
+
+/**
+ * Return `{ segment, explicitRepo }` for every `gh pr ready` segment (ignoring --help/-h) —
+ * PreToolUse gate scope check use only. Mirrors `extractRepoFlagsFromGhPrCreateSegments`.
+ * @param {string} command @returns {{ segment: string, explicitRepo: string|null }[]}
+ */
+export function extractRepoFlagsFromGhPrReadySegments(command) {
+  return extractRepoFlagsFromGhSubcmdVerbSegments(command, "pr", "ready");
+}
+
 /** @param {string} command @returns {number|null} */
 export function extractPrNumberFromGhPrMerge(command) {
   return extractPrNumberFromGhPrVerb(command, "merge");
@@ -574,13 +674,22 @@ export function extractGhApiEndpointSegments(command) {
   return out;
 }
 
-/** The `gh api` segments whose endpoint is the target repo's URL path. Matches the absolute
- * slug-embedded form (`repos/mfittko/dev-loops/...`) and the bare relative form (`issues/...`),
- * which gh api resolves against the cwd repo — the decideBashGate call site gates the relative form
- * on `inTargetRepo`. */
-function targetGhApiPathRegex(suffix) {
-  const slug = TARGET_REPO_SLUG.replace("/", "\\/");
-  return new RegExp(`(?:repos/${slug}/|^)${suffix}`);
+/** The `gh api` segments whose endpoint is the dev-loops-managed repo's URL path. Matches the
+ * absolute slug-embedded form (`repos/<managedSlug>/...`) when `managedSlug` resolves, plus the
+ * bare relative form (`issues/...`), which gh api resolves against the cwd repo — the
+ * decideBashGate call site gates the relative form on `inManagedRepo`. When `managedSlug` is null
+ * (the managed repo's identity could not be resolved in a managed context — AC4's fail-closed
+ * case), the absolute arm matches ANY owner/repo rather than a specific slug: identity is unknown,
+ * so an absolute write must be denied regardless of which repo it targets, not waved through for
+ * lack of a slug to compare against. The absolute arm fully regex-escapes a resolved slug (a `.`
+ * in a legitimate repo name must match literally, not as a wildcard) and matches
+ * case-insensitively (GitHub repo identity is case-insensitive). */
+function managedGhApiPathRegex(suffix, managedSlug) {
+  if (!managedSlug) {
+    return new RegExp(`(?:repos/[^/]+/[^/]+/|^)${suffix}`, "i");
+  }
+  const slug = managedSlug.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+  return new RegExp(`(?:repos/${slug}/|^)${suffix}`, "i");
 }
 
 /** Strip a `scheme://host` prefix from an absolute gh api URL endpoint (`https://api.github.com/...`),
@@ -617,15 +726,18 @@ function ghApiSegmentHasWriteMethod(segment) {
 }
 
 /**
- * SUBISSUE-NO-ADHOC-BYPASS: raw `gh api` WRITE to `.../issues/<n>/sub_issues[/priority]` on the target
- * repo — the ad-hoc sub-issue mutation that must flow through the sanctioned `manage-sub-issues`
- * wrapper instead. Actor-independent (the issue's decided policy): the main agent gets no reserved
- * direct path to sub-issue writes. Anchored on the target repo's URL path segment AND an explicit write
- * method, so a `gh api` read or another repo's `sub_issues` write passes through (no false deny).
- * @param {string} command @returns {boolean}
+ * SUBISSUE-NO-ADHOC-BYPASS: raw `gh api` WRITE to `.../issues/<n>/sub_issues[/priority]` on the
+ * dev-loops-managed repo — the ad-hoc sub-issue mutation that must flow through the sanctioned
+ * `manage-sub-issues` wrapper instead. Actor-independent (the issue's decided policy): the main
+ * agent gets no reserved direct path to sub-issue writes. Anchored on the managed repo's URL path
+ * segment AND an explicit write method, so a `gh api` read or another repo's `sub_issues` write
+ * passes through (no false deny).
+ * @param {string} command @param {string|null} [managedSlug] - Resolved managed-repo slug, or
+ *   null when unresolvable (both the relative and any absolute repos/<owner>/<repo>/ form match then, fail closed).
+ * @returns {boolean}
  */
-export function commandContainsSubIssueAdHocBypass(command) {
-  const re = targetGhApiPathRegex(`issues/\\d+/sub_issues(?:/priority)?(?:\\s|$)`);
+export function commandContainsSubIssueAdHocBypass(command, managedSlug = null) {
+  const re = managedGhApiPathRegex(`issues/\\d+/sub_issues(?:/priority)?(?:\\s|$)`, managedSlug);
   return extractGhApiEndpointSegments(command).some(
     ({ segment, endpoint }) => Boolean(endpoint) && re.test(normalizeGhApiEndpoint(endpoint)) && ghApiSegmentHasWriteMethod(segment),
   );
@@ -633,12 +745,15 @@ export function commandContainsSubIssueAdHocBypass(command) {
 
 /**
  * COPILOT-FOLLOWUP-REPLY-RESOLVE-HELPER (REST half): raw `gh api` POST to
- * `.../pulls/<n>/comments/<m>/replies` on the target repo — the ad-hoc thread reply that must flow
- * through `reply-resolve-review-thread(s).mjs`. Actor-independent: no reserved direct reply path.
- * @param {string} command @returns {boolean}
+ * `.../pulls/<n>/comments/<m>/replies` on the dev-loops-managed repo — the ad-hoc thread reply
+ * that must flow through `reply-resolve-review-thread(s).mjs`. Actor-independent: no reserved
+ * direct reply path.
+ * @param {string} command @param {string|null} [managedSlug] - Resolved managed-repo slug, or
+ *   null when unresolvable (both the relative and any absolute repos/<owner>/<repo>/ form match then, fail closed).
+ * @returns {boolean}
  */
-export function commandContainsReplyResolveBypass(command) {
-  const re = targetGhApiPathRegex(`pulls/\\d+/comments/\\d+/replies(?:\\s|$)`);
+export function commandContainsReplyResolveBypass(command, managedSlug = null) {
+  const re = managedGhApiPathRegex(`pulls/\\d+/comments/\\d+/replies(?:\\s|$)`, managedSlug);
   return extractGhApiEndpointSegments(command).some(
     ({ segment, endpoint }) => Boolean(endpoint) && re.test(normalizeGhApiEndpoint(endpoint)) && ghApiSegmentHasWriteMethod(segment),
   );
@@ -657,12 +772,14 @@ export function commandContainsGraphqlResolveReviewThread(command) {
 
 /**
  * COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY (REST half): raw `gh api` write to
- * `.../pulls/<n>/requested_reviewers` on the target repo — the ad-hoc Copilot review request that must
- * flow through `scripts/github/request-copilot-review.mjs`. Actor-independent.
- * @param {string} command @returns {boolean}
+ * `.../pulls/<n>/requested_reviewers` on the dev-loops-managed repo — the ad-hoc Copilot review
+ * request that must flow through `scripts/github/request-copilot-review.mjs`. Actor-independent.
+ * @param {string} command @param {string|null} [managedSlug] - Resolved managed-repo slug, or
+ *   null when unresolvable (both the relative and any absolute repos/<owner>/<repo>/ form match then, fail closed).
+ * @returns {boolean}
  */
-export function commandContainsCopilotRequestBypass(command) {
-  const re = targetGhApiPathRegex(`pulls/\\d+/requested_reviewers(?:\\s|$)`);
+export function commandContainsCopilotRequestBypass(command, managedSlug = null) {
+  const re = managedGhApiPathRegex(`pulls/\\d+/requested_reviewers(?:\\s|$)`, managedSlug);
   return extractGhApiEndpointSegments(command).some(
     ({ segment, endpoint }) => Boolean(endpoint) && re.test(normalizeGhApiEndpoint(endpoint)) && ghApiSegmentHasWriteMethod(segment),
   );

package/src/loop/child-launch-bound.mjs

@@ -0,0 +1,152 @@
+/**
+ * child-launch-bound.mjs — dev-loop execution-cap fail-fast child-launch
+ * bound (epic decided approach): a bounded, deterministic primitive that
+ * attempts a child launch AT MOST ONCE, queries the harness-supported-model
+ * inventory AT MOST ONCE and ONLY after a failed launch, and always produces
+ * a durable blocker record on failure — never a retry, a silent model
+ * substitution, or a dispatch without the requested override.
+ *
+ * Pure and offline: launch/query behavior is fully caller-injected
+ * (attemptLaunch/querySupportedModels); this module never imports a runtime
+ * harness adapter, reads a file, or performs I/O of its own.
+ */
+
+/**
+ * Dev-loop harnesses this bound recognizes; any other value fails closed.
+ * This primitive only carries the harness label through the request/blocker
+ * — it does not branch on it or depend on per-harness capability data (e.g.
+ * HARNESS_DEFAULT_CAPABILITIES), so it stays agnostic across pi, claude, and
+ * codex.
+ */
+const HARNESS_VALUES = Object.freeze(["pi", "claude", "codex"]);
+
+/** @param {unknown} value @returns {boolean} */
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Validate + normalize the child-launch request. Fails closed (TypeError) on
+ * any malformed/empty field, at the trust boundary of this function.
+ * @param {object} request
+ * @returns {{run:string, roleOrAngle:string, model:string, harness:"pi"|"claude"|"codex"}}
+ */
+function validateRequest(request) {
+  if (!request || typeof request !== "object") {
+    throw new TypeError("enforceChildLaunchBound requires a request object");
+  }
+  const { run, roleOrAngle, model, harness } = request;
+  if (!isNonEmptyString(run)) throw new TypeError("request.run must be a non-empty string");
+  if (!isNonEmptyString(roleOrAngle)) throw new TypeError("request.roleOrAngle must be a non-empty string");
+  if (!isNonEmptyString(model)) throw new TypeError("request.model must be a non-empty string");
+  if (!HARNESS_VALUES.includes(harness)) {
+    throw new TypeError(`request.harness must be one of ${HARNESS_VALUES.join(", ")}, got ${JSON.stringify(harness)}`);
+  }
+  return { run: run.trim(), roleOrAngle: roleOrAngle.trim(), model: model.trim(), harness };
+}
+
+// Note: querySupportedModels may return { supported: [...] }, a bare
+// array, or a Set — normalizing all three into one Set here keeps the
+// caller-facing contract flexible without adding a second exported shape.
+/** @param {{supported?: unknown}|unknown[]|Set<string>} result @returns {Set<string>} */
+function toSupportedSet(result) {
+  const list = result && typeof result === "object" && !Array.isArray(result) && !(result instanceof Set)
+    ? result.supported
+    : result;
+  if (list instanceof Set) return list;
+  if (Array.isArray(list)) return new Set(list);
+  return new Set();
+}
+
+/**
+ * Enforce the bounded, deterministic child-launch fail-fast protocol.
+ *
+ * Scope: this bounds ONE invocation — one launch attempt plus at most one
+ * inventory query for that same call. It holds no state across calls, so
+ * cross-call terminality (never re-launching the same `(run, roleOrAngle,
+ * model)` after a prior call already returned a blocked verdict) is the
+ * caller's/coordinator's contract, not something a persisted token here
+ * enforces.
+ *
+ * Deadline contract: `deadlineMs` is a MEASUREMENT bound, not a per-call
+ * timeout. The function times the elapsed wall-clock span of the one launch
+ * attempt plus (on failure) the one inventory query, and reports
+ * `withinDeadline` fail-closed (`elapsedMs <= deadlineMs`) — it never cancels
+ * or races `attemptLaunch`/`querySupportedModels` against the clock. The
+ * <=60s guarantee holds only because each injected operation is a single
+ * bounded call, never a retry loop, inside this function; enforcing a hard
+ * per-operation timeout/cancellation on a slow `attemptLaunch` or
+ * `querySupportedModels` implementation is the caller's operation-budget
+ * responsibility and is intentionally out of scope for this pure primitive.
+ *
+ * @param {object} options
+ * @param {{run:string, roleOrAngle:string, model:string, harness:"pi"|"claude"|"codex"}} options.request
+ * @param {(request:object)=>({ok:true,launch:*}|{ok:false,reason:string})} options.attemptLaunch
+ *   Called AT MOST ONCE.
+ * @param {(request:object)=>({supported:string[]}|string[]|Set<string>)} options.querySupportedModels
+ *   Called AT MOST ONCE, and only after a failed launch.
+ * @param {()=>number} [options.now] - injectable clock, default Date.now.
+ * @param {number} [options.deadlineMs] - measurement bound in ms, default 60000.
+ * @returns {object} `{ ok: true, launch, events, elapsedMs, withinDeadline }`
+ *   on success, or the durable blocker `{ ok: false, verdict: "blocked",
+ *   reason, launchFailureDetail, request, modelSupported, elapsedMs,
+ *   withinDeadline, events }` on failure. `launchFailureDetail` is the failed
+ *   `attemptLaunch` result verbatim (its own reason plus any error/message it
+ *   carried), preserved alongside the normalized `reason`.
+ */
+export function enforceChildLaunchBound({ request, attemptLaunch, querySupportedModels, now = () => Date.now(), deadlineMs = 60000 } = {}) {
+  const normalizedRequest = validateRequest(request);
+  if (typeof attemptLaunch !== "function") {
+    throw new TypeError("enforceChildLaunchBound requires attemptLaunch to be a function");
+  }
+  if (typeof querySupportedModels !== "function") {
+    throw new TypeError("enforceChildLaunchBound requires querySupportedModels to be a function");
+  }
+
+  const events = [];
+  const start = now();
+
+  // EXACTLY one launch attempt, ever — no retry, no model substitution.
+  const launchResult = attemptLaunch(normalizedRequest);
+  events.push({ type: "launch_attempt" });
+
+  if (launchResult && launchResult.ok === true) {
+    // Success: never query the inventory, never attempt a second launch.
+    const elapsedMs = now() - start;
+    return { ok: true, launch: launchResult.launch, events, elapsedMs, withinDeadline: elapsedMs <= deadlineMs };
+  }
+
+  // Launch failed: query the harness's supported-model inventory EXACTLY
+  // once, only now (never before a launch attempt, never more than once).
+  const inventory = querySupportedModels(normalizedRequest);
+  events.push({ type: "inventory_query" });
+  const modelSupported = toSupportedSet(inventory).has(normalizedRequest.model);
+
+  const launchReason = launchResult && typeof launchResult.reason === "string" ? launchResult.reason : null;
+  const reason = launchReason === "unresolvable"
+    ? "child_model_unresolvable"
+    : !modelSupported
+      ? "child_model_unsupported"
+      : "child_launch_failed_model_supported";
+  // Verbatim passthrough of the failed launch result (its own reason plus any
+  // error/message/detail it carried) — never inspected or altered — so a
+  // caller can see the exact failure detail alongside the normalized reason.
+  const launchFailureDetail = launchResult && typeof launchResult === "object" ? launchResult : null;
+
+  const elapsedMs = now() - start;
+  // Measurement, not enforcement: a slow adapter still returns the blocker
+  // (fail-closed) rather than being cancelled or retried against the clock.
+  const withinDeadline = elapsedMs <= deadlineMs;
+
+  return {
+    ok: false,
+    verdict: "blocked",
+    reason,
+    launchFailureDetail,
+    request: normalizedRequest,
+    modelSupported,
+    elapsedMs,
+    withinDeadline,
+    events,
+  };
+}

package/src/loop/copilot-loop-state.mjs

@@ -197,6 +197,7 @@ export function buildSnapshotFromPrFacts({
   lastCopilotRoundMaxSignal = null,
   failureDetails = [],
   excludedFailureDetails,
+  copilotBodyFeedbackUnresolved = false,
 }) {
   const prState = typeof prData?.state === "string" ? prData.state.toUpperCase() : "OPEN";
   const prMerged = prState === "MERGED";
@@ -205,6 +206,9 @@ export function buildSnapshotFromPrFacts({
   // that never threads an explicit ciStatus (e.g. gate-coordination detection)
   // still never treats it as a blocking CI failure.
   const rollupDerivation = deriveLoopCiStatusFromRollup(prData?.statusCheckRollup);
+  const currentHeadSha = typeof prData?.headRefOid === "string" && prData.headRefOid.trim().length > 0
+    ? prData.headRefOid.trim()
+    : null;
 
   return normalizeSnapshot({
     prExists: true,
@@ -212,6 +216,7 @@ export function buildSnapshotFromPrFacts({
     prDraft: Boolean(prData?.isDraft),
     prMerged,
     prClosed,
+    currentHeadSha,
     copilotReviewRequestStatus,
     copilotReviewPresent,
     copilotReviewOnCurrentHead,
@@ -222,6 +227,7 @@ export function buildSnapshotFromPrFacts({
     ciStatus: ciStatus ?? rollupDerivation.status,
     failureDetails,
     excludedFailureDetails: excludedFailureDetails ?? rollupDerivation.excludedFailureDetails,
+    copilotBodyFeedbackUnresolved,
   });
 }
 
@@ -269,6 +275,9 @@ export function normalizeSnapshot(raw) {
     prDraft: Boolean(raw.prDraft),
     prMerged: Boolean(raw.prMerged),
     prClosed: Boolean(raw.prClosed),
+    currentHeadSha: typeof raw.currentHeadSha === "string" && raw.currentHeadSha.trim().length > 0
+      ? raw.currentHeadSha.trim()
+      : null,
     copilotReviewRequestStatus: VALID_REVIEW_REQUEST_STATUSES.has(raw.copilotReviewRequestStatus)
       ? raw.copilotReviewRequestStatus
       : "none",
@@ -288,6 +297,7 @@ export function normalizeSnapshot(raw) {
     agentFixStatus: raw.agentFixStatus === "applied" ? "applied" : null,
     failureDetails: Array.isArray(raw.failureDetails) ? raw.failureDetails : [],
     excludedFailureDetails: Array.isArray(raw.excludedFailureDetails) ? raw.excludedFailureDetails : [],
+    copilotBodyFeedbackUnresolved: Boolean(raw.copilotBodyFeedbackUnresolved),
   };
 }
 
@@ -397,7 +407,7 @@ export function interpretLoopState(snapshot, refinementConfig) {
       && state !== STATE.PR_DRAFT && state !== STATE.REVIEW_REQUEST_UNAVAILABLE
       && state !== STATE.BLOCKED_NEEDS_USER_DECISION) {
     const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen" || !preApprovalRequireCi;
-    const cleanThreads = s.unresolvedThreadCount === 0;
+    const cleanThreads = s.unresolvedThreadCount === 0 && !s.copilotBodyFeedbackUnresolved;
     if (cleanThreads && ciClean) {
       state = STATE.ROUND_CAP_CLEAN_FALLBACK;
     } else if (!reviewInFlight) {
@@ -406,11 +416,16 @@ export function interpretLoopState(snapshot, refinementConfig) {
     // Not clean WITH an in-flight request: leave state undecided for the routing below.
   }
 
+  // Unresolved feedback includes both inline review threads and a Copilot
+  // review-body finding on the current head (a body-only "Changes recommended"
+  // review with zero inline threads must not read as clean).
+  const unresolvedFeedback = s.unresolvedThreadCount > 0 || s.copilotBodyFeedbackUnresolved;
+
   if (state === undefined) {
-    if (s.unresolvedThreadCount > 0 && s.agentFixStatus === "applied") {
+    if (unresolvedFeedback && s.agentFixStatus === "applied") {
       // Agent has fixed the code; threads still need reply/resolve on GitHub
       state = STATE.ALREADY_FIXED_NEEDS_REPLY_RESOLVE;
-    } else if (s.unresolvedThreadCount > 0) {
+    } else if (unresolvedFeedback) {
       // Unresolved feedback exists — do not wait; enter fix/reply-resolve handling
       state = STATE.UNRESOLVED_FEEDBACK_PRESENT;
     } else if (s.copilotReviewRequestStatus === "requested" || s.copilotReviewRequestStatus === "already-requested") {
@@ -459,7 +474,8 @@ export function interpretLoopState(snapshot, refinementConfig) {
   const sameHeadCleanConverged = state === STATE.READY_TO_REREQUEST_REVIEW
     && s.copilotReviewOnCurrentHead
     && s.unresolvedThreadCount === 0
-    && s.actionableThreadCount === 0;
+    && s.actionableThreadCount === 0
+    && !s.copilotBodyFeedbackUnresolved;
 
   let nextAction = NEXT_ACTIONS[state];
   if (sameHeadCleanConverged) {