@yemi33/minions 0.1.2196 → 0.1.2198

package/engine/pr-temp-clone.js

@@ -0,0 +1,414 @@
+/**
+ * engine/pr-temp-clone.js — Temp-clone fix executor (the DEFAULT execution target
+ * for a projectless one-off PR fix).
+ *
+ * Plan: projectless-pr-actions, Phase 2, item P-ppa10006. This is the first
+ * executor in the chain that actually MUTATES code. The execution-target choice
+ * surface (engine/pr-fix-target.js) routes `temp-clone` 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).
+ *
+ * Contract (from the choice surface's description): "Ephemeral clone on D:, fix +
+ * run tests, push to the PR branch, then discard. Nothing persists."
+ *
+ *   planTempClone(input, opts)    — resolve the PR ref + its source branch + a
+ *                                   clone URL, and compute the ephemeral clone
+ *                                   dir. PLANNING ONLY: nothing is created on
+ *                                   disk, nothing is cloned.
+ *   executeTempClone(plan, opts)  — run the full ephemeral lifecycle:
+ *                                     clone → fix → validate → commit → push →
+ *                                     ALWAYS discard.
+ *   cleanupTempClone(dir, opts)   — idempotent recursive remove of an ephemeral
+ *                                   clone dir (Windows file-lock tolerant).
+ *
+ * Load-bearing invariants (read before extending):
+ *  - EPHEMERAL: the clone dir lives OUTSIDE the worktree pool / project roots so
+ *    the worktree GC + lifecycle never touch it, and it is ALWAYS removed in a
+ *    `finally` — success, failure, or noop. Nothing persists by design.
+ *  - DELEGATED EDIT: this module owns the ENVIRONMENT (clone, branch, validate,
+ *    push, discard) but not the edit itself. The actual code change is performed
+ *    by the injected `opts.runFix` runner (the engine wires a fix-agent spawn in
+ *    the clone dir). Without a runner there is nothing to execute — we fail fast
+ *    BEFORE cloning rather than clone-and-discard for nothing.
+ *  - VALIDATE-THEN-PUSH: when a validator is supplied and it fails, we DO NOT
+ *    push (the temp-clone target's whole point over remote-patch is that it runs
+ *    tests). A noop fix (no file changes) also never pushes.
+ *  - ALL git/network/edit steps are injectable seams so unit tests never clone a
+ *    real repo; the defaults are real (shellSafeGit / fetchPrBranches).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const shared = require('./shared');
+const prResolve = require('./pr-resolve');
+const ghToken = require('./gh-token');
+const { PrActionError } = require('./pr-action');
+
+const TEMP_CLONE_TMP_PREFIX = 'pr-temp-clone-';
+const CLONE_TIMEOUT_MS = 5 * 60 * 1000;   // shallow clones are quick but allow for big repos
+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
+ * and choice-surface 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 ephemeral dir name). */
+function _safeDirSlug(prId) {
+  return String(prId || 'pr').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'pr';
+}
+
+/** The ephemeral-clone root — on the working drive, OUTSIDE the worktree pool. */
+function _tmpRoot(opts = {}) {
+  return opts.tmpRoot || path.join(shared.MINIONS_DIR, 'engine', 'tmp', 'pr-temp-clones');
+}
+
+// ── Planning ──────────────────────────────────────────────────────────────────
+
+/**
+ * Plan a temp-clone fix: resolve the PR ref, fetch its source branch + clone URL,
+ * and compute the ephemeral clone dir. 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.tmpRoot` — override the ephemeral-clone root.
+ *
+ * Returns `{ status:'temp-clone-planned', target:'temp-clone', ref, prId, prUrl,
+ *   sourceBranch, targetBranch, cloneUrl, sourceRepoSlug, isFork, cloneDir,
+ *   validates:true }`.
+ * Throws `PrActionError` (400) on bad input; re-throws fetch errors.
+ */
+async function planTempClone(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`.
+  shared.validateGitRef(sourceBranch);
+
+  const cloneDir = path.join(_tmpRoot(opts), `${TEMP_CLONE_TMP_PREFIX}${_safeDirSlug(prId)}-${shared.uid()}`);
+
+  return {
+    status: 'temp-clone-planned',
+    target: 'temp-clone',
+    ref,
+    prId,
+    prUrl,
+    sourceBranch,
+    targetBranch: branches.targetBranch || null,
+    cloneUrl: branches.cloneUrl || null,
+    sourceRepoSlug: branches.sourceRepoSlug || ref.slug,
+    isFork: !!branches.isFork,
+    cloneDir,
+    validates: true,
+  };
+}
+
+// ── Default git seams (real implementations; 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.sourceRepoSlug || 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 (forks + private). */
+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;
+  await runGit(
+    ['clone', '--depth', '1', '--single-branch', '--branch', plan.sourceBranch, url, plan.cloneDir],
+    { timeout: CLONE_TIMEOUT_MS, gitExtraArgs: _gitAuthArgs(plan, token) },
+  );
+}
+
+/** True when the working tree has staged/unstaged changes after the fix runs. */
+async function _defaultHasChanges(cloneDir, opts = {}) {
+  const runGit = opts._shellSafeGit || shared.shellSafeGit;
+  const out = await runGit(['-C', cloneDir, 'status', '--porcelain'], { timeout: GIT_OP_TIMEOUT_MS });
+  return String(out || '').trim().length > 0;
+}
+
+async function _defaultCommit(plan, opts = {}) {
+  const runGit = opts._shellSafeGit || shared.shellSafeGit;
+  await runGit(['-C', plan.cloneDir, 'add', '-A'], { timeout: GIT_OP_TIMEOUT_MS });
+  await runGit(
+    ['-C', plan.cloneDir,
+      '-c', 'user.email=minions@localhost',
+      '-c', 'user.name=Minions',
+      'commit', '-m', `Fix ${plan.prId || plan.sourceBranch}`],
+    { timeout: GIT_OP_TIMEOUT_MS },
+  );
+}
+
+async function _defaultGitPush(plan, token, opts = {}) {
+  const runGit = opts._shellSafeGit || shared.shellSafeGit;
+  await runGit(
+    ['-C', plan.cloneDir, 'push', 'origin', `HEAD:${plan.sourceBranch}`],
+    { timeout: GIT_OP_TIMEOUT_MS, gitExtraArgs: _gitAuthArgs(plan, token) },
+  );
+}
+
+// ── Cleanup ───────────────────────────────────────────────────────────────────
+
+/**
+ * Idempotently remove an ephemeral clone dir. Windows file-lock tolerant via
+ * fs.rm's built-in retry. Returns true on success (or already-gone), false if it
+ * could not be removed. NEVER throws — cleanup runs in a `finally` and must not
+ * mask the real result.
+ */
+async function cleanupTempClone(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-temp-clone: failed to discard ephemeral clone ${dir}: ${e?.message || e}`);
+    return false;
+  }
+}
+
+// ── Execution ─────────────────────────────────────────────────────────────────
+
+function _record(plan, fields) {
+  return {
+    status: 'failed',
+    target: 'temp-clone',
+    ref: plan.ref,
+    prId: plan.prId,
+    prUrl: plan.prUrl,
+    sourceBranch: plan.sourceBranch,
+    cloneDir: plan.cloneDir,
+    changed: false,
+    validated: false,
+    validationOk: null,
+    pushed: false,
+    discarded: false,
+    output: '',
+    failure_class: null,
+    retryable: false,
+    error: null,
+    ...fields,
+  };
+}
+
+/**
+ * Execute the temp-clone fix lifecycle for a planned (or raw) PR fix:
+ * clone the PR's source branch into an ephemeral dir, run the injected fix
+ * runner, validate, commit + push to the PR branch, then ALWAYS discard the
+ * clone.
+ *
+ * `planOrInput` — a plan from `planTempClone`, a routed plan from
+ *   pr-fix-target.js, a normalized ref, or `{ url }`.
+ * `opts`:
+ *   - `runFix({ cloneDir, ref, prId, sourceBranch })` — REQUIRED. Performs the
+ *     edits in `cloneDir`. May return `{ changed, summary }` (advisory — the real
+ *     change signal is `git status`). Throws to fail the fix.
+ *   - `validate({ cloneDir, ref, prId, sourceBranch })` — OPTIONAL. Returns
+ *     `{ ok, output }`. When supplied and `ok === false`, the fix is NOT pushed.
+ *   - test seams: `gitClone`, `hasChanges`, `commit`, `gitPush`, `cleanup`,
+ *     `fetchPrBranches`, `token`/`_resolveTokenForSlug`/`_acquireAdoToken`.
+ *
+ * Returns a terminal record. Throws `PrActionError` (400) only for bad input;
+ * every downstream failure is captured in a `failed` record (clone still
+ * discarded).
+ */
+async function executeTempClone(planOrInput = {}, opts = {}) {
+  // Fail fast BEFORE any clone when there is no edit runner — temp-clone is
+  // delegated-edit; cloning-then-discarding for nothing wastes disk + network.
+  const runFix = opts.runFix;
+  if (typeof runFix !== 'function') {
+    // Resolve identity for the record without a network fetch where possible.
+    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, cloneDir: null }, {
+      status: 'failed',
+      failure_class: shared.FAILURE_CLASS.CONFIG_ERROR,
+      retryable: false,
+      error: 'temp-clone executor requires a fix runner (opts.runFix)',
+    });
+  }
+
+  // Accept an already-built plan, else plan now (resolves branch + clone dir).
+  let plan;
+  if (planOrInput && planOrInput.status === 'temp-clone-planned' && planOrInput.cloneDir) {
+    plan = planOrInput;
+  } else {
+    plan = await planTempClone(planOrInput, opts); // PrActionError(400) on bad input propagates
+  }
+
+  const gitClone = opts.gitClone || ((p, token) => _defaultGitClone(p, token, opts));
+  const hasChanges = opts.hasChanges || ((dir) => _defaultHasChanges(dir, opts));
+  const commit = opts.commit || ((p) => _defaultCommit(p, opts));
+  const gitPush = opts.gitPush || ((p, token) => _defaultGitPush(p, token, opts));
+  const cleanup = opts.cleanup || ((dir) => cleanupTempClone(dir, opts));
+
+  let token = null;
+  let cloned = false;
+  const rec = _record(plan, {});
+
+  try {
+    token = await _resolveToken(plan, opts);
+
+    // 1) Ephemeral clone of the PR's source branch.
+    try {
+      await fs.promises.mkdir(path.dirname(plan.cloneDir), { recursive: true });
+      await gitClone(plan, token);
+      cloned = true;
+    } catch (e) {
+      rec.failure_class = shared.FAILURE_CLASS.NETWORK_ERROR;
+      rec.retryable = true;
+      rec.error = `clone failed: ${e?.message || e}`;
+      return rec;
+    }
+
+    // 2) The delegated edit.
+    let fixResult;
+    try {
+      fixResult = await runFix({ cloneDir: plan.cloneDir, ref: plan.ref, prId: plan.prId, sourceBranch: plan.sourceBranch });
+    } catch (e) {
+      rec.failure_class = shared.FAILURE_CLASS.UNKNOWN;
+      rec.retryable = true;
+      rec.error = `fix runner failed: ${e?.message || e}`;
+      return rec;
+    }
+    if (fixResult && typeof fixResult.summary === 'string') rec.output = fixResult.summary;
+
+    // 3) Did the fix actually change anything? A clean tree is a legit noop.
+    let changed;
+    try {
+      changed = await hasChanges(plan.cloneDir);
+    } catch (e) {
+      rec.failure_class = shared.FAILURE_CLASS.UNKNOWN;
+      rec.retryable = true;
+      rec.error = `git status failed: ${e?.message || e}`;
+      return rec;
+    }
+    rec.changed = changed;
+    if (!changed) {
+      rec.status = 'done';
+      rec.noop = true;
+      rec.failure_class = null;
+      rec.retryable = false;
+      rec.error = null;
+      return rec;
+    }
+
+    // 4) Validate (run tests) BEFORE pushing — temp-clone's defining feature.
+    if (typeof opts.validate === 'function') {
+      rec.validated = true;
+      let v;
+      try {
+        v = await opts.validate({ cloneDir: plan.cloneDir, ref: plan.ref, prId: plan.prId, sourceBranch: plan.sourceBranch });
+      } catch (e) {
+        v = { ok: false, output: `validation threw: ${e?.message || e}` };
+      }
+      rec.validationOk = !!(v && v.ok);
+      if (v && typeof v.output === 'string' && v.output) rec.output = v.output;
+      if (!rec.validationOk) {
+        rec.failure_class = shared.FAILURE_CLASS.BUILD_FAILURE;
+        rec.retryable = true;
+        rec.error = 'validation failed — fix not pushed';
+        return rec;
+      }
+    }
+
+    // 5) Commit + push to the PR's source branch.
+    try {
+      await commit(plan);
+      await gitPush(plan, token);
+      rec.pushed = true;
+    } catch (e) {
+      rec.failure_class = shared.FAILURE_CLASS.AUTH;
+      rec.retryable = true;
+      rec.error = `push failed: ${e?.message || e}`;
+      return rec;
+    }
+
+    rec.status = 'done';
+    rec.failure_class = null;
+    rec.retryable = false;
+    rec.error = null;
+    return rec;
+  } finally {
+    // ALWAYS discard the ephemeral clone — nothing persists.
+    if (cloned || (plan && plan.cloneDir)) {
+      rec.discarded = await cleanup(plan.cloneDir);
+    } else {
+      rec.discarded = true;
+    }
+  }
+}
+
+module.exports = {
+  TEMP_CLONE_TMP_PREFIX,
+  planTempClone,
+  executeTempClone,
+  cleanupTempClone,
+  // Exported for testing.
+  _resolveRef,
+  _safeDirSlug,
+  _authedGithubUrl,
+  _gitAuthArgs,
+};

