@dev-loops/core 0.7.2 → 0.9.0

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

@@ -0,0 +1,348 @@
+/**
+ * Drive orchestrator for the ui_review route (Stage 2).
+ *
+ * Authenticates as the change's target role via a project-provided dev-login
+ * recipe, then walks the changed UI flows against the arbitrary running-app URL
+ * handed off by Stage 1 — rendering each page, exercising its declared
+ * interactions, and capturing an ordered set of step screenshots. While it
+ * drives, response/requestfailed/pageerror listeners and a server-log tail run
+ * so a swallowed error response (a 500 the UI hides) is still recorded.
+ *
+ * This module is PURE orchestration: all browser/page IO, the auth recipe, the
+ * interstitial dismissal, the per-step capture, the event collection, and the
+ * server-log tail are injected seams. The thin CLI/harness wires real Playwright
+ * (WebKit). The decision logic that lives here is: which flows to drive
+ * (a bounded changed-flow heuristic over an explicit allowlist), cap
+ * enforcement (max screenshots, screens skipped, no-retry) with explicit logs,
+ * and failure classification (collating error responses, request failures,
+ * page errors, and server-log exceptions into one structured list).
+ *
+ * Fail closed: a can't-authenticate condition STOPS with a stated reason and
+ * drives nothing. The structured captured-failures list feeds the next stage.
+ *
+ * Out of scope (later stages): exception -> source-line mapping, review
+ * posting, visual-regression/pixel-diffing, cross-browser matrix.
+ */
+
+const MUST_FIX = "must-fix";
+
+/** 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
+ * buffer bounding) and the classifier, so the policy has a single source. */
+export function isErrorResponseStatus(status) {
+  return typeof status === "number" && (status < 200 || status >= 400);
+}
+
+/** 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;
+
+/** 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
+ * lines) survive into the Stage 3 feed. */
+const SERVER_LOG_CONTEXT_LINES = 4;
+/** Char cap on the preserved server-log context window per failure entry. */
+const SERVER_LOG_CONTEXT_MAX_CHARS = 2000;
+
+/** Bounded caps. A project cannot raise these past the ceilings — the walker is
+ * a diagnostic pass over the changed flows, never an unbounded crawl. */
+export const DEFAULT_DRIVE_CAPS = Object.freeze({
+  maxScreenshots: 40,
+  maxFlows: 12,
+  maxStepsPerFlow: 20,
+  // No-retry is a fixed policy, not a tunable: a flaky step is a finding, not
+  // something to paper over by re-running. Logged explicitly on every run.
+  retries: 0,
+});
+
+/** Merge project caps onto the defaults, clamping each to its ceiling so a
+ * recipe can only tighten a cap, never loosen it past the diagnostic budget. */
+export function resolveCaps(caps = {}) {
+  const clamp = (v, ceiling) =>
+    Number.isInteger(v) && v >= 0 ? Math.min(v, ceiling) : ceiling;
+  return {
+    maxScreenshots: clamp(caps.maxScreenshots, DEFAULT_DRIVE_CAPS.maxScreenshots),
+    maxFlows: clamp(caps.maxFlows, DEFAULT_DRIVE_CAPS.maxFlows),
+    maxStepsPerFlow: clamp(caps.maxStepsPerFlow, DEFAULT_DRIVE_CAPS.maxStepsPerFlow),
+    retries: 0,
+  };
+}
+
+/**
+ * Changed-flow discovery: pick which allowlisted flows to drive.
+ *
+ * This is a DOCUMENTED HEURISTIC over an EXPLICIT allowlist, never an unbounded
+ * crawl. Each flow declares `pathPatterns` (plain substrings matched against the
+ * PR's changed file paths). A flow is in scope when any changed path contains
+ * any of its patterns. A flow with no `pathPatterns` is always in scope (the
+ * project opted it into every run). When `changedPaths` is empty/absent the diff
+ * is unknown, so every allowlisted flow is driven — the safe over-approximation.
+ * The selection is then capped at `caps.maxFlows`; the overflow is skipped and
+ * logged, never silently dropped.
+ *
+ * @returns {{ selected: object[], skipped: {name:string, reason:string}[] }}
+ */
+export function selectFlows({ flows = [], changedPaths = [], caps = DEFAULT_DRIVE_CAPS } = {}) {
+  const paths = Array.isArray(changedPaths) ? changedPaths : [];
+  const haveDiff = paths.length > 0;
+  const matched = [];
+  const skipped = [];
+  for (const flow of flows) {
+    const patterns = Array.isArray(flow.pathPatterns) ? flow.pathPatterns : [];
+    let inScope;
+    if (!haveDiff || patterns.length === 0) {
+      inScope = true; // unknown diff, or an always-on flow
+    } else {
+      inScope = patterns.some((p) => paths.some((cp) => cp.includes(p)));
+    }
+    if (inScope) matched.push(flow);
+    else skipped.push({ name: flow.name, reason: "no changed path matched its pathPatterns" });
+  }
+  const selected = matched.slice(0, caps.maxFlows);
+  for (const flow of matched.slice(caps.maxFlows)) {
+    skipped.push({ name: flow.name, reason: `maxFlows cap (${caps.maxFlows}) reached` });
+  }
+  return { selected, skipped };
+}
+
+/**
+ * Classify raw captured events + the server-log tail into one structured failure
+ * list. Pure. This is where a swallowed error response surfaces twice — once
+ * from the response listener and once from the server-log tail — so a 500 the UI
+ * hid is still recorded.
+ *
+ * @param {object} input
+ * @param {{url?:string,status:number}[]} [input.responses] - from page.on('response')
+ * @param {{url?:string,failure?:string}[]} [input.requestFailures] - from page.on('requestfailed')
+ * @param {{message?:string,stack?:string|null}[]} [input.pageErrors] - from page.on('pageerror'); `stack` (file:line) feeds Stage 3
+ * @param {string} [input.serverLogTail] - tail text of the project server log
+ * @param {string} [input.serverLogExceptionPattern] - regex (source) flagging a log exception line
+ * @returns {{kind:string, severity:string, message:string, [k:string]:unknown}[]}
+ */
+export function classifyFailures({
+  responses = [],
+  requestFailures = [],
+  pageErrors = [],
+  serverLogTail = "",
+  serverLogExceptionPattern,
+} = {}) {
+  const failures = [];
+
+  for (const r of responses) {
+    // A swallowed 500 lands here even when the page rendered a success state,
+    // because the listener sees the wire. The error-response threshold has one
+    // owner: isErrorResponseStatus.
+    if (isErrorResponseStatus(r.status)) {
+      failures.push({
+        kind: "error-response",
+        severity: MUST_FIX,
+        status: r.status,
+        url: r.url ?? null,
+        message: `error response ${r.status}${r.url ? ` at ${r.url}` : ""}`,
+      });
+    }
+  }
+
+  for (const f of requestFailures) {
+    failures.push({
+      kind: "request-failed",
+      severity: MUST_FIX,
+      url: f.url ?? null,
+      message: `request failed${f.url ? ` at ${f.url}` : ""}${f.failure ? `: ${f.failure}` : ""}`,
+    });
+  }
+
+  for (const e of pageErrors) {
+    // Carry the bounded stack so Stage 3's exception -> source-line mapping has
+    // the file:line signal; null when the listener captured no stack.
+    const stack = typeof e.stack === "string" && e.stack.length > 0 ? e.stack.slice(0, PAGE_ERROR_STACK_MAX_CHARS) : null;
+    failures.push({
+      kind: "page-error",
+      severity: MUST_FIX,
+      message: `uncaught page error: ${e.message ?? "(no message)"}`,
+      stack,
+    });
+  }
+
+  if (serverLogTail && serverLogExceptionPattern) {
+    // Config validates the pattern only on the CLI path; a direct caller can
+    // pass an invalid regex. Guard the compile so a bad pattern degrades to a
+    // surfaced note instead of throwing and breaking the whole drive envelope.
+    let re;
+    try {
+      re = new RegExp(serverLogExceptionPattern, "iu");
+    } catch (err) {
+      failures.push({
+        kind: "server-log-pattern-invalid",
+        severity: "note",
+        message: `server-log exception pattern is not a valid regex; skipped server-log classification: ${err?.message ?? String(err)}`,
+      });
+    }
+    if (re) {
+      const lines = serverLogTail.split("\n");
+      for (let i = 0; i < lines.length; i += 1) {
+        const trimmed = lines[i].trim();
+        if (trimmed.length > 0 && re.test(trimmed)) {
+          // Preserve the contiguous frames around the match: the file:line the
+          // traceback carries usually sits on adjacent, non-matching lines that
+          // the per-line match alone would drop. Bounded on both axes.
+          const from = Math.max(0, i - SERVER_LOG_CONTEXT_LINES);
+          const to = Math.min(lines.length, i + SERVER_LOG_CONTEXT_LINES + 1);
+          const context = lines.slice(from, to).join("\n").slice(0, SERVER_LOG_CONTEXT_MAX_CHARS);
+          failures.push({
+            kind: "server-log-exception",
+            severity: MUST_FIX,
+            message: `server log exception: ${trimmed.slice(0, 500)}`,
+            context,
+          });
+        }
+      }
+    }
+  }
+
+  return failures;
+}
+
+/**
+ * Run the auth + drive sequence over the changed flows.
+ *
+ * @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 {object[]} [input.flows] - Allowlisted changed-flow definitions.
+ * @param {object[]} [input.interstitials] - Config-declared dismiss selectors.
+ * @param {string[]} [input.changedPaths] - Changed file paths (drives selection).
+ * @param {string} [input.serverLogExceptionPattern] - regex source for log-tail classification.
+ * @param {object} [input.caps] - Project cap overrides (clamped to the ceilings).
+ * @param {object} seams - Injected IO.
+ * @param {(a:{appUrl:string,login:object})=>Promise<{ok:boolean,detail:string}>} seams.authenticate
+ * @param {(a:{interstitials:object[]})=>Promise<{dismissed:string[]}>} [seams.dismissInterstitials]
+ * @param {(a:{appUrl:string,flow:object,step:object,index:number})=>Promise<{screenshotPath?:string,statePath?:string,ok?:boolean,detail?:string}>} seams.runStep
+ * @param {()=>{responses?:object[],requestFailures?:object[],pageErrors?:object[]}} seams.getCapturedEvents
+ * @param {()=>Promise<string>} [seams.readServerLogTail]
+ * @param {(msg:string)=>void} [seams.log]
+ * @returns {Promise<object>} Result envelope (steps, captures, failures, caps, logs).
+ */
+export async function driveUiReview(
+  { appUrl, login, flows = [], interstitials = [], changedPaths = [], serverLogExceptionPattern, caps = {} },
+  {
+    authenticate,
+    dismissInterstitials = async () => ({ dismissed: [] }),
+    runStep,
+    getCapturedEvents,
+    readServerLogTail = async () => "",
+    log = () => {},
+  } = {},
+) {
+  const logs = [];
+  const record = (msg) => {
+    logs.push(msg);
+    log(msg);
+  };
+  const resolvedCaps = resolveCaps(caps);
+  // 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 });
+
+  // 1. Authenticate as the target role. Fail closed: no session -> STOP, drive
+  //    nothing (a review that never reached the app is worthless, not empty).
+  const auth = await authenticate({ appUrl, login });
+  if (!auth.ok) {
+    const stopReason = `cannot authenticate: ${auth.detail ?? "dev-login recipe did not yield a session"}`;
+    record(`STOP: ${stopReason}`);
+    return {
+      ok: false,
+      stopped: true,
+      stopReason,
+      steps: [],
+      captures: [],
+      failures: [{ kind: "auth-failed", severity: MUST_FIX, message: stopReason }],
+      caps: resolvedCaps,
+      ...base(),
+    };
+  }
+  record(`authenticated: ${auth.detail ?? "session established"}`);
+
+  // 2. Dismiss known interstitials ONCE per browser context (config-declared).
+  const dismiss = await dismissInterstitials({ interstitials });
+  if (dismiss.dismissed?.length) record(`interstitials dismissed: ${dismiss.dismissed.join(", ")}`);
+
+  // 3. Select the changed flows (bounded heuristic over the explicit allowlist).
+  const { selected, skipped } = selectFlows({ flows, changedPaths, caps: resolvedCaps });
+  for (const s of skipped) record(`flow skipped: ${s.name} (${s.reason})`);
+  record(`driving ${selected.length} flow(s)`);
+
+  // 4. Walk each flow's steps, capturing every step, until the screenshot cap.
+  //    No retry: a step that throws is recorded as a step failure and the walk
+  //    moves on — deterministic, bounded, never re-run.
+  const steps = [];
+  const captures = [];
+  let screenshots = 0;
+  let screensSkipped = 0;
+  for (const flow of selected) {
+    const declaredSteps = Array.isArray(flow.steps) ? flow.steps : [];
+    const flowSteps = declaredSteps.slice(0, resolvedCaps.maxStepsPerFlow);
+    if (declaredSteps.length > flowSteps.length) {
+      record(`steps skipped: ${flow.name} truncated to ${flowSteps.length} step(s) at the maxStepsPerFlow cap (${resolvedCaps.maxStepsPerFlow})`);
+    }
+    for (let i = 0; i < flowSteps.length; i += 1) {
+      const step = flowSteps[i];
+      if (screenshots >= resolvedCaps.maxScreenshots) {
+        screensSkipped += 1;
+        continue;
+      }
+      let outcome;
+      try {
+        outcome = await runStep({ appUrl, flow, step, index: screenshots });
+      } catch (err) {
+        outcome = { ok: false, detail: (err?.message ?? String(err)).slice(0, 500) };
+      }
+      const ok = outcome?.ok !== false;
+      screenshots += 1;
+      const entry = {
+        flow: flow.name,
+        step: step.name ?? step.action ?? `step-${i}`,
+        order: screenshots,
+        ok,
+        screenshotPath: outcome?.screenshotPath ?? null,
+        statePath: outcome?.statePath ?? null,
+        detail: outcome?.detail ?? null,
+      };
+      steps.push(entry);
+      if (entry.screenshotPath) captures.push({ flow: flow.name, step: entry.step, screenshotPath: entry.screenshotPath, statePath: entry.statePath });
+      if (!ok) record(`step failed (no retry): ${flow.name} / ${entry.step}: ${entry.detail ?? "unknown"}`);
+    }
+  }
+  if (screensSkipped > 0) record(`screens skipped: ${screensSkipped} step(s) past the maxScreenshots cap (${resolvedCaps.maxScreenshots})`);
+
+  // 5. Collate the out-of-band captures: listener events + the server-log tail.
+  const events = getCapturedEvents() ?? {};
+  const serverLogTail = await readServerLogTail();
+  const failures = classifyFailures({
+    responses: events.responses ?? [],
+    requestFailures: events.requestFailures ?? [],
+    pageErrors: events.pageErrors ?? [],
+    serverLogTail,
+    serverLogExceptionPattern,
+  });
+  // A step that threw is a drive failure too — surface it in the structured list.
+  for (const s of steps) {
+    if (!s.ok) failures.push({ kind: "step-failure", severity: MUST_FIX, message: `step failed: ${s.flow} / ${s.step}${s.detail ? `: ${s.detail}` : ""}` });
+  }
+  record(`captured ${failures.length} failure(s) across ${steps.length} step(s)`);
+
+  return {
+    ok: failures.length === 0,
+    stopped: false,
+    stopReason: null,
+    steps,
+    captures,
+    failures,
+    caps: resolvedCaps,
+    screensSkipped,
+    ...base(),
+  };
+}

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

