@yemi33/minions 0.1.2252 → 0.1.2254

package/dashboard.js

@@ -53,6 +53,7 @@ const steering = require('./engine/steering');
 const steeringStore = require('./engine/steering-store');
 const projectDiscovery = require('./engine/project-discovery');
 const prAction = require('./engine/pr-action');
+const createPrWorktree = require('./engine/create-pr-worktree');
 const prResolve = require('./engine/pr-resolve');
 const prFixTarget = require('./engine/pr-fix-target');
 const prTrack = require('./engine/pr-track');
@@ -13325,11 +13326,53 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const changedFileCount = porcelain.split('\n').map(s => s.trim()).filter(Boolean).length;
         const hasChanges = changedFileCount > 0;
         const branch = (typeof body?.branch === 'string' && body.branch.trim()) || currentBranch || '';
+        // The Create-PR action follows the SAME checkout pattern as a dispatch
+        // for this project: 'live' commits in the live checkout; 'worktree'
+        // routes the changes through an isolated worktree (so nothing is ever
+        // committed in the operator's live main). See engine/create-pr-worktree.js.
+        const checkoutMode = shared.resolveCheckoutMode(project);
         const followups = hasChanges
-          ? prAction.buildCreatePrFollowups({ project: projectName, branch, contextOnly: !!body?.contextOnly })
+          ? prAction.buildCreatePrFollowups({ project: projectName, branch, contextOnly: !!body?.contextOnly, checkoutMode })
           : [];
         recordCcTurnIfPresent(req, { kind: 'pr-action', id: '', title: `offer create-pr (${projectName})`, project: projectName, followups });
