@yemi33/minions 0.1.2197 → 0.1.2198

package/engine/pr-clone-keep.js

@@ -0,0 +1,370 @@
+/**
+ * engine/pr-clone-keep.js — Clone & keep fix executor: auto-clone a PR's repo and
+ * register it as a PERSISTENT project so ongoing tracking / auto-fix works.
+ *
+ * Plan: projectless-pr-actions, Phase 2, item P-ppa10007. This is the second
+ * mutating executor in the chain (after the ephemeral temp-clone, P-ppa10006).
+ * The execution-target choice surface (engine/pr-fix-target.js) routes
+ * `clone-keep` here once the user has explicitly picked it — the "never clone
+ * silently" invariant lives upstream; by the time we run, the user has chosen to
+ * clone AND keep.
+ *
+ * Contract (from the choice surface's description): "Auto-clone the repo and
+ * register it as a persistent project so ongoing tracking/auto-fix works.
+ * Disk-resident."
+ *
+ *   planCloneKeep(input, opts)    — resolve the PR ref, confirm auth + the base
+ *                                   repo's clone URL + default branch, and compute
+ *                                   the PERSISTENT project dir + name. PLANNING
+ *                                   ONLY: nothing is created on disk, nothing is
+ *                                   cloned.
+ *   executeCloneKeep(plan, opts)  — clone the BASE repo into the persistent dir
+ *                                   and register it as a project via
+ *                                   engine/projects.js#addProject. The repo then
+ *                                   becomes `project-ready` so the fix itself
+ *                                   flows through the engine's normal project fix
+ *                                   path. On registration failure the partial
+ *                                   clone is rolled back so no orphan dir leaks.
+ *
+ * Load-bearing invariants (read before extending):
+ *  - PERSISTENT (the whole point vs temp-clone): the clone dir is durable and is
+ *    handed to addProject as the project's `localPath`. It is NOT discarded on
+ *    success. It IS rolled back if registration fails (so a half-registered repo
+ *    never leaves an orphan directory behind).
+ *  - BASE REPO, NOT FORK: a persistent project tracks the canonical PR target
+ *    repo (`ref.slug`), never a contributor's fork — ongoing auto-fix is about the
+ *    base repo. The base clone URL is derived from the ref, independent of the
+ *    PR head repo.
+ *  - REGISTER-THEN-DONE: this executor sets up the ENVIRONMENT (clone + project
+ *    registration). It does NOT run the fix/tests/push itself — once the project
+ *    is registered the repo is `project-ready` and the fix routes through the
+ *    existing project worktree/fix path. Keeping the two concerns separate is why
+ *    a single dispatch can never both clone-silently and skip the choice.
+ *  - IDEMPOTENT RE-CHECK: a stale clone-keep plan must never re-clone a repo that
+ *    has since become a configured project. executeCloneKeep re-derives the
+ *    configured-project check from current config and short-circuits to
+ *    `project-ready` (no clone) when the repo is already linked.
+ *  - All git/network/register steps are injectable seams so unit tests never clone
+ *    a real repo; the defaults are real (shellSafeGit / projects.addProject).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const shared = require('./shared');
+const prResolve = require('./pr-resolve');
+const ghToken = require('./gh-token');
+const prFixTarget = require('./pr-fix-target');
+const { PrActionError } = require('./pr-action');
+
+const CLONE_KEEP_DIR_NAME = 'cloned-repos';      // persistent root, under MINIONS_DIR
+const CLONE_TIMEOUT_MS = 10 * 60 * 1000;         // full clone can be large
+const GIT_OP_TIMEOUT_MS = 60 * 1000;
+
+// ── Ref resolution ────────────────────────────────────────────────────────────
+
+/**
+ * Resolve `{ url }` (raw PR URL / canonical id), an already-normalized ref, or a
+ * routed plan (carrying `.ref`) into a normalized PR ref. Throws
+ * `PrActionError` (400) on missing/unrecognized input — mirrors the read-only,
+ * choice-surface, and temp-clone paths so the dashboard reflects a 400, not a 500.
+ */
+function _resolveRef(input) {
+  if (input && typeof input === 'object') {
+    if (input.host && input.slug && input.number) return input; // already normalized
+    if (input.ref && input.ref.host) return input.ref;          // plan/handle carrying a ref
+  }
+  const rawUrl = input && typeof input === 'object'
+    ? (typeof input.url === 'string' ? input.url.trim() : '')
+    : (typeof input === 'string' ? input.trim() : '');
+  if (!rawUrl) throw new PrActionError('url required');
+  const ref = prResolve.normalizePrRef(rawUrl);
+  if (!ref) throw new PrActionError(`unrecognized PR reference: ${JSON.stringify(rawUrl.slice(0, 120))}`);
+  return ref;
+}
+
+function _prId(ref) {
+  if (!ref) return null;
+  return ref.id || (ref.host && ref.slug && ref.number ? `${ref.host}:${ref.slug}#${ref.number}` : null);
+}
+
+/** Filesystem-safe slug for the persistent project dir name (from the repo name). */
+function _safeDirSlug(name) {
+  return String(name || 'repo').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'repo';
+}
+
+/** The persistent-clone root — durable, OUTSIDE the worktree pool + tmp roots. */
+function _cloneRoot(opts = {}) {
+  return opts.cloneRoot || path.join(shared.MINIONS_DIR, CLONE_KEEP_DIR_NAME);
+}
+
+/**
+ * The BASE repo clone URL for a normalized ref (the PR TARGET repo, never a fork).
+ * GitHub is derived from the validated slug; ADO uses the base repo remoteUrl that
+ * fetchPrBranches already resolved (ADO PRs are same-repo, so it is the base repo).
+ */
+function _baseCloneUrl(ref, branches) {
+  if (ref.host === 'github') {
+    const slug = shared.validateGhSlug(ref.slug);
+    return `https://github.com/${slug}.git`;
+  }
+  if (ref.host === 'ado') {
+    return (branches && branches.cloneUrl) || null;
+  }
+  return null;
+}
+
+// ── Planning ──────────────────────────────────────────────────────────────────
+
+/**
+ * Plan a clone-keep fix: resolve the PR ref, confirm auth + the base repo's clone
+ * URL + default branch (via fetchPrBranches, mirroring temp-clone), and compute
+ * the persistent project dir + name. NOTHING is created or cloned here.
+ *
+ * `input` — `{ url }`, a normalized ref, or a routed plan from
+ *   engine/pr-fix-target.js#resolvePrFixTarget.
+ * `opts.fetchPrBranches` — override the branch fetch (test seam).
+ * `opts.prUrl` — original user URL (preferred for surfacing).
+ * `opts.cloneRoot` — override the persistent-clone root.
+ * `opts.projectName` — override the derived project name.
+ *
+ * Returns `{ status:'clone-keep-planned', target:'clone-keep', ref, prId, prUrl,
+ *   cloneUrl, targetBranch, projectDir, projectName, validates:true }`.
+ * Throws `PrActionError` (400) on bad input; re-throws fetch errors.
+ */
+async function planCloneKeep(input = {}, opts = {}) {
+  const ref = _resolveRef(input);
+  const prUrl = opts.prUrl || (input && typeof input === 'object' ? input.url : undefined) || null;
+  const prId = _prId(ref);
+
+  // Confirm the PR exists + auth works, and learn the base (target) branch. This
+  // mirrors temp-clone — a clone-keep on a repo we cannot reach should fail in
+  // planning, before we touch the disk.
+  const fetchBranches = opts.fetchPrBranches || prResolve.fetchPrBranches;
+  const branches = await fetchBranches(ref, opts);
+
+  const cloneUrl = _baseCloneUrl(ref, branches);
+  if (!cloneUrl) throw new PrActionError(`could not resolve a base clone URL for ${prId || 'PR'}`, 502);
+
+  const projectName = _safeDirSlug(opts.projectName || ref.repo || ref.slug);
+  const projectDir = path.join(_cloneRoot(opts), projectName);
+
+  return {
+    status: 'clone-keep-planned',
+    target: 'clone-keep',
+    ref,
+    prId,
+    prUrl,
+    cloneUrl,
+    targetBranch: (branches && branches.targetBranch) || null,
+    projectDir,
+    projectName,
+    validates: true,
+  };
+}
+
+// ── Default git seam (real implementation; tests inject their own) ─────────────
+
+/** Resolve an auth token for the PR's host (GitHub PAT per-slug / ADO bearer). */
+async function _resolveToken(plan, opts = {}) {
+  if (opts.token) return opts.token;
+  if (plan.ref.host === 'github') {
+    const resolve = opts._resolveTokenForSlug || ghToken.resolveTokenForSlug;
+    return resolve(plan.ref.slug) || null;
+  }
+  if (plan.ref.host === 'ado') {
+    const acquire = opts._acquireAdoToken || require('./ado-token').acquireAdoToken;
+    const acquired = await acquire();
+    return (acquired && acquired.token) || null;
+  }
+  return null;
+}
+
+/** Build an HTTPS clone URL with an embedded GitHub token (private base repos). */
+function _authedGithubUrl(cloneUrl, token) {
+  if (!token) return cloneUrl;
+  try {
+    const u = new URL(cloneUrl);
+    u.username = 'x-access-token';
+    u.password = token;
+    return u.toString();
+  } catch {
+    return cloneUrl;
+  }
+}
+
+/** Per-invocation git auth args. ADO injects a bearer header; GitHub embeds in URL. */
+function _gitAuthArgs(plan, token) {
+  if (plan.ref.host === 'ado' && token) {
+    return ['-c', `http.extraHeader=Authorization: Bearer ${token}`];
+  }
+  return [];
+}
+
+async function _defaultGitClone(plan, token, opts = {}) {
+  const runGit = opts._shellSafeGit || shared.shellSafeGit;
+  const url = plan.ref.host === 'github' ? _authedGithubUrl(plan.cloneUrl, token) : plan.cloneUrl;
+  // Full clone (NOT --depth 1 / --single-branch): a persistent project needs the
+  // whole history + every branch so the engine can later create worktrees and
+  // fetch the PR branch through the normal project fix path.
+  await runGit(
+    ['clone', url, plan.projectDir],
+    { timeout: CLONE_TIMEOUT_MS, gitExtraArgs: _gitAuthArgs(plan, token) },
+  );
+}
+
+/**
+ * Best-effort recursive remove of a partial clone dir on rollback. NEVER throws —
+ * rollback runs after a failure and must not mask the real error.
+ */
+async function _rollbackClone(dir, opts = {}) {
+  if (!dir) return true;
+  const rm = opts._rm || ((d) => fs.promises.rm(d, { recursive: true, force: true, maxRetries: 6, retryDelay: 200 }));
+  try {
+    await rm(dir);
+    return true;
+  } catch (e) {
+    shared.log('warn', `pr-clone-keep: failed to roll back partial clone ${dir}: ${e?.message || e}`);
+    return false;
+  }
+}
+
+// ── Execution ─────────────────────────────────────────────────────────────────
+
+function _record(plan, fields) {
+  return {
+    status: 'failed',
+    target: 'clone-keep',
+    ref: plan.ref,
+    prId: plan.prId,
+    prUrl: plan.prUrl,
+    cloneUrl: plan.cloneUrl,
+    projectDir: plan.projectDir,
+    projectName: plan.projectName,
+    cloned: false,
+    registered: false,
+    project: null,
+    rolledBack: false,
+    failure_class: null,
+    retryable: false,
+    error: null,
+    ...fields,
+  };
+}
+
+/**
+ * Execute the clone-keep lifecycle for a planned (or raw) PR fix: clone the BASE
+ * repo into a persistent dir and register it as a project so the repo becomes
+ * `project-ready`. The fix itself is NOT run here — once registered it flows
+ * through the engine's normal project fix path.
+ *
+ * `planOrInput` — a plan from `planCloneKeep`, a routed plan from pr-fix-target.js,
+ *   a normalized ref, or `{ url }`.
+ * `opts`:
+ *   - `config` — full config; re-checks configured-project so a stale plan can't
+ *     re-clone a repo that is already linked.
+ *   - `registerOptions` — passed through to projects.addProject (name override,
+ *     worktreeMode, observeAuthors, …).
+ *   - test seams: `gitClone`, `addProject`, `findConfiguredProject`, `fetchPrBranches`,
+ *     `token`/`_resolveTokenForSlug`/`_acquireAdoToken`, `cloneRoot`, `_rm`, `_mkdir`.
+ *
+ * Returns:
+ *   - `{ status:'project-ready', alreadyConfigured:true, project, projectName,
+ *        cloned:false, registered:false, ... }` — repo is already a configured
+ *     project; NOTHING is cloned, route to the existing project fix path.
+ *   - `{ status:'done', registered:true, project, projectDir, projectName,
+ *        cloned:true, ... }` — clone + registration succeeded.
+ *   - a `failed` record on any downstream failure (partial clone rolled back).
+ *
+ * Throws `PrActionError` (400) only for bad input.
+ */
+async function executeCloneKeep(planOrInput = {}, opts = {}) {
+  // 0) Idempotent re-check: never re-clone a repo that is ALREADY a configured
+  //    project (a stale awaiting-choice plan must route to the project path).
+  const ref = _resolveRef(planOrInput); // PrActionError(400) on bad input propagates
+  const findConfigured = opts.findConfiguredProject || prFixTarget.findConfiguredProjectForRef;
+  const existing = findConfigured(ref, opts.config);
+  if (existing) {
+    return {
+      status: 'project-ready',
+      target: 'clone-keep',
+      ref,
+      prId: _prId(ref),
+      prUrl: (planOrInput && typeof planOrInput === 'object' ? (planOrInput.prUrl || planOrInput.url) : null) || null,
+      alreadyConfigured: true,
+      project: existing,
+      projectName: existing.name || null,
+      cloned: false,
+      registered: false,
+      failure_class: null,
+      retryable: false,
+      error: null,
+    };
+  }
+
+  // Accept an already-built plan, else plan now (resolves clone URL + project dir).
+  let plan;
+  if (planOrInput && planOrInput.status === 'clone-keep-planned' && planOrInput.projectDir) {
+    plan = planOrInput;
+  } else {
+    plan = await planCloneKeep(planOrInput, opts); // PrActionError(400) on bad input propagates
+  }
+
+  const gitClone = opts.gitClone || ((p, token) => _defaultGitClone(p, token, opts));
+  const addProject = opts.addProject || ((target, registerOptions) => require('./projects').addProject(target, registerOptions));
+  const mkdir = opts._mkdir || ((dir) => fs.promises.mkdir(dir, { recursive: true }));
+
+  const rec = _record(plan, {});
+  let token = null;
+
+  // 1) Persistent clone of the BASE repo.
+  try {
+    token = await _resolveToken(plan, opts);
+    await mkdir(path.dirname(plan.projectDir));
+    await gitClone(plan, token);
+    rec.cloned = true;
+  } catch (e) {
+    rec.failure_class = shared.FAILURE_CLASS.NETWORK_ERROR;
+    rec.retryable = true;
+    rec.error = `clone failed: ${e?.message || e}`;
+    // Best-effort rollback of any partial clone dir before reporting.
+    rec.rolledBack = await _rollbackClone(plan.projectDir, opts);
+    return rec;
+  }
+
+  // 2) Register the clone as a persistent project.
+  let registered;
+  try {
+    registered = await addProject(plan.projectDir, { ...(opts.registerOptions || {}) });
+  } catch (e) {
+    rec.failure_class = shared.FAILURE_CLASS.CONFIG_ERROR;
+    rec.retryable = false;
+    rec.error = `project registration failed: ${e?.message || e}`;
+    // Roll back the clone we created so a failed registration leaves no orphan.
+    rec.rolledBack = await _rollbackClone(plan.projectDir, opts);
+    rec.cloned = false;
+    return rec;
+  }
+
+  rec.status = 'done';
+  rec.registered = true;
+  rec.project = (registered && registered.project) || registered || null;
+  rec.projectName = (rec.project && rec.project.name) || plan.projectName;
+  rec.failure_class = null;
+  rec.retryable = false;
+  rec.error = null;
+  return rec;
+}
+
+module.exports = {
+  CLONE_KEEP_DIR_NAME,
+  planCloneKeep,
+  executeCloneKeep,
+  // Exported for testing.
+  _resolveRef,
+  _safeDirSlug,
+  _baseCloneUrl,
+  _authedGithubUrl,
+  _gitAuthArgs,
+  _rollbackClone,
+};

