@yemi33/minions 0.1.2260 → 0.1.2262

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/cli.js

@@ -609,28 +609,6 @@ const commands = {
     try { shared.applyLegacyCcModelMigration(config, { logger: e.log }); }
     catch (err) { e.log('warn', `legacy ccModel migration failed: ${err.message}`); }
 
-    // One-time force-on of the CC worker pool. The pool has been the resolved
-    // default for copilot CC since PR #2492, but configs still carrying an
-    // explicit `ccUseWorkerPool: false` (set before the default flipped) stay
-    // opted out forever. Flip those to ON once, persisting the
-    // `engine._ccPoolForcedOnV1` marker so a deliberate later opt-out sticks.
-    // Disk-side re-derives from the on-disk copy so a concurrent dashboard
-    // write isn't clobbered; skipWriteIfUnchanged makes it a no-op once marked.
-    try {
-      const forced = shared.applyCcWorkerPoolForceOnMigration(config);
-      if (forced.changed) {
-        const configPath = path.join(shared.MINIONS_DIR, 'config.json');
-        shared.mutateJsonFileLocked(configPath, (onDisk) => {
-          shared.applyCcWorkerPoolForceOnMigration(onDisk);
-          return onDisk;
-        }, { defaultValue: {}, skipWriteIfUnchanged: true });
-        if (forced.flipped.length) {
-          e.log('info', `Forced CC worker pool ON — flipped explicit opt-out in: ${forced.flipped.join(', ')}`);
-          console.log(`  Forced CC worker pool ON (was explicitly off in: ${forced.flipped.join(', ')}).`);
-        }
-      }
-    } catch (err) { e.log('warn', `cc worker pool force-on migration failed: ${err.message}`); }
-
     // Repair work-item note links that broke before the rewriter covered
     // completion-report artifact links (W-mq1j85cj00055a8f). Notes the engine
     // auto-archived back then left the WI pill pointing at the gone

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

@@ -3523,51 +3523,6 @@ function _resetLegacyCcModelMigrationFlag() {
   _legacyCcModelMigrationLogged = false;
 }
 
-/**
- * One-time force-on for the CC worker pool.
- *
- * The pool has been the resolved default for copilot CC since PR #2492
- * (`resolveCcUseWorkerPool` returns true when the config has no explicit
- * value). But configs that carried an explicit `ccUseWorkerPool: false` —
- * set before the default flipped, or copied from an old template — stay
- * opted out forever. This migration flips those explicit-false opt-outs to
- * `true` ONCE, on both surfaces the value lives in (`engine.ccUseWorkerPool`
- * which the resolver reads, and `features.ccUseWorkerPool` which drives the
- * Settings toggle / `isFeatureOn`), so the two stay consistent.
- *
- * Idempotency: records `engine._ccPoolForcedOnV1` after running. Once that
- * marker is set the migration never touches the value again — so an operator
- * who *deliberately* turns the pool off afterward is never re-forced. The
- * marker is persisted even when nothing needed flipping, which is what lets a
- * later opt-out be distinguished from a never-migrated config.
- *
- * Pure + idempotent: safe to call in-memory then re-apply to the on-disk copy
- * under a lock (mirrors backfillProjectWorkSourceDefaults). Returns
- * `{ changed, flipped }` — `changed` true means the config was mutated (marker
- * set and/or values flipped) and should be persisted; `flipped` lists which
- * surfaces ('engine'/'features') were actually turned on.
- */
-function applyCcWorkerPoolForceOnMigration(config) {
-  const result = { changed: false, flipped: [] };
-  if (!config || typeof config !== 'object') return result;
-  const engine = (config.engine && typeof config.engine === 'object') ? config.engine : null;
-  if (!engine) return result; // no engine section — retry next start, harmless
-  if (engine._ccPoolForcedOnV1) return result; // already forced once; respect later opt-out
-
-  if (engine.ccUseWorkerPool === false) {
-    engine.ccUseWorkerPool = true;
-    result.flipped.push('engine');
-  }
-  const features = (config.features && typeof config.features === 'object') ? config.features : null;
-  if (features && features.ccUseWorkerPool === false) {
-    features.ccUseWorkerPool = true;
-    result.flipped.push('features');
-  }
-  engine._ccPoolForcedOnV1 = true; // marker — never force again
-  result.changed = true; // marker always needs persisting on first run
-  return result;
-}
-
 // ─── Runtime Config Preflight Warnings ──────────────────────────────────────
 //
 // Emit non-fatal warnings about runtime/CLI configuration drift. Consumed by
@@ -4362,13 +4317,6 @@ const FAILURE_CLASS = {
   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 = {
-  NO_RETRY: 'no-retry',         // CONFIG_ERROR, PERMISSION_BLOCKED — never retry
-  RETRY_SAME: 'retry-same',     // MERGE_CONFLICT, BUILD_FAILURE, MAX_TURNS — retry same agent
-  RETRY_FRESH: 'retry-fresh',   // TIMEOUT, SPAWN_ERROR — retry with fresh session
-  HUMAN_REVIEW: 'human-review', // EMPTY_OUTPUT, OUT_OF_CONTEXT — flag for human
-  AUTO: 'auto',                 // UNKNOWN, NETWORK_ERROR — use default retry logic
-};
 
 // Structured completion protocol — fields agents must produce in ```completion blocks
 const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'not_changed', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts', 'nonce', 'securityFlags'];
@@ -4724,51 +4672,6 @@ function agentCanUseRepo(agent, repoTarget) {
   return false;
 }
 
-/**
- * Check whether `agent` may invoke `toolName`. Case-sensitive comparison —
- * tool names are canonical (e.g. `Edit`, `Read`, `Bash`).
- *
- * Null/missing `allowed_tools` → permissive.
- * Empty array → denies everything.
- */
-function agentCanUseTool(agent, toolName) {
-  const manifest = resolveAgentManifest(agent);
-  if (manifest.allowed_tools == null) return true;
-  if (typeof toolName !== 'string' || toolName.length === 0) return false;
-  return manifest.allowed_tools.includes(toolName);
-}
-
-/**
- * Check whether `agent` may fetch `urlString`. Wildcard entries of the form
- * `*.example.com` match any subdomain AND the apex (`example.com`). Bare
- * `example.com` matches only the exact host.
- *
- * Null/missing `allowed_external_urls` → permissive.
- * Empty array → denies everything.
- * Malformed URL → denied (cannot extract host to compare).
- */
-function agentCanFetchUrl(agent, urlString) {
-  const manifest = resolveAgentManifest(agent);
-  if (manifest.allowed_external_urls == null) return true;
-  let host = '';
-  try {
-    host = new URL(String(urlString)).hostname.toLowerCase();
-  } catch { return false; }
-  if (!host) return false;
-  if (manifest.allowed_external_urls.length === 0) return false;
-  for (const raw of manifest.allowed_external_urls) {
-    const entry = String(raw).trim().toLowerCase();
-    if (!entry) continue;
-    if (entry.startsWith('*.')) {
-      const suffix = entry.slice(2);
-      if (host === suffix || host.endsWith('.' + suffix)) return true;
-    } else if (host === entry) {
-      return true;
-    }
-  }
-  return false;
-}
-
 /** Return the agent's effective memory scope. Unknown values fall back to 'shared'. */
 function agentMemoryScope(agent) {
   const manifest = resolveAgentManifest(agent);
@@ -8854,7 +8757,6 @@ module.exports = {
   resolveCopilotAgentDisabledMcpServers,
   resolveAgentHermeticHarness,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
-  applyCcWorkerPoolForceOnMigration,
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
@@ -8862,7 +8764,7 @@ module.exports = {
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
-  FAILURE_CLASS, ESCALATION_POLICY, COMPLETION_FIELDS,
+  FAILURE_CLASS, COMPLETION_FIELDS,
   HARNESS_USED_KINDS, HARNESS_USED_MAX_ENTRIES, HARNESS_USED_MAX_FIELD_LEN, normalizeHarnessUsed, groundHarnessUsed,
   DEFAULT_AGENT_METRICS,
   DEFAULT_AGENTS,
@@ -8874,8 +8776,6 @@ module.exports = {
   validateWorkspaceManifest,
   resolveAgentManifest,
   agentCanUseRepo,
-  agentCanUseTool,
-  agentCanFetchUrl,
   agentMemoryScope,
   mergeManifestAllowedTools,
   formatManifestRejection,

package/package.json

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