-        return jsonReply(res, 200, { ok: true, hasChanges, branch, changedFileCount, followups }, req);
+        return jsonReply(res, 200, { ok: true, hasChanges, branch, changedFileCount, checkoutMode, followups }, req);
+      } catch (e) {
+        return jsonReply(res, e.statusCode || 400, { error: e.message }, req);
+      }
+    }},
+
+    { method: 'POST', path: '/api/pr-action/prepare-create-pr-worktree', desc: 'Stage a worktree-mode project\'s uncommitted live-checkout changes into an ISOLATED git worktree and restore the live checkout clean (P-cc-createpr-checkout-mode). The Create-PR action calls this for projects whose checkoutMode is "worktree" so the subsequent commit/push/PR happen off the operator tree — never committing to the live main. Safe ordering: the worktree is populated and verified BEFORE the live checkout is touched; on apply failure the worktree is removed and the live checkout is left untouched. Returns {ok, worktreePath, branch, baseBranch, baseSha, trackedChanged, untrackedCount}; {ok:false, reason:"no-changes"} when the tree is clean.', params: 'project (configured project name), branch (optional preferred branch name)', handler: async (req, res) => {
+      const body = await readBody(req);
+      try {
+        reloadConfig();
+        const projectName = typeof body?.project === 'string' ? body.project.trim() : '';
+        if (!projectName) return jsonReply(res, 400, { error: 'project is required' }, req);
+        const project = shared.getProjects(CONFIG).find(p => p && p.name === projectName);
+        if (!project) return jsonReply(res, 404, { error: `unknown project: ${projectName}` }, req);
+        if (!project.localPath) return jsonReply(res, 400, { error: `project ${projectName} has no localPath` }, req);
+        const result = await createPrWorktree.prepareCreatePrWorktree({
+          project,
+          branch: typeof body?.branch === 'string' ? body.branch : undefined,
+          minionsDir: MINIONS_DIR,
+          engine: CONFIG.engine,
+          log: (lvl, msg) => console.log(msg),
+        });
+        return jsonReply(res, 200, result, req);
+      } catch (e) {
+        return jsonReply(res, e.statusCode || 400, { error: e.message }, req);
+      }
+    }},
+
+    { method: 'POST', path: '/api/pr-action/cleanup-create-pr-worktree', desc: 'Remove an isolated worktree created by /api/pr-action/prepare-create-pr-worktree once its PR has been pushed/opened (P-cc-createpr-checkout-mode). Refuses any path missing the minions ownership marker, so it can never delete an arbitrary directory.', params: 'project (configured project name), worktreePath (the path returned by prepare-create-pr-worktree)', handler: async (req, res) => {
+      const body = await readBody(req);
+      try {
+        reloadConfig();
+        const projectName = typeof body?.project === 'string' ? body.project.trim() : '';
+        const project = projectName ? shared.getProjects(CONFIG).find(p => p && p.name === projectName) : null;
+        const worktreePath = typeof body?.worktreePath === 'string' ? body.worktreePath.trim() : '';
+        if (!worktreePath) return jsonReply(res, 400, { error: 'worktreePath is required' }, req);
+        const result = await createPrWorktree.cleanupCreatePrWorktree({ worktreePath, project });
+        return jsonReply(res, 200, result, req);
       } catch (e) {
         return jsonReply(res, e.statusCode || 400, { error: e.message }, req);
       }

package/engine/cleanup.js

@@ -425,6 +425,39 @@ function _killProcessInWorktree(dir, activeProcesses, activeIds) {
   } catch {} // tmp dir may not exist
 }
 
+// Agent scratch (`.agent-temp` under the worktree root) holds throwaway git
+// repos written by dispatched agents + the test-suite-run-by-agents. Nothing
+// owns its lifecycle, so it accumulates unboundedly (observed: 26k+ dirs). The
+// worktree sweeps now SKIP it (shared.isWorktreeRootInfraEntry), so the pile no
+// longer stalls the tick loop — but it still needs bounded hygiene. This reaps
+// entries whose mtime is older than the TTL via plain fs deletion (NOT
+// removeWorktree — these are standalone repos, not worktrees). Bounded per pass
+// so the reaper itself can never stall the tick on a huge backlog; it drains
+// across cleanup cycles.
+const AGENT_SCRATCH_TTL_MS = 6 * 60 * 60 * 1000; // 6h — comfortably > agentTimeout (5h), so only dead-dispatch scratch is reaped
+const AGENT_SCRATCH_MAX_SCAN_PER_CLEANUP = 2000;
+
+function reapAgentScratch(worktreeRoot) {
+  const scratchDir = path.join(worktreeRoot, shared.WORKTREE_SCRATCH_DIR_NAME);
+  let names;
+  try { names = fs.readdirSync(scratchDir); } catch { return 0; } // no scratch dir → nothing to do
+  const cutoff = Date.now() - AGENT_SCRATCH_TTL_MS;
+  let reaped = 0;
+  const limit = Math.min(names.length, AGENT_SCRATCH_MAX_SCAN_PER_CLEANUP);
+  for (let i = 0; i < limit; i++) {
+    const full = path.join(scratchDir, names[i]);
+    let stat;
+    try { stat = fs.statSync(full); } catch { continue; }
+    if (stat.mtimeMs >= cutoff) continue; // recent — may belong to a live dispatch
+    try { fs.rmSync(full, { recursive: true, force: true }); reaped++; }
+    catch { /* locked / in use — leave it for a later pass */ }
+  }
+  if (reaped > 0) {
+    log('info', `Reaped ${reaped} stale agent-scratch entries (>${Math.round(AGENT_SCRATCH_TTL_MS / 3600000)}h) from ${scratchDir}`);
+  }
+  return reaped;
+}
+
 // ─── Cleanup Orchestrator ────────────────────────────────────────────────────
 
 async function runCleanup(config, verbose = false) {
@@ -685,6 +718,8 @@ async function runCleanup(config, verbose = false) {
 
   // 3. Clean git worktrees for merged/abandoned PRs
   const _attemptedWorktreePaths = new Set(); // dedup across projects sharing a worktreeRoot
+  const _reapedScratchRoots = new Set();     // reap each worktree root's .agent-temp once per cleanup
+  cleaned.agentScratch = 0;
   for (const project of projects) {
     const root = project.localPath ? path.resolve(project.localPath) : null;
     if (!root || !fs.existsSync(root)) continue;
@@ -698,6 +733,14 @@ async function runCleanup(config, verbose = false) {
 
     for (const worktreeRoot of worktreeRoots) {
 
+    // Bounded TTL reaper for the agent-scratch dir under this worktree root
+    // (once per unique root). Plain fs deletion — these are standalone repos,
+    // not worktrees, so removeWorktree (correctly) refuses them.
+    if (!_reapedScratchRoots.has(worktreeRoot)) {
+      _reapedScratchRoots.add(worktreeRoot);
+      try { cleaned.agentScratch += reapAgentScratch(worktreeRoot); } catch (_e) { /* best-effort */ }
+    }
+
     // Get PRs for this project
     const prs = safeJson(projectPrPath(project)) || [];
     const mergedBranches = new Set();
@@ -714,6 +757,12 @@ async function runCleanup(config, verbose = false) {
       const allDirs = [];
       const topDirs = fs.readdirSync(worktreeRoot);
       for (const dir of topDirs) {
+        // Skip infra/scratch dirs (`.agent-temp`, `.git`, …). They are never
+        // managed worktrees, and recursing into them (the else branch below)
+        // would readdir + stat their entire contents — `.agent-temp` routinely
+        // holds thousands of throwaway test/agent git repos, and walking that
+        // pile every cleanup cycle stalls the engine tick loop ("engine stale").
+        if (shared.isWorktreeRootInfraEntry(dir)) continue;
         const dirPath = path.join(worktreeRoot, dir);
         try { if (!fs.statSync(dirPath).isDirectory()) continue; } catch { continue; }
         // Check if this is a git worktree (has .git file) or a parent directory
@@ -1672,4 +1721,5 @@ module.exports = {
   getWorktreeBranch,         // exported for lifecycle cleanup
   cleanupMergedPrLocalBranch, // exported for lifecycle cleanup and testing
   collectPhantomBranchesForProject, // P-e0b4f7a5 — exported for testing
+  reapAgentScratch,                 // exported for testing
 };

package/engine/create-pr-worktree.js

@@ -0,0 +1,179 @@
+/**
+ * engine/create-pr-worktree.js — checkout-mode-aware Create-PR staging.
+ *
+ * Background (the bug this fixes): the CC "Create PR" flow has the LLM commit /
+ * branch / push directly in the project's LIVE operator checkout
+ * (`project.localPath`). For a `checkoutMode: "worktree"` project that is wrong —
+ * a misstep by the LLM (committing before branching, freelancing `git pull`)
+ * leaks commits / merges onto the operator's `main`. The Create-PR action must
+ * follow the SAME checkout pattern as a normal dispatch for that project:
+ *   - `live`     → operate in the live checkout (handled by the existing flow);
+ *   - `worktree` → operate in an isolated git worktree, never the live checkout.
+ *
+ * This module implements the `worktree` path. `prepareCreatePrWorktree` moves the
+ * uncommitted edits CC made in the live checkout into a fresh worktree (created
+ * off the same base commit, on a new branch) and then restores the live checkout
+ * clean — DETERMINISTICALLY, server-side, so nothing relies on the LLM running
+ * git correctly. CC is then told to commit / push / open the PR inside the
+ * returned worktree path, and to call `cleanupCreatePrWorktree` when done.
+ *
+ * Safety ordering: the worktree is populated and verified BEFORE the live
+ * checkout is touched. If applying the diff fails, the worktree is removed and
+ * the live checkout is left exactly as it was — the operator never loses work.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+
+const PATCH_APPLY_TIMEOUT_MS = 120000;
+
+/**
+ * Move a worktree-mode project's uncommitted live-checkout changes into an
+ * isolated worktree and restore the live checkout clean.
+ *
+ * @returns {Promise<{ ok:true, worktreePath, branch, baseBranch, baseSha,
+ *   trackedChanged:boolean, untrackedCount:number } | { ok:false, reason:string }>}
+ * @throws on a git/fs failure AFTER which the live checkout is guaranteed
+ *   untouched (the operator keeps their work).
+ */
+async function prepareCreatePrWorktree({
+  project, branch, minionsDir, engine, log = () => {}, _git, _fs,
+} = {}) {
+  const git = _git || ((args, opts) => shared.shellSafeGit(args, opts));
+  const fsm = _fs || fs;
+  if (!project || typeof project !== 'object') {
+    throw new Error('prepareCreatePrWorktree: project object required');
+  }
+  const localPath = project.localPath;
+  if (!localPath) {
+    throw new Error('prepareCreatePrWorktree: project.localPath required');
+  }
+  const mainBranch = (project.mainBranch && String(project.mainBranch).trim()) || 'main';
+
+  // 1. Capture the uncommitted state from the live checkout.
+  const baseSha = (await git(['-C', localPath, 'rev-parse', 'HEAD'])).trim();
+  if (!/^[0-9a-f]{7,40}$/i.test(baseSha)) {
+    throw new Error(`prepareCreatePrWorktree: could not resolve HEAD in ${localPath} (got ${JSON.stringify(baseSha)})`);
+  }
+  // `git diff HEAD --binary` captures staged + unstaged tracked changes
+  // (including deletions and binary deltas) as a single patch.
+  const trackedDiff = await git(['-C', localPath, 'diff', '--binary', 'HEAD']);
+  const porcelain = await git(['-C', localPath, 'status', '--porcelain']);
+  const untracked = porcelain
+    .split('\n')
+    .filter(l => l.startsWith('?? '))
+    .map(l => l.slice(3).trim())
+    .filter(Boolean);
+  const hasTracked = !!trackedDiff.trim();
+  if (!hasTracked && untracked.length === 0) {
+    return { ok: false, reason: 'no-changes' };
+  }
+
+  // 2. Create an isolated worktree off the SAME base commit the edits were made
+  //    against, on a NEW branch (so it never collides with `main` being checked
+  //    out in the live tree, and never commits onto a shared branch).
+  const uid = shared.uid();
+  const sanitized = String(project.name || 'project').replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 40) || 'project';
+  const requested = branch && String(branch).trim();
+  const branchName = (requested && /^[\w./-]{1,80}$/.test(requested) && requested !== mainBranch)
+    ? requested
+    : `cc-pr/${sanitized}-${uid}`;
+
+  let projectRoot;
+  try { projectRoot = shared.resolveProjectRootDir(localPath, minionsDir); }
+  catch (e) { throw new Error(`prepareCreatePrWorktree: cannot resolve project root for ${localPath} — ${e.message}`); }
+  const wtRel = (engine && engine.worktreeRoot) || shared.ENGINE_DEFAULTS.worktreeRoot;
+  const worktreesBase = path.resolve(projectRoot, wtRel);
+  const wtPath = path.join(worktreesBase, `cc-createpr-${sanitized}-${uid}`);
+  try { fsm.mkdirSync(worktreesBase, { recursive: true }); } catch { /* best-effort; worktree add will surface a real failure */ }
+
+  await git(
+    ['-C', localPath, 'worktree', 'add', '-b', branchName, wtPath, baseSha],
+    { timeout: shared.ENGINE_DEFAULTS.worktreeCreateTimeout },
+  );
+  try { shared.writeWorktreeOwnerMarker(wtPath, { source: 'cc-create-pr', project: project.name }); } catch { /* marker is best-effort */ }
+
+  // 3. Reproduce the live-checkout changes inside the worktree. If anything here
+  //    fails, tear the worktree down and leave the live checkout untouched.
+  try {
+    if (hasTracked) {
+      const patchFile = path.join(wtPath, `.cc-createpr-${uid}.patch`);
+      fsm.writeFileSync(patchFile, trackedDiff);
+      await git(['-C', wtPath, 'apply', '--whitespace=nowarn', patchFile], { timeout: PATCH_APPLY_TIMEOUT_MS });
+      try { fsm.unlinkSync(patchFile); } catch { /* ignore */ }
+    }
+    for (const rel of untracked) {
+      // `?? dir/` entries from porcelain are directories — copy their tree.
+      const src = path.join(localPath, rel);
+      const dst = path.join(wtPath, rel);
+      _copyRecursive(fsm, src, dst);
+    }
+  } catch (e) {
+    try { await git(['-C', localPath, 'worktree', 'remove', '--force', wtPath]); } catch { /* leak rather than throw a second error */ }
+    throw new Error(
+      `prepareCreatePrWorktree: failed to stage changes into the worktree — ${e.message}. ` +
+      'The live checkout was left untouched.',
+    );
+  }
+
+  // 4. The worktree now holds the changes — restore the live checkout clean.
+  await git(['-C', localPath, 'checkout', '--', '.']);
+  for (const rel of untracked) {
+    try { fsm.rmSync(path.join(localPath, rel.replace(/\/$/, '')), { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+
+  log('info', `[cc-create-pr] staged ${project.name} changes into isolated worktree ${wtPath} on branch ${branchName} (live checkout restored)`);
+  return {
+    ok: true,
+    worktreePath: wtPath,
+    branch: branchName,
+    baseBranch: mainBranch,
+    baseSha,
+    trackedChanged: hasTracked,
+    untrackedCount: untracked.length,
+  };
+}
+
+/**
+ * Remove a worktree previously created by prepareCreatePrWorktree. Refuses to
+ * touch a path that doesn't carry the minions ownership marker (so a bad/forged
+ * path can never delete an arbitrary directory).
+ */
+async function cleanupCreatePrWorktree({ worktreePath, project, _git, _fs } = {}) {
+  const git = _git || ((args, opts) => shared.shellSafeGit(args, opts));
+  const fsm = _fs || fs;
+  if (!worktreePath || typeof worktreePath !== 'string') {
+    throw new Error('cleanupCreatePrWorktree: worktreePath required');
+  }
+  if (!fsm.existsSync(worktreePath)) {
+    return { ok: true, alreadyGone: true };
+  }
+  // Guard: only ever remove a directory the engine stamped as its own worktree.
+  if (!shared.hasWorktreeOwnerMarker(worktreePath)) {
+    return { ok: false, reason: 'not-owned' };
+  }
+  const fromDir = (project && project.localPath) || worktreePath;
+  try {
+    await git(['-C', fromDir, 'worktree', 'remove', '--force', worktreePath]);
+  } catch (e) {
+    return { ok: false, reason: 'remove-failed', error: e.message };
+  }
+  return { ok: true };
+}
+
+// Copy a file or directory tree (untracked entries may be either).
+function _copyRecursive(fsm, src, dst) {
+  const st = fsm.statSync(src);
+  if (st.isDirectory()) {
+    fsm.mkdirSync(dst, { recursive: true });
+    for (const entry of fsm.readdirSync(src)) {
+      _copyRecursive(fsm, path.join(src, entry), path.join(dst, entry));
+    }
+  } else {
+    fsm.mkdirSync(path.dirname(dst), { recursive: true });
+    fsm.copyFileSync(src, dst);
+  }
+}
+
+module.exports = { prepareCreatePrWorktree, cleanupCreatePrWorktree };

package/engine/lifecycle.js

@@ -1966,6 +1966,89 @@ async function enforcePrAttachmentContract(type, meta, agentId, config, resultSu
   return { reason, itemId: meta.item.id, severity, phantom: isPhantom };
 }
 
+// W-mqsk1ip00006cbae — After a verify WI transitions to done, assert that a PR
+// exists: either a direct reference on the item (_pr/_prUrl) or a matching
+// entry in pull-requests.json for the plan (by sourcePlan). If no PR is found,
+// flip the WI to failed with failure_class: verify-missing-pr and write an
+// inbox alert so operators can investigate.
+//
+// Returns null on the happy path (PR found or type is not verify).
+// Returns { reason, severity: 'hard', failureClass: 'verify-missing-pr' } when
+// the guard fires so the caller can set skipDoneStatus = true.
+function enforceVerifyPrContract(type, meta, agentId, config, resultSummary) {
+  if (type !== WORK_TYPE.VERIFY) return null;
+  if (!meta?.item?.id) return null;
+
+  const item = meta.item;
+
+  // Fast path: direct PR reference stamped on the WI.
+  if (item._pr || item._prUrl) return null;
+
+  // Canonical tracker check: does any PR record list this WI in prdItems?
+  try {
+    if (hasCanonicalPrAttachment(item.id, config)) return null;
+  } catch (err) {
+    // If the check throws (e.g. unreadable PR file) we cannot confirm a PR
+    // exists, so fall through to the failure path.
+    log('warn', `enforceVerifyPrContract: canonical PR check failed for ${item.id}: ${err.message}`);
+  }
+
+  // Plan-level check: any PR with matching sourcePlan in project PR files.
+  if (item.sourcePlan) {
+    try {
+      const projects = shared.getProjects(config);
+      for (const p of projects) {
+        const prs = readOptionalJsonStrict(shared.projectPrPath(p), 'project pull-requests', Array.isArray) || [];
+        if (prs.some(pr => pr.sourcePlan === item.sourcePlan)) return null;
+      }
+      const centralPrs = readOptionalJsonStrict(path.join(MINIONS_DIR, 'pull-requests.json'), 'central pull-requests', Array.isArray) || [];
+      if (centralPrs.some(pr => pr.sourcePlan === item.sourcePlan)) return null;
+    } catch (err) {
+      log('warn', `enforceVerifyPrContract: sourcePlan PR check failed for ${item.id}: ${err.message}`);
+    }
+  }
+
+  // No PR found — flip WI to failed and surface an alert.
+  const failureClass = FAILURE_CLASS.VERIFY_MISSING_PR;
+  const reason = `Verify WI ${item.id} completed done but no PR was found ` +
+    `(no _prUrl/_pr on item, no canonical attachment, and no pull-requests.json entry for plan ` +
+    `${item.sourcePlan || '(none)'}). Flipped to failed so the plan does not silently advance. ` +
+    `(Branch: ${meta.branch || '(none)'}, agent: ${agentId})`;
+
+  const wiPath = resolveWorkItemPath(meta);
+  if (wiPath) {
+    mutateJsonFileLocked(wiPath, data => {
+      if (!Array.isArray(data)) return data;
+      const w = data.find(i => i.id === item.id);
+      if (!w) return data;
+      w.status = WI_STATUS.FAILED;
+      w._failureClass = failureClass;
+      w.failReason = reason;
+      w.failedAt = ts();
+      delete w.completedAt;
+      return data;
+    }, { skipWriteIfUnchanged: true });
+  }
+
+  if (item.sourcePlan) {
+    try { syncPrdItemStatus(item.id, WI_STATUS.FAILED, item.sourcePlan); } catch (e) { log('warn', `verify-missing-pr PRD sync: ${e.message}`); }
+  }
+
+  shared.writeToInbox('engine', `verify-missing-pr-${item.id}`,
+    `# Verify WI completed without a PR: ${item.id}\n\n` +
+    `**Agent:** ${agentId}\n` +
+    `**Work item:** \`${item.id}\` — ${item.title || ''}\n` +
+    `**Plan:** ${item.sourcePlan || '(none)'}\n` +
+    `**Branch:** ${meta.branch || '(none)'}\n\n` +
+    `${reason}\n` +
+    (resultSummary ? `\n## Agent summary\n${resultSummary}\n` : ''),
+    null,
+    { sourceItem: item.id, reason: 'verify-missing-pr' });
+
+  log('warn', reason);
+  return { reason, itemId: item.id, severity: 'hard', failureClass };
+}
+
 // ─── Post-Completion Hooks ──────────────────────────────────────────────────
 
 /**
@@ -5141,6 +5224,17 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
 
+  // W-mqsk1ip00006cbae — verify WI PR guard. After enforcePrAttachmentContract
+  // (which skips verify types), assert that a verify WI has a PR before
+  // allowing the done transition.
+  if (effectiveSuccess && meta?.item?.id && !skipDoneStatus && !noopRationale) {
+    const verifyContractFailure = enforceVerifyPrContract(type, meta, agentId, config, resultSummary);
+    if (verifyContractFailure?.severity === 'hard') {
+      completionContractFailure = completionContractFailure || verifyContractFailure;
+      skipDoneStatus = true;
+    }
+  }
+
   if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
     meta._agentId = agentId;
     if (noopRationale) {
@@ -5946,6 +6040,7 @@ module.exports = {
   deferNonTerminalCompletion,
   deferPhantomCompletion,
   enforcePrAttachmentContract,
+  enforceVerifyPrContract,
   markMissingPrAttachment,
   parseCompletionReportFile,
   resolveHarnessPropagated,

package/engine/pr-action.js

@@ -146,36 +146,62 @@ const CREATE_PR_FOLLOWUP = Object.freeze({ kind: 'create-pr', label: 'Create PR'
  *                  well-named branch" wording when absent.
  * `contextOnly`  — when true, the chip links the new PR as context-only instead
  *                  of auto-managed (the default is auto-managed / contextOnly:false).
+ * `checkoutMode` — the project's resolved checkout pattern
+ *                  (`shared.resolveCheckoutMode(project)`). The Create-PR action
+ *                  MUST follow the same pattern as a normal dispatch for that
+ *                  project: `'live'` operates in the live operator checkout
+ *                  (legacy behavior); `'worktree'` (the default) routes the
+ *                  changes through an isolated git worktree so nothing is ever
+ *                  committed in the operator's live `main`. Defaults to `'live'`
+ *                  for back-compat when a caller doesn't resolve it.
  *
  * Each chip: `{ kind:'create-pr', label, project, branch, message }` where
  * `message` is the Command Center turn the chip click should send.
  */
-function buildCreatePrFollowups({ project, branch, contextOnly = false } = {}) {
+function buildCreatePrFollowups({ project, branch, contextOnly = false, checkoutMode = 'live' } = {}) {
   const proj = (project && String(project).trim()) || '';
   if (!proj) return [];
   const br = branch && String(branch).trim() ? String(branch).trim() : '';
-  const branchClause = br
-    ? `(the working tree is on branch ${br}; if ${br} is the project's default/main branch, create a new well-named branch off it and commit there rather than committing to ${br} directly)`
-    : 'on a new well-named branch off the project main branch';
   const linkBody = contextOnly
     ? `{"url":"<new PR url>","project":"${proj}","contextOnly":true}`
     : `{"url":"<new PR url>","project":"${proj}","contextOnly":false}`;
   const trackNote = contextOnly
     ? 'so it is tracked but not auto-reviewed'
     : 'so the engine auto-manages it (review -> fix -> re-review -> auto-merge)';
-  // The original branch CC must return to once the PR is open, so the new PR
-  // branch is never left checked out in the shared operator working tree.
-  const restoreClause = br
-    ? `switch the working tree back to the ORIGINAL branch (${br})`
-    : 'switch the working tree back to the original branch it started on';
-  const message =
-    `Create a PR from the local changes you just made in the ${proj} project. ` +
-    (br ? `Remember the working tree's current branch (${br}) as the ORIGINAL branch to return to when done. ` : '') +
-    `Steps: (1) in that project's working tree, stage and commit the modified files with a clear conventional-commit message ${branchClause}; ` +
-    `(2) push the branch; (3) open a PR against the project's main branch using the right CLI for the repo host (gh for GitHub, az repos for ADO); ` +
-    `(4) link it to the tracker by calling POST /api/pull-requests/link with ${linkBody} ${trackNote}; ` +
-    `(5) finally, ${restoreClause} — do not leave the new PR branch checked out. ` +
-    `Then show me the PR URL.`;
+
+  let message;
+  if (checkoutMode === 'worktree') {
+    // Worktree-mode projects: the server moves the live-checkout changes into an
+    // isolated worktree and restores the live checkout clean, so the commit /
+    // push / PR all happen OFF the operator's tree. CC never runs git in the
+    // live checkout — that is what kept leaking commits onto `main`.
+    message =
+      `Create a PR from the local changes you just made in the ${proj} project. ` +
+      `This project uses isolated worktrees, so do NOT commit, branch, or push in its live checkout. ` +
+      `Steps: (1) call POST /api/pr-action/prepare-create-pr-worktree with {"project":"${proj}"} — the server moves your uncommitted changes into a fresh isolated worktree, restores the live checkout clean, and returns {worktreePath, branch, baseBranch}; ` +
+      `(2) run all git from inside worktreePath (use \`git -C <worktreePath> ...\`): stage and commit the changes on the returned branch with a clear conventional-commit message; ` +
+      `(3) push that branch; (4) open a PR against baseBranch using the right CLI for the repo host (gh for GitHub, az repos for ADO); ` +
+      `(5) link it by calling POST /api/pull-requests/link with ${linkBody} ${trackNote}; ` +
+      `(6) finally call POST /api/pr-action/cleanup-create-pr-worktree with {"project":"${proj}","worktreePath":"<worktreePath>"} to remove the worktree. ` +
+      `Never git-commit/-push in the live checkout. Then show me the PR URL.`;
+  } else {
+    // Live-checkout projects: operate in place, but branch off main and restore
+    // the original branch so the PR branch is never left checked out.
+    const branchClause = br
+      ? `(the working tree is on branch ${br}; if ${br} is the project's default/main branch, create a new well-named branch off it and commit there rather than committing to ${br} directly)`
+      : 'on a new well-named branch off the project main branch';
+    const restoreClause = br
+      ? `switch the working tree back to the ORIGINAL branch (${br})`
+      : 'switch the working tree back to the original branch it started on';
+    message =
+      `Create a PR from the local changes you just made in the ${proj} project. ` +
+      (br ? `Remember the working tree's current branch (${br}) as the ORIGINAL branch to return to when done. ` : '') +
+      `Steps: (1) in that project's working tree, stage and commit the modified files with a clear conventional-commit message ${branchClause}; ` +
+      `(2) push the branch; (3) open a PR against the project's main branch using the right CLI for the repo host (gh for GitHub, az repos for ADO); ` +
+      `(4) link it to the tracker by calling POST /api/pull-requests/link with ${linkBody} ${trackNote}; ` +
+      `(5) finally, ${restoreClause} — do not leave the new PR branch checked out. ` +
+      `Then show me the PR URL.`;
+  }
   return [{ kind: CREATE_PR_FOLLOWUP.kind, label: CREATE_PR_FOLLOWUP.label, project: proj, branch: br || null, message }];
 }
 

package/engine/shared.js

@@ -4359,6 +4359,7 @@ const FAILURE_CLASS = {
   WORKSPACE_MANIFEST_URL: 'workspace-manifest-url-forbidden',   // W-mq07avbk000m5543: out-of-scope external URL fetch. Non-retryable as-is.
   SPAWN_PHASE_STALL: 'spawn-phase-stall', // W-mq0e2dae000a003d: process spawned and ran startup-only events (MCP init / hooks) but never emitted real task progress; CPU usage stayed below threshold past the grace window. Engine kills the wedged child and treats this as retryable (fresh-session) so a re-spawn can clear a transient MCP wedge.
   OUTPUT_TRUNCATED: 'output-truncated',   // P-8e4c2a17: the agent streamed more stdout than the engine's hard capture cap (engine.js AGENT_OUTPUT_CAP_BYTES, 1MB) BEFORE the terminal `result` event arrived. The result (session id, completion block, final text) lives at the END of the stream, so it fell outside the captured window and parseOutput found nothing — the dispatch would otherwise fail as an opaque UNKNOWN and retry to death. Surfaced loudly with an actionable message; non-retryable (mechanical retry just reproduces the overflow — the agent must reduce output volume or the task must be split).
+  VERIFY_MISSING_PR: 'verify-missing-pr', // W-mqsk1ip00006cbae: a verify WI exited done but no PR was attached (neither _prUrl/_pr on the item nor a matching pull-requests.json entry for the plan). Flipped to failed so the plan doesn't silently advance without an E2E PR. Retryable — agent may have phantom-crashed before pushing the branch.
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 const ESCALATION_POLICY = {
@@ -5552,6 +5553,21 @@ function buildWorktreeDirName({
   return `${projectSlug}-${branchSlug}-${suffix}`;
 }
 
+// The worktree root (`<localPath>/../worktrees`) is a SHARED namespace: it holds
+// managed git worktrees AND infra/scratch dirs — most importantly `.agent-temp`,
+// the agent scratch base (`resolveAgentTempBaseDir`) where dispatched agents and
+// the test-suite-run-by-agents write thousands of throwaway git repos. Worktree
+// names from `buildWorktreeDirName` are ALWAYS `W-…` / `<project>-<branch>-<hash>`
+// and never dot-prefixed, so any dot-prefixed entry in the worktree root is infra
+// or scratch, never a managed worktree. The worktree sweeps MUST skip these — a
+// single `.agent-temp` accumulating thousands of entries otherwise makes the
+// sweep (which recurses one level into non-worktree dirs) readdir + stat the
+// whole pile every cleanup cycle, stalling the engine tick loop (engine "stale").
+const WORKTREE_SCRATCH_DIR_NAME = '.agent-temp';
+function isWorktreeRootInfraEntry(name) {
+  return typeof name === 'string' && name.length > 0 && name.charCodeAt(0) === 46; // '.'
+}
+
 /**
  * True when `childPath` is strictly nested within `parentPath` (descendant,
  * NOT the same path). Cross-platform via `path.relative`; resilient to mixed
@@ -8903,6 +8919,8 @@ module.exports = {
   deriveWorkItemBranchName,
   safeSlugComponent,
   buildWorktreeDirName, // exported for testing
+  isWorktreeRootInfraEntry,
+  WORKTREE_SCRATCH_DIR_NAME,
   isPathInside,
   isPathInsideOrEqual,
   parseWorktreePorcelain,

package/engine/worktree-gc.js

@@ -819,6 +819,8 @@ function pruneOrphanWorktrees(opts) {
       if (!ent || (typeof ent.isDirectory === 'function' && !ent.isDirectory())) continue;
       const name = ent.name || ent;
       if (typeof name !== 'string' || name.length === 0) continue;
+      // Skip infra/scratch dirs (`.agent-temp`, `.git`, …) — never worktrees.
+      if (shared.isWorktreeRootInfraEntry(name)) continue;
       projStats.scanned++;
       result.scanned++;
       const wtPath = path.join(wtParent, name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2252",
+  "version": "0.1.2254",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/prompts/cc-system.md

@@ -96,7 +96,11 @@ curl -s -X POST http://localhost:{{dashboard_port}}/api/pr-action/offer-create-p
   -H 'Content-Type: application/json' -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
   -d '{"project":"<project name>"}'
 ```
-This checks the project's working tree (`git status --porcelain`) and, when there are uncommitted changes, returns a **`[Create PR]`** follow-up chip to the user (same chip mechanism as the `pr-action` `[Comment]`/`[Fix once]`/`[Track for auto-fix]` chips). When the user clicks it, you'll receive a turn instructing you to commit → push → open the PR → link it to the tracker → switch the working tree back to the original branch (never leave the new PR branch checked out in the shared operator tree). Pass `"contextOnly":true` if the PR should be tracked-but-not-auto-reviewed; omit it to have the engine auto-manage the PR (review → fix → re-review → auto-merge). If `hasChanges` is `false`, there's nothing to PR — skip the offer. Don't commit/push on your own initiative; surface the chip and let the user decide.
+This checks the project's working tree (`git status --porcelain`) and, when there are uncommitted changes, returns a **`[Create PR]`** follow-up chip to the user (same chip mechanism as the `pr-action` `[Comment]`/`[Fix once]`/`[Track for auto-fix]` chips). When the user clicks it, you'll receive a turn with **explicit step-by-step instructions — follow them exactly**. The instructions adapt to the project's checkout pattern, so just do what the turn says:
+- **Worktree-mode projects** (the default): the turn tells you to first `POST /api/pr-action/prepare-create-pr-worktree {"project":"…"}`. The server moves your uncommitted changes into an **isolated worktree** and restores the live checkout clean, returning `{worktreePath, branch, baseBranch}`. You then run **all git from inside `worktreePath`** (`git -C <worktreePath> …`) to commit/push/open the PR, then `POST /api/pr-action/cleanup-create-pr-worktree` to remove it. **Never commit, branch, or push in the live checkout** — that leaks commits onto the operator's `main`.
+- **Live-mode projects**: the turn tells you to commit on a new branch off main in the live checkout and switch back to the original branch when done.
+
+Pass `"contextOnly":true` if the PR should be tracked-but-not-auto-reviewed; omit it to have the engine auto-manage the PR (review → fix → re-review → auto-merge). If `hasChanges` is `false`, there's nothing to PR — skip the offer. Don't commit/push on your own initiative; surface the chip and let the user decide.
 
 ## When to dispatch vs answer inline