package/engine/pr-devbox.js

@@ -0,0 +1,322 @@
+/**
+ * engine/pr-devbox.js — DevBox execution target (the "never touches your machine"
+ * option for a projectless one-off PR fix).
+ *
+ * Plan: projectless-pr-actions, Phase 4 (stretch), item P-ppa10011. Like
+ * engine/pr-temp-clone.js this is an EXECUTOR the choice surface
+ * (engine/pr-fix-target.js) routes to once the user has EXPLICITLY picked it —
+ * the "never clone silently" invariant lives upstream; by the time we run, the
+ * user has chosen the DevBox target.
+ *
+ * Contract (from the choice surface's description): "Clone ephemerally ON A
+ * DEVBOX, run the fix there, push from the DevBox. Zero local footprint — the
+ * answer for high PR volume."
+ *
+ *   planDevBox(input, opts)      — resolve the PR ref + its source branch + a
+ *                                  clone URL and compute the REMOTE clone dir (on
+ *                                  the DevBox). PLANNING ONLY: nothing is created
+ *                                  on the local machine, nothing is cloned. The
+ *                                  branch fetch is a network metadata call, not a
+ *                                  local checkout.
+ *   executeDevBox(plan, opts)    — delegate the full remote lifecycle to the
+ *                                  injected DevBox runner (clone → fix → validate
+ *                                  → push, all ON the DevBox), then ALWAYS tear
+ *                                  the remote clone down. The engine never writes
+ *                                  to local disk on this path.
+ *
+ * Load-bearing invariants (read before extending):
+ *  - ZERO LOCAL FOOTPRINT: this module touches NO local disk. It pulls in no local
+ *    filesystem module, never runs a local clone, and every record it returns
+ *    flags `localFootprint: false`. A source-inspection test guards this. The
+ *    clone, build/test, and push all happen on the DevBox.
+ *  - DELEGATED LIFECYCLE: the engine daemon cannot call the DevBox MCP tools
+ *    directly (they are agent-side tools — see the `devbox-remote-control` skill).
+ *    So the ENTIRE remote lifecycle is performed by the injected `opts.runOnDevBox`
+ *    runner (the engine/agent wires the DevBox MCP `task_resource` calls). Without
+ *    a runner there is nothing to execute — we fail fast (CONFIG_ERROR) BEFORE
+ *    selecting/provisioning a DevBox rather than spin one up for nothing.
+ *  - ALWAYS TEAR DOWN: the remote ephemeral clone is removed in a `finally` —
+ *    success, failure, or noop — so nothing persists on the DevBox either.
+ *  - EXPLICIT CONSENT ONLY: DevBox is never the default target and is never
+ *    auto-selected; it only runs when the user picks `devbox` at the choice
+ *    surface (engine/pr-fix-target.js).
+ */
+
+const shared = require('./shared');
+const prResolve = require('./pr-resolve');
+const { PrActionError } = require('./pr-action');
+
+const DEVBOX_TMP_PREFIX = 'pr-devbox-';
+// DevBoxes are Windows (Windows App, WindowsTerminal, powershell — see the
+// devbox-remote-control skill), so the remote ephemeral-clone root defaults to a
+// Windows temp path. This is a REMOTE path string only — never created locally.
+const DEFAULT_REMOTE_TMP_ROOT = 'C:/minions-devbox-tmp';
+
+// ── Ref resolution ────────────────────────────────────────────────────────────
+
+/**
+ * Resolve `{ url }` (raw PR URL / canonical id), an already-normalized ref, or a
+ * routed/devbox plan (carrying `.ref`) into a normalized PR ref. Throws
+ * `PrActionError` (400) on missing/unrecognized input — mirrors the other
+ * projectless paths so the dashboard reflects a 400, not a 500.
+ */
+function _resolveRef(input) {
+  if (input && typeof input === 'object') {
+    if (input.host && input.slug && input.number) return input; // already normalized
+    if (input.ref && input.ref.host) return input.ref;          // plan/handle carrying a ref
+  }
+  const rawUrl = input && typeof input === 'object'
+    ? (typeof input.url === 'string' ? input.url.trim() : '')
+    : (typeof input === 'string' ? input.trim() : '');
+  if (!rawUrl) throw new PrActionError('url required');
+  const ref = prResolve.normalizePrRef(rawUrl);
+  if (!ref) throw new PrActionError(`unrecognized PR reference: ${JSON.stringify(rawUrl.slice(0, 120))}`);
+  return ref;
+}
+
+function _prId(ref) {
+  if (!ref) return null;
+  return ref.id || (ref.host && ref.slug && ref.number ? `${ref.host}:${ref.slug}#${ref.number}` : null);
+}
+
+/** Filesystem-safe slug for a PR id (used in the remote dir name). */
+function _safeDirSlug(prId) {
+  return String(prId || 'pr').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'pr';
+}
+
+/**
+ * Join a remote root + child into a single forward-slashed REMOTE path. We do NOT
+ * use path.join — that would apply the LOCAL separator and risks coupling the
+ * remote path to the host OS; the runner interprets the string on the DevBox.
+ */
+function _remoteJoin(root, name) {
+  return `${String(root || DEFAULT_REMOTE_TMP_ROOT).replace(/[\\/]+$/, '')}/${name}`;
+}
+
+// ── Planning ──────────────────────────────────────────────────────────────────
+
+/**
+ * Plan a DevBox fix: resolve the PR ref, fetch its source branch + clone URL
+ * (network metadata only), and compute the REMOTE ephemeral clone dir. NOTHING is
+ * created on the local machine and NOTHING is cloned here.
+ *
+ * `input` — `{ url }`, a normalized ref, or a routed plan from
+ *   engine/pr-fix-target.js#resolvePrFixTarget.
+ * `opts.fetchPrBranches` — override the branch fetch (test seam).
+ * `opts.prUrl` — original user URL (preferred for surfacing).
+ * `opts.remoteTmpRoot` — override the DevBox-side ephemeral-clone root.
+ *
+ * Returns `{ status:'devbox-planned', target:'devbox', ref, prId, prUrl,
+ *   sourceBranch, targetBranch, cloneUrl, sourceRepoSlug, isFork, remoteCloneDir,
+ *   validates:true, localFootprint:false }`.
+ * Throws `PrActionError` (400) on bad input; re-throws fetch errors.
+ */
+async function planDevBox(input = {}, opts = {}) {
+  const ref = _resolveRef(input);
+  const prUrl = opts.prUrl || (input && typeof input === 'object' ? input.url : undefined) || null;
+  const prId = _prId(ref);
+
+  const fetchBranches = opts.fetchPrBranches || prResolve.fetchPrBranches;
+  const branches = await fetchBranches(ref, opts);
+  const sourceBranch = branches && branches.sourceBranch;
+  if (!sourceBranch) throw new PrActionError(`could not resolve source branch for ${prId || 'PR'}`, 502);
+  // Defensive re-validation (fetchPrBranches already validates, but a custom seam
+  // might not) — a poisoned ref name must never reach `git` on the DevBox.
+  shared.validateGitRef(sourceBranch);
+
+  const remoteCloneDir = _remoteJoin(opts.remoteTmpRoot, `${DEVBOX_TMP_PREFIX}${_safeDirSlug(prId)}-${shared.uid()}`);
+
+  return {
+    status: 'devbox-planned',
+    target: 'devbox',
+    ref,
+    prId,
+    prUrl,
+    sourceBranch,
+    targetBranch: branches.targetBranch || null,
+    cloneUrl: branches.cloneUrl || null,
+    sourceRepoSlug: branches.sourceRepoSlug || ref.slug,
+    isFork: !!branches.isFork,
+    remoteCloneDir,
+    validates: true,
+    localFootprint: false,
+  };
+}
+
+// ── Execution ─────────────────────────────────────────────────────────────────
+
+function _record(plan, fields) {
+  return {
+    status: 'failed',
+    target: 'devbox',
+    ref: plan.ref,
+    prId: plan.prId,
+    prUrl: plan.prUrl,
+    sourceBranch: plan.sourceBranch || null,
+    remoteCloneDir: plan.remoteCloneDir || null,
+    devBox: plan.devBox || null,
+    changed: false,
+    validated: false,
+    validationOk: null,
+    pushed: false,
+    remoteDiscarded: false,
+    localFootprint: false,
+    output: '',
+    failure_class: null,
+    retryable: false,
+    error: null,
+    ...fields,
+  };
+}
+
+/**
+ * Execute the DevBox fix lifecycle for a planned (or raw) PR fix. The engine never
+ * touches local disk here: it selects/provisions a DevBox, hands the whole
+ * clone → fix → validate → push lifecycle to the injected `opts.runOnDevBox`
+ * runner (which drives the DevBox MCP), then ALWAYS tears the remote clone down.
+ *
+ * `planOrInput` — a plan from `planDevBox`, a routed plan from pr-fix-target.js, a
+ *   normalized ref, or `{ url }`.
+ * `opts`:
+ *   - `runOnDevBox({ devBox, remoteCloneDir, ref, prId, sourceBranch, targetBranch,
+ *      cloneUrl, isFork })` — REQUIRED. Performs the ENTIRE remote lifecycle on the
+ *      DevBox (clone the source branch, run the fix, run tests, push to the PR
+ *      branch). Returns `{ changed, validated, validationOk, pushed, output,
+ *      failure_class?, retryable?, error? }`. Throws to fail the run.
+ *   - `selectDevBox()` — OPTIONAL. Resolves/provisions the target DevBox descriptor
+ *      (`{ name, projectName, devCenterName, locationInUri, powerState }`). Defaults
+ *      to the DevBox already on the plan, else null (the runner may pick its own).
+ *   - `teardown(remoteCloneDir, devBox)` — OPTIONAL. Removes the remote ephemeral
+ *      clone. Best-effort, never throws. Defaults to a no-op that returns true
+ *      (the runner is expected to clean up its own remote dir).
+ *
+ * Returns a terminal record. Throws `PrActionError` (400) only for bad input;
+ * every downstream failure is captured in a `failed` record (remote clone still
+ * torn down).
+ */
+async function executeDevBox(planOrInput = {}, opts = {}) {
+  // Fail fast BEFORE selecting/provisioning a DevBox when there is no runner — the
+  // remote lifecycle is delegated; spinning up a DevBox for nothing wastes a slot.
+  const runOnDevBox = opts.runOnDevBox;
+  if (typeof runOnDevBox !== 'function') {
+    let ref = null; let prId = null; let prUrl = null;
+    try { ref = _resolveRef(planOrInput); prId = _prId(ref); } catch { /* leave null */ }
+    prUrl = (planOrInput && typeof planOrInput === 'object' ? (planOrInput.prUrl || planOrInput.url) : null) || null;
+    return _record({ ref, prId, prUrl, sourceBranch: null, remoteCloneDir: null }, {
+      status: 'failed',
+      failure_class: shared.FAILURE_CLASS.CONFIG_ERROR,
+      retryable: false,
+      error: 'devbox executor requires a DevBox runner (opts.runOnDevBox)',
+    });
+  }
+
+  // Accept an already-built plan, else plan now (resolves branch + remote dir).
+  let plan;
+  if (planOrInput && planOrInput.status === 'devbox-planned' && planOrInput.remoteCloneDir) {
+    plan = planOrInput;
+  } else {
+    plan = await planDevBox(planOrInput, opts); // PrActionError(400) on bad input propagates
+  }
+
+  const teardown = opts.teardown || (async () => true);
+  let provisioned = false;
+  const rec = _record(plan, {});
+
+  try {
+    // 1) Select / provision the DevBox (no local disk touched).
+    if (plan.devBox) {
+      rec.devBox = plan.devBox;
+    } else if (typeof opts.selectDevBox === 'function') {
+      try {
+        rec.devBox = await opts.selectDevBox();
+        provisioned = true;
+      } catch (e) {
+        rec.failure_class = shared.FAILURE_CLASS.CONFIG_ERROR;
+        rec.retryable = true;
+        rec.error = `devbox selection failed: ${e?.message || e}`;
+        return rec;
+      }
+    }
+
+    // 2) Delegate the ENTIRE remote lifecycle (clone → fix → validate → push).
+    let result;
+    try {
+      result = await runOnDevBox({
+        devBox: rec.devBox,
+        remoteCloneDir: plan.remoteCloneDir,
+        ref: plan.ref,
+        prId: plan.prId,
+        sourceBranch: plan.sourceBranch,
+        targetBranch: plan.targetBranch,
+        cloneUrl: plan.cloneUrl,
+        isFork: plan.isFork,
+      });
+    } catch (e) {
+      rec.failure_class = shared.FAILURE_CLASS.UNKNOWN;
+      rec.retryable = true;
+      rec.error = `devbox runner failed: ${e?.message || e}`;
+      return rec;
+    }
+
+    result = result || {};
+    rec.changed = !!result.changed;
+    rec.validated = !!result.validated;
+    rec.validationOk = result.validationOk == null ? null : !!result.validationOk;
+    rec.pushed = !!result.pushed;
+    if (typeof result.output === 'string' && result.output) rec.output = result.output;
+
+    // 3) Classify the outcome the runner reported.
+    if (rec.pushed) {
+      rec.status = 'done';
+      rec.failure_class = null;
+      rec.retryable = false;
+      rec.error = null;
+      return rec;
+    }
+    if (!rec.changed) {
+      // A clean tree is a legit noop — nothing to push.
+      rec.status = 'done';
+      rec.noop = true;
+      rec.failure_class = null;
+      rec.retryable = false;
+      rec.error = null;
+      return rec;
+    }
+    if (rec.validated && rec.validationOk === false) {
+      // Changed but tests failed on the DevBox — not pushed (validate-then-push).
+      rec.failure_class = shared.FAILURE_CLASS.BUILD_FAILURE;
+      rec.retryable = true;
+      rec.error = result.error || 'validation failed on the DevBox — fix not pushed';
+      return rec;
+    }
+    // Changed but the runner did not push and gave no validation verdict — surface
+    // whatever it reported.
+    rec.failure_class = result.failure_class || shared.FAILURE_CLASS.UNKNOWN;
+    rec.retryable = result.retryable != null ? !!result.retryable : true;
+    rec.error = result.error || 'devbox fix did not push (no validation verdict)';
+    return rec;
+  } finally {
+    // ALWAYS tear the remote ephemeral clone down — nothing persists on the DevBox.
+    if (plan && plan.remoteCloneDir) {
+      try { rec.remoteDiscarded = await teardown(plan.remoteCloneDir, rec.devBox); }
+      catch (e) {
+        shared.log('warn', `pr-devbox: failed to tear down remote clone ${plan.remoteCloneDir}: ${e?.message || e}`);
+        rec.remoteDiscarded = false;
+      }
+    } else {
+      rec.remoteDiscarded = true;
+    }
+    void provisioned; // (kept for readability; teardown above is unconditional)
+  }
+}
+
+module.exports = {
+  DEVBOX_TMP_PREFIX,
+  DEFAULT_REMOTE_TMP_ROOT,
+  planDevBox,
+  executeDevBox,
+  // Exported for testing.
+  _resolveRef,
+  _safeDirSlug,
+  _remoteJoin,
+};