@yemi33/minions 0.1.2259 → 0.1.2261

package/docs/command-center.md

@@ -70,6 +70,25 @@ Any violation rejects the **whole turn** with a typed error envelope (`code: 'in
 
 **No new `engine.*` flag.** The limits above are module-level constants in `dashboard.js` (`CC_IMAGE_MAX_COUNT`, `CC_IMAGE_MAX_DECODED_BYTES`, `CC_IMAGE_MIME_ALLOWLIST`), not config keys; `engine/shared.js` `ENGINE_DEFAULTS` was not touched. Per CLAUDE.md Best Practice #9 (Settings parity), no Settings toggle is added because no new `engine.*` flag was introduced. Runtime selection that determines whether images are accepted is the existing `engine.ccCli` / `ccModel` override, which already has a Settings control.
 
+## Create-PR flow — checkout-mode-aware (PR #387)
+
+The "Create PR" chip offered by CC after a local edit follows the **same checkout pattern** as a normal dispatch for the project (`shared.resolveCheckoutMode`).
+
+- **`checkoutMode: 'live'`** (default for live-mode projects): unchanged behavior — the agent commits and pushes directly in the operator's live checkout as the CC system prompt instructs.
+- **`checkoutMode: 'worktree'`** (the default for most projects): the engine routes the changes through an isolated worktree deterministically and server-side so nothing depends on the LLM running git correctly.
+
+For worktree-mode projects the flow uses **`engine/create-pr-worktree.js`**:
+
+1. `prepareCreatePrWorktree` captures the live checkout's uncommitted changes (tracked diff via `git diff --binary HEAD` + untracked files) and applies them into a fresh worktree on a `cc-pr/<project>-<uid>` branch. 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 (operator never loses work).
+2. The agent then commits, pushes, and opens the PR from inside the worktree.
+3. `cleanupCreatePrWorktree` removes the worktree, refusing any path without the `.minions-worktree` ownership marker.
+
+Dashboard endpoints added by this feature:
+- `POST /api/pr-action/prepare-create-pr-worktree` — called before the agent's git operations
+- `POST /api/pr-action/cleanup-create-pr-worktree` — called after the PR is open (or on failure)
+
+The `buildCreatePrFollowups` helper in `engine/pr-action.js` emits worktree-aware instructions for worktree mode and the legacy live-checkout instructions for live mode; `dashboard.js /api/pr-action/offer-create-pr` resolves the checkout mode and passes it through.
+
 ## Per-turn surfacing pipeline
 
 CC handler generates `ccTurnId = 'cct-' + shared.uid()` per request; injected into sysprompt AND prompt body via `_ccTurnHeaderPart(turnId)` (load-bearing: on resumed sessions `engine/llm.js` skips re-sending the sysprompt, so without body injection CC keeps the stale turn ID). Handler reads via `_readCcTurnIdHeader(req)` and calls `_recordCcTurnCreation(turnId, ...)` on success. End-of-turn: `_buildSyntheticActionResultsForTurn` produces synthetic `{action, result}` pairs (`_serverExecuted: true`). Client renders as standalone `role='action'` messages outside the assistant bubble. TTL: 5 min. Endpoints wired: `/api/work-items`, `/api/notes`, `/api/plan`, `/api/knowledge`, `/api/watches`.

package/docs/worktree-lifecycle.md

@@ -174,6 +174,40 @@ EPERM/EBUSY stragglers that the dispatch-end GC couldn't reap and sweeps
 the `git worktree list` registry for OUT-of-root entries the in-root
 scanner is blind to.
 
+### Scratch-dir skip and bounded reaper (PR #388)
+
+The worktree root (`<localPath>/../worktrees/`) is a **shared namespace**: it
+holds both engine-managed worktrees AND `.agent-temp` — the scratch base where
+dispatched agents and agent-run test suites write throwaway git repos. Before
+this fix, `cleanup.js` enumerated the worktree root one level deep on every
+cleanup cycle and called `removeWorktree` on each entry (which correctly
+refused — scratch repos are not worktrees). With 26k+ leaked scratch dirs that
+readdir + stat walk stalled the tick loop for minutes, surfacing as "engine
+stale" (process alive but `lastTickAt` minutes in the past).
+
+**Architectural invariant:** any dot-prefixed entry in the worktree root is
+infra / scratch, never a managed worktree. Engine-created worktree dir names
+(`buildWorktreeDirName`) are always `W-…` or `<project>-<branch>-<hash>` and
+never start with `.`. The predicate `shared.isWorktreeRootInfraEntry(name)`
+(returns `true` when `name` starts with `.`) is now applied at **both**
+on-disk enumeration sites — `cleanup.js` worktree scan and
+`worktree-gc.js#pruneOrphanWorktrees` — so the sweep is O(1) on scratch size
+regardless of backlog.
+
+**Bounded TTL reaper (`cleanup.js#reapAgentScratch`).** Skipping scratch
+prevents stalls but doesn't shrink the pile. `reapAgentScratch` deletes
+entries under `<worktreeRoot>/.agent-temp`
+(`shared.WORKTREE_SCRATCH_DIR_NAME`) whose `mtime` is older than **6 h**
+(comfortably above the 5 h `agentTimeout`, so only dead-dispatch scratch is
+touched). Scan is capped at **2,000 entries per cleanup cycle** so the reaper
+itself can never stall the tick on a huge backlog — it drains across cycles.
+Deletion is plain `fs.rmSync` (not `removeWorktree`) because scratch repos are
+not registered worktrees.
+
+When adding new code that enumerates the worktree root directory, apply
+`shared.isWorktreeRootInfraEntry(name)` to skip dot-prefixed entries before
+calling any `removeWorktree` path.
+
 ### Ownership marker — out-of-root GC only touches engine worktrees (W-mqecdoot)
 
 A project repo's `git worktree list` includes EVERY worktree registered

package/engine/create-pr-worktree.js

@@ -118,9 +118,17 @@ async function prepareCreatePrWorktree({
   }
 
   // 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 */ }
+  try {
+    await git(['-C', localPath, 'checkout', '--', '.']);
+    for (const rel of untracked) {
+      try { fsm.rmSync(path.join(localPath, rel.replace(/\/$/, '')), { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+  } catch (e) {
+    try { await git(['-C', localPath, 'worktree', 'remove', '--force', wtPath]); } catch { /* leak rather than double-throw */ }
+    throw new Error(
+      `prepareCreatePrWorktree: failed to restore live checkout — ${e.message}. ` +
+      `Worktree at ${wtPath} may need manual cleanup.`,
+    );
   }
 
   log('info', `[cc-create-pr] staged ${project.name} changes into isolated worktree ${wtPath} on branch ${branchName} (live checkout restored)`);

package/engine/shared.js

@@ -5720,14 +5720,32 @@ function resolveProjectRootDir(localPath, minionsDir) {
  * unaffected — it uses GH_TOKEN / the OS credential store, not files under the
  * home — and the operator's real `~/.copilot` (interactive copilot) is untouched.
  *
- * Placed on the MINIONS_DIR volume (copilot's session-store can grow to GBs, so
- * keep it off a possibly-full system drive) but OUTSIDE the repo, at the drive
- * root, so concurrent git branch switches in the working tree can never delete or
- * dirty it. Stable path so copilot session resume (`--resume`) stays consistent
- * across spawns. Falls back to the user home when no minionsDir is given.
+ * Placed OUTSIDE the repo so concurrent git branch switches in the working tree
+ * can never delete or dirty it, on the MINIONS_DIR volume (copilot's session-store
+ * can grow to GBs, so keep it off a possibly-full system drive). Stable path so
+ * copilot session resume (`--resume`) stays consistent across spawns. Falls back
+ * to the user home when no minionsDir is given.
+ *
+ * Base selection is cross-platform (W-copilot-home-posix-root): on Windows the
+ * MINIONS_DIR drive root (`C:\`, `D:\`, or a UNC share root) is user-writable, so
+ * we anchor there. On POSIX the filesystem root (`/`) is NOT user-writable — a
+ * home placed there can never be created (`mkdir` EACCES), `ensureAgentCopilotHome`
+ * fail-opens and returns the uncreatable path anyway, and every spawned
+ * `copilot --acp` / copilot agent then inherits a `COPILOT_HOME` it can't use and
+ * exits code 1 silently (surfaced in CC as "Load failed"). So when the drive root
+ * is the bare POSIX root we fall back to the user home — repo-external, writable,
+ * and on the user's own volume.
  */
 function resolveAgentCopilotHome(minionsDir) {
-  const base = minionsDir ? path.parse(path.resolve(String(minionsDir))).root : os.homedir();
+  let base;
+  if (minionsDir) {
+    const root = path.parse(path.resolve(String(minionsDir))).root;
+    // The POSIX filesystem root ('/') is not user-writable; Windows drive/UNC
+    // roots are. Anchor at the user home in the unwritable-root case.
+    base = (root === '/' || root === path.sep) ? os.homedir() : root;
+  } else {
+    base = os.homedir();
+  }
   return path.join(base, '.minions-agent-copilot-home');
 }
 

package/package.json

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