@dev-loops/core 1.0.2 → 1.0.4-pre.0

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-ci-status.mjs

@@ -20,16 +20,33 @@ const STATUS_CONTEXT_SUCCESS_STATES = new Set(["SUCCESS"]);
 export const LOOP_DERIVED_CI_CHECK_NAME = "gate-evidence";
 
 /**
- * The same workflow ALSO surfaces as a check run under its job id
- * (`gate-evidence-runner`) beside the commit status named above, and both are
- * the loop's own derived signal. Excluding only the status context left the
- * runner's conclusion gating the loop's own pre_approval step: once the
- * workflow gained job-level concurrency, a superseded run is cancelled as
+ * The same workflow ALSO surfaces as check runs under its two job ids
+ * (`gate-evidence-runner`, the compute-heavy detector, and
+ * `gate-evidence-reporter`, the always-settling job that owns the status
+ * above — see docs/decisions/0076) beside the commit status named above, and
+ * all are the loop's own derived signal. Excluding only the status context
+ * left either job's conclusion gating the loop's own pre_approval step: once
+ * the workflow gained job-level concurrency, a superseded run is cancelled as
  * normal operation, and a cancelled run is deliberately NOT treated as green
  * (see normalizeStatusCheckRollupStatus) — so one routine cancellation made
  * the whole head read "none" and the loop waited on CI forever.
  */
