@dev-loops/core 0.9.0 → 1.0.0-rc.1

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

@@ -136,7 +136,25 @@ export const NEXT_ACTIONS = Object.freeze({
 
 const SAME_HEAD_CLEAN_CONVERGED_NEXT_ACTION = "Current head already has a clean submitted Copilot review; suppress automatic same-head re-request unless a meaningful remediation event occurs, or explicitly request another Copilot pass";
 
-const VALID_REVIEW_REQUEST_STATUSES = new Set(["requested", "already-requested", "unavailable", "none", "failed"]);
+/**
+ * Canonical snapshot request-status enum (single source of truth). Any request
+ * outcome plumbed into the shared loop contract MUST normalize to one of these;
+ * richer request-tool outcomes (round_cap_reached, suppressed_*, etc.) collapse
+ * to "none" here because they mean "no active Copilot request is in flight".
+ */
+export const VALID_REVIEW_REQUEST_STATUSES = new Set(["requested", "already-requested", "unavailable", "none", "failed"]);
+
+/**
+ * Collapse an arbitrary request-tool outcome to the canonical snapshot
+ * request-status enum. Unrecognized statuses (round cap / suppression
+ * diagnostics) map to "none" so they never leak into the shared contract.
+ *
+ * @param {string|undefined} status
+ * @returns {string} a member of VALID_REVIEW_REQUEST_STATUSES
+ */
+export function toSharedRequestStatus(status) {
+  return VALID_REVIEW_REQUEST_STATUSES.has(status) ? status : "none";
+}
 const VALID_CI_STATUSES = new Set(["success", "failure", "pending", "none", "crediblyGreen"]);
 const ACTIVE_REQUEST_STATUSES = new Set(["requested", "already-requested"]);
 
@@ -341,6 +359,9 @@ export function applyConfirmedReviewRequest(snapshot, reviewRequestStatus) {
  * @param {number} [refinementConfig.lowSignalRoundThreshold]
  * @param {number} [refinementConfig.lowSignalMaxComments]
  * @param {number} [refinementConfig.maxCopilotRounds]
+ * @param {boolean} [refinementConfig.preApprovalRequireCi] - #1337: default true. When false,
+ *   the pre-approval CI precondition is opted out, so a non-draft PR with a pending/none/failure
+ *   CI verdict is not routed to waiting_for_ci / blocked_needs_user_decision (it is past the draft gate).
  * @returns {{
  *   state: string,
  *   allowedTransitions: string[],
@@ -353,6 +374,17 @@ export function applyConfirmedReviewRequest(snapshot, reviewRequestStatus) {
 export function interpretLoopState(snapshot, refinementConfig) {
   const s = normalizeSnapshot(snapshot);
 
+  // Pre-approval CI opt-out (#1337): when `gates.preApproval.requireCi` is false,
+  // the CI verdict must not gate progression at the pre-approval boundary. A
+  // non-draft PR is past the draft gate, so this is the applicable knob — treat
+  // pending/none/failure CI as non-blocking here so a repo with no CI is not
+  // routed to WAITING_FOR_CI / BLOCKED_NEEDS_USER_DECISION before the downstream
+  // gate-coordination guards (which already honor this flag) are ever reached.
+  // Default true preserves current behavior for every caller that does not thread it.
+  const preApprovalRequireCi = refinementConfig?.preApprovalRequireCi !== false;
+  const ciBlocks = preApprovalRequireCi && isBlockedCiStatus(s.ciStatus);
+  const ciWaits = preApprovalRequireCi && isWaitingCiStatus(s.ciStatus);
+
   let state;
 
   if (!s.prExists) {
@@ -403,7 +435,7 @@ export function interpretLoopState(snapshot, refinementConfig) {
       && state !== STATE.NO_PR && state !== STATE.DONE
       && state !== STATE.PR_DRAFT && state !== STATE.REVIEW_REQUEST_UNAVAILABLE
       && state !== STATE.BLOCKED_NEEDS_USER_DECISION) {
-    const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen";
+    const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen" || !preApprovalRequireCi;
     const cleanThreads = s.unresolvedThreadCount === 0;
     if (cleanThreads && ciClean) {
       // Clean PR at the cap: proceed to the pre_approval_gate fallback regardless of a
@@ -430,18 +462,18 @@ export function interpretLoopState(snapshot, refinementConfig) {
       state = STATE.WAITING_FOR_COPILOT_REVIEW;
     } else if (s.copilotReviewPresent) {
       // Copilot has reviewed at least once; all threads resolved
-      if (isBlockedCiStatus(s.ciStatus)) {
+      if (ciBlocks) {
         state = STATE.BLOCKED_NEEDS_USER_DECISION;
-      } else if (isWaitingCiStatus(s.ciStatus)) {
+      } else if (ciWaits) {
         state = STATE.WAITING_FOR_CI;
       } else {
         state = STATE.READY_TO_REREQUEST_REVIEW;
       }
     } else {
       // No Copilot review yet; not currently requested
-      if (isBlockedCiStatus(s.ciStatus)) {
+      if (ciBlocks) {
         state = STATE.BLOCKED_NEEDS_USER_DECISION;
-      } else if (isWaitingCiStatus(s.ciStatus)) {
+      } else if (ciWaits) {
         state = STATE.WAITING_FOR_CI;
       } else {
         state = STATE.PR_READY_NO_FEEDBACK;

package/src/loop/gate-carry-forward.mjs

@@ -0,0 +1,244 @@
+/**
+ * Gate carry-forward: a pure, fail-closed seam that decides whether a clean gate
+ * angle verdict recorded at head A may be CARRIED FORWARD to head B without
+ * re-running that angle's reviewer.
+ *
+ * Motivation: fresh-context-per-head re-fans ALL gate angles on every head bump,
+ * even when the delta between the two heads provably cannot affect most angles
+ * (e.g. a doc-only follow-up commit cannot change what a code-correctness angle
+ * would find). Carry-forward lets the gate reuse the prior clean verdict for such
+ * angles — but ONLY when it is provably safe.
+ *
+ * FAIL-CLOSED is paramount. An angle carries forward ONLY when EVERY changed file
+ * in the delta A..B is provably OUTSIDE that angle's declared review surface. The
+ * default in every uncertain case (non-clean prior verdict, empty/unavailable
+ * delta, an unclassifiable file, an angle with no declared surface, a mandatory /
+ * always-run angle) is MUST-RE-RUN. Carry-forward never fabricates a verdict: the
+ * caller records the carried verdict with provenance pointing at the PRIOR head's
+ * reviewer (that reviewer genuinely reviewed this angle's surface, which the delta
+ * did not touch), clearly marked as carried — see
+ * docs/gate-review-sub-loop-contract.md and write-gate-findings-log.mjs's
+ * `carriedFromHead` provenance field.
+ *
+ * The angle -> review-surface mapping is DERIVED from the single source of truth
+ * for change-category -> angle relevance (CATEGORY_ANGLE_MAP in
+ * ../analysis/change-classifier.mjs) so the two never drift: an angle's review
+ * surface is exactly the set of file "surface kinds" whose change could, under the
+ * existing dynamic-angle rules, implicate that angle. File classification reuses
+ * classifyFile() from the diff analyzer (the same classifier dynamic angle
+ * resolution already trusts).
+ *
+ * This module is intentionally pure and side-effect free.
+ */
+
+import { classifyFile } from "../analysis/diff-analyzer.mjs";
+import { ALWAYS_INCLUDE, CATEGORY_ANGLE_MAP } from "../analysis/change-classifier.mjs";
+
+/**
+ * File surface kind (classifyFile output) -> the change categories a change of
+ * that kind can produce. A code file can be either a logic change or a
+ * comment-only change; the other kinds each map to their single `_ONLY` category.
+ * "unknown" is intentionally ABSENT: an unclassifiable file is treated as
+ * touching EVERY angle's surface (fail-closed), so it never appears here.
+ *
+ * RENAME_ONLY is not a file kind — a renamed file still classifies by its
+ * destination path's kind, so the destination kind's own categories already
+ * implicate the right angles (a renamed code file -> code -> LOGIC_CHANGE, a
+ * renamed doc -> docs -> DOCS_ONLY). Folding RENAME_ONLY into every kind would
+ * over-attribute code angles to a doc-only delta and defeat the primary
+ * carry-forward case, so it is deliberately omitted here. A destination-kind
+ * classification alone, though, misses what the RENAME itself implicates (a
+ * moved doc can break a link; a moved test/code file shifts scope /
+ * contract-surface). Rename detection therefore lives at the DELTA layer: the
+ * CLI notices any rename/copy row and forces {@link RENAME_ONLY_ANGLES} to
+ * re-run for that run (fail-closed), instead of encoding a phantom "rename" file
+ * kind here.
+ *
+ * @type {Record<string, string[]>}
+ */
+const KIND_TO_CATEGORIES = {
+  docs: ["DOCS_ONLY"],
+  config: ["CONFIG_ONLY"],
+  test: ["TEST_ONLY"],
+  ci: ["CI_ONLY"],
+  code: ["LOGIC_CHANGE", "COMMENT_ONLY"],
+};
+
+/**
+ * The angles a pure rename implicates (CATEGORY_ANGLE_MAP[RENAME_ONLY]), minus
+ * any always-run angle (already never carried). A delta containing ANY rename
+ * forces these to re-run — a rename's effect (moved doc breaking a link, moved
+ * test/code shifting scope/contract-surface) is not captured by classifying the
+ * destination path alone. Derived from the single source of truth so it never
+ * drifts from the dynamic-angle rules.
+ *
+ * @type {string[]}
+ */
+export const RENAME_ONLY_ANGLES = (CATEGORY_ANGLE_MAP.RENAME_ONLY ?? []).filter(
+  (angle) => !ALWAYS_INCLUDE.has(angle),
+);
+
+/**
+ * angle -> Set<surface kind>: an angle's review surface is the set of file kinds
+ * whose change could implicate it, inverted from CATEGORY_ANGLE_MAP via
+ * KIND_TO_CATEGORIES. Built once at module load. ALWAYS_INCLUDE angles are NOT
+ * given a kinds surface here — they always re-run (handled in angleReviewSurface).
+ *
+ * @type {Map<string, Set<string>>}
+ */
+const ANGLE_SURFACE_KINDS = (() => {
+  const map = new Map();
+  for (const [kind, categories] of Object.entries(KIND_TO_CATEGORIES)) {
+    for (const category of categories) {
+      for (const angle of CATEGORY_ANGLE_MAP[category] ?? []) {
+        if (ALWAYS_INCLUDE.has(angle)) continue;
+        if (!map.has(angle)) map.set(angle, new Set());
+        map.get(angle).add(kind);
+      }
+    }
+  }
+  return map;
+})();
+
+/**
+ * @typedef {{ kind: "always" }
+ *   | { kind: "unknown" }
+ *   | { kind: "kinds", kinds: Set<string> }} AngleReviewSurface
+ */
+
+/**
+ * Resolve an angle's declared review surface (the pure angle -> surface mapping).
+ *
+ * - ALWAYS_INCLUDE angles (gate-evidence, renderer-security, pr-description) plus
+ *   any explicit alwaysRerun angle -> `{ kind: "always" }`. These review a surface
+ *   we cannot fully bound from the file delta alone (e.g. pr-description also
+ *   depends on the PR body, which is not a changed FILE), so they NEVER carry
+ *   forward.
+ * - A mapped angle -> `{ kind: "kinds", kinds }` (the file kinds that implicate it).
+ * - An unmapped / unknown angle -> `{ kind: "unknown" }` (fail-closed: never carry).
+ *
+ * @param {string} angle
+ * @param {{ alwaysRerun?: Iterable<string> }} [options]
+ * @returns {AngleReviewSurface}
+ */
+export function angleReviewSurface(angle, { alwaysRerun } = {}) {
+  const name = typeof angle === "string" ? angle.trim() : "";
+  if (name.length === 0) return { kind: "unknown" };
+  if (ALWAYS_INCLUDE.has(name)) return { kind: "always" };
+  if (alwaysRerun && new Set(alwaysRerun).has(name)) return { kind: "always" };
+  const kinds = ANGLE_SURFACE_KINDS.get(name);
+  if (!kinds || kinds.size === 0) return { kind: "unknown" };
+  return { kind: "kinds", kinds: new Set(kinds) };
+}
+
+/**
+ * Pure, deterministic, FAIL-CLOSED carry-forward decision for a single angle.
+ *
+ * Given a prior CLEAN verdict recorded at head A, the changed files of the delta
+ * A..B, and the angle's declared review surface, decide whether the clean verdict
+ * may be carried forward to head B (carryForward: true) or the angle MUST re-run
+ * (carryForward: false). Defaults to must-re-run in every uncertain case.
+ *
+ * @param {object} input
+ * @param {string} input.angle
+ * @param {AngleReviewSurface} [input.angleSurface] — the angle's declared surface;
+ *   derived from {@link angleReviewSurface} when omitted.
+ * @param {string[]} input.changedFiles — repo-relative paths changed between head
+ *   A and head B (the delta, NOT the full PR diff against base).
+ * @param {string} input.prevVerdict — the angle's verdict at head A. Only "clean"
+ *   is carry-forward-eligible.
+ * @returns {{ carryForward: boolean, reason: string }}
+ */
+export function resolveAngleCarryForward({ angle, angleSurface, changedFiles, prevVerdict }) {
+  if (prevVerdict !== "clean") {
+    return { carryForward: false, reason: `prior verdict is ${JSON.stringify(prevVerdict ?? null)}, not "clean"` };
+  }
+  const surface = angleSurface ?? angleReviewSurface(angle);
+  if (surface.kind === "always") {
+    return { carryForward: false, reason: "angle always re-runs (mandatory / always-include surface)" };
+  }
+  if (surface.kind === "unknown") {
+    return { carryForward: false, reason: "angle has no declared review surface (fail-closed)" };
+  }
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return { carryForward: false, reason: "delta is empty or unavailable (fail-closed)" };
+  }
+  for (const file of changedFiles) {
+    const kind = classifyFile(file);
+    if (kind === "unknown") {
+      return { carryForward: false, reason: `delta contains an unclassifiable file (fail-closed): ${file}` };
+    }
+    if (surface.kinds.has(kind)) {
+      return { carryForward: false, reason: `delta touches the angle's review surface (${kind}): ${file}` };
+    }
+  }
+  return {
+    carryForward: true,
+    reason: `delta is provably outside the angle's review surface (surface kinds: ${[...surface.kinds].sort().join(", ")})`,
+  };
+}
+
+/**
+ * Convenience: partition a set of previously-clean angles into those that may be
+ * carried forward and those that must re-run, given the delta A..B. Each entry
+ * carries the decision reason. Non-clean angles are not carry-forward-eligible and
+ * belong in the re-run set — callers should pass only angles whose prior verdict
+ * was clean, or set `prevVerdict` per angle via the single-angle function.
+ *
+ * @param {object} input
+ * @param {string[]} input.prevAngles — angles that were clean at head A
+ * @param {string[]} input.changedFiles — delta A..B
+ * @param {{ alwaysRerun?: Iterable<string> }} [input.options]
+ * @returns {{ carried: Array<{ angle: string, reason: string }>, mustRerun: Array<{ angle: string, reason: string }> }}
+ */
+export function resolveCarryForwardAngles({ prevAngles, changedFiles, options = {} }) {
+  const carried = [];
+  const mustRerun = [];
+  for (const angle of Array.isArray(prevAngles) ? prevAngles : []) {
+    const decision = resolveAngleCarryForward({
+      angle,
+      angleSurface: angleReviewSurface(angle, options),
+      changedFiles,
+      prevVerdict: "clean",
+    });
+    (decision.carryForward ? carried : mustRerun).push({ angle, reason: decision.reason });
+  }
+  return { carried, mustRerun };
+}
+
+/**
+ * The file surface kinds the external Copilot code review actually reviews. Docs
+ * and comment-only prose are NOT part of it; everything a Copilot review could
+ * legitimately raise a code nit about is (code, tests, config, CI).
+ * @type {Set<string>}
+ */
+const COPILOT_REVIEW_SURFACE_KINDS = new Set(["code", "test", "config", "ci"]);
+
+/**
+ * AC2, fail-closed: decide whether a post-convergence head bump may carry forward
+ * a settled clean Copilot convergence instead of forcing a fresh BLOCKING Copilot
+ * round. Carries forward ONLY when the delta since the converged head is provably
+ * outside Copilot's review surface — a pure doc/prose-only bump (every changed
+ * file classifies as `docs`; a code comment-only change classifies as `code` and
+ * re-runs, since classifyFile is path-based). Any code/test/config/CI file, an unclassifiable
+ * file, or an empty/unavailable delta -> re-run (fresh blocking round required).
+ *
+ * @param {object} input
+ * @param {string[]} input.changedFiles — delta since the converged head
+ * @returns {{ carryForward: boolean, reason: string }}
+ */
+export function resolveConvergenceCarryForward({ changedFiles }) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return { carryForward: false, reason: "delta is empty or unavailable (fail-closed)" };
+  }
+  for (const file of changedFiles) {
+    const kind = classifyFile(file);
+    if (kind === "unknown") {
+      return { carryForward: false, reason: `delta contains an unclassifiable file (fail-closed): ${file}` };
+    }
+    if (COPILOT_REVIEW_SURFACE_KINDS.has(kind)) {
+      return { carryForward: false, reason: `delta touches Copilot's review surface (${kind}): ${file}` };
+    }
+  }
+  return { carryForward: true, reason: "delta is a pure doc/prose bump, provably outside Copilot's review surface" };
+}

package/src/loop/policy-constants.mjs

@@ -12,6 +12,3 @@ export const COPILOT_FIRST_DURABLE_WAIT_TIMEOUT_MS = 3_600_000;
 
 /** Copilot review wait: external healthy-wait budget */
 export const COPILOT_REVIEW_WAIT_TIMEOUT_MS = 1_800_000;
-
-/** Explicit single-check timeout value (used only for status probes) */
-export const PROBE_ONLY_TIMEOUT_MS = 0;

package/src/loop/pr-gate-coordination.mjs

@@ -660,6 +660,11 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const conflictFiles = normalizeConflictFiles(input.conflictFiles);
   const ciStatus = normalizeCiStatus(input.ciStatus);
   const draftGateRequireCi = input.draftGateRequireCi !== false;
+  // Opt-out CI precondition at the pre-approval boundary (mirrors the draft
+  // gate). Default true keeps CI required; false ignores the CI verdict
+  // entirely — a "none"/"pending"/"crediblyGreen"/"failure" head no longer
+  // waits on or blocks pre_approval.
+  const preApprovalRequireCi = input.preApprovalRequireCi !== false;
   const copilotReviewRoundCount = normalizeNonNegativeInteger(input.copilotReviewRoundCount);
   const maxCopilotRounds = normalizePositiveInteger(input.maxCopilotRounds);
   const roundCapReached = isCopilotRoundCapReached({ copilotReviewRoundCount, maxCopilotRounds });
@@ -998,7 +1003,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
   if (effectiveLifecycleState === STATE.PR_READY_NO_FEEDBACK) {
     if (reviewMode === "internal_only") {
       // Explicitly internal-only PR: skip the external Copilot review cycle
-      if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+      if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
         pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
         pushUnique(forbiddenActions, internalOnlyPostDraftForbidden);
         return buildResult({
@@ -1201,7 +1206,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
   }
 
   if (effectiveLifecycleState === STATE.READY_TO_REREQUEST_REVIEW) {
-    if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+    if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1226,7 +1231,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       });
     }
 
-    if (ciStatus === "pending" || ciStatus === "none") {
+    if (preApprovalRequireCi && (ciStatus === "pending" || ciStatus === "none")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1410,7 +1415,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         copilotReviewRoundCount,
       });
     }
-    if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+    if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1434,7 +1439,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           refinementArtifact,
       });
     }
-    if (ciStatus === "pending" || ciStatus === "none") {
+    if (preApprovalRequireCi && (ciStatus === "pending" || ciStatus === "none")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1553,7 +1558,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
   }
 
   if (effectiveLifecycleState === STATE.LOW_SIGNAL_CONVERGED) {
-    if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+    if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1577,7 +1582,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           refinementArtifact,
       });
     }
-    if (ciStatus === "pending" || ciStatus === "none") {
+    if (preApprovalRequireCi && (ciStatus === "pending" || ciStatus === "none")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({

package/src/loop/queue-state.mjs

@@ -285,12 +285,3 @@ export function appendBugIssue(queue, issueNumber, dependsOn = null) {
   queue.entries.push(entry);
   return entry;
 }
-
-// ── Serialization helpers ────────────────────────────────────────────
-
-export function serializeQueue(queue) {
-  return {
-    version: queue.version,
-    entries: queue.entries.map((e) => ({ ...e })),
-  };
-}

package/src/loop/steering.mjs

@@ -718,10 +718,12 @@ export function getEffectiveConstraints(steeringState) {
  *
  * @param {object} snapshot - raw or normalized loop snapshot
  * @param {object} steeringState - current steering state for this run
+ * @param {object} [refinementConfig] - interpreter refinement config; pass a config-derived
+ *   `resolveRefinement(config)` so the base interpretation honors gates.preApproval.requireCi:false (#1337).
  * @returns {{ state: string, allowedTransitions: string[], nextAction: string, steeringApplied: boolean, pendingStopAtNextSafeGate: boolean, terminalStopAtNextSafeGate: boolean, effectiveConstraints: object }}
  */
-export function resolveEffectiveLoopState(snapshot, steeringState) {
-  const base = interpretLoopState(snapshot);
+export function resolveEffectiveLoopState(snapshot, steeringState, refinementConfig) {
+  const base = interpretLoopState(snapshot, refinementConfig);
   const constraints = getEffectiveConstraints(steeringState);
   const category = classifySafePoint(base.state);
 

package/src/loop/ui-review-drive.mjs

@@ -26,6 +26,16 @@
 
 const MUST_FIX = "must-fix";
 
+/** Request header the drive advertises its drive-session id on, so a cooperating
+ * app can tag the dev-DB rows a create/edit/upload persists during the walk.
+ * Stage-5 teardown deletes exactly those tagged rows from an emitted manifest. */
+export const DRIVE_SESSION_HEADER = "X-UI-Review-Drive-Session";
+
+/** Step actions that can persist dev-DB state (a create/edit/reorder/upload/
+ * toggle). `goto` is navigation and `fill` only types into a field before a
+ * submit, so neither is recorded as a row-creating mutation in the manifest. */
+const MUTATING_ACTIONS = new Set(["click", "select", "upload", "dispatch"]);
+
 /** The one owner of the error-response threshold: an error response is anything
  * outside 2xx/3xx. 3xx redirects are normal navigation (login/canonical), not
  * errors, so they are not flagged. Shared by the CLI listener's pre-filter (for
@@ -36,8 +46,9 @@ export function isErrorResponseStatus(status) {
 
 /** Bound the stack text carried onto a page-error failure so a runaway stack
  * (or a synthetic error with a huge stack) can't bloat the feed envelope. Keeps
- * the head — the top frames, where the throwing file:line sits. */
-const PAGE_ERROR_STACK_MAX_CHARS = 4000;
+ * the head — the top frames, where the throwing file:line sits. Exported so the
+ * per-state console.json shaping clamps to the SAME bound as the mechanical feed. */
+export const PAGE_ERROR_STACK_MAX_CHARS = 4000;
 
 /** Lines of context to preserve on each side of a matching server-log line, so
  * the traceback frames that carry file:line (often on adjacent, non-matching
@@ -211,6 +222,9 @@ export function classifyFailures({
  * @param {object} input
  * @param {string} input.appUrl - The arbitrary running-app URL from Stage 1.
  * @param {object} input.login - Resolved dev-login recipe (loginUrl + selectors).
+ * @param {string|null} [input.driveSession] - Unique id advertised to the app on
+ *   DRIVE_SESSION_HEADER; stamps the emitted row manifest so Stage-5 teardown can
+ *   drop exactly the rows a mutating step created. Null => no manifest is emitted.
  * @param {object[]} [input.flows] - Allowlisted changed-flow definitions.
  * @param {object[]} [input.interstitials] - Config-declared dismiss selectors.
  * @param {string[]} [input.changedPaths] - Changed file paths (drives selection).
@@ -226,7 +240,7 @@ export function classifyFailures({
  * @returns {Promise<object>} Result envelope (steps, captures, failures, caps, logs).
  */
 export async function driveUiReview(
-  { appUrl, login, flows = [], interstitials = [], changedPaths = [], serverLogExceptionPattern, caps = {} },
+  { appUrl, login, flows = [], interstitials = [], changedPaths = [], serverLogExceptionPattern, caps = {}, driveSession = null },
   {
     authenticate,
     dismissInterstitials = async () => ({ dismissed: [] }),
@@ -245,7 +259,8 @@ export async function driveUiReview(
   // No-retry is a fixed policy — log it every run so the bound is never implicit.
   record(`caps: maxScreenshots=${resolvedCaps.maxScreenshots}, maxFlows=${resolvedCaps.maxFlows}, maxStepsPerFlow=${resolvedCaps.maxStepsPerFlow}, retries=${resolvedCaps.retries} (no-retry)`);
 
-  const base = () => ({ appUrl: appUrl ?? null, logs });
+  const session = typeof driveSession === "string" && driveSession.trim().length > 0 ? driveSession.trim() : null;
+  const base = () => ({ appUrl: appUrl ?? null, logs, driveSession: session });
 
   // 1. Authenticate as the target role. Fail closed: no session -> STOP, drive
   //    nothing (a review that never reached the app is worthless, not empty).
@@ -261,6 +276,7 @@ export async function driveUiReview(
       captures: [],
       failures: [{ kind: "auth-failed", severity: MUST_FIX, message: stopReason }],
       caps: resolvedCaps,
+      rowManifest: [],
       ...base(),
     };
   }
@@ -280,6 +296,10 @@ export async function driveUiReview(
   //    moves on — deterministic, bounded, never re-run.
   const steps = [];
   const captures = [];
+  // Row manifest: one session-tagged record per mutating step driven, so Stage-5
+  // teardown can drop exactly the dev-DB rows this walk created. Only built when a
+  // session is present (no session => nothing to tag => no manifest to drop).
+  const rowManifest = [];
   let screenshots = 0;
   let screensSkipped = 0;
   for (const flow of selected) {
@@ -313,6 +333,9 @@ export async function driveUiReview(
       };
       steps.push(entry);
       if (entry.screenshotPath) captures.push({ flow: flow.name, step: entry.step, screenshotPath: entry.screenshotPath, statePath: entry.statePath });
+      if (session && MUTATING_ACTIONS.has(step.action)) {
+        rowManifest.push({ session, flow: flow.name, step: entry.step, action: step.action });
+      }
       if (!ok) record(`step failed (no retry): ${flow.name} / ${entry.step}: ${entry.detail ?? "unknown"}`);
     }
   }
@@ -343,6 +366,7 @@ export async function driveUiReview(
     failures,
     caps: resolvedCaps,
     screensSkipped,
+    rowManifest,
     ...base(),
   };
 }

package/src/loop/ui-review-report.mjs

@@ -12,8 +12,9 @@
  *   - a self-contained, CSP-safe HTML artifact string (ranked findings + inline
  *     screenshot evidence), and
  *   - a harness-aware hosting directive (Claude Code -> a publishable Artifacts
- *     directive for the orchestrator; any other harness -> fail closed with a
- *     stated reason and a follow-up marker — no hosted link this stage).
+ *     directive for the orchestrator; any other harness -> a GitHub-native
+ *     gist-publish directive the CLI executes, which yields a real per-run URL
+ *     or fails closed with a stated reason — never a fake link).
  *
  * All IO (reading the diagnose output + the screenshot bytes, writing the HTML,
  * invoking the poster) lives in the thin CLI. This module reads only its inputs.
@@ -22,9 +23,6 @@
 import { isClaudeHarness } from "./run-context.mjs";
 import { sanitizeCopilotSummonTokens } from "../github/copilot-helpers.mjs";
 
-/** Follow-up marker for the descoped GitHub-native hosting fallback. */
-export const HOSTING_FOLLOWUP = "#1285";
-
 /** Findings past this cap are dropped from the artifact and the drop is logged. */
 export const ARTIFACT_MAX_FINDINGS = 100;
 
@@ -105,9 +103,11 @@ export function severityToEvent({ findings = [], submitAuthorized = false } = {}
 /**
  * Harness-aware hosting directive (pure). Claude Code -> a publishable Artifacts
  * directive for the orchestrator to host (this module never calls an agent tool
- * itself). Any other harness / Artifacts unavailable -> fail closed with a
- * stated reason and the follow-up marker. The self-contained HTML is produced
- * regardless; only this link step is harness-aware.
+ * itself). Any other harness -> the portable GitHub-native default: publish the
+ * self-contained HTML as a secret GitHub Gist (a real per-run URL, zero repo
+ * pollution). This module decides the STRATEGY only; the CLI performs the gist
+ * publish IO and fails closed with a stated reason if it does not yield a URL.
+ * The self-contained HTML is produced regardless; only this link step differs.
  *
  * @param {{htmlPath: string, env?: Record<string,string|undefined>}} input
  */
@@ -115,13 +115,7 @@ export function decideHosting({ htmlPath, env = process.env } = {}) {
   if (isClaudeHarness(env)) {
     return { hosting: "claude-artifact", publishable: true, htmlPath: htmlPath ?? null };
   }
-  return {
-    hosting: "unavailable",
-    publishable: false,
-    htmlPath: htmlPath ?? null,
-    reason: "no hosted-artifact publisher on this harness; GitHub-native fallback is deferred",
-    followup: HOSTING_FOLLOWUP,
-  };
+  return { hosting: "github-gist", publishable: true, htmlPath: htmlPath ?? null };
 }
 
 /** One review-body line describing where the screenshot artifact lives. Links a
@@ -129,14 +123,22 @@ export function decideHosting({ htmlPath, env = process.env } = {}) {
  * the review never blocks on hosting. */
 function artifactBodyLine({ hosting, hostedUrl }) {
   if (typeof hostedUrl === "string" && hostedUrl.length > 0) {
+    // Only an ACTUALLY-published gist gets the source-rendered caveat: an explicit
+    // --hosted-url override leaves the strategy as github-gist but sets no gist, so
+    // a self-hosted (maybe live-rendered) URL falls through to the neutral line.
+    const rawUrl = hosting?.gist?.rawUrl;
+    if (rawUrl) {
+      // A gist renders HTML as source, not a live page; the raw file is the
+      // download/plain-text view — surface it so "open raw" is actually actionable.
+      return `Screenshot artifact (GitHub Gist — renders as source; open the raw file to view/download the HTML): ${hostedUrl} (raw: ${rawUrl})`;
+    }
     return `Screenshot artifact: ${hostedUrl}`;
   }
   if (hosting?.hosting === "claude-artifact") {
     return "Screenshot artifact prepared for Claude Artifacts hosting (published by the harness; see run output).";
   }
   const reason = hosting?.reason ? ` (${hosting.reason})` : "";
-  const followup = hosting?.followup ? ` [follow-up ${hosting.followup}]` : "";
-  return `Screenshot artifact is unhosted this stage${reason}${followup}. Findings are included below.`;
+  return `Screenshot artifact is unhosted this stage${reason}. Findings are included below.`;
 }
 
 /** A finding is inlineable ONLY with a complete anchor buildDraftReviewPayload