@@ -0,0 +1,264 @@
+/**
+ * Provision + boot orchestrator for the ui_review route (Stage 1).
+ *
+ * Provisions an isolated worktree for a PR head and boots the branch's app to a
+ * ready state, then hands off a booted app for the running-app review stages.
+ * The orchestration is a fail-closed sequence:
+ *
+ *   1. create-or-reuse the PR worktree (fetch before) and provision it
+ *   2. refuse to operate in the primary checkout (worktree guard)
+ *   3. install ONLY the dependency-lock delta vs. the primary checkout
+ *   4. run pending dev-DB migrations; a destructive one stops for explicit ack
+ *   5. resolve a per-project run recipe (no app is ever guessed)
+ *   6. boot the app and poll an HTTP readiness probe (never a fixed sleep)
+ *
+ * Every bounded cap (install skipped, migration ack required, boot timeout) is
+ * logged — no silent truncation. This module is pure orchestration: all IO
+ * (git/worktree, config, spawn, HTTP probe, clock) is injected so it is fully
+ * testable against a fixture project. The thin CLI wires the real seams.
+ *
+ * Out of scope (later stages): browser driving, auth, screenshots, review
+ * posting, production DB.
+ */
+
+import path from "node:path";
+
+const MUST_FIX = "must-fix";
+
+/**
+ * Run the provision+boot sequence.
+ *
+ * @param {object} input
+ * @param {string} input.repoRoot - Absolute path to the primary checkout.
+ * @param {number} input.pr - PR number whose head is provisioned.
+ * @param {string} [input.branch] - Branch to check out (default: pr-<n>).
+ * @param {boolean} [input.ackDestructiveMigration] - Explicit ack unblocking a
+ *   destructive/blocked migration. Fail-closed: absent means "not acknowledged".
+ * @param {object} seams - Injected IO (all required except clock/log defaults).
+ * @param {(a:{repoRoot:string,pr:number,branch?:string})=>Promise<{path:string,created:boolean,reused:boolean}>} seams.ensureWorktree
+ * @param {(a:{worktreePath:string,repoRoot:string})=>{ok:boolean,message?:string,mainWorktreePath?:string|null}} seams.assertNotPrimary
+ * @param {(a:{repoRoot:string,worktreePath:string})=>Promise<{changed:boolean,detail:string}>} seams.detectDepDelta
+ * @param {(a:{worktreePath:string})=>Promise<{ok:boolean,detail:string}>} seams.installDeps
+ * @param {(worktreePath:string)=>Promise<object|null>} seams.resolveRunRecipe
+ * @param {(a:{worktreePath:string,recipe:object,runCwd:string})=>Promise<{pending:string[],destructive:string[],detail:string}>} seams.inspectMigrations — MUST run in `runCwd` (the guard-validated absolute cwd), never re-derive it
+ * @param {(a:{worktreePath:string,recipe:object,runCwd:string})=>Promise<{ok:boolean,applied:number,detail:string}>} seams.applyMigrations — MUST run in `runCwd`
+ * @param {(a:{worktreePath:string,recipe:object,runCwd:string})=>Promise<{pid:number|null,detail:string}>} seams.bootApp — MUST run in `runCwd`
+ * @param {(url:string)=>Promise<boolean>} seams.probe
+ * @param {(ms:number)=>Promise<false> & {clear?:()=>void}} [seams.probeTimeout] -
+ *   Per-attempt cap: resolves false once `ms` elapses, so a hung probe can't
+ *   outlive the budget. May expose `clear()`; the poll calls it after each race
+ *   resolves so a pending timer is cancelled rather than left to fire.
+ * @param {(ms:number)=>Promise<void>} [seams.delay]
+ * @param {()=>number} [seams.now]
+ * @param {(msg:string)=>void} [seams.log]
+ * @returns {Promise<object>} A result envelope (see fields assembled below).
+ */
+export async function provisionAndBoot(
+  { repoRoot, pr, branch, ackDestructiveMigration = false },
+  {
+    ensureWorktree,
+    assertNotPrimary,
+    detectDepDelta,
+    installDeps,
+    resolveRunRecipe,
+    inspectMigrations,
+    applyMigrations,
+    bootApp,
+    probe,
+    probeTimeout = (ms) => {
+      let t;
+      const p = /** @type {Promise<false> & {clear?:()=>void}} */ (
+        new Promise((resolve) => {
+          t = setTimeout(() => resolve(false), ms);
+        })
+      );
+      // Self-clearing: the poll calls clear() after the race resolves, so a
+      // still-pending timer is cancelled outright (never left to fire, never
+      // holds the process open) — bounding any injected probe seam.
+      p.clear = () => clearTimeout(t);
+      return p;
+    },
+    delay = (ms) => new Promise((r) => setTimeout(r, ms)),
+    now = () => Date.now(),
+    log = () => {},
+  } = {},
+) {
+  const logs = [];
+  const findings = [];
+  const record = (msg) => {
+    logs.push(msg);
+    log(msg);
+  };
+  const base = () => ({ pr, branch: branch ?? null, findings, logs });
+  const stop = (stopReason, finding, extra = {}) => {
+    if (finding) findings.push(finding);
+    record(`STOP: ${stopReason}`);
+    return { ok: false, stopped: true, stopReason, ...base(), ...extra };
+  };
+
+  // 1. Create-or-reuse the PR worktree (ensureWorktree fetches + provisions).
+  const wt = await ensureWorktree({ repoRoot, pr, branch });
+  const worktreePath = wt.path;
+  record(`worktree ${wt.created ? "created" : "reused"}: ${worktreePath}`);
+
+  // 2. Fail closed if that path is the primary checkout — never operate there.
+  const guard = assertNotPrimary({ worktreePath, repoRoot });
+  if (!guard.ok) {
+    return stop(
+      "worktree guard: refusing to operate in the primary checkout",
+      { kind: "worktree-guard", severity: MUST_FIX, message: guard.message ?? "resolved worktree is the primary checkout" },
+      { worktreePath },
+    );
+  }
+
+  // 3. Install only the dependency-lock delta vs. the primary checkout. No delta
+  //    => deps are shared; installing anything would be a blind re-install.
+  const delta = await detectDepDelta({ repoRoot, worktreePath });
+  let depInstall = { installed: false, detail: delta.detail };
+  if (delta.changed) {
+    record(`dependency-lock delta detected (${delta.detail}); installing branch deps`);
+    const inst = await installDeps({ worktreePath });
+    depInstall = { installed: inst.ok, detail: inst.detail };
+    record(`dependency install ${inst.ok ? "ok" : "FAILED"}: ${inst.detail}`);
+    if (!inst.ok) {
+      return stop(
+        "dependency install failed",
+        { kind: "dep-install", severity: MUST_FIX, message: inst.detail },
+        { worktreePath, depInstall },
+      );
+    }
+  } else {
+    record(`dependency install skipped: no lock delta vs primary checkout (${delta.detail})`);
+  }
+
+  // 4. Resolve the per-project run recipe before migrate/boot (no app guessed).
+  const recipe = await resolveRunRecipe(worktreePath);
+  if (!recipe) {
+    return stop(
+      "no run recipe: the branch declares no uiReview.run recipe (cannot boot the app)",
+      { kind: "run-recipe-missing", severity: MUST_FIX, message: "declare uiReview.run.command + readyUrl in .devloops" },
+      { worktreePath, depInstall },
+    );
+  }
+
+  // 4b. Resolve + validate the run recipe's cwd ONCE, here — the single source
+  //     of cwd truth. The recipe's cwd is worktree-relative; a recipe that
+  //     escapes the worktree (e.g. cwd "../..") would run migrate/boot in
+  //     another checkout, so fail closed unless the resolved cwd stays inside
+  //     the provisioned tree. The validated ABSOLUTE path (`runCwd`) is what the
+  //     migrate/boot seams execute in — they consume it verbatim and never
+  //     re-derive it, so the guarded path and the executed path cannot drift.
+  let runCwd = worktreePath;
+  if (recipe.cwd) {
+    const resolvedCwd = path.resolve(worktreePath, recipe.cwd);
+    const insideWorktree = resolvedCwd === worktreePath || resolvedCwd.startsWith(worktreePath + path.sep);
+    if (!insideWorktree) {
+      return stop(
+        "run recipe cwd escapes the provisioned worktree",
+        { kind: "cwd-traversal", severity: MUST_FIX, message: `uiReview.run.cwd (${recipe.cwd}) resolves outside the worktree: ${resolvedCwd}` },
+        { worktreePath, depInstall },
+      );
+    }
+    runCwd = resolvedCwd;
+  }
+
+  // 5. Dev-DB migrations. A destructive/blocked migration fails closed to a
+  //    finding requiring explicit ack; nothing is applied until acknowledged.
+  let migrations = { pending: 0, applied: 0, destructive: [], detail: "no migrate recipe" };
+  if (recipe.migrate) {
+    const mig = await inspectMigrations({ worktreePath, recipe, runCwd });
+    record(`migration status: ${mig.pending.length} pending, ${mig.destructive.length} destructive (${mig.detail})`);
+    if (mig.destructive.length > 0 && !ackDestructiveMigration) {
+      return stop(
+        "destructive migration requires explicit acknowledgement",
+        {
+          kind: "destructive-migration",
+          severity: MUST_FIX,
+          requiresAck: true,
+          message: `${mig.destructive.length} destructive migration(s) blocked pending ack`,
+          destructive: mig.destructive,
+        },
+        { worktreePath, depInstall, migrations: { pending: mig.pending.length, applied: 0, destructive: mig.destructive, detail: mig.detail } },
+      );
+    }
+    if (mig.pending.length > 0) {
+      if (mig.destructive.length > 0) {
+        record(`destructive migration(s) acknowledged; applying ${mig.pending.length} pending migration(s)`);
+      }
+      const applied = await applyMigrations({ worktreePath, recipe, runCwd });
+      if (!applied.ok) {
+        return stop(
+          "migration apply failed",
+          { kind: "migration-apply", severity: MUST_FIX, message: applied.detail },
+          { worktreePath, depInstall, migrations: { pending: mig.pending.length, applied: 0, destructive: mig.destructive, detail: applied.detail } },
+        );
+      }
+      migrations = { pending: mig.pending.length, applied: applied.applied, destructive: mig.destructive, detail: applied.detail };
+      record(`migrations applied: ${applied.applied} (${applied.detail})`);
+    } else {
+      migrations = { pending: 0, applied: 0, destructive: mig.destructive, detail: "no pending migrations" };
+      record("no pending migrations");
+    }
+  } else {
+    record("migrations skipped: branch declares no migrate recipe");
+  }
+
+  // 6. Boot the app, then poll the readiness probe against an explicit deadline.
+  const boot = await bootApp({ worktreePath, recipe, runCwd });
+  record(`app booting (pid ${boot.pid ?? "n/a"}): ${boot.detail}`);
+
+  const timeoutMs = recipe.readyTimeoutMs;
+  const intervalMs = recipe.readyIntervalMs;
+  const deadline = now() + timeoutMs;
+  let ready = false;
+  let attempts = 0;
+  // Bounded poll (never a fixed sleep): probe, then wait one interval, until the
+  // deadline. The injected clock/delay make the timeout deterministic in tests.
+  while (now() <= deadline) {
+    attempts += 1;
+    // Fail closed: a probe that throws/rejects counts as "not ready yet" so the
+    // deadline path produces the clean boot-timeout stop instead of crashing.
+    // Bound each attempt by the remaining budget (raced against probeTimeout) so
+    // a slow/hung probe can't exceed the deadline or block forever — a per-attempt
+    // timeout is just "not ready yet", keeping boot-timeout deterministic.
+    let probeOk = false;
+    const timeout = probeTimeout(Math.max(0, deadline - now()));
+    try {
+      probeOk = await Promise.race([Promise.resolve(probe(recipe.readyUrl)), timeout]);
+    } catch {
+      probeOk = false;
+    } finally {
+      timeout.clear?.(); // cancel the pending per-attempt timer once the race is decided
+    }
+    if (probeOk) {
+      ready = true;
+      break;
+    }
+    if (now() + intervalMs > deadline) break; // would overshoot the deadline
+    await delay(intervalMs);
+  }
+
+  const bootResult = { pid: boot.pid ?? null, ready, attempts, readyUrl: recipe.readyUrl, timeoutMs, intervalMs };
+  if (!ready) {
+    record(`boot timeout: not ready after ${timeoutMs}ms (${attempts} probe attempt(s)) at ${recipe.readyUrl}`);
+    return stop(
+      `readiness probe timed out after ${timeoutMs}ms (${attempts} attempt(s) at ${recipe.readyUrl})`,
+      { kind: "boot-timeout", severity: MUST_FIX, message: `app never became ready within ${timeoutMs}ms` },
+      { worktreePath, depInstall, migrations, boot: bootResult },
+    );
+  }
+
+  record(`app ready after ${attempts} probe attempt(s) at ${recipe.readyUrl}`);
+  return {
+    ok: true,
+    stopped: false,
+    stopReason: null,
+    worktreePath,
+    created: wt.created,
+    reused: wt.reused,
+    depInstall,
+    migrations,
+    boot: bootResult,
+    ...base(),
+  };
+}