package/engine/pr-track.js

@@ -0,0 +1,209 @@
+/**
+ * engine/pr-track.js — Promote a one-off PR to TRACKED auto-fix (enrollment
+ * wiring).
+ *
+ * Plan: projectless-pr-actions, Phase 3, item P-ppa10010. The "Track for auto-fix"
+ * follow-up chip (P-ppa10004) enrolls a PR the user previously ran a read-only
+ * pr-action on (P-ppa10003) into the EXISTING auto-managed pipeline:
+ *   pollers → PR discovery → review / fix / re-review → auto-merge.
+ *
+ * There is NO new fix engine here — enrollment is "mostly wiring":
+ *   1. The canonical auto-managed signal is a SINGLE field: `contextOnly:false`
+ *      (`shared.isAutoManagedPrRecord` — engine/shared.js). Enrolling a PR means
+ *      ensuring a tracked record exists with `contextOnly:false` so the existing
+ *      PR-discovery auto-managed gate flips on.
+ *   2. If the PR's repo is NOT a configured project, ongoing auto-fix needs a
+ *      PERSISTENT checkout, so promotion surfaces the SAME execution-target
+ *      choice as a one-off fix (engine/pr-fix-target.js, P-ppa10005) but with
+ *      "Clone & keep" (engine/pr-clone-keep.js, P-ppa10007 — the persistent
+ *      project executor) as the implied/default selection. NOTHING is cloned
+ *      until the user picks.
+ *   3. Once the repo is project-ready (already configured, or after Clone & keep
+ *      registers it), enrollment links the PR with `contextOnly:false` and the
+ *      existing machinery takes over unchanged.
+ *
+ * Load-bearing invariants (read before extending):
+ *  - NO new engine: this module registers no poller / timer / discovery surface
+ *    and introduces no fix executor. A source-inspection test enforces it.
+ *  - NEVER clone silently: the unconfigured-repo branch reuses the choice surface
+ *    and PAUSES; this module imports no clone / worktree / spawn primitive.
+ *  - "Clone & keep" implied: temp-clone is ephemeral (the clone is discarded after
+ *    one push), so it is NOT a valid ongoing-tracking target — the recommended /
+ *    default selection for promotion is `clone-keep`.
+ *  - The actual record write is done by the existing manual-link path
+ *    (dashboard.js#linkPullRequestForTracking → shared.upsertPullRequestRecord),
+ *    which both creates a missing record and PROMOTES an existing context-only
+ *    record to auto-managed (upsert refuses to DEMOTE a managed PR). This module
+ *    only computes the canonical enrollment signal — it does not duplicate the
+ *    project-resolution / persistence logic that link already owns.
+ */
+
+const prResolve = require('./pr-resolve');
+const prFixTarget = require('./pr-fix-target');
+const { PrActionError } = require('./pr-action');
+
+// For ongoing auto-fix the checkout must persist across ticks, so "Clone & keep"
+// (engine/pr-clone-keep.js, P-ppa10007) is the implied selection when promoting a
+// PR whose repo is not yet a configured project. temp-clone discards its clone
+// after one push, so it can never back ongoing tracking.
+const TRACK_RECOMMENDED_TARGET = 'clone-keep';
+
+// ── Ref resolution ──────────────────────────────────────────────────────────
+
+/**
+ * Resolve `{ url }` (raw PR URL / canonical id), an already-normalized ref, or a
+ * plan carrying `.ref` into a normalized PR ref. Throws `PrActionError` (400) on
+ * missing/unrecognized input so the dashboard reflects a 400 — mirrors the
+ * read-only and choice-surface paths.
+ */
+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);
+}
+
+// ── Choice surface (Clone & keep implied) ─────────────────────────────────────
+
+/**
+ * The Command Center text presenting the promotion choice for an unconfigured
+ * repo. It is the fix choice surface, re-flavored for ongoing tracking: Clone &
+ * keep is recommended because temp clone is discarded after one push.
+ */
+function buildPrTrackTargetPrompt(plan) {
+  const prId = (plan && (plan.prId || (plan.ref && plan.ref.id))) || 'this pull request';
+  const lines = [
+    `Tracking ${prId} for auto-fix needs a PERSISTENT checkout, but its repo is not a configured project.`,
+    'Choose an execution target before anything is cloned (nothing is cloned until you pick):',
+    '',
+  ];
+  for (const t of prFixTarget.EXECUTION_TARGETS) {
+    const tag = t.id === TRACK_RECOMMENDED_TARGET
+      ? ' [recommended for ongoing tracking]'
+      : (t.id === prFixTarget.DEFAULT_EXECUTION_TARGET ? ' [one-off default — discarded after one push]' : (t.trivialOnly ? ' [trivial only]' : ''));
+    lines.push(`- ${t.label}${tag} — ${t.description}`);
+  }
+  lines.push('');
+  lines.push(`Reply with one of: ${prFixTarget.EXECUTION_TARGET_IDS.join(', ')} (recommended: ${TRACK_RECOMMENDED_TARGET}). "Clone & keep" registers a persistent project so the existing pollers/auto-fix loop can track this PR going forward; temp clone leaves nothing behind and cannot back ongoing tracking.`);
+  return lines.join('\n');
+}
+
+// ── State machine ─────────────────────────────────────────────────────────────
+
+/**
+ * Plan the promotion of a PR to tracked auto-fix. The decision/routing entry
+ * point — it does NOT write anything.
+ *
+ * Delegates configured-project detection + the choice surface to
+ * engine/pr-fix-target.js (so the "never clone silently" invariant + the
+ * configured-vs-unconfigured logic live in exactly one place), then re-flavors
+ * the unconfigured branch for ongoing tracking (Clone & keep recommended).
+ *
+ * `input` — `{ url }` (raw PR URL / canonical id) or an already-normalized ref.
+ * `opts.config` — full config (for configured-project detection).
+ * `opts.prUrl` — original user-supplied URL (preferred in the surfaces).
+ *
+ * Returns one of:
+ *   - `{ status:'project-ready', ref, prId, prUrl, project, projectName,
+ *        recommendedTarget }` — the repo IS already a configured project; the
+ *     caller can enroll immediately (link with contextOnly:false). No clone.
+ *   - `{ status:'awaiting-target-choice', ref, prId, prUrl, options, default,
+ *        recommendedTarget, reason, prompt, modal }` — the repo is unconfigured;
+ *     PAUSE for the user to pick a persistent target. NOTHING is cloned here.
+ *
+ * Throws `PrActionError` (400) on bad input.
+ */
+function planPrTrack(input = {}, opts = {}) {
+  const fixPlan = prFixTarget.planPrFix(input, opts);
+
+  if (fixPlan.status === 'project-ready') {
+    return {
+      status: 'project-ready',
+      ref: fixPlan.ref,
+      prId: fixPlan.prId,
+      prUrl: fixPlan.prUrl,
+      project: fixPlan.project,
+      projectName: fixPlan.projectName,
+      recommendedTarget: TRACK_RECOMMENDED_TARGET,
+    };
+  }
+
+  // Unconfigured repo — reuse the SAME choice surface but recommend Clone & keep
+  // (ongoing tracking needs persistence). We override the default but keep the
+  // full option set so the user can still pick temp-clone/remote-patch knowingly.
+  const modal = {
+    ...fixPlan.modal,
+    default: TRACK_RECOMMENDED_TARGET,
+    recommendedTarget: TRACK_RECOMMENDED_TARGET,
+    title: 'Track for auto-fix — choose execution target',
+    message: 'Tracking this PR for ongoing auto-fix needs a persistent checkout. "Clone & keep" registers a project so the existing pollers/auto-fix loop can track it; temp clone is discarded after one push and cannot back ongoing tracking. Nothing is cloned until you choose.',
+  };
+
+  return {
+    status: 'awaiting-target-choice',
+    ref: fixPlan.ref,
+    prId: fixPlan.prId,
+    prUrl: fixPlan.prUrl,
+    options: fixPlan.options,
+    default: TRACK_RECOMMENDED_TARGET,
+    recommendedTarget: TRACK_RECOMMENDED_TARGET,
+    reason: 'Ongoing auto-fix needs a persistent checkout, so "Clone & keep" is recommended (temp clone is discarded after one push).',
+    prompt: buildPrTrackTargetPrompt(fixPlan),
+    modal,
+  };
+}
+
+/**
+ * Build the canonical enrollment signal for a PR (or plan/ref). Enrollment is a
+ * single field: `contextOnly:false` — that is the ONE thing
+ * `shared.isAutoManagedPrRecord` reads to decide a PR is auto-managed. The caller
+ * feeds `{ url, contextOnly }` to the existing manual-link path
+ * (dashboard.js#linkPullRequestForTracking), which creates the record if missing
+ * and promotes an existing context-only record (upsert refuses to demote).
+ *
+ * `observe:true` is included as the public/back-compat inverse used by
+ * `POST /api/pull-requests/observe` (observe → contextOnly = !observe).
+ *
+ * Returns `{ host, slug, number, prId, prUrl, url, contextOnly:false,
+ *            observe:true }`. Throws `PrActionError` (400) on bad input.
+ */
+function buildTrackEnrollment(input = {}, opts = {}) {
+  const ref = _resolveRef(input);
+  const prUrl = opts.prUrl
+    || (input && typeof input === 'object' ? (input.prUrl || input.url) : undefined)
+    || null;
+  const prId = _prId(ref);
+  return {
+    host: ref.host,
+    slug: ref.slug,
+    number: ref.number,
+    prId,
+    prUrl,
+    url: prUrl || prId,
+    // Canonical auto-managed signal (shared.isAutoManagedPrRecord).
+    contextOnly: false,
+    // Public/back-compat inverse for POST /api/pull-requests/observe.
+    observe: true,
+  };
+}
+
+module.exports = {
+  TRACK_RECOMMENDED_TARGET,
+  planPrTrack,
+  buildTrackEnrollment,
+  buildPrTrackTargetPrompt,
+  // Exported for testing.
+  _resolveRef,
+};