-export const LOOP_DERIVED_CI_CHECK_NAMES = Object.freeze([LOOP_DERIVED_CI_CHECK_NAME, "gate-evidence-runner"]);
+export const LOOP_DERIVED_CI_CHECK_NAMES = Object.freeze([
+  LOOP_DERIVED_CI_CHECK_NAME,
+  "gate-evidence-runner",
+  "gate-evidence-reporter",
+]);
+
+/**
+ * The two Gate-evidence JOB check-run names — the detector and the reporter.
+ * These (and ONLY these, never the `gate-evidence` status name) are the runs
+ * whose superseded CANCELLED check-runs `classifyBenignGateEvidenceUnstable`
+ * treats as cosmetic UNSTABLE noise.
+ */
+export const GATE_EVIDENCE_JOB_CHECK_NAMES = Object.freeze([
+  "gate-evidence-runner",
+  "gate-evidence-reporter",
+]);
 
 function checkEntryName(entry) {
   if (typeof entry?.name === "string" && entry.name.length > 0) return entry.name;
@@ -141,6 +158,27 @@ export function normalizeStatusCheckRollupStatus(rollup) {
   return "none";
 }
 
+/**
+ * Resolve the normalized status of ONE named context/check within a
+ * `statusCheckRollup` (or check-runs-shaped) payload — e.g. whether the
+ * required `gate-evidence` context itself (as opposed to the loop's own
+ * exclusion of it, see `deriveLoopCiStatusFromRollup`) is success, failure,
+ * pending, or absent. Reuses the same name matching
+ * (`partitionEntriesByCheckName`) and state normalization
+ * (`normalizeStatusCheckRollupStatus`) the rollup helpers on this module
+ * already use, so a caller that needs one context's own state (e.g.
+ * merge-pr.mjs naming the real cause of a block on `gate-evidence`) does not
+ * re-derive name matching or status normalization.
+ *
+ * @param {Array<object>} rollup
+ * @param {string} contextName
+ * @returns {"success"|"failure"|"pending"|"none"}
+ */
+export function resolveNamedContextState(rollup, contextName) {
+  const { matched } = partitionEntriesByCheckName(rollup, contextName);
+  return normalizeStatusCheckRollupStatus(matched);
+}
+
 /**
  * Summarize the GitHub check-runs API payload for one head SHA.
  *
@@ -317,6 +355,78 @@ export function normalizeHeadScopedCiContract({
   return buildCiContract(overallStatus);
 }
 
+/**
+ * Classify a `mergeStateStatus === "UNSTABLE"` as BENIGN when the required
+ * `gate-evidence` commit status is itself `success` and the ONLY non-success
+ * rollup entries are superseded Gate-evidence job check-runs (the
+ * `gate-evidence-runner` detector OR the `gate-evidence-reporter`, conclusion
+ * `CANCELLED`).
+ *
+ * Both jobs cancel superseded runs: the detector via `cancel-in-progress`, the
+ * reporter via its non-cancelling group cancelling a still-queued run superseded
+ * by a newer one. Each leaves a `cancelled` check-run on the head, so
+ * `mergeStateStatus` reads `UNSTABLE` on nearly every PR even when the required
+ * `gate-evidence` status on the head is green. The cancellation is correct and
+ * stays (docs/decisions/0076); this classifier only lets a reader distinguish
+ * that cosmetic noise from a real non-success.
+ *
+ * Fail-closed: only an actual `UNSTABLE` with a `success` `gate-evidence` status
+ * and no other non-success entry is benign. A failed (not cancelled) Gate-evidence
+ * job, a non-success `gate-evidence` status, or any other failing/pending check
+ * makes it non-benign.
+ *
+ * ponytail: `gh pr view --json statusCheckRollup` returns a single bounded page
+ * (~100 contexts); a very chatty PR could exceed it and hide a real failure,
+ * failing this open. Acceptable because this is a display-only surface — the
+ * merge path never consults it. Do NOT wire this classifier into a merge
+ * decision without adding pagination.
+ *
+ * @param {Array<object>} rollup A `gh pr view --json statusCheckRollup` payload.
+ * @param {string|null} mergeStateStatus
+ * @returns {{ benign: boolean, reason: string }}
+ */
+export function classifyBenignGateEvidenceUnstable(rollup, mergeStateStatus) {
+  const state = typeof mergeStateStatus === "string" ? mergeStateStatus.toUpperCase() : "";
+  if (state !== "UNSTABLE") {
+    return { benign: false, reason: "mergeStateStatus is not UNSTABLE" };
+  }
+  if (!Array.isArray(rollup)) {
+    return { benign: false, reason: "status rollup unavailable" };
+  }
+  // The required gate-evidence signal is a commit STATUS (a StatusContext,
+  // `.context`), never a check-run (`.name`). Anchor the success guard on the
+  // StatusContext alone so a same-named success check-run can never stand in for
+  // an absent required status (partitionEntriesByCheckName matches `.name` OR
+  // `.context`, so it would otherwise accept either).
+  const gateEvidenceStatusEntries = rollup.filter(
+    (entry) => entry?.context === LOOP_DERIVED_CI_CHECK_NAME && typeof entry?.state === "string",
+  );
+  if (normalizeStatusCheckRollupStatus(gateEvidenceStatusEntries) !== "success") {
+    return { benign: false, reason: "gate-evidence status is not success" };
+  }
+  const offenders = [];
+  for (const entry of rollup) {
+    if (normalizeStatusCheckRollupStatus([entry]) === "success") continue;
+    const name = checkEntryName(entry);
+    const conclusion = typeof entry?.conclusion === "string" ? entry.conclusion.toUpperCase() : "";
+    // Only a cancelled Gate-evidence JOB check-run (runner or reporter) is the
+    // superseded-run artifact this classifier ignores — an explicit two-job
+    // allowlist, not LOOP_DERIVED_CI_CHECK_NAMES (which also carries the
+    // `gate-evidence` status name), so a cancelled entry named `gate-evidence`
+    // can never be waved through as benign.
+    if (GATE_EVIDENCE_JOB_CHECK_NAMES.includes(name) && conclusion === "CANCELLED") continue;
+    const status = typeof entry?.status === "string" ? entry.status.toUpperCase() : "";
+    offenders.push(`${name || "unknown"}=${conclusion || status || "?"}`);
+  }
+  if (offenders.length > 0) {
+    return { benign: false, reason: `non-benign non-success checks present: ${offenders.join(", ")}` };
+  }
+  return {
+    benign: true,
+    reason: "no non-success entry other than superseded Gate-evidence job cancellations; gate-evidence status is success",
+  };
+}
+
 /**
  * Derive a loop-safe CI status from a PR `statusCheckRollup` snapshot: the
  * `LOOP_DERIVED_CI_CHECK_NAMES` entries (the `gate-evidence` status and the

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) {