@yemi33/minions 0.1.2251 → 0.1.2253

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');
@@ -299,6 +300,51 @@ try {
   });
 } catch { /* defensive — wiring is best-effort, queries probes still work without it */ }
 
+// opg-microsoft/minions#381 — watch each project's .git/HEAD with fs.watch so
+// a bare `git checkout` / `git switch` outside the dashboard immediately busts
+// the status cache rather than waiting for the next 4-second SPA poll to detect
+// the mtime change. When HEAD changes the watcher calls invalidateStatusCache()
+// which (a) clears _statusCache and (b) debounce-pushes the updated state to
+// connected SSE clients within ~500ms — zero polling lag for SSE consumers.
+//
+// The mtime-based polling in getStatusSlowStateMtimePaths + _projectGitRefFiles
+// (queries.js) remains as a belt-and-suspenders fallback for environments where
+// fs.watch is unreliable (network drives, some WSL mounts).
+const _projectHeadWatchers = new Map(); // localPath → fs.FSWatcher
+
+function _setupProjectHeadWatchers() {
+  const currentPaths = new Set(PROJECTS.filter(p => p && p.localPath).map(p => p.localPath));
+  // Close watchers for projects that are no longer configured.
+  for (const [localPath, watcher] of _projectHeadWatchers) {
+    if (!currentPaths.has(localPath)) {
+      try { watcher.close(); } catch { /* ignore close errors */ }
+      _projectHeadWatchers.delete(localPath);
+    }
+  }
+  // Add watchers for newly-configured projects.
+  for (const project of PROJECTS) {
+    if (!project || !project.localPath || _projectHeadWatchers.has(project.localPath)) continue;
+    let headPath = null;
+    try {
+      const resolvedGitDir = queries._resolveGitDir(project.localPath);
+      if (resolvedGitDir) headPath = path.join(resolvedGitDir, 'HEAD');
+    } catch { /* _resolveGitDir is best-effort */ }
+    if (!headPath) continue;
+    try {
+      const watcher = fs.watch(headPath, () => {
+        try { invalidateStatusCache(); } catch { /* best-effort */ }
+      });
+      watcher.on('error', () => {
+        // Silently discard watch errors (e.g. path deleted) — polling fallback handles it.
+        try { watcher.close(); } catch { /* ignore */ }
+        _projectHeadWatchers.delete(project.localPath);
+      });
+      _projectHeadWatchers.set(project.localPath, watcher);
+    } catch { /* fs.watch not available on this fs (network drive etc.) — polling covers it */ }
+  }
+}
+try { _setupProjectHeadWatchers(); } catch { /* best-effort */ }
+
 function resolveScheduleProjectValue(project, projects = PROJECTS) {
   if (project === undefined) return { project: undefined };
   const target = shared.resolveConfiguredProject(project, projects);
@@ -9042,6 +9088,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
       reloadConfig(); // Update in-memory project list immediately
       warmProjectGitStatusCache(); // Probe the new project's git status in the background
+      try { _setupProjectHeadWatchers(); } catch { /* best-effort */ } // opg#381: watch new project's HEAD
       // includeSlow: PROJECTS lives in the slow-state cache (60s TTL); without
       // flushing it, /api/status keeps returning the previous project list for
       // up to a minute after the add. Matches handleProjectsRemove's behavior.
@@ -13279,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/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/queries.js

@@ -1658,6 +1658,11 @@ let _kbCache = null;       // last good snapshot — never nulled by invalidate
 let _kbCacheTs = 0;
 let _kbCacheStale = true;  // invalidate marks stale; snapshot kept for sync readers
 let _kbRefreshPromise = null; // in-flight scan dedupe
+// Incremental-scan cache: filePath -> { mtimeMs, byteSize, entry }. Lets a
+// rescan reuse the derived entry for any file whose mtime+size are unchanged,
+// so the expensive readFile+parse only runs for genuinely-changed files. Keyed
+// off the live stat, so in-place edits (agent memory appends) are still caught.
+let _kbFileMetaCache = new Map();
 const KB_CACHE_TTL = 30000; // 30s — KB changes infrequently
 
 function invalidateKnowledgeBaseCache() {
@@ -1684,32 +1689,28 @@ async function _scanKnowledgeBase() {
   // ~30 large KB entries. `_flat()` materialises a fresh flat string via
   // Buffer round-trip so the cached entry no longer pins the parent file.
   const _flat = (s) => Buffer.from(String(s || ''), 'utf8').toString('utf8');
-  // Build the full (category, file) work list first, THEN process it with a
-  // bounded concurrency window. The KB tree holds thousands of files; the old
-  // unbounded `Promise.all(files.map(...))` per category fired thousands of
-  // concurrent readFile+stat ops at once, flooding the (default-4, now 16)
-  // libuv thread pool and starving every other fs-dependent dashboard request
-  // — including the /api/status poll — for tens of seconds, which is what
-  // tripped the "stale / unreachable" banner. Capping in-flight reads keeps
-  // the scan from monopolizing the pool. (Load-reduction audit 2026-06-24.)
+  // Incremental, bounded-concurrency scan. The KB tree holds thousands of files;
+  // re-reading every file's full content on each cache rebuild was the dominant
+  // disk load behind dashboard staleness (the readFile + parse + string-alloc of
+  // ~3.5k files, repeated every TTL expiry, on a disk already contended by live
+  // agents). Two defenses: (1) a per-file metadata cache keyed on mtime+size, so
+  // a rescan only re-reads files that actually changed — steady state is one
+  // light stat() per file and ~zero readFile; (2) a bounded in-flight window so
+  // the scan can't flood the libuv thread pool and starve /api/status (which
+  // trips the "stale" banner). (Load-reduction audit 2026-06-24.)
   const work = [];
   for (const cat of KB_CATEGORIES) {
     const catDir = path.join(KNOWLEDGE_DIR, cat);
     const files = (await fsp.readdir(catDir).catch(() => [])).filter(f => f.endsWith('.md'));
     for (const f of files) work.push({ cat, catDir, f });
   }
-  const scanOne = async ({ cat, catDir, f }) => {
-    const filePath = path.join(catDir, f);
-    const [content, stat] = await Promise.all([
-      fsp.readFile(filePath, 'utf8').catch(() => ''),
-      fsp.stat(filePath).catch(() => null),
-    ]);
+  const nextMetaCache = new Map();
+  const deriveEntry = (cat, f, content, sortTs) => {
     const titleMatch = content.match(/^#\s+(.+)/m);
     const title = _flat(titleMatch ? titleMatch[1].trim() : f.replace(/\.md$/, ''));
     const agentMatch = f.match(/^\d{4}-\d{2}-\d{2}-(\w+)-/);
     const dateMatch = f.match(/^(\d{4}-\d{2}-\d{2})/) || content.match(/^date:\s*(\d{4}-\d{2}-\d{2})$/m);
     const sourceMatch = content.match(/^source:\s*(.+)/m);
-    const sortTs = (stat && stat.mtimeMs) || 0;
     const displayDate = dateMatch ? _flat(dateMatch[1]) : (sortTs ? new Date(sortTs).toISOString().slice(0, 10) : '');
     return {
       cat, file: f, title,
@@ -1721,6 +1722,22 @@ async function _scanKnowledgeBase() {
       size: content.length,
     };
   };
+  const scanOne = async ({ cat, catDir, f }) => {
+    const filePath = path.join(catDir, f);
+    const stat = await fsp.stat(filePath).catch(() => null);
+    const sortTs = (stat && stat.mtimeMs) || 0;
+    // Reuse the cached derived entry when mtime+size are unchanged — skips the
+    // readFile + regex parse + string allocations entirely for stable files.
+    const cached = _kbFileMetaCache.get(filePath);
+    if (cached && stat && cached.mtimeMs === stat.mtimeMs && cached.byteSize === stat.size) {
+      nextMetaCache.set(filePath, cached);
+      return cached.entry;
+    }
+    const content = await fsp.readFile(filePath, 'utf8').catch(() => '');
+    const entry = deriveEntry(cat, f, content, sortTs);
+    nextMetaCache.set(filePath, { mtimeMs: sortTs, byteSize: stat ? stat.size : Buffer.byteLength(content), entry });
+    return entry;
+  };
   const entries = [];
   const KB_SCAN_CONCURRENCY = 16;
   let _next = 0;
@@ -1731,6 +1748,8 @@ async function _scanKnowledgeBase() {
     }
   };
   await Promise.all(Array.from({ length: Math.min(KB_SCAN_CONCURRENCY, work.length) }, worker));
+  // Swap in the rebuilt cache (drops metadata for files that were deleted).
+  _kbFileMetaCache = nextMetaCache;
   entries.sort((a, b) =>
     (b.sortTs || 0) - (a.sortTs || 0) ||
     (b.date || '').localeCompare(a.date || '') ||
@@ -2758,6 +2777,11 @@ function _projectGitRefFiles(localPath, configuredMainBranch) {
   if (!gitDir) return null;
   const commonGitDir = _resolveCommonGitDir(gitDir);
   const files = [
+    // opg-microsoft/minions#381 — track HEAD directly so a bare `git checkout`
+    // (which rewrites .git/HEAD but may not advance logs/HEAD when reflog is
+    // disabled or when the snapshot already reflects the post-checkout mtime)
+    // still triggers refsAdvanced=true and the gitStale marker on the next call.
+    path.join(gitDir, 'HEAD'),
     path.join(gitDir, 'logs', 'HEAD'),
     path.join(commonGitDir, 'FETCH_HEAD'),
   ];
@@ -3149,10 +3173,14 @@ function getStatusSlowStateMtimePaths(config) {
   // not into the per-worktree subdir. For the main worktree both
   // resolvers return the same gitdir, so the behavior collapses to the
   // expected `<localPath>/.git/{logs/HEAD,FETCH_HEAD}` pair.
+  // opg-microsoft/minions#381 — also track HEAD itself so `git checkout`
+  // (which always rewrites HEAD) busts the cache even when logs/HEAD is
+  // absent or was already captured at the post-checkout mtime.
   for (const project of projects) {
     if (!project || !project.localPath) continue;
     const gitDir = _resolveGitDir(project.localPath) || path.join(project.localPath, '.git');
     const commonGitDir = _resolveCommonGitDir(gitDir);
+    files.push(path.join(gitDir, 'HEAD'));
     files.push(path.join(gitDir, 'logs', 'HEAD'));
     files.push(path.join(commonGitDir, 'FETCH_HEAD'));
   }
@@ -3183,6 +3211,7 @@ module.exports = {
   _setProbeWatchdogForTest,
   _getProbeTimeoutsForTest,
   _getProjectGitStatusCacheForTest,
+  _resolveGitDir, // opg-microsoft/minions#381 — dashboard.js uses this to locate HEAD for fs.watch
   // W-mpftp7na000td0f4 — engine→dashboard cache-invalidation registry
   getStatusFastStateMtimePaths,
   getStatusSlowStateMtimePaths,

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 = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2251",
+  "version": "0.1.2253",
   "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