@yemi33/minions 0.1.2382 → 0.1.2384

package/bin/minions.js

@@ -912,6 +912,7 @@ function init() {
 
   // Copy with smart merge logic
   copyDir(PKG_ROOT, MINIONS_HOME, excludeTop, alwaysUpdate, neverOverwrite, isUpgrade, actions);
+  shared.syncBundledPersonalSkills(path.join(MINIONS_HOME, 'skills'), { homeDir: os.homedir() });
 
   // Create config from template if it doesn't exist
   const configPath = path.join(MINIONS_HOME, 'config.json');

package/dashboard/js/refresh.js

@@ -175,7 +175,8 @@ const RENDER_VERSIONS = {
   // Bumped to 3 by W-mqk2s8q1 (Advanced → Diagnostics: relocated the diag button).
   // Bumped to 4 by W-mqrdavob (Agents table: per-agent charter editor column).
   // Bumped to 5 by W-mr0qs0vw (Worker Pool: CC session idle-timeout field).
-  settings: 5,
+  // Bumped to 6 for the fleet ACP pool opt-in default and warning copy.
+  settings: 6,
 };
 const _sectionCache = {};
 const _lastValueByKey = {};

package/dashboard/js/settings.js

@@ -448,7 +448,7 @@ async function openSettings() {
     '<div class="settings-pane-sub">Persistent CC worker pool and git worktree provisioning. Tune these only if you see worktree-create timeouts or slow CC cold-spawns.</div>' +
     '<div class="settings-stack" style="margin-bottom:12px">' +
       settingsToggle('CC Worker Pool', 'set-ccUseWorkerPool', (e.ccUseWorkerPool === undefined ? ((e.ccCli || e.defaultCli) === 'copilot') : !!e.ccUseWorkerPool), 'Route Command Center / doc-chat through a persistent copilot --acp worker per tab instead of spawning a fresh CLI per turn. Copilot-only (Agent Client Protocol transport); Claude does not implement ACP, so this toggle has no effect when CC runtime is Claude. Default ON for copilot (cold-spawn ~20s on Windows); forced OFF for non-copilot CC runtimes regardless of this toggle.') +
-      settingsToggle('Agent Worker Pool', 'set-agentUseWorkerPool', e.agentUseWorkerPool !== false, 'Route fleet Copilot dispatches through persistent copilot --acp workers. Default ON; runtimes without ACP support ignore this setting.') +
+      settingsToggle('Agent Worker Pool', 'set-agentUseWorkerPool', e.agentUseWorkerPool === true, 'Route fleet Copilot dispatches through persistent copilot --acp workers. Default OFF while the newer fleet-pool lifecycle path stabilizes; runtimes without ACP support ignore this setting.') +
       // W-mq6f2fe0000557fa — opt-in: auto-kill orphan spawn-agent processes
       // holding a stuck worktree's cwd. Gated by safe-reap criteria (cmdline
       // matches spawn-agent.js + basename + age > agentTimeout * 2). Default

package/dashboard.js

@@ -26,7 +26,7 @@ const fs = require('fs');
 const path = require('path');
 const v8 = require('v8');
 const llm = require('./engine/llm');
-const { resolveRuntime } = require('./engine/runtimes');
+const { resolveRuntime, shouldSuppressPostMutationError } = require('./engine/runtimes');
 
 // Dashboard version stamp — captured at module load so it reflects the code actually running.
 // codeCommit is read via _readGitHeadShort (defined below — function declarations
@@ -1974,11 +1974,19 @@ function _countWorktrees() {
   try {
     const config = queries.getConfig();
     const projects = shared.getProjects(config);
-    let count = 0;
+    const worktreeRoots = new Map();
     for (const p of projects) {
-      const root = p.localPath ? path.resolve(p.localPath) : null;
-      if (!root) continue;
-      const wtRoot = path.resolve(root, config.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot);
+      if (!p.localPath) continue;
+      const wtRoot = path.resolve(
+        p.localPath,
+        config.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot,
+      );
+      const rootKey = shared._normalizeWorktreePath(wtRoot);
+      if (!worktreeRoots.has(rootKey)) worktreeRoots.set(rootKey, wtRoot);
+    }
+
+    let count = 0;
+    for (const wtRoot of worktreeRoots.values()) {
       try {
         for (const dir of fs.readdirSync(wtRoot)) {
           const dirPath = path.join(wtRoot, dir);
@@ -4678,6 +4686,7 @@ function _invokeDocChatViaPool({ prompt, model, effort, engineConfig, systemProm
   (async () => {
     try {
       sessionHandle = await ccWorkerPool.getSession({
+        runtime: llm._resolveRuntimeFor({ engineConfig }),
         tabId: tabKey,
         model,
         effort,
@@ -5345,13 +5354,15 @@ function _recoverPartialDocChatResponse(result, sessionKey) {
 function _shouldSuppressDocChatPostPatchError(ccError, finalize) {
   if (!finalize || finalize.edited !== true) return false;
   if (!ccError) return false;
-  // W-mpmwxni2000c25c7-a — accept both the legacy 'unknown-model' errorClass
-  // (still emitted by the dashboard preflight at _preflightModelCheck) and
-  // the new 'model-unavailable' code returned by copilot.parseError for
-  // invalid-model responses. Suppress in either case — the edit already
-  // landed, so the stale model error shouldn't surface to the user.
-  if (ccError.errorClass !== 'unknown-model' && ccError.errorClass !== 'model-unavailable') return false;
-  return String(ccError.runtime || '').toLowerCase() === 'copilot';
+  try {
+    const runtime = resolveRuntime(ccError.runtime);
+    return shouldSuppressPostMutationError(runtime, {
+      mutationApplied: true,
+      error: ccError,
+    });
+  } catch {
+    return false;
+  }
 }
 
 function _buildDocChatResponsePayload({
@@ -9447,6 +9458,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     if (!shared.resolveCcUseWorkerPool(CONFIG.engine)) return { skipped: 'pool-disabled' };
     if (!tabId) throw new Error('tabId required');
     const result = await ccWorkerPool.warmTab({
+      runtime: resolveRuntime(shared.resolveCcCli(CONFIG.engine)),
       tabId,
       model: CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel,
       effort: CONFIG.engine?.ccEffort || shared.ENGINE_DEFAULTS.ccEffort,
@@ -9823,6 +9835,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     (async () => {
       try {
         sessionHandle = await ccWorkerPool.getSession({
+          runtime: llm._resolveRuntimeFor({ engineConfig }),
           tabId: resolvedTabId,
           model,
           effort,
@@ -13614,6 +13627,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           status: 'enrolled',
           prId: linkResult.id,
           autoManaged,
+          resurrected: linkResult.resurrected === true,
           contextOnly: false,
           project: linkResult.targetProject?.name || 'central',
           projectName: plan.projectName || linkResult.targetProject?.name || null,
@@ -13623,7 +13637,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }
     }},
 
-    { method: 'POST', path: '/api/pr-action/offer-create-pr', desc: 'Offer a "Create PR" follow-up chip after Command Center makes a LOCAL code edit itself in a configured project (P-cc-createpr). Validates the project has uncommitted working-tree changes (git status --porcelain in project.localPath) and returns a create-pr follow-up chip — same CC-mediated shape as the pr-action chips, so the existing dashboard chip renderer/click handler light up unchanged. Returns {ok, hasChanges, branch, changedFileCount, followups}; followups is [] when there is nothing to PR. READ-ONLY: never stages/commits/pushes — clicking the chip routes a fresh CC turn that does the commit/push/PR-create/link.', params: 'project (configured project name), branch (optional — defaults to the working-tree current branch), contextOnly (optional bool — link the new PR as context-only instead of auto-managed)', handler: async (req, res) => {
+    { method: 'POST', path: '/api/pr-action/offer-create-pr', desc: 'Offer a "Create PR" follow-up chip for pre-existing operator changes in a configured project. Validates the project has uncommitted working-tree changes (git status --porcelain in project.localPath) and returns a create-pr follow-up chip. Returns {ok, hasChanges, branch, changedFileCount, followups}; followups is [] when there is nothing to PR. READ-ONLY: never stages/commits/pushes.', params: 'project (configured project name), branch (optional — defaults to the working-tree current branch), contextOnly (optional bool — link the new PR as context-only instead of auto-managed)', handler: async (req, res) => {
       const body = await readBody(req);
       try {
         reloadConfig();
@@ -13644,10 +13658,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         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);
+        // for this project: 'live' uses the live-checkout flow; 'worktree'
+        // copies changes into an isolated worktree and preserves the source.
+        const checkoutMode = shared.resolveCheckoutMode(project, shared.WORK_TYPE.IMPLEMENT);
         // Resolve the project's actual main/base branch instead of trusting
         // whatever `git rev-parse --abbrev-ref HEAD` returned as a safe base —
         // the live checkout may be sitting on a stale/topic branch whose
@@ -13663,7 +13676,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }
     }},
 
-    { 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) => {
+    { method: 'POST', path: '/api/pr-action/prepare-create-pr-worktree', desc: 'Copy a worktree-mode project\'s pre-existing operator changes into an ISOLATED git worktree without modifying the source checkout. Subsequent commit/push/PR operations happen only in the returned worktree. Returns {ok, worktreePath, branch, baseBranch, baseSha, trackedChanged, untrackedCount, sourceCheckoutPreserved}; {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();
@@ -13674,6 +13687,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         if (!project.localPath) return jsonReply(res, 400, { error: `project ${projectName} has no localPath` }, req);
         const result = await createPrWorktree.prepareCreatePrWorktree({
           project,
+          projects: shared.getProjects(CONFIG),
           branch: typeof body?.branch === 'string' ? body.branch : undefined,
           minionsDir: MINIONS_DIR,
           engine: CONFIG.engine,
@@ -13693,7 +13707,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         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 });
+        const result = await createPrWorktree.cleanupCreatePrWorktree({
+          worktreePath,
+          project,
+          projects: shared.getProjects(CONFIG),
+        });
         return jsonReply(res, 200, result, req);
       } catch (e) {
         return jsonReply(res, e.statusCode || 400, { error: e.message }, req);

package/docs/completion-reports.md

@@ -90,6 +90,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 |---|---|---|
 | `noop` | boolean | Canonical no-op signal. See [No-op semantics](#no-op-semantics). |
 | `noopReason` | string | Human-readable rationale shown when `noop: true`. Falls back to `summary` if absent. |
+| `reviewFindingResolution` | object | Required when a review-feedback fix leaves the PR branch unchanged. Shape: `{findingId, disposition, currentCodeEvidence}`; see [Review-fix no-op evidence](#review-fix-no-op-evidence). |
 | `files_changed` | string \| array | Comma-separated list (or array) of key files changed. |
 | `affected_files` | string[] | Optional array of relative file paths this dispatch touched or plans to touch. Used by the dispatcher to emit a conflict warning (`WI <new-id> may conflict with in-progress <existing-id> on files: [list]`) when a new WI's `affected_files` overlaps with an in-progress WI's `affected_files`. Logging-only — dispatch is never blocked. Stored back onto the work item after completion so re-dispatches can also participate in overlap detection. |
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
@@ -223,7 +224,7 @@ All three classes are **never retryable** — they signal a structural/environme
 
 ## No-op semantics
 
-A no-op completion declares that the agent correctly **declined** to do the work — the change was already shipped on master, the dispatch premise was wrong, the flagged review comment was an author-note, etc.
+A no-op completion declares that the agent correctly **declined** to do the work — the change was already shipped on master, the dispatch premise was wrong, or an exact review finding was proven resolved/invalid with current-code evidence.
 
 To signal a no-op:
 
@@ -245,6 +246,24 @@ Engine behavior when `noop: true` (`engine/lifecycle.js` `parseCompletionNoop` +
 
 Without `noop: true`, an empty PR field will be flagged as a missing-PR-attachment failure and auto-retried up to `ENGINE_DEFAULTS.maxRetries` times.
 
+### Review-fix no-op evidence
+
+Review-feedback fixes have a stricter no-op contract because all agents can share one platform credential. `viewerDidAuthor: true` does not identify the Minions agent that authored a finding, and reviewer/fixer agent equality is allowed.
+
+If the live PR branch did not advance, the completion must set `noop: true` and include:
+
+```json
+{
+  "reviewFindingResolution": {
+    "findingId": "review-0123456789abcdef",
+    "disposition": "already-resolved",
+    "currentCodeEvidence": "engine/lifecycle.js:4600 already enforces the condition; test/unit/example.test.js covers it."
+  }
+}
+```
+
+The `findingId` is injected into the fix playbook from trusted `minionsReview` provenance. `disposition` is `already-resolved` or `invalid`, and `currentCodeEvidence` must cite a current `file:line` or commit. An identity-only no-op is retried and does not increment `_noOpFixes`.
+
 ## PR-comment follow-ups
 
 Fix and review agents can spin off new Minions work items in response to PR

package/docs/keep-processes.md

@@ -22,7 +22,7 @@ Set `meta.keep_processes: true` on the WI; agent writes `agents/<id>/keep-pids.j
 {
   "pids": [12345],                 // ≤5 entries
   "purpose": "gradle daemon for follow-up test WI",
-  "cwd": "D:/repos/my-android-app", // MUST be a real git worktree
+  "cwd": "<MINIONS_AGENT_CWD>",      // assigned dispatch root or a subdirectory
   "ports": [8080],                  // advisory, engine doesn't bind
   "expires_at": "2026-04-29T00:00:00Z", // TTL ≤1440 min; default 60
   "written_by": "ripley",
@@ -42,6 +42,11 @@ Set `meta.keep_processes: true` on the WI; agent writes `agents/<id>/keep-pids.j
 
 - **PIDs:** ≤5 per sidecar.
 - **TTL:** ≤1440 min (24h). Default 60.
-- **Cwd:** must exist and resolve to inside a git worktree (`requireGitWorkdir: true`). Monorepo subdirs walk up to `gitWorktreeMaxParentDepth` (default 6).
+- **Cwd:** must exist, resolve inside a git worktree, and stay at or below the current dispatch root from `MINIONS_AGENT_CWD`. Monorepo subdirs are allowed. In worktree mode, pointing at `project.localPath` is rejected before the wrapper decides which descendants survive. `keep_processes` dispatches use the cold spawn wrapper rather than the ACP pool so descendant ownership remains enforceable.
+
+After acceptance, the engine adds project/work-type/checkout-mode/dispatch-root
+provenance to the sidecar. Boot sweep uses it to kill and unlink any retained
+process whose cwd now overlaps a worktree-mode operator checkout (including
+legacy sidecars from the old read-only-in-`localPath` behavior).
 
 See also: [`CLAUDE.md`](../CLAUDE.md) → **Agent Spawn**, [managed-spawn.md](managed-spawn.md).

package/docs/live-checkout-mode.md

@@ -78,7 +78,7 @@ This is **DESTRUCTIVE** — tracked WIP and untracked files can be permanently u
 
 #### 2c. Stale `.git/index.lock` self-heal (W-mr3tayu4)
 
-Before any preflight git command runs, `prepareLiveCheckout` calls the shared, age-gated `shared.removeStaleIndexLock(localPath)` to clear a leftover `.git/index.lock` from a crashed/killed git process. Live mode never resets/cleans the operator tree, so nothing else would clear it, and — since `LIVE_CHECKOUT_FAILED` is retryable — every automatic retry used to hit the same stale lock and fail identically forever until an operator deleted it by hand. The remover only touches locks older than 5 minutes, so a lock held by a currently-running git process is never removed out from under it. `engine.js`'s own worktree-mode lock cleanup now delegates to the same shared helper.
+Before any preflight git command runs, `prepareLiveCheckout` calls the shared, age-gated `shared.removeStaleIndexLock(localPath)` to clear a leftover `.git/index.lock` from a crashed/killed git process. Live mode never resets/cleans the operator tree, so nothing else would clear it, and — since `LIVE_CHECKOUT_FAILED` is retryable — every automatic retry used to hit the same stale lock and fail identically forever until an operator deleted it by hand. The remover only touches locks older than 5 minutes, so a lock held by a currently-running git process is never removed out from under it. Worktree-mode setup never calls this helper against `project.localPath`.
 
 ### 3. No implicit remote sync or force checkout
 
@@ -214,7 +214,7 @@ Enable it fleet-wide via **Settings → "Live-checkout auto-base-repair (fleet-w
 
 ## Dispatch-end auto-restore
 
-Live-mode agents run **in-place** in the operator's checkout, so when a dispatch ends the engine switches the tree back to the ref it was on before the agent ran. This runs on **every** terminal result — success, failure, timeout, crash — and also on **every restart-recovery reaping path**: the engine-restart re-attach orphan-completion path (`engine/cli.js`) AND the `engine/timeout.js` paths that reap a dispatch the engine lost the process handle for (`completeFromOutput` + the orphan sweep). All three route through the shared `maybeRestoreLiveCheckoutFromRecord(item, …)` helper (which fires from the *persisted* dispatch record — `originalRef`'s presence is the live-mode signal), so a live agent that spans an engine restart and finishes afterward never strands the checkout on the agent's branch. (Previously the timeout.js reaping paths had **no** restore wiring, which is exactly how a restart-spanning live dispatch left the operator stuck on `work/W-…`.)
+Live-mode agents run **in-place** in the operator's checkout, so when a dispatch ends the engine switches the tree back to the ref it was on before the agent ran. This runs on terminal results and restart-recovery reaping paths through `maybeRestoreLiveCheckoutFromRecord`. Restore now requires both persisted `checkoutMode: "live"` provenance (legacy records may use `originalRef`) and a current configured mode that still resolves live for the dispatch type. A worktree marker or current worktree mode fails closed before any Git probe.
 
 - **Original-ref capture.** `prepareLiveCheckout` records the operator's starting ref *before* the first checkout: `git symbolic-ref --short HEAD` → `{ originalRef:<branch>, originalRefType:'branch' }`, falling back to `git rev-parse HEAD` → `{ originalRef:<sha>, originalRefType:'detached' }`. `spawnAgent` persists `originalRef` / `originalRefType` onto the dispatch record via `mutateDispatch`, so the restore survives an engine restart, where the in-memory spawn closure is gone and only the persisted record remains.
 - **Self-healing dirty recovery (PL-live-checkout-reliability-hardening).** Before the plain checkout, if the tree is **dirty AND HEAD is on the agent branch** (and that branch differs from `originalRef`), the dirt is provably **agent-authored** — the engine created that branch and verified the tree clean before switching to it. The leftovers are committed onto the **agent branch** (`git add -A` + `git commit --no-verify -m "minions: auto-save agent WIP (dispatch …)"`), so the plain `git checkout <originalRef>` then succeeds and the operator tree returns clean. This is the fix for the *"no recovery from dirty checkout"* deadlock, where an agent's crash-leftover WIP refused the restore, stranded the tree dirty on the agent branch, and then made **every future WI** for that project fail `LIVE_CHECKOUT_DIRTY` until a human cleaned it. It only ever mutates the engine-created branch, never the operator's branch, never discards (the WIP lands as a visible, revertable commit / on its PR), and gitignored artifacts are never staged (so a tree dirty only with ignored build output never reaches here). Best-effort: a failed auto-commit falls through to the manual-recovery alert below.
@@ -229,7 +229,7 @@ The core invariant holds end-to-end through restore: **the engine only ever swit
 
 ## Create-PR chip safety (CC-initiated, separate from the dispatch path)
 
-The Command Center **"Create PR"** chip (`dashboard.js` → `POST /api/pr-action/offer-create-pr` → `engine/pr-action.js#buildCreatePrFollowups`) is a **separate, ad-hoc path** that opens a PR for a local edit Command Center just made in a live-checkout project. It does **not** go through `prepareLiveCheckout`, so the dirty-tree / orphaned-branch / mid-operation defenses above (Guarantees 2 & 5, dispatch-start self-heal) do **not** apply to it. This path needs its own equivalent safety contract, because it shares the same failure mode: the live checkout may be sitting on a stale/topic branch left over from a previous run, a manually-checked-out branch, or any other non-main state.
+Command Center never creates edits inside a configured project's `localPath`. The **"Create PR"** chip is only for pre-existing operator changes. In worktree mode, `prepareCreatePrWorktree` creates a fresh branch from `origin/<mainBranch>` (falling back to local main when no remote exists), applies only the uncommitted diff/untracked files, and leaves the source checkout unchanged. Topic commits from the operator's current branch cannot leak into the PR. Live-mode Create-PR remains a deliberate in-place flow and retains the base-branch protections below.
 
 **The bug it fixes (W-mr3jbpru).** The old live-mode chip message keyed its branch instruction off `git rev-parse --abbrev-ref HEAD` (the *current* branch) and only told the agent to branch off cleanly **if** that current branch already happened to be the project's main branch. If the checkout was on any other branch, the message told the agent to commit the new changes **directly onto that branch** — silently carrying all of that branch's unrelated commits into the new PR. There was no engine-side verification that the current branch was clean or at parity with main; it was trusted blindly. A user hit exactly this: a Create-PR chip PR ended up built on top of a leftover topic branch and carried unrelated diffs.
 
@@ -240,7 +240,7 @@ The Command Center **"Create PR"** chip (`dashboard.js` → `POST /api/pr-action
 3. If `git stash pop` reports a merge conflict (the stashed diff doesn't cleanly apply onto the fresh main tip), the message instructs the agent to **stop and surface the conflict** to the user rather than force-resolving it silently.
 4. The message **names the resolved main branch explicitly** (e.g. `origin/android`) instead of leaving "the project main branch" vague, so the always-branch-off-resolved-main rule is stated unambiguously.
 
-This mirrors, in CC-instruction form, what `prepareLiveCheckout` enforces engine-side for the dispatch path: never reuse whatever branch the live checkout happened to be on as the base for new work. The **worktree-mode** branch of `buildCreatePrFollowups` is unaffected — that path already routes the changes through an isolated worktree (`engine/create-pr-worktree.js`) so nothing is ever committed on the operator's `main`.
+This mirrors, in CC-instruction form, what `prepareLiveCheckout` enforces engine-side for the dispatch path: never reuse whatever branch the live checkout happened to be on as the base for new work. The **worktree-mode** branch copies existing changes to an isolated worktree without modifying the operator checkout.
 
 ## Operator workflow
 
@@ -362,11 +362,11 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 |---|---|
 | `engine/shared.js` — `CHECKOUT_MODES`, `validateCheckoutMode`, `resolveCheckoutMode`, `isLiveCheckoutProject` | Enum + validator + back-compat resolver (P-a3f9b201; consolidated W-mqiaw974). |
 | `engine/shared.js` — `resolveLiveCheckoutAutoReset` + `ENGINE_DEFAULTS.liveCheckoutAutoReset` | Pure precedence resolver (per-project boolean > fleet-wide engine default > false) + the fleet-wide default (OFF as of W-mrawgw4q000a6bff — was ON as of W-mqzbbhn2). Gates the dirty-tree auto-reset in `prepareLiveCheckout` (W-mqvejug6000eeb20); in `engine.js spawnAgent` only fires as a fallback after auto-stash fails/is disabled (W-mrawgw4q000a6bff). |
-| `engine/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live projects (P-a3f9b202). |
+| `engine/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live dispatches; project-bound worktree-mode read-only types request detached worktree placement. |
 | `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper by default: pre-mutation mid-operation / detached-HEAD preflight, original-ref capture, dirty check, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch`/`worktree-conflict` classification**, and opt-in destructive WIP cleanup (`reset --hard HEAD` + `clean -fd` + re-check + audit note) that preserves the branch and committed history. Git probes use a **50 MB maxBuffer**. |
 | `engine/live-checkout.js` — `restoreLiveCheckoutAtDispatchEnd` | Dispatch-end auto-restore (plain `git checkout <originalRef>`, never `--force`/reset/clean/stash, best-effort) + **self-healing dirty recovery** (auto-commit agent WIP onto the agent branch) + `live-checkout-failed-<dispatchId>` terminal-failure alert + `live-checkout-branch-<dispatchId>` fallback notify (now also on unexpected restore errors) (P-d9e6b2c4; self-heal PL-live-checkout-reliability-hardening). |
 | `engine/live-checkout.js` — `resolveLiveCheckoutAutoStash`, `performLiveCheckoutAutoStash`, `applyLiveCheckoutAutoStash` | Auto-stash resolver (per-project boolean, then fleet setting, then default true) + `git stash push --include-untracked` runner + stash/re-preflight orchestration. Engine never auto-pops (W-mqtvnnj1000357fa). |
-| `engine/live-checkout.js` — `maybeRestoreLiveCheckoutFromRecord` | Shared wrapper that fires the dispatch-end restore from a persisted dispatch record; used by `cli.js` + both `timeout.js` reaping paths so a restart-spanning live dispatch is never stranded (PL-live-checkout-reliability-hardening). |
+| `engine/live-checkout.js` — `maybeRestoreLiveCheckoutFromRecord` | Shared persisted-record restore wrapper; requires explicit live provenance plus current live configuration and fails closed for worktree mode. |
 | `engine.js` — `spawnAgent` live-mode block | Calls `prepareLiveCheckout`, delegates opt-in auto-stash to `applyLiveCheckoutAutoStash` on a dirty tree (W-mqtvnnj1000357fa), handles dirty / throw branches, gates `git worktree add` on `!liveMode` (P-a3f9b204). |
 | `engine.js` — `spawnAgent` mid-op / detached-HEAD refusal block | Emits `LIVE_CHECKOUT_MID_OPERATION`, writes `live-checkout-blocked-<wi-id>` alert, stamps `_pendingReason: 'live_checkout_mid_operation'` / `'live_checkout_detached_head'` (P-c5a1f3b8). |
 | `engine.js` — `spawnAgent` originalRef persistence | Persists `originalRef` / `originalRefType` onto the dispatch record via `mutateDispatch` so restore survives an engine restart (P-c5a1f3b8). |
@@ -376,7 +376,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `engine.js` — dispatcher `liveProjectsInUse` set | Per-project mutating-concurrency cap (P-a3f9b205). |
 | `engine.js` — worktree-pool / orphan-GC short-circuits | `worktreePath===null` no-ops in live mode (P-a3f9b206). |
 | `engine/cleanup.js` — `runPeriodicWorktreeSweep` live filter | Excludes live-checkout projects from the registry-derived periodic worktree GC so the operator's primary checkout never enters the GC decision surface (PL-live-checkout-reliability-hardening). |
-| `engine/create-pr-worktree.js` — `prepareCreatePrWorktree` step-4 restore | `reset --hard HEAD` (not the index-leaking `checkout -- .`) + retried untracked removal + `liveTreeDirty` surfaced + `shared.removeWorktree` teardown (PL-live-checkout-reliability-hardening). |
+| `engine/create-pr-worktree.js` — `prepareCreatePrWorktree` | Copies pre-existing operator changes into an isolated worktree and returns `sourceCheckoutPreserved: true`; never resets, cleans, checks out, or deletes source files. |
 | `engine/pr-action.js` — `buildCreatePrFollowups({ …, mainBranch })` live-mode message | CC "Create PR" chip instruction. In live mode the PR is ALWAYS built on a fresh branch off `origin/<mainBranch>` (stash → fetch → `checkout -B` → pop → commit → push → PR → restore), never reusing the current branch as the base; stop-on-stash-pop-conflict. `dashboard.js` `POST /api/pr-action/offer-create-pr` resolves `mainBranch` via `shared.resolveMainBranch` and threads it in (W-mr3jbpru). |
 | `dashboard/js/settings.js` — checkoutMode dropdown + chip + `set-liveCheckoutAutoReset` fleet toggle | Operator-facing UI; the fleet-wide auto-reset toggle persists to `engine.liveCheckoutAutoReset` (per-project UI deferred — config.json only) (P-a3f9b207; auto-reset toggle W-mqvejug6000eeb20). |
 | `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring,live-checkout-auto-stash,live-checkout-stash-before-reset}.test.js` | Wiring and contract tests (P-a3f9b208; auto-stash helpers W-mqtvnnj1000357fa; stash-before-reset ordering W-mrawgw4q000a6bff). |

package/docs/managed-spawn.md

@@ -35,7 +35,7 @@ The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is
       "name": "constellation-host",          // kebab-case, ≤64 chars, unique within file
       "cmd": "bun",                          // must be on engine.managedSpawn.executableAllowlist
       "args": ["run", "dev"],                // ≤64 entries
-      "cwd": "D:/repos/constellation",       // must be inside a real git worktree (requireGitWorkdir: true) — monorepo subdirs ok, ancestor walked up to gitWorktreeMaxParentDepth parents
+      "cwd": "<MINIONS_AGENT_CWD>",          // assigned dispatch root or a subdirectory
       "env": { "CONSTELLATION_SERVER": "http://localhost:3000" },  // ≤32 keys; POSIX-shape + denylist enforced
       "ports": [3001],                       // 1024-65535; ≤20 per spec; advisory only (engine doesn't bind)
       "ttl_minutes": 240,                    // ≤1440 (24h hard cap); defaults to 720 (12h)
@@ -59,6 +59,19 @@ The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is
 
 The renderer in [`buildManagedSpawnHint`](../engine/managed-spawn.js) at `engine/managed-spawn.js:419` emits this exact shape (with allowlist + cap reminders) into the agent's prompt whenever the work item has `meta.managed_spawn: true`. Treat the rendered hint as the source of truth — if this doc and the hint drift, the hint wins.
 
+The engine also confines every spec to the dispatch root: `cwd` must resolve at
+or below `MINIONS_AGENT_CWD`. In worktree mode, `project.localPath` is rejected
+even though it is a valid Git checkout. Project-specific env deny patterns are
+resolved from the dispatch's configured project, not inferred from the sibling
+worktree path.
+
+Persisted managed-process rows carry the canonical dispatch root and originating
+work type. Manual restart and boot reconciliation revalidate that provenance
+against current project checkout mode; a legacy or live-to-worktree record that
+would restart inside `project.localPath` is killed and removed instead. The
+periodic sweep applies the same check, so mode drift is enforced immediately
+rather than waiting for TTL or another engine restart.
+
 ### Smoke-test before writing the sidecar (mandatory, W-mpbpexrg00110661)
 
 The hint mandates that agents run each `cmd args` in the declared `cwd` for at least 5 seconds AND confirm the healthcheck endpoint returns the expected status BEFORE writing `managed-spawn.json`. Sidecars written from guessed-at commands are how dispatches silently lose specs: the engine spawns what the agent declared; if the command crashes on first launch, the engine kills the spec, removes it from state, and (for partial failures) marks the WI with `_managedSpawnPartial` rather than demoting it — the agent's primary work succeeded by validator standards. The cost of guessing wrong is the operator finding out hours later that half the stack is down.

package/docs/runtime-adapters.md

@@ -8,7 +8,8 @@ behavior is hidden behind an adapter object resolved through `resolveRuntime()`.
 
 | File | Role |
 |------|------|
-| `engine/runtimes/index.js` | Adapter registry. `resolveRuntime(name)`, `listRuntimes()`, `registerRuntime()`. Engine code MUST go through these. |
+| `engine/runtimes/contract.js` | Versioned adapter contract, capability gating, opaque invocation-option transport, and optional-hook facades. |
+| `engine/runtimes/index.js` | Adapter registry and the only runtime facade imported by orchestration code. |
 | `engine/runtimes/claude.js` | Claude Code adapter. Owns binary probe, `--system-prompt-file`, JSONL parser, model shorthands, budget cap, bare mode. |
 | `engine/runtimes/copilot.js` | GitHub Copilot CLI adapter. Owns standalone-vs-`gh-copilot` resolution, stdin-only prompt delivery, `https://api.githubcopilot.com/models` discovery, effort `'max' → 'xhigh'` mapping. |
 | `engine/runtimes/codex.js` | OpenAI Codex CLI adapter. Owns `@openai/codex`/native binary resolution, `codex exec --json -` prompt delivery, `codex debug models --bundled` discovery, `.agents/skills` roots, and Codex JSONL parsing. |
@@ -30,6 +31,7 @@ methods that genuinely differ.
 
 | Member | Type / Returns | Purpose |
 |--------|----------------|---------|
+| `apiVersion` | number | Contract version. Bundled adapters use `1`; incompatible versions fail at registration. |
 | `name` | string | Adapter identifier (matches the registry key). |
 | `capabilities` | flag object (see below) | Feature flags consumed by engine code. |
 | `resolveBinary({ env, config? })` | `{ bin, native, leadingArgs }` or null | Probe PATH, npm-globals, package overrides; cached to `engine/<name>-caps.json`. `leadingArgs` is `[]` for direct binaries and `['copilot']` for the `gh copilot` extension fallback. |
@@ -39,7 +41,8 @@ methods that genuinely differ.
 | `modelsCache` | absolute path | Cache file for `listModels()` results. |
 | `spawnScript` | absolute path | Path to the runtime-agnostic spawn wrapper (currently `engine/spawn-agent.js` for both runtimes). |
 | `buildArgs(opts)` | `string[]` | CLI args excluding the binary itself. |
-| `buildSpawnFlags(opts)` | `string[]` | Optional; engine-side flags consumed by `engine/spawn-agent.js` (overrides the default `_buildAgentSpawnFlags`). |
+| `resolveInvocationOptions({ options, engineConfig, config, failureClass })` | object | Optional; maps harness-specific config and retry policy into semantic invocation options. Core code never reads harness-specific invocation keys. |
+| `buildSpawnFlags(opts)` | `string[]` | Optional compatibility flags for older spawn wrappers. New fields travel in the opaque `--runtime-options` bag automatically. |
 | `buildPrompt(promptText, sysPromptText)` | string | Final prompt delivered to the CLI. Adapters that lack `--system-prompt-file` (Copilot) prepend a `<system>` block here. |
 | `getUserAssetDirs({ homeDir })` | `string[]` | Runtime-native global asset roots passed to spawn as `--add-dir` so worktrees still see them. |
 | `getSkillRoots({ homeDir, project? })` | `[{ scope, dir, projectName? }]` | Where `collectSkillFiles` looks for native + project skill markdown. |
@@ -52,11 +55,39 @@ methods that genuinely differ.
 | `parseStreamChunk(line)` | event object or null | Single JSONL line → typed event. |
 | `parseError(rawOutput)` | `{ message, code, retriable }` | Codes: `auth-failure`, `context-limit`, `budget-exceeded`, `model-unavailable` (retriable=true for upstream overload/503; retriable=false for invalid/typo'd model id — Copilot enriches the message via `_warmModelCache()` so it lists the available models), `crash`, null. |
 | `createStreamConsumer(ctx)` | consumer object | Stream accumulator used by `engine/llm.js`. |
-| `detectPermissionGate`, `getPromptDeliveryMode`, `usesSystemPromptFile`, `classifyFailure` | misc | Adapter-owned policy that engine code reads through accessors instead of branching on `runtime.name`. |
-
-The contract surface is documented inline at the top of `engine/runtimes/claude.js`
-(see the JSDoc block at the start of that file). Keep that block authoritative —
-this table is the human-readable mirror.
+| `prepareWorkspace(ctx)` | result object | Optional synchronous hook for harness-owned workspace state, such as trust configuration. |
+| `isSpawnStartupEvent(event)` | boolean | Optional startup-event classifier used by the spawn-phase watchdog. |
+| `shouldSuppressPostMutationError(ctx)` | boolean | Optional harness quirk policy for an error received after a confirmed mutation. |
+| `buildWorkerArgs(opts)` | string[] | Required with `acpWorkerPool`; owns persistent-worker CLI flags. |
+| `encodePooledOutput(event)` | string | Required with `acpWorkerPool`; translates semantic pooled events into the adapter's normal parser format. |
+| `detectPermissionGate`, `getPromptDeliveryMode`, `usesSystemPromptFile`, `classifyFailure` | misc | Adapter-owned policy that orchestration reads through the facade instead of branching on `runtime.name`. |
+
+`engine/runtimes/contract.js` is authoritative. Registration normalizes legacy
+partial test/tooling adapters, validates bundled adapters strictly, and rejects
+an explicit unsupported `apiVersion`.
+
+### Stable invocation boundary
+
+Minions passes semantic values such as `model`, `effort`, and `sessionId`; it
+does not construct harness CLI argv. The selected adapter:
+
+1. maps its config through `resolveInvocationOptions()`;
+2. receives the full options object through an opaque base64url JSON
+   `--runtime-options` channel when the spawn wrapper is used; and
+3. converts those options to real CLI flags only in `buildArgs()`.
+
+Legacy named wrapper flags remain for backward compatibility, but they are no
+longer the extension point. A new harness option can be added entirely inside
+its adapter without teaching `engine.js`, `engine/llm.js`, or
+`engine/spawn-agent.js` another CLI flag. Large image payloads are written to a
+protected per-call sidecar; only its path enters the options argument, and the
+wrapper hydrates then deletes it before invoking the adapter.
+
+Retirement gates for the temporary compatibility surfaces are tracked in
+`docs/deprecated.json`: `legacy-runtime-named-spawn-flags`,
+`versionless-runtime-adapter-compat`, and
+`preapprove-workspace-mcps-wrapper`. Calendar dates never override their
+external-usage gates.
 
 ## Capability Flags
 
@@ -81,7 +112,7 @@ real behavioral split appears between adapters.
 | `resumePromptCarryover` | ✗ | ✓ | ✓ | CC resume turns prepend recent visible Q&A in stdin when the runtime session store is opaque to Minions. |
 | `resumeBookkeepingTurn` | ✓ | — | — | Claude CLI injects a synthetic "Continue from where you left off." meta turn on `--resume`; CC prompts must tell the model not to treat it as user intent. |
 | `streamConsumer` | ✓ | ✓ | ✓ | Adapter implements `createStreamConsumer(ctx)` — required by `engine/llm.js` accumulator. |
-| `imageInput` | ✓ | ✓ | ✗ | Runtime accepts `images: [{mimeType, dataBase64}]` and delivers them to the CLI. Claude: Anthropic Messages base64 content-block envelope via `--input-format stream-json`. Copilot: base64 payloads materialized to tmp files and passed as `--attachment <path>` (W-mqv7324u0021db5d). When false, `_resolveImageOpts` returns a typed `model-unavailable` error. |
+| `imageInput` | ✓ | ✓ | ✓ | Runtime accepts `images: [{mimeType, dataBase64}]` and delivers them to the CLI using adapter-owned transport. When false, `_resolveImageOpts` returns a typed `model-unavailable` error. |
 | `acpWorkerPool` | ✗ | ✓ | ✗ | Runtime supports `<bin> --acp` (Agent Client Protocol), so it can be routed through a persistent worker pool instead of cold-spawning a fresh CLI process per turn/dispatch. Two independent consumers gate on this flag: `engine/cc-worker-pool.js` (CC/doc-chat tabs, `resolveCcUseWorkerPool`) and `engine/agent-worker-pool.js` (fleet agent dispatch, `resolveAgentUseWorkerPool`). Both resolvers hard-return `false` whenever this flag isn't `true` on the resolved runtime, regardless of any operator override, so a future non-ACP runtime can never be silently pooled. See [ACP Worker Pool](#acp-worker-pool-fleet-agent-dispatch) below. |
 
 When a behavior is genuinely uniform across all current adapters, it still gets
@@ -128,12 +159,15 @@ handlers, PID-file writing, live-output.log, timeout/steering cancel-vs-kill,
 restart-reattach) runs unmodified regardless of whether `proc` is a real OS
 process or a pooled lease. Assignment strategy, in order:
 
-1. A **free** worker whose MCP-server set already matches wins first — reused
-   via a fresh `session/new`, no respawn.
+1. A **free** worker whose MCP-server set, process environment, and canonical
+   process cwd already match wins first — reused via a fresh `session/new`, no
+   respawn.
 2. Otherwise another free worker is **evicted** (closed) and a replacement is
    spawned fresh with the requested MCP servers/cwd (MCP servers are resolved
-   at `copilot --acp` process boot, so a changed server set requires a full
-   respawn, not just a new session).
+   at `copilot --acp` process boot, so a changed server set or process cwd
+   requires a full respawn, not just a new session). This prevents a worker OS
+   process rooted in a live operator checkout from carrying that cwd into an
+   isolated worktree dispatch.
 3. Otherwise, if the pool has room (fewer than `agentAcpPoolSize` workers
    allocated across free + busy + in-flight-spawn), a brand-new worker spawns.
 4. Otherwise the request queues FIFO until a `release()` or worker crash frees
@@ -197,9 +231,9 @@ agent fleet to Copilot, and vice versa. Both paths fall through to
 `engine.defaultCli` (the fleet-wide default), but they never see each other's
 overrides.
 
-Six helpers in `engine/shared.js` are the single source of truth for runtime/model
-resolution. Engine code MUST go through them instead of reading config keys
-directly.
+The helpers in `engine/shared.js` are the single source of truth for
+runtime/model and cross-runtime policy resolution. Engine code MUST go through
+them instead of reading config keys directly.
 
 | Helper | Chain |
 |--------|-------|
@@ -207,6 +241,7 @@ directly.
 | `resolveCcCli(engine)` | `engine.ccCli` → `engine.defaultCli` → `'copilot'` |
 | `resolveAgentModel(agent, engine)` | `agent.model` → `engine.defaultModel` → undefined |
 | `resolveCcModel(engine)` | `engine.ccModel` → `engine.defaultModel` → undefined |
+| `resolveAgentAllowedTools(config)` | Legacy `config.claude.allowedTools` fleet ceiling → undefined. Despite its legacy namespace, it applies to every selected runtime. |
 | `resolveAgentMaxBudget(agent, engine)` | `agent.maxBudgetUsd` → `engine.maxBudgetUsd`. Honors literal `0`. |
 | `resolveAgentBareMode(agent, engine)` | `agent.bareMode` → `engine.claudeBareMode` → false. Strict null check so per-agent `false` overrides engine `true`. |
 
@@ -285,8 +320,9 @@ codifies are documented in [`docs/harness-propagation.md`](./harness-propagation
 
 ## The "No Runtime-Name Branching" Rule
 
-The whole point of this layer: **engine code MUST gate behavior on
-`runtime.capabilities.*` flags, not on `runtime.name === 'claude'` comparisons.**
+The whole point of this layer: **orchestration code MUST use the runtime facade,
+capabilities, and adapter hooks rather than concrete imports, harness config
+keys, or `runtime.name === 'claude'` comparisons.**
 
 If you find yourself wanting to write `if (runtime.name === 'copilot')` in
 engine code, the correct response is one of:
@@ -296,19 +332,18 @@ engine code, the correct response is one of:
 3. Move the special case into the adapter's `buildArgs` / `buildPrompt` /
    `parseOutput` where it belongs.
 
-Tests in `test/unit/runtime-adapters.test.js` and `test/unit/copilot-adapter.test.js`
-enforce the contract; the source-inspection tests in `test/unit.test.js` look
-for `resolveRuntime(...)` call sites and reject runtime-name comparisons in new
-code.
+Tests in `test/unit/runtime-adapters.test.js` enforce the contract.
+`test/unit/runtime-boundary.test.js` rejects concrete adapter imports,
+runtime-name branches, and harness-specific invocation config in core paths.
 
 ## Adding a New Runtime
 
-1. Create `engine/runtimes/<name>.js` implementing the full adapter contract.
-   Copy `claude.js` as the template and override only the members that differ.
-   Set a useful `installHint`.
+1. Create `engine/runtimes/<name>.js` implementing adapter API version `1`.
+   Keep all CLI flags, output schemas, workspace quirks, and worker behavior in
+   that file. Set a useful `installHint`.
 2. Register it in `engine/runtimes/index.js`:
    ```js
-   registry.set('<name>', require('./<name>'));
+   registerRuntime('<name>', require('./<name>'), { strict: true });
    ```
 3. Add unit coverage modeled on `test/unit/runtime-adapters.test.js`.
 
@@ -324,6 +359,6 @@ flags — never special-case in engine code.
 - `docs/copilot-cli-schema.md` — empirical Copilot CLI behavior captured during
   the spike that produced the Copilot adapter; cite it when changing
   Copilot-specific capability flags.
-- `engine/runtimes/claude.js` JSDoc header — authoritative adapter contract.
+- `engine/runtimes/contract.js` — authoritative adapter contract and facade.
 - `engine/shared.js` `resolveAgentCli` / `resolveCcCli` etc. — the only
   supported way to read runtime / model selection from config.

package/docs/skills.md

@@ -4,6 +4,8 @@ Agents emit a fenced `skill` block when they discover a durable, reusable workfl
 
 The engine extracts valid blocks from agent stdout and from inbox findings (`notes/inbox/*.md`) and writes them into the selected runtime's native personal skills directory (e.g. `~/.claude/skills/<name>/SKILL.md` for Claude, the equivalent personal skills directory for Copilot). Project-scoped skills are landed via PR into the matching project's playbook tree.
 
+Packaged `scope: minions` skills are synchronized into every registered runtime's personal skill directory during `minions init` and upgrades. A packaged skill replaces an existing same-name personal copy so contract fixes take effect immediately.
+
 ## Block format
 
 ````

package/docs/workspace-manifests.md

@@ -54,7 +54,7 @@ A config that never mentions `workspace_manifest` produces the exact same dispat
 | Phase | Location | What it does |
 | ----- | -------- | ------------ |
 | **Dispatch — repo gate** | `engine.js spawnAgent()` (right after project resolution) | Calls `shared.agentCanUseRepo(agent, project)`. Mismatch → `completeDispatch(... FAILURE_CLASS.WORKSPACE_MANIFEST_REPO, agentRetryable: false)` and `cleanupTempAgent` runs. Non-retryable because the structural answer is "widen the manifest or pick a different agent". |
-| **Spawn — tool merge** | `engine.js spawnAgent()` → `_buildAgentSpawnFlags(..., allowedTools)` | `shared.mergeManifestAllowedTools(claudeConfig.allowedTools, manifest.allowed_tools)` produces the intersection of the runtime baseline and the manifest list. Result is passed as `--allowedTools <csv>` to Claude / Copilot / Codex, so the CLI itself enforces the narrowed surface. Empty manifest list (`[]`) = deny-all. Same merge runs on the steering-resume codepath. |
+| **Spawn — tool merge** | `engine.js spawnAgent()` → `_buildAgentSpawnFlags(..., allowedTools)` | `shared.resolveAgentAllowedTools(config)` preserves the legacy fleet baseline for every selected runtime, then `shared.mergeManifestAllowedTools(baseline, manifest.allowed_tools)` produces the intersection. Result is passed through the Claude / Copilot / Codex adapter option path. Empty manifest list (`[]`) = deny-all. Same resolved option bag is reused on the steering-resume codepath. |
 | **Agent context** | Future work (playbook.js) | Manifest can be surfaced into the agent prompt so the agent sees its declared scope. Today, `shared.resolveAgentManifest(agent)` returns the resolved struct any caller can read. |
 | **URL fetch** | Advisory today | `allowed_external_urls` is validated at config load. No runtime helper function — a future runtime adapter hook can wire URL-fetch intercepts against the manifest. |
 | **Memory scope** | Advisory today | `memory_scope` field is stored in the manifest (`private` = agent only sees its own `knowledge/agents/<id>.md`; `shared` = full team knowledge (current default); `read-only-shared` = reads shared memory but should not write inbox/notes). No runtime enforcement helper — full enforcement at the consolidation layer is future work. |

package/docs/worktree-lifecycle.md

@@ -11,6 +11,28 @@ Lifecycle keeps the cross-cutting invariants; the detail lives here.
 > `_killGitDescendantsForWorktree`, `pruneOrphanWorktrees*`, `gcDispatchWorktreeIfOrphan`),
 > `engine/cleanup.js`. Last verified: 2026-06-09.
 
+## Operator-checkout boundary
+
+For `checkoutMode: "worktree"`, `project.localPath` is an operator-owned source
+checkout, not an execution directory. Project-bound read-only and mutating
+dispatches both run in engine-owned worktrees; Command Center delegates writes;
+Create-PR staging copies existing operator changes without resetting or deleting
+the source; restart restore requires explicit live dispatch provenance plus
+current live configuration. Branchless project dispatches receive detached
+worktrees, and path containment resolves symlinks/junctions before accepting a
+worktree or `meta.workdir`. Placement and removal are checked against **every**
+configured `localPath`, so a nested project's worktree cannot land inside a
+parent project's operator checkout. Restart reattachment requires either a
+validated persisted worktree path or current live-mode provenance; unsafe
+legacy processes are terminated and retried. Worktree setup may update shared Git refs/metadata,
+but it never checks out, resets, cleans, writes files, or removes
+`.git/index.lock` in the operator checkout.
+
+Worktrees that host live `managed_spawn` or `keep_processes` cwd records are
+anchored across dispatch-end, periodic, boot, in-root, and out-of-root GC.
+Anchor comparisons use canonical filesystem paths so junction/case aliases do
+not make a live service's worktree look orphaned.
+
 ## Live-worktree guard (W-mq5rwwss000f30a7)
 
 **Invariant:** every code path that wipes, renames, or recycles a worktree
@@ -47,6 +69,20 @@ recycle worktree dirs across branches.
   → `git checkout --detach origin/<main>` → mark IDLE.
 - **State** in SQLite (`worktree_pool`); git ops outside the transaction.
 
+## Fresh ordinary branch bases
+
+When the pool is disabled or has no usable entry, a brand-new ordinary mutating
+branch is created only after `git fetch origin <mainBranch>` succeeds, and its
+base is always `origin/<mainBranch>`. A network or authentication failure stops
+before `git worktree add` or agent spawn and leaves the work item retryable; the
+engine never falls back to a potentially stale local `<mainBranch>`.
+
+This fail-closed rule applies only when the requested branch is confirmed absent
+from origin. PR-targeted / `useExistingBranch`, shared-branch, and retry paths
+that intentionally preserve an existing branch continue using that branch
+unchanged. Warm-pool borrowing keeps its existing fetch-and-checkout of
+`origin/<mainBranch>`.
+
 ## Ownership marker is never "dirty" (#284)
 
 The reused-worktree preflight (`assertCleanSharedWorktree`) builds its