@dev-loops/core 0.7.2 → 0.9.0

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

@@ -0,0 +1,287 @@
+/**
+ * Report for the ui_review route (Stage 4, terminal reporting stage).
+ *
+ * Pure decision layer. Maps the Stage-3 ranked findings into:
+ *   - a pending draft-review input (consumed by buildDraftReviewPayload — the
+ *     shared poster's contract: {path,line,body,side:RIGHT} inline comments, no
+ *     `event`), with anchorable findings inlined on their exact diff anchors and
+ *     non-anchorable findings retained in the review body,
+ *   - a severity->event policy (a confirmed user-facing server error maps to
+ *     REQUEST_CHANGES ONLY when the caller authorizes submit; otherwise the
+ *     review stays pending with the severity recorded — never auto-submit),
+ *   - 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).
+ *
+ * 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.
+ */
+
+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;
+
+/** A screenshot whose data URI exceeds this is omitted from the artifact (logged). */
+export const ARTIFACT_MAX_SCREENSHOT_BYTES = 4 * 1024 * 1024;
+
+/** The drive kinds that count as a confirmed user-facing server error. Both are
+ * must-fix in the drive's classification: an error response the app returned and
+ * a server-log exception the request raised. */
+const SERVER_ERROR_KINDS = new Set(["error-response", "server-log-exception"]);
+
+function normalizeSha(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+/** A confirmed user-facing server error: a must-fix error-response / server-log
+ * exception. This is the single-source predicate the severity policy keys off. */
+function isBlockingFinding(finding) {
+  return finding?.severity === "must-fix" && SERVER_ERROR_KINDS.has(finding?.kind);
+}
+
+/** Render a finding's reproduced exception as one line, falling back to its
+ * message when the drive captured no parseable exception. */
+function reproducedLine(finding) {
+  const type = finding?.exception?.type;
+  const message = finding?.exception?.message;
+  if (typeof type === "string" && type.length > 0) {
+    return message ? `${type}: ${message}` : type;
+  }
+  return typeof finding?.message === "string" && finding.message.length > 0
+    ? finding.message
+    : "Captured failure (no exception detail)";
+}
+
+/** A short, kind-specific fix direction. Deliberately generic — the goal is to
+ * point the author at the changed line, not to prescribe the patch. */
+function fixDirection(kind) {
+  switch (kind) {
+    case "error-response":
+      return "Fix the request path so it no longer returns an error response.";
+    case "server-log-exception":
+    case "page-error":
+      return "Guard the throwing code path; the exception above was raised here.";
+    case "request-failed":
+      return "The request from this change failed at the wire; verify the endpoint/URL.";
+    default:
+      return "Address the reproduced failure on this changed line.";
+  }
+}
+
+/** Inline-comment body for an anchorable finding: reproduced exception + fix direction. */
+export function formatInlineBody(finding) {
+  return `Reproduced in the running app: ${reproducedLine(finding)}\nFix direction: ${fixDirection(finding?.kind)}`;
+}
+
+/**
+ * Severity->event policy (pure). A confirmed user-facing server error maps to
+ * REQUEST_CHANGES ONLY when submit is authorized; otherwise the review stays
+ * pending (event null) with the severity recorded. Never auto-submits.
+ *
+ * @param {{findings?: object[], submitAuthorized?: boolean}} [input]
+ * @returns {{event: "REQUEST_CHANGES"|null, blocking: boolean, submitAuthorized: boolean, severity: string}}
+ */
+export function severityToEvent({ findings = [], submitAuthorized = false } = {}) {
+  const list = Array.isArray(findings) ? findings : [];
+  const blocking = list.some(isBlockingFinding);
+  const severity = blocking
+    ? "must-fix"
+    : (list.some((f) => f?.severity === "must-fix") ? "must-fix" : (list.length > 0 ? "note" : "none"));
+  return {
+    event: submitAuthorized && blocking ? "REQUEST_CHANGES" : null,
+    blocking,
+    submitAuthorized: Boolean(submitAuthorized),
+    severity,
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {{htmlPath: string, env?: Record<string,string|undefined>}} input
+ */
+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,
+  };
+}
+
+/** One review-body line describing where the screenshot artifact lives. Links a
+ * real hosted URL when one exists; otherwise states the harness-aware status so
+ * the review never blocks on hosting. */
+function artifactBodyLine({ hosting, hostedUrl }) {
+  if (typeof hostedUrl === "string" && hostedUrl.length > 0) {
+    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.`;
+}
+
+/** A finding is inlineable ONLY with a complete anchor buildDraftReviewPayload
+ * will keep: a non-blank path and a line > 0 (exactly the payload's inline
+ * filter), side RIGHT. A finding flagged anchorable but carrying a
+ * malformed/incomplete anchor (blank path, line <= 0) falls back to the body
+ * (summaryFindings) instead of being dropped by the payload's inline filter. */
+function hasValidAnchor(finding) {
+  const a = finding?.anchor;
+  return Boolean(
+    finding?.anchorable &&
+    a &&
+    typeof a.path === "string" && a.path.trim().length > 0 &&
+    typeof a.line === "number" && a.line > 0 &&
+    a.side === "RIGHT"
+  );
+}
+
+/** Body line for a non-anchorable finding: it is kept, never dropped. */
+function nonAnchorableBodyMessage(finding) {
+  const reason = finding?.nonAnchorableReason ? ` — not inlined: ${finding.nonAnchorableReason}` : "";
+  return `${reproducedLine(finding)}${reason}`;
+}
+
+/**
+ * Map Stage-3 findings + hosting status into the merged-result input that the
+ * shared buildDraftReviewPayload consumes. Anchorable findings become inline
+ * comments on their exact {path,line,side:RIGHT} anchors; the artifact line and
+ * every non-anchorable finding are retained as summary (body) findings.
+ *
+ * @param {{findings?: object[], headSha?: string|null, hosting?: object, hostedUrl?: string}} input
+ */
+export function buildReviewInput({ findings = [], headSha = null, hosting = null, hostedUrl = null } = {}) {
+  const list = Array.isArray(findings) ? findings : [];
+  const anchorable = list.filter(hasValidAnchor);
+  const nonAnchorable = list.filter((f) => !hasValidAnchor(f));
+
+  // Untrusted target-app text (exception type/message, log lines, nonAnchorableReason)
+  // flows into these bodies. Sanitize copilot-summon tokens before they enter the
+  // payload buildDraftReviewPayload posts verbatim — every sibling posting path does.
+  const inlineComments = anchorable.map((f) => ({
+    path: f.anchor.path,
+    line: f.anchor.line,
+    message: sanitizeCopilotSummonTokens(formatInlineBody(f)),
+    severity: f.severity ?? "note",
+  }));
+
+  const summaryFindings = [
+    { message: sanitizeCopilotSummonTokens(artifactBodyLine({ hosting, hostedUrl })), severity: "note" },
+    ...nonAnchorable.map((f) => ({ message: sanitizeCopilotSummonTokens(nonAnchorableBodyMessage(f)), severity: f.severity ?? "note" })),
+  ];
+
+  const blocking = list.some(isBlockingFinding);
+  const verdict = list.length === 0 ? "APPROVE" : (blocking ? "REQUEST_CHANGES" : "COMMENT");
+
+  return {
+    headSha: normalizeSha(headSha),
+    verdict,
+    inlineComments,
+    summaryFindings,
+    totalFindings: list.length,
+    runsMerged: 0,
+  };
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/gu, (c) => (
+    { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]
+  ));
+}
+
+const ARTIFACT_STYLE = [
+  "body{font:14px/1.5 system-ui,sans-serif;margin:0;padding:24px;color:#1a1a1a;background:#fafafa}",
+  "h1{font-size:20px;margin:0 0 4px}",
+  ".meta{color:#666;margin-bottom:20px}",
+  ".finding{border:1px solid #ddd;border-radius:6px;padding:12px 16px;margin:0 0 12px;background:#fff}",
+  ".finding.blocking{border-left:4px solid #c0392b}",
+  ".finding.note{border-left:4px solid #999}",
+  ".sev{font-weight:600;text-transform:uppercase;font-size:11px;letter-spacing:.05em}",
+  ".anchor{color:#2c3e50;font-family:ui-monospace,monospace;font-size:12px}",
+  ".exc{font-family:ui-monospace,monospace;white-space:pre-wrap;margin:6px 0}",
+  ".reason{color:#c0392b;font-size:12px}",
+  "img{max-width:100%;border:1px solid #ddd;border-radius:4px;margin-top:12px}",
+].join("");
+
+const ARTIFACT_CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'";
+
+/**
+ * Build the self-contained, CSP-safe HTML artifact (ranked findings + inline
+ * screenshot evidence). Fully inlined: no external scripts/styles/fonts/images.
+ * Bounded caps (findings past ARTIFACT_MAX_FINDINGS, an oversized screenshot)
+ * are applied here and returned in `caps` so the CLI can log them — never a
+ * silent truncation.
+ *
+ * @param {{findings?: object[], counts?: object, pr?: object, screenshot?: {path:string,dataUri:string}|null, generatedAt?: string}} input
+ * @returns {{html: string, caps: string[]}}
+ */
+export function buildArtifactHtml({ findings = [], counts = {}, pr = {}, screenshot = null, generatedAt } = {}) {
+  const caps = [];
+  const list = Array.isArray(findings) ? findings : [];
+
+  let shown = list;
+  if (list.length > ARTIFACT_MAX_FINDINGS) {
+    shown = list.slice(0, ARTIFACT_MAX_FINDINGS);
+    caps.push(`artifact: findings truncated to ${ARTIFACT_MAX_FINDINGS} of ${list.length} (${list.length - ARTIFACT_MAX_FINDINGS} not rendered)`);
+  }
+
+  let screenshotHtml = "";
+  if (screenshot && typeof screenshot.dataUri === "string") {
+    if (screenshot.dataUri.length > ARTIFACT_MAX_SCREENSHOT_BYTES) {
+      caps.push(`artifact: screenshot omitted (${screenshot.dataUri.length} bytes > ${ARTIFACT_MAX_SCREENSHOT_BYTES} cap): ${screenshot.path ?? "unknown"}`);
+    } else {
+      screenshotHtml = `<h2>Reproduced evidence</h2><img alt="reproduced state" src="${escapeHtml(screenshot.dataUri)}" />`;
+    }
+  }
+
+  const findingsHtml = shown.map((f) => {
+    const blocking = isBlockingFinding(f);
+    const cls = blocking ? "blocking" : "note";
+    const anchor = f?.anchor
+      ? `<div class="anchor">${escapeHtml(f.anchor.path)}:${escapeHtml(f.anchor.line)} (${escapeHtml(f.anchor.side)})</div>`
+      : `<div class="reason">not inlined: ${escapeHtml(f?.nonAnchorableReason ?? "no anchor")}</div>`;
+    return [
+      `<div class="finding ${cls}">`,
+      `<div class="sev">${escapeHtml(f?.severity ?? "note")} · ${escapeHtml(f?.kind ?? "finding")}</div>`,
+      `<div class="exc">${escapeHtml(reproducedLine(f))}</div>`,
+      anchor,
+      "</div>",
+    ].join("");
+  }).join("");
+
+  const total = Number.isFinite(counts?.total) ? counts.total : list.length;
+  const html = [
+    "<!doctype html>",
+    '<html lang="en"><head><meta charset="utf-8" />',
+    `<meta http-equiv="Content-Security-Policy" content="${ARTIFACT_CSP}" />`,
+    "<title>UI review findings</title>",
+    `<style>${ARTIFACT_STYLE}</style>`,
+    "</head><body>",
+    `<h1>UI review findings — PR #${escapeHtml(pr?.number ?? "?")}</h1>`,
+    `<div class="meta">head ${escapeHtml(pr?.headSha ?? "?")} · ${escapeHtml(total)} finding(s) · ${escapeHtml(counts?.anchorable ?? 0)} anchorable · generated ${escapeHtml(generatedAt ?? "")}</div>`,
+    findingsHtml,
+    screenshotHtml,
+    "</body></html>",
+  ].join("");
+
+  return { html, caps };
+}

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

@@ -0,0 +1,250 @@
+/**
+ * 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
+ * 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
+ * is ever silently orphaned, whether teardown succeeds, is skipped, or partially
+ * fails.
+ *
+ * Two safety rails:
+ *   - Destructive steps (row drops, worktree removal) run ONLY on explicit
+ *     confirmation. Without it the destructive steps are skipped and the ledger
+ *     records what remains. Stopping the app is a clean shutdown of a process
+ *     the loop itself started, not a destructive mutation of persisted state, so
+ *     it runs regardless of confirmation.
+ *   - A failed kill/drop/removal is REPORTED in the ledger and the result's
+ *     errors list, never swallowed.
+ *
+ * This module is PURE orchestration: the process kill, the row drop, and the
+ * worktree removal are injected seams so it is fully testable without real side
+ * effects. The thin CLI wires the real ones.
+ *
+ * Non-goals (explicit): NO rollback of the branch's dev-DB migrations by default
+ * (they were applied to a dev DB; reversal is a separate explicit action — the
+ * ledger records they were applied, not reverted). NO production teardown.
+ */
+
+/**
+ * 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.
+ */
+
+const ROW_STATUS = Object.freeze({
+  DROPPED: "dropped",
+  DROP_FAILED: "drop-failed",
+  MAY_REMAIN_UNTAGGED: "may-remain-untagged",
+  SKIPPED_UNCONFIRMED: "skipped-unconfirmed",
+  NONE: "none",
+});
+
+const WORKTREE_STATUS = Object.freeze({
+  REMOVED: "removed",
+  REMOVE_FAILED: "remove-failed",
+  SKIPPED_UNCONFIRMED: "skipped-unconfirmed",
+  // No worktree path in the provision result at all. Distinct from
+  // SKIPPED_UNCONFIRMED (which is the confirmation gate) so the ledger says WHY
+  // removal did not run — a missing path, not a withheld confirmation.
+  MISSING_PATH: "missing-path",
+});
+
+const PROCESS_STATUS = Object.freeze({
+  STOPPED: "stopped",
+  KILL_FAILED: "kill-failed",
+  MAY_BE_RUNNING: "may-be-running",
+  SKIPPED: "skipped",
+});
+
+/**
+ * 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
+ * create/edit/upload interactions, so rows may have been created. A drive that
+ * stopped before driving anything (e.g. auth failure) created nothing.
+ */
+function driveMayHaveCreatedRows(driveResult) {
+  if (!driveResult || driveResult.stopped) return false;
+  return Array.isArray(driveResult.steps) && driveResult.steps.length > 0;
+}
+
+/**
+ * Run the teardown sequence and always return a result carrying the side-effect
+ * ledger.
+ *
+ * @param {object} input
+ * @param {object} input.provisionResult - Stage-1 result: `boot.pid` (app PID),
+ *   `migrations` (applied count/detail), and `worktreePath`.
+ * @param {object|null} [input.driveResult] - Stage-2 result: the rows-created
+ *   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 {boolean} [input.confirm] - Explicit authorization for the destructive
+ *   steps (row drop, worktree removal). 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
+ * @param {(a:{pid:number})=>Promise<{stopped:boolean,forced:boolean,detail:string,mayBeRunning?:boolean}>} seams.killProcess
+ *   `mayBeRunning:true` marks a NOT-ATTEMPTED outcome (e.g. win32, where process-group
+ *   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 {(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 = () => {} } = {},
+) {
+  const logs = [];
+  const errors = [];
+  const record = (msg) => {
+    logs.push(msg);
+    log(msg);
+  };
+  const fail = (msg) => {
+    errors.push(msg);
+    record(msg);
+  };
+
+  const provision = provisionResult ?? {};
+  // `worktreePath` is read from disk (trust boundary). A non-string (number,
+  // object, array) must never reach `removeWorktree` — the CLI's cleanup path
+  // calls `path.resolve(worktreePath)`, which throws on a non-string, breaking
+  // the always-emit-ledger invariant. Coerce to a usable string or null here.
+  const rawWorktreePath = provision.worktreePath ?? null;
+  const worktreePath = typeof rawWorktreePath === "string" ? rawWorktreePath : null;
+  const worktreePathMalformed = rawWorktreePath != null && typeof rawWorktreePath !== "string";
+  const pid = provision.boot?.pid ?? null;
+  const migrations = provision.migrations ?? { applied: 0, pending: 0, destructive: [], detail: "no provision migrations" };
+
+  // 1. Stop the app (clean shutdown; NOT confirmation-gated). Uses the Stage-1
+  //    boot PID. A missing OR unusable PID means we cannot stop it — the ledger
+  //    reports it may still be running rather than guessing. `boot.pid` is read
+  //    from disk (trust boundary), so anything that is not a positive integer
+  //    (0, negative, NaN, float, string) is rejected here: passing it to the
+  //    kill seam would let the CLI's process-group kill signal `process.kill(0)`
+  //    (this loop's OWN group) or `process.kill(-1)` (every process).
+  const usablePid = Number.isInteger(pid) && pid > 0;
+  let processLedger;
+  if (!stopApp) {
+    processLedger = { pid: usablePid ? pid : null, status: PROCESS_STATUS.SKIPPED, forced: false, detail: "app stop skipped by request" };
+    record(`app stop skipped (pid ${usablePid ? pid : "n/a"})`);
+  } else if (!usablePid) {
+    const detail = pid == null
+      ? "no PID captured from Stage 1; process may still be running"
+      : "no usable PID from Stage 1 (not a positive integer); process may still be running";
+    processLedger = { pid: null, status: PROCESS_STATUS.MAY_BE_RUNNING, forced: false, detail };
+    record(`app stop: ${detail}`);
+  } else {
+    // A seam that THROWS must still yield a fully-emitted ledger: catch it,
+    // record KILL_FAILED, and press on. The always-emit invariant holds even
+    // when a real IO seam rejects.
+    try {
+      const kill = await killProcess({ pid });
+      if (kill.stopped) {
+        processLedger = { pid, status: PROCESS_STATUS.STOPPED, forced: !!kill.forced, detail: kill.detail };
+        record(`app stopped (pid ${pid})${kill.forced ? " [force-killed: SIGKILL fallback]" : ""}: ${kill.detail}`);
+      } else if (kill.mayBeRunning) {
+        // The kill was NOT ATTEMPTED (e.g. win32 process-group signalling is
+        // unsupported) — this is a "couldn't stop", not a failed attempt, so it
+        // is non-fatal (matches the null-PID may-be-running treatment): the
+        // ledger reports the app may still be running and `ok` is left intact.
+        processLedger = { pid, status: PROCESS_STATUS.MAY_BE_RUNNING, forced: !!kill.forced, detail: kill.detail };
+        record(`app stop: ${kill.detail}`);
+      } else {
+        processLedger = { pid, status: PROCESS_STATUS.KILL_FAILED, forced: !!kill.forced, detail: kill.detail };
+        fail(`app stop FAILED (pid ${pid}): ${kill.detail}`);
+      }
+    } catch (err) {
+      processLedger = { pid, status: PROCESS_STATUS.KILL_FAILED, forced: false, detail: `kill seam threw: ${err?.message ?? err}` };
+      fail(`app stop FAILED (pid ${pid}): kill seam threw: ${err?.message ?? err}`);
+    }
+  }
+
+  // 2. Drop dev-DB rows — DESTRUCTIVE, confirmation-gated, dev DB only. Only ever
+  //    drops an explicit manifest; never guesses untagged rows (see file header).
+  const hasManifest = Array.isArray(rowManifest) && rowManifest.length > 0;
+  let rowsLedger;
+  if (!confirm) {
+    if (hasManifest) {
+      rowsLedger = { status: ROW_STATUS.SKIPPED_UNCONFIRMED, dropped: 0, candidates: rowManifest.length, detail: `${rowManifest.length} row(s) NOT dropped: teardown not confirmed` };
+      record(`row drop skipped (not confirmed): ${rowManifest.length} manifest row(s) remain`);
+    } else if (driveMayHaveCreatedRows(driveResult)) {
+      rowsLedger = { status: ROW_STATUS.MAY_REMAIN_UNTAGGED, dropped: 0, candidates: 0, detail: "rows may remain (untagged): drive created rows but no session tag/manifest to target them, and teardown not confirmed" };
+      record("row drop skipped: rows may remain (untagged)");
+    } else {
+      rowsLedger = { status: ROW_STATUS.NONE, dropped: 0, candidates: 0, detail: "no rows created (drive drove no mutating steps)" };
+    }
+  } else if (hasManifest) {
+    try {
+      const drop = await dropRows({ rows: rowManifest });
+      if (drop.ok) {
+        rowsLedger = { status: ROW_STATUS.DROPPED, dropped: drop.dropped ?? rowManifest.length, candidates: rowManifest.length, detail: drop.detail };
+        record(`dev-DB rows dropped: ${drop.dropped ?? rowManifest.length} (${drop.detail})`);
+      } else {
+        rowsLedger = { status: ROW_STATUS.DROP_FAILED, dropped: drop.dropped ?? 0, candidates: rowManifest.length, detail: drop.detail };
+        fail(`dev-DB row drop FAILED: ${drop.detail}`);
+      }
+    } catch (err) {
+      rowsLedger = { status: ROW_STATUS.DROP_FAILED, dropped: 0, candidates: rowManifest.length, detail: `drop seam threw: ${err?.message ?? err}` };
+      fail(`dev-DB row drop FAILED: drop seam threw: ${err?.message ?? err}`);
+    }
+  } else if (driveMayHaveCreatedRows(driveResult)) {
+    // Confirmed, but nothing to target: honesty over a guess-drop.
+    rowsLedger = { status: ROW_STATUS.MAY_REMAIN_UNTAGGED, dropped: 0, candidates: 0, detail: "rows may remain (untagged): drive created rows but no session tag/manifest to target them; refusing to guess which rows to drop" };
+    record("row drop: rows may remain (untagged) — no manifest to target, not guessing");
+  } else {
+    rowsLedger = { status: ROW_STATUS.NONE, dropped: 0, candidates: 0, detail: "no rows created (drive drove no mutating steps)" };
+  }
+
+  // 3. Remove the worktree — DESTRUCTIVE, confirmation-gated. Delegated to the
+  //    shared cleanup path, which refuses anything outside the loop namespace.
+  let worktreeLedger;
+  if (worktreePathMalformed) {
+    worktreeLedger = { path: null, removed: false, status: WORKTREE_STATUS.REMOVE_FAILED, detail: `malformed worktree path in provision result (not a string): ${typeof rawWorktreePath}` };
+    fail(`worktree removal FAILED: malformed worktree path in provision result (not a string): ${typeof rawWorktreePath}`);
+  } else if (!worktreePath) {
+    worktreeLedger = { path: null, removed: false, status: WORKTREE_STATUS.MISSING_PATH, detail: "no worktree path in provision result" };
+    record("worktree removal skipped: no worktree path in provision result");
+  } else if (!confirm) {
+    worktreeLedger = { path: worktreePath, removed: false, status: WORKTREE_STATUS.SKIPPED_UNCONFIRMED, detail: "worktree retained: teardown not confirmed" };
+    record(`worktree removal skipped (not confirmed): ${worktreePath} retained`);
+  } else {
+    try {
+      const rm = await removeWorktree({ worktreePath });
+      if (rm.removed) {
+        worktreeLedger = { path: worktreePath, removed: true, status: WORKTREE_STATUS.REMOVED, detail: rm.detail };
+        record(`worktree removed: ${worktreePath} (${rm.detail})`);
+      } else {
+        worktreeLedger = { path: worktreePath, removed: false, status: WORKTREE_STATUS.REMOVE_FAILED, detail: rm.detail };
+        fail(`worktree removal FAILED: ${worktreePath} (${rm.detail})`);
+      }
+    } catch (err) {
+      worktreeLedger = { path: worktreePath, removed: false, status: WORKTREE_STATUS.REMOVE_FAILED, detail: `removeWorktree seam threw: ${err?.message ?? err}` };
+      fail(`worktree removal FAILED: ${worktreePath} (removeWorktree 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 = {
+    confirmed: confirm,
+    migrations: {
+      applied: migrations.applied ?? 0,
+      reverted: false,
+      detail: migrations.detail ?? null,
+      note: "not reverted (dev DB; migration reversal is a separate explicit action)",
+    },
+    rows: rowsLedger,
+    worktree: worktreeLedger,
+    process: processLedger,
+  };
+
+  return { ok: errors.length === 0, confirmed: confirm, ledger, errors, logs };
+}
+
+export { ROW_STATUS, WORKTREE_STATUS, PROCESS_STATUS };