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

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

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

@@ -2,7 +2,7 @@
  * Teardown + side-effect ledger orchestrator for the ui_review route (Stage 5).
  *
  * Terminal cleanup for a running-app review: stop the app booted in Stage 1,
- * drop the dev-DB rows the Stage-2 drive created, and remove the provisioned
+ * drop the dev-DB rows the Stage-2 drive tagged, and remove the provisioned
  * worktree. The core safety property of this stage is that a side-effect ledger
  * is ALWAYS emitted — enumerating every migration applied, row created/dropped,
  * the worktree path, and any process left running — so nothing the loop touched
@@ -28,11 +28,12 @@
  */
 
 /**
- * The honest row-drop reality: Stage 2 does NOT tag the dev-DB rows it creates
- * with a session id or row manifest. So unless an explicit row manifest is
- * handed in (and confirmed), this stage CANNOT know which rows to drop and MUST
- * NOT guess. When the drive ran mutating flows without a manifest, the ledger
- * reports rows "may remain (untagged)" rather than dropping anything.
+ * Row-drop model: Stage 2 stamps each mutating step with a drive-session id and
+ * emits a session-tagged row manifest. Given that manifest (and confirmation),
+ * this stage drops exactly the rows tagged with that session. Only the fallback
+ * case — a drive that mutated but handed in no manifest — CANNOT know which rows
+ * to drop and MUST NOT guess: the ledger reports rows "may remain (untagged)"
+ * rather than dropping anything.
  */
 
 const ROW_STATUS = Object.freeze({
@@ -60,6 +61,13 @@ const PROCESS_STATUS = Object.freeze({
   SKIPPED: "skipped",
 });
 
+const GIST_STATUS = Object.freeze({
+  DELETED: "deleted",
+  DELETE_FAILED: "delete-failed",
+  SKIPPED_UNCONFIRMED: "skipped-unconfirmed",
+  NONE: "none",
+});
+
 /**
  * Did the Stage-2 drive potentially create dev-DB rows? Without row tagging this
  * is a coarse but honest signal: a drive that actually walked steps exercised
@@ -82,8 +90,12 @@ function driveMayHaveCreatedRows(driveResult) {
  *   signal (whether the drive walked mutating steps). Null when no drive ran.
  * @param {Array<object>|null} [input.rowManifest] - Explicit rows to drop, when
  *   a session tag/manifest is available. Absent/empty => untagged fallback.
+ * @param {{id?:string|null,url?:string|null}|null} [input.gist] - The Stage-4
+ *   GitHub-native hosting artifact (a secret gist) to prune, when one was
+ *   published off-Claude. Absent => nothing to prune.
  * @param {boolean} [input.confirm] - Explicit authorization for the destructive
- *   steps (row drop, worktree removal). Fail-safe: absent means NOT confirmed.
+ *   steps (row drop, worktree removal, gist deletion). Fail-safe: absent means
+ *   NOT confirmed.
  * @param {boolean} [input.stopApp] - Stop the Stage-1 app (default true). This is
  *   a clean shutdown, NOT gated on confirmation.
  * @param {object} seams
@@ -92,12 +104,14 @@ function driveMayHaveCreatedRows(driveResult) {
  *   signalling is unsupported) — mapped to MAY_BE_RUNNING (non-fatal), not KILL_FAILED.
  * @param {(a:{rows:Array<object>})=>Promise<{ok:boolean,dropped:number,detail:string}>} seams.dropRows
  * @param {(a:{worktreePath:string})=>Promise<{removed:string|null,ok:boolean,detail:string}>} seams.removeWorktree
+ * @param {(a:{id:string})=>Promise<{ok:boolean,detail:string}>} [seams.deleteGist] - Prune the
+ *   Stage-4 hosting gist. Only invoked when a gist id is present AND confirmed.
  * @param {(msg:string)=>void} [seams.log]
  * @returns {Promise<{ok:boolean,confirmed:boolean,ledger:object,errors:string[],logs:string[]}>}
  */
 export async function teardown(
-  { provisionResult, driveResult = null, rowManifest = null, confirm = false, stopApp = true },
-  { killProcess, dropRows, removeWorktree, log = () => {} } = {},
+  { provisionResult, driveResult = null, rowManifest = null, gist = null, confirm = false, stopApp = true },
+  { killProcess, dropRows, removeWorktree, deleteGist, log = () => {} } = {},
 ) {
   const logs = [];
   const errors = [];
@@ -229,6 +243,33 @@ export async function teardown(
     }
   }
 
+  // 4. Prune the Stage-4 hosting gist — DESTRUCTIVE, confirmation-gated. A gist
+  //    accretes one secret entry per run; deleting it keeps the hosting target
+  //    from piling up. Only ever acts on an explicit gist id from the report
+  //    result; a missing id is NONE (nothing published, or Claude-hosted).
+  const gistId = typeof gist?.id === "string" && gist.id.trim().length > 0 ? gist.id.trim() : null;
+  let gistLedger;
+  if (!gistId) {
+    gistLedger = { id: null, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.NONE, detail: "no hosting gist to prune" };
+  } else if (!confirm) {
+    gistLedger = { id: gistId, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.SKIPPED_UNCONFIRMED, detail: "hosting gist retained: teardown not confirmed" };
+    record(`gist prune skipped (not confirmed): ${gistId} retained`);
+  } else {
+    try {
+      const del = await deleteGist({ id: gistId });
+      if (del.ok) {
+        gistLedger = { id: gistId, url: gist?.url ?? null, deleted: true, status: GIST_STATUS.DELETED, detail: del.detail };
+        record(`hosting gist deleted: ${gistId} (${del.detail})`);
+      } else {
+        gistLedger = { id: gistId, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.DELETE_FAILED, detail: del.detail };
+        fail(`hosting gist delete FAILED: ${gistId} (${del.detail})`);
+      }
+    } catch (err) {
+      gistLedger = { id: gistId, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.DELETE_FAILED, detail: `deleteGist seam threw: ${err?.message ?? err}` };
+      fail(`hosting gist delete FAILED: ${gistId} (deleteGist seam threw: ${err?.message ?? err})`);
+    }
+  }
+
   // The ledger is ALWAYS emitted (every case), enumerating every known side
   // effect. Migrations are recorded as applied-not-reverted by design.
   const ledger = {
@@ -241,10 +282,11 @@ export async function teardown(
     },
     rows: rowsLedger,
     worktree: worktreeLedger,
+    gist: gistLedger,
     process: processLedger,
   };
 
   return { ok: errors.length === 0, confirmed: confirm, ledger, errors, logs };
 }
 
-export { ROW_STATUS, WORKTREE_STATUS, PROCESS_STATUS };
+export { ROW_STATUS, WORKTREE_STATUS, PROCESS_STATUS, GIST_STATUS };