@yemi33/minions 0.1.2179 → 0.1.2180

package/engine/shared.js

@@ -2699,6 +2699,36 @@ const ENGINE_DEFAULTS = {
   claudeFallbackModel: undefined,// Claude --fallback-model — Claude CLI honors this on rate-limit (429) only; engine retry on FAILURE_CLASS.MODEL_UNAVAILABLE keeps the flag passed so the CLI can swap internally
   copilotFallbackModel: undefined,// W-mpg6isvy000xca4d: Copilot has no --fallback-model flag; engine retry on FAILURE_CLASS.MODEL_UNAVAILABLE OVERRIDES --model directly with this value (separate knob from claudeFallbackModel because model namespaces differ across runtimes)
   copilotDisableBuiltinMcps: true,   // Copilot --disable-builtin-mcps: keep github-mcp-server out so it can't bypass pull-requests.json tracking
+  // P-7d31a06b — Claude pre-approves workspace .mcp.json servers in ~/.claude.json on every spawn into a fresh
+  // worktree cwd. Without this, the first Claude invocation in a brand-new worktree shows a project-scoped MCP
+  // "trust this server?" prompt that blocks until a human accepts — invisible behind --dangerously-skip-permissions
+  // so the agent silently runs without the workspace MCPs. Pre-warming
+  // projects.<worktreePath>.enabledMcpjsonServers (the field Claude Code actually reads — see live ~/.claude.json
+  // shape) means the workspace MCPs are connected on first call. Best-effort: failures NEVER block dispatch.
+  // Engine-scoped per the CLAUDE.md rule against `runtime.name === ...` branches at call sites — the runtime check
+  // lives inside the helper (engine/spawn-agent.js#preApproveWorkspaceMcps) which no-ops for non-Claude runtimes.
+  claudePreApproveWorkspaceMcps: true,
+  // P-08b62d49 — propagate project-local-on-main harness dirs (uncommitted
+  // <repo>/.claude/skills, <repo>/.copilot/commands, etc.) into the worktree
+  // dispatch via additional `--add-dir` entries. Defaults TRUE so the
+  // worktree-uncommitted footgun described in docs/harness-propagation.md is
+  // closed by default. Set to false to fall back to the legacy
+  // "only committed assets are visible" behavior.
+  harnessPropagateProjectLocal: true,
+  // P-49e1c8b7 — hermetic harness opt-out. When TRUE the spawned agent runs
+  // with a known-empty harness surface around the worktree:
+  //   - `--add-dir` is exactly `[minionsDir]` (user-scope skill/command/MCP
+  //     roots from `runtime.getUserAssetDirs(...)` are dropped);
+  //   - project-local-on-main harness propagation (`harnessPropagateProjectLocal`)
+  //     is skipped — no `--project-harness-dir` flags emitted;
+  //   - Claude workspace `.mcp.json` pre-approval (`claudePreApproveWorkspaceMcps`)
+  //     is skipped.
+  // Independent of `copilotDisableBuiltinMcps` and `copilotSuppressAgentsMd` —
+  // those keep their existing semantics so operators can mix-and-match. Use
+  // per-agent override `agent.hermeticHarness` for targeted runs. Resolved
+  // through `shared.resolveAgentHermeticHarness(agent, engine)` (mirrors
+  // `resolveAgentBareMode`).
+  hermeticHarness: false,
   copilotSuppressAgentsMd: true,     // Copilot --no-custom-instructions: stop AGENTS.md auto-load from fighting Minions playbook prompts
   copilotStreamMode: 'on',           // Copilot --stream <on|off>: 'on' streams assistant.message_delta events live; 'off' batches them
   copilotReasoningSummaries: false,  // Copilot --enable-reasoning-summaries (Anthropic-family models only)
@@ -3151,6 +3181,32 @@ function resolveCopilotAgentDisabledMcpServers(agent, engine) {
   return [];
 }
 
+/**
+ * P-49e1c8b7 — Resolve whether this agent should run with a hermetic harness.
+ * Priority (mirrors `resolveAgentBareMode`):
+ *   1. `agent.hermeticHarness`    — per-agent override (boolean)
+ *   2. `engine.hermeticHarness`   — fleet default
+ *   3. `false`                    — hardcoded fallback
+ *
+ * Strict undefined/null check (not falsy) so a per-agent `false` correctly
+ * overrides an engine `true`. Truthy/falsy non-bool values are coerced via
+ * `!!` for config tolerance.
+ *
+ * When TRUE, engine.js (a) skips Claude workspace .mcp.json pre-approval,
+ * (b) skips project-local-on-main `--project-harness-dir` propagation, and
+ * (c) forwards `--hermetic-harness` to spawn-agent.js so `computeAddDirs`
+ * returns `[minionsDir]` only (user-scope skill/command/MCP roots stripped).
+ * Independent of `copilotDisableBuiltinMcps` and `copilotSuppressAgentsMd`.
+ */
+function resolveAgentHermeticHarness(agent, engine) {
+  const a = agent ? agent.hermeticHarness : undefined;
+  if (a !== undefined && a !== null) return !!a;
+  const e = engine ? engine.hermeticHarness : undefined;
+  if (e !== undefined && e !== null) return !!e;
+  return false;
+}
+
+
 // ─── Legacy ccModel → defaultModel Migration ─────────────────────────────────
 //
 // Pre-P-3b8e5f1d, `engine.ccModel` was the single fleet-wide model knob (it
@@ -4021,6 +4077,7 @@ const FAILURE_CLASS = {
   MANAGED_SPAWN_HEALTHCHECK_FAILED: 'managed-spawn-healthcheck-failed', // P-7a3b1c92: at least one managed-spawn spec was spawned but failed its healthcheck within timeout_s. Engine killed the failing PIDs; siblings stay alive. Dispatch ERROR with the failing spec name + log tail surfaced in the inbox alert.
   INJECTION_FLAGGED: 'injection-flagged', // F5 (W-mpeklod3000we69c): the agent set `securityFlags.injectionAttempt:true` in its completion report after spotting a prompt-injection attempt inside an <UNTRUSTED-INPUT> fence. Engine writes a security inbox note + stamps `_securityFlag` on the WI and treats the dispatch as non-retryable so a human can review the source before the agent re-runs.
   LIVE_CHECKOUT_DIRTY: 'live-checkout-dirty', // P-a3f9b204 (live-checkout dispatch mode): spawnAgent ran prepareLiveCheckout against project.localPath and `git status --porcelain` reported uncommitted changes. Engine refused to spawn (it never runs `git reset`/`git clean` against the operator tree). Inbox alert lists dirty files; WI is stamped `_pendingReason: 'live_checkout_dirty'`. Non-retryable — operator must commit/stash/discard before re-dispatch.
+  INVALID_WORKDIR: 'invalid-workdir',     // P-714ef144: dispatch carried a meta.workdir override that failed validation — non-string, absolute path, drive-letter prefix, null byte, ".." segment, or post-resolve containment escape against project.localPath / worktree root. Engine refuses to spawn (the subpath would either be unreachable on disk or point outside the operator's allowed surface). Non-retryable — operator must fix the WI's meta.workdir before re-dispatch. Inbox alert lists the offending value + the resolved-vs-base mismatch.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).
   WORKSPACE_MANIFEST_REPO: 'workspace-manifest-repo-forbidden', // W-mq07avbk000m5543: dispatch routed an agent to a project/repo not present in its workspace_manifest.allowed_repos. Structural — never retryable until the manifest is widened or a different agent is chosen.
   WORKSPACE_MANIFEST_TOOL: 'workspace-manifest-tool-forbidden', // W-mq07avbk000m5543: out-of-scope tool call (manifest enforcement at the runtime gate). Non-retryable as-is.
@@ -5278,21 +5335,47 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * `LIVE_CHECKOUT_NO_LOCALPATH` if `localPath` is missing/falsy — live mode
  * has no fallback because there is no neutral location to dispatch into.
  *
+ * **Workdir override (P-714ef144).** When `options.workdir` is a non-empty
+ * relative POSIX subpath (already validated by `validateWorkItemWorkdir`),
+ * the resolver joins it onto the spawn cwd:
+ *
+ *   - live mode: cwd = path.join(localPath, workdir)
+ *   - read-only mode: cwd = path.join(<base>, workdir)
+ *   - mutating mode: cwd stays null (worktree doesn't exist yet); the
+ *     normalized workdir is echoed back as result.workdir so spawnAgent
+ *     can apply `shared.applyWorkdir(worktreePath, workdir)` after
+ *     `git worktree add` succeeds.
+ *
+ * Live and read-only branches run the post-resolve containment guard via
+ * `applyWorkdir` and throw an Error with `code: 'INVALID_WORKDIR'` if the
+ * resolved cwd escapes its base (defense-in-depth — validator already
+ * rejects ".." / absolute paths, but symlink-style attacks can only be
+ * caught post-resolve). The mutating containment check happens later in
+ * spawnAgent, against the actual worktree path.
+ *
  * @param {{ localPath?: string|null, worktreeMode?: string|null }|null|undefined} project
  * @param {string} type — work type (e.g. 'fix', 'explore', 'meeting')
  * @param {string} minionsDir — MINIONS_DIR fallback anchor (ignored in live mode)
- * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean }}
- *   - For live mode (any type): { cwd: <abs localPath>, worktreeRootDir: null, liveMode: true }
- *   - For isolated read-only types: { cwd: <project dir or MINIONS_DIR>, worktreeRootDir: null }
- *   - For isolated code-mutating types: { cwd: null, worktreeRootDir: <project root> }
- *     (caller defaults cwd to worktreeRootDir before worktree creation)
+ * @param {{ workdir?: string|null }} [options] — optional per-WI overrides
+ * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean, workdir?: string|null }}
+ *   - For live mode (any type): { cwd: <abs localPath[/workdir]>, worktreeRootDir: null, liveMode: true }
+ *   - For isolated read-only types: { cwd: <project dir[/workdir] or MINIONS_DIR>, worktreeRootDir: null }
+ *   - For isolated code-mutating types: { cwd: null, worktreeRootDir: <project root>, workdir: <subpath|null> }
+ *     (caller defaults cwd to worktreeRootDir before worktree creation,
+ *      then runs shared.applyWorkdir(worktreePath, result.workdir) to land
+ *      the agent inside the subpackage cwd)
  *   The optional `liveMode` discriminator lets callers branch on one boolean
  *   instead of re-reading `project.worktreeMode`.
  * @throws {Error} LIVE_CHECKOUT_NO_LOCALPATH (live mode, missing localPath),
+ *                 INVALID_WORKDIR (live or read-only, workdir escapes base),
  *                 WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT (isolated code-mutating),
  *                 or WORKTREE_ROOTDIR_MISSING_BASE if neither anchor present.
  */
-function resolveSpawnPaths(project, type, minionsDir) {
+function resolveSpawnPaths(project, type, minionsDir, options) {
+  const workdir = (options && typeof options === 'object' && typeof options.workdir === 'string' && options.workdir)
+    ? options.workdir
+    : null;
+
   // ── Live-checkout mode short-circuit (P-a3f9b202) ──────────────────────
   // Runs BEFORE the read-only / code-mutating split so live mode is the
   // single decision point regardless of task type — read-only tasks in
@@ -5306,8 +5389,10 @@ function resolveSpawnPaths(project, type, minionsDir) {
       err.code = 'LIVE_CHECKOUT_NO_LOCALPATH';
       throw err;
     }
+    const baseLive = path.resolve(String(project.localPath));
+    const liveCwd = _applyWorkdirOrThrow(baseLive, workdir);
     return {
-      cwd: path.resolve(String(project.localPath)),
+      cwd: liveCwd,
       worktreeRootDir: null,
       liveMode: true,
     };
@@ -5315,14 +5400,189 @@ function resolveSpawnPaths(project, type, minionsDir) {
 
   const isReadOnly = READ_ONLY_ROOT_TASK_TYPES.has(type);
   if (isReadOnly) {
-    if (project?.localPath) return { cwd: path.resolve(String(project.localPath)), worktreeRootDir: null };
-    if (minionsDir) return { cwd: path.resolve(String(minionsDir)), worktreeRootDir: null };
-    const err = new Error('Cannot resolve cwd for read-only spawn: no project.localPath and no MINIONS_DIR provided.');
-    err.code = 'WORKTREE_ROOTDIR_MISSING_BASE';
-    throw err;
+    let base = null;
+    if (project?.localPath) base = path.resolve(String(project.localPath));
+    else if (minionsDir) base = path.resolve(String(minionsDir));
+    else {
+      const err = new Error('Cannot resolve cwd for read-only spawn: no project.localPath and no MINIONS_DIR provided.');
+      err.code = 'WORKTREE_ROOTDIR_MISSING_BASE';
+      throw err;
+    }
+    const roCwd = _applyWorkdirOrThrow(base, workdir);
+    return { cwd: roCwd, worktreeRootDir: null };
   }
   const worktreeRootDir = resolveProjectRootDir(project?.localPath, minionsDir);
-  return { cwd: null, worktreeRootDir };
+  // Mutating types: workdir is echoed back UNAPPLIED. spawnAgent calls
+  // `shared.applyWorkdir(worktreePath, workdir)` after `git worktree add`
+  // succeeds, which is the only time the actual base path exists on disk.
+  return { cwd: null, worktreeRootDir, workdir };
+}
+
+// ── meta.workdir helpers (P-714ef144) ────────────────────────────────────
+//
+// Per-WI `meta.workdir` is a relative POSIX subpath under the spawn base
+// (project.localPath for read-only / live; worktree root for mutating).
+// When set, the engine lands the agent at <base>/<workdir> so monorepo
+// subpackage dispatches can use the runtime CLI's native cwd-rooted skill
+// discovery (`<workdir>/.claude/skills/<name>/SKILL.md`) without engine
+// awareness of which package is which. Cross-package skill aggregation is
+// explicitly out of scope (per PRD open_question) — when workdir is set,
+// the harness propagation block in engine.js also CLIPS its candidate
+// `--project-harness-dir` set to dirs that live under the workdir mirror
+// in `project.localPath`, so a `packages/foo` dispatch never sees
+// `packages/bar/.claude/skills/...`.
+//
+// Three pure helpers, all unit-tested in test/unit/work-item-workdir.test.js:
+//
+//   1. validateWorkItemWorkdir(value) — input validation for the
+//      dashboard.js POST /api/work-items handler. Returns
+//      `{ valid: true, value: null }` for empty/unset (back-compat
+//      default), `{ valid: true, value: <normalized POSIX subpath> }`
+//      for a clean subpath, or `{ valid: false, error: <human reason> }`
+//      for any rejection. The normalized form has backslashes folded to
+//      `/`, trims surrounding whitespace, drops leading `./` and trailing
+//      `/`, and rejects `..` segments, absolute paths (POSIX or Windows
+//      drive-letter), null bytes, and non-string types.
+//
+//   2. applyWorkdir(base, workdir) — pure join + containment guard.
+//      Returns `{ cwd: <resolved absolute path>, error?: <reason> }`. The
+//      `error` field is set when the resolved cwd would escape `base`
+//      (defense-in-depth against symlink-style attacks; the validator
+//      already rejects bare `..` / absolute strings). `base` MUST be
+//      absolute. Empty/null workdir returns the base unchanged.
+//
+//   3. filterProjectHarnessDirsForWorkdir(dirs, opts) — clips the
+//      candidate `--project-harness-dir` set to entries under the resolved
+//      cwd anchor in `project.localPath`, excluding entries under the
+//      worktree mirror (already discoverable via the agent's cwd). When
+//      `workdir` is null/empty the behavior matches P-08b62d49 unchanged
+//      (filter to project.localPath, exclude worktree).
+//
+// The private `_applyWorkdirOrThrow(base, workdir)` is the throw-on-error
+// adapter used inside resolveSpawnPaths so live/read-only callers don't
+// need to forward the `error` field.
+
+function _applyWorkdirOrThrow(base, workdir) {
+  if (!workdir) return base;
+  const r = applyWorkdir(base, workdir);
+  if (r.error) {
+    const err = new Error(r.error);
+    err.code = 'INVALID_WORKDIR';
+    err.workdir = workdir;
+    err.base = base;
+    throw err;
+  }
+  return r.cwd;
+}
+
+function validateWorkItemWorkdir(value) {
+  // Unset / empty → null (back-compat default, today's project-root behavior)
+  if (value === undefined || value === null) return { valid: true, value: null };
+  if (typeof value !== 'string') {
+    return { valid: false, error: 'meta.workdir must be a string (got ' + typeof value + ')' };
+  }
+  const trimmed = value.trim();
+  if (!trimmed) return { valid: true, value: null };
+
+  // Null bytes — common path-injection signal; refuse defensively.
+  if (trimmed.indexOf('\u0000') !== -1) {
+    return { valid: false, error: 'meta.workdir must not contain null bytes' };
+  }
+
+  // Windows drive-letter prefix (e.g. "C:\\Windows", "D:foo") — even when
+  // the path looks "inside" the project, it's an absolute reference.
+  if (/^[A-Za-z]:[\\/]?/.test(trimmed)) {
+    return { valid: false, error: 'meta.workdir must be a relative POSIX subpath, not a Windows drive path (got "' + value + '")' };
+  }
+
+  // POSIX absolute / UNC / backslash-absolute.
+  if (path.isAbsolute(trimmed) || trimmed.startsWith('/') || trimmed.startsWith('\\')) {
+    return { valid: false, error: 'meta.workdir must be a relative path, not absolute (got "' + value + '")' };
+  }
+
+  // ".." segments — pre-resolve guard. applyWorkdir runs the post-resolve
+  // containment check as defense-in-depth, but rejecting `..` here gives
+  // operators a clearer error message at the dashboard validation site.
+  const segments = trimmed.split(/[\\/]+/);
+  if (segments.some(s => s === '..')) {
+    return { valid: false, error: 'meta.workdir may not contain ".." segments (escape attempt blocked)' };
+  }
+
+  // Normalize: backslashes → forward slashes, drop leading "./", strip
+  // trailing slashes. Preserve "." segments (filtered out by path.join later).
+  let normalized = trimmed.replace(/\\/g, '/');
+  while (normalized.startsWith('./')) normalized = normalized.slice(2);
+  normalized = normalized.replace(/\/+$/, '');
+  if (!normalized) return { valid: true, value: null };
+
+  return { valid: true, value: normalized };
+}
+
+function applyWorkdir(base, workdir) {
+  if (workdir === null || workdir === undefined || workdir === '') {
+    return { cwd: base };
+  }
+  if (typeof workdir !== 'string') {
+    return { cwd: base, error: 'workdir must be a string (got ' + typeof workdir + ')' };
+  }
+  // Refuse absolute workdir even if it'd technically resolve inside — only
+  // relative subpaths are allowed. This catches the "operator pasted an
+  // absolute path" authoring error before path.join silently swaps the base.
+  if (path.isAbsolute(workdir) || /^[A-Za-z]:[\\/]?/.test(workdir) || workdir.startsWith('/') || workdir.startsWith('\\')) {
+    return { cwd: base, error: 'workdir must be relative, not absolute (got "' + workdir + '")' };
+  }
+  const baseAbs = path.resolve(String(base));
+  const joined = path.resolve(baseAbs, workdir);
+  // Containment guard: resolved cwd must equal base or live strictly inside.
+  if (joined !== baseAbs && !joined.startsWith(baseAbs + path.sep)) {
+    return {
+      cwd: baseAbs,
+      error: 'workdir resolved outside base (containment escape): "' + workdir + '" → "' + joined + '" not inside "' + baseAbs + '"',
+    };
+  }
+  return { cwd: joined };
+}
+
+function filterProjectHarnessDirsForWorkdir(dirs, opts) {
+  if (!Array.isArray(dirs) || dirs.length === 0) return [];
+  const projectLocalPath = opts && opts.projectLocalPath;
+  const worktreePath = opts && opts.worktreePath;
+  const workdir = opts && opts.workdir;
+  if (!projectLocalPath || !worktreePath) return [];
+
+  const projectLocalAbs = path.resolve(String(projectLocalPath));
+  const worktreeAbs = path.resolve(String(worktreePath));
+
+  // When workdir is set, the harness propagation anchors shift to the
+  // subpath mirror in BOTH the project root and the worktree root, so a
+  // `packages/foo` dispatch only sees `<projectLocal>/packages/foo/...`
+  // harness dirs (its actual cwd in the operator's main checkout) and
+  // excludes `<worktree>/packages/foo/...` (already discoverable via cwd).
+  let projectAnchor = projectLocalAbs;
+  let worktreeAnchor = worktreeAbs;
+  if (workdir && typeof workdir === 'string' && workdir) {
+    const pr = applyWorkdir(projectLocalAbs, workdir);
+    const wr = applyWorkdir(worktreeAbs, workdir);
+    // If either join fails containment, drop everything — better empty than wrong.
+    if (pr.error || wr.error) return [];
+    projectAnchor = pr.cwd;
+    worktreeAnchor = wr.cwd;
+  }
+
+  const seen = new Set();
+  const out = [];
+  for (const dir of dirs) {
+    if (typeof dir !== 'string' || !dir) continue;
+    const abs = path.resolve(dir);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    const insideProject = abs === projectAnchor || abs.startsWith(projectAnchor + path.sep);
+    if (!insideProject) continue;
+    const insideWorktree = abs === worktreeAnchor || abs.startsWith(worktreeAnchor + path.sep);
+    if (insideWorktree) continue;
+    out.push(abs);
+  }
+  return out;
 }
 
 // ── HTTP Origin Allowlist & Security Headers ─────────────────────────────────
@@ -7805,6 +8065,7 @@ module.exports = {
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentModel, resolveCcModel,
   resolveAgentMaxBudget, resolveAgentBareMode,
   resolveCopilotAgentDisabledMcpServers,
+  resolveAgentHermeticHarness,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   applyCcWorkerPoolForceOnMigration,
   runtimeConfigWarnings,
@@ -7897,6 +8158,9 @@ module.exports = {
   assertWorktreeOutsideProject,
   resolveProjectRootDir,
   resolveSpawnPaths,
+  validateWorkItemWorkdir,
+  applyWorkdir,
+  filterProjectHarnessDirsForWorkdir,
   READ_ONLY_ROOT_TASK_TYPES,
   isLiveCommandCenterPath,
   describeCcProtectedPaths,

package/engine/spawn-agent.js

@@ -55,6 +55,15 @@ function parseSpawnArgs(argv) {
   let runtimeName = 'claude';
   const opts = {};
   const passthrough = [];
+  // P-08b62d49 — accumulating array of project-local-on-main harness dirs that
+  // engine.js wants `computeAddDirs` to surface as additional `--add-dir`
+  // entries. Multiple `--project-harness-dir <path>` flags accumulate in
+  // declaration order; the dedup/exists filter happens inside `computeAddDirs`.
+  const projectHarnessDirs = [];
+  // P-49e1c8b7 — hermetic harness opt-out (boolean). Set by engine.js when
+  // shared.resolveAgentHermeticHarness(agent, engine) is true; propagates to
+  // computeAddDirs which then returns [minionsDir] only.
+  let hermetic = false;
 
   for (let i = 2; i < args.length; i++) {
     const a = args[i];
@@ -77,6 +86,17 @@ function parseSpawnArgs(argv) {
       case '--disable-builtin-mcps':       opts.disableBuiltinMcps = true; break;
       case '--no-custom-instructions':     opts.suppressAgentsMd = true; break;
       case '--enable-reasoning-summaries': opts.reasoningSummaries = true; break;
+      case '--project-harness-dir': {
+        const v = peek();
+        if (typeof v === 'string' && v) projectHarnessDirs.push(v);
+        break;
+      }
+      // P-49e1c8b7 — hermetic harness opt-out. When set, computeAddDirs in
+      // main() returns [minionsDir] only (user-scope asset dirs from
+      // runtime.getUserAssetDirs AND any forwarded --project-harness-dir
+      // entries are dropped). Engine.js gates this flag via
+      // shared.resolveAgentHermeticHarness(agent, engine).
+      case '--hermetic-harness':           hermetic = true; break;
       // LEGACY: dropped — the runtime adapter emits its own permission flag.
       // Pre-P-2a6d9c4f engine.js still passes `--permission-mode bypassPermissions`;
       // letting it through would duplicate the permission flag for Claude.
@@ -85,7 +105,7 @@ function parseSpawnArgs(argv) {
     }
   }
 
-  return { promptFile, sysPromptFile, runtimeName, opts, passthrough };
+  return { promptFile, sysPromptFile, runtimeName, opts, passthrough, projectHarnessDirs, hermetic };
 }
 
 /**
@@ -299,18 +319,39 @@ function createParentPipeForwarder(stream, outputPath, prefix = '') {
 
 /**
  * Build the `--add-dir` list passed to the runtime CLI. Pure: takes
- * `{ runtime, minionsDir, homeDir, exists }` and returns an ordered, deduped
- * array of dirs the agent should be able to read from outside its worktree.
+ * `{ runtime, minionsDir, homeDir, projectHarnessDirs, hermetic, exists }`
+ * and returns an ordered, deduped array of dirs the agent should be able to
+ * read from outside its worktree.
+ *
+ * Order:
+ *   1. minionsDir (always first, so playbooks/system-prompt are reachable).
+ *   2. Every existing dir from `runtime.getUserAssetDirs({ homeDir })` —
+ *      user-scope skill/command/MCP roots (`~/.claude`, `~/.copilot`,
+ *      `~/.agents`, …) so worktree-bound agents inherit user-installed
+ *      harnesses.
+ *   3. P-08b62d49 — Every existing dir in `projectHarnessDirs` (engine.js
+ *      passes the union of `queries.getProjectHarnesses(project).{skills,
+ *      commands}` dirs that live in `project.localPath` but NOT under the
+ *      worktree, so uncommitted `<repo>/.claude/skills/…` etc. on the main
+ *      checkout are reachable from worktree dispatches). See
+ *      `docs/harness-propagation.md` → "The worktree-uncommitted footgun".
  *
- * Order: minionsDir first (so playbooks/system-prompt are always reachable),
- * followed by every existing dir from `runtime.getUserAssetDirs({ homeDir })`.
- * Non-existent asset dirs are dropped — Claude CLI rejects unknown `--add-dir`
- * entries. The dedup compares resolved paths so we never emit minionsDir twice
- * (e.g. when runtime asset dir IS the minions repo in unusual setups).
+ * Non-existent dirs are dropped at every layer — Claude CLI rejects unknown
+ * `--add-dir` entries. The dedup compares resolved paths so we never emit a
+ * dir twice (e.g. when a runtime asset dir IS the minions repo in unusual
+ * setups, or when a project-harness dir duplicates a user-asset dir).
+ *
+ * P-49e1c8b7 — When `hermetic === true`, the result is exactly `[minionsDir]`:
+ * both the runtime adapter's user-asset dirs AND `projectHarnessDirs` are
+ * dropped so the spawned agent runs with a known-empty harness surface.
+ * Engine.js sets this via `shared.resolveAgentHermeticHarness(agent, engine)`
+ * and forwards `--hermetic-harness` to spawn-agent so the flag survives the
+ * subprocess hop.
  *
  * `exists` is injectable for tests; defaults to `fs.existsSync`.
  */
-function computeAddDirs({ runtime, minionsDir, homeDir, exists = fs.existsSync } = {}) {
+function computeAddDirs({ runtime, minionsDir, homeDir, projectHarnessDirs, hermetic, exists = fs.existsSync } = {}) {
+  if (hermetic) return [minionsDir];
   const out = [minionsDir];
   const seen = new Set([path.resolve(minionsDir)]);
   const assetDirs = typeof runtime?.getUserAssetDirs === 'function'
@@ -324,9 +365,121 @@ function computeAddDirs({ runtime, minionsDir, homeDir, exists = fs.existsSync }
     out.push(d);
     seen.add(resolved);
   }
+  if (Array.isArray(projectHarnessDirs)) {
+    for (const d of projectHarnessDirs) {
+      if (!d) continue;
+      const resolved = path.resolve(d);
+      if (seen.has(resolved)) continue;
+      if (!exists(d)) continue;
+      out.push(d);
+      seen.add(resolved);
+    }
+  }
   return out;
 }
 
+/**
+ * P-7d31a06b — Pre-approve a worktree's `.mcp.json` servers in `~/.claude.json`
+ * so Claude Code's first invocation in a fresh worktree cwd doesn't show the
+ * project-scoped "trust this MCP server?" prompt (which `--dangerously-skip-permissions`
+ * silently suppresses → the agent runs without the workspace MCPs).
+ *
+ * Writes to `projects[worktreePath].enabledMcpjsonServers` (the field Claude
+ * Code actually reads — confirmed against the live `~/.claude.json` schema:
+ * `enabledMcpjsonServers` / `disabledMcpjsonServers` are siblings of
+ * `mcpServers`, indexed by absolute project path). Notes on the PRD wording
+ * "mcpServers.approved": that's the intent label; `enabledMcpjsonServers` is
+ * the on-disk reality.
+ *
+ * Pure-ish: all I/O (fs reads, mutator) is injected for tests. Best-effort —
+ * callers MUST swallow errors and never block dispatch on this.
+ *
+ * Returns `{ wrote: boolean, reason: string, servers: string[] }`:
+ *   - reason ∈ { 'ok', 'flag-off', 'not-claude', 'no-worktree',
+ *                'no-workspace-mcp', 'invalid-workspace-mcp', 'no-servers' }
+ *   - servers: keys discovered in the workspace `.mcp.json` (regardless of write)
+ *
+ * Args:
+ *   runtimeName             — `runtime.name` from `resolveRuntime(...)`. Helper no-ops if !== 'claude'.
+ *   worktreePath            — absolute path to the agent's cwd (the worktree). Used as both the file location
+ *                             (`<worktreePath>/.mcp.json`) and the `projects[...]` key in `~/.claude.json`.
+ *   homeDir                 — `os.homedir()`. Injected for test isolation; helper does NOT call os.homedir directly.
+ *   engineConfig            — config.engine object; reads `claudePreApproveWorkspaceMcps` (default true via ENGINE_DEFAULTS).
+ *   mutateJsonFileLocked    — injected file-locked mutator (engine/shared.js#mutateJsonFileLocked).
+ *   existsSync, readFileSync — injectable fs primitives (default to node:fs).
+ */
+function preApproveWorkspaceMcps({
+  runtimeName,
+  worktreePath,
+  homeDir,
+  engineConfig,
+  mutateJsonFileLocked,
+  existsSync = fs.existsSync,
+  readFileSync = fs.readFileSync,
+} = {}) {
+  if (engineConfig && engineConfig.claudePreApproveWorkspaceMcps === false) {
+    return { wrote: false, reason: 'flag-off', servers: [] };
+  }
+  if (runtimeName !== 'claude') {
+    return { wrote: false, reason: 'not-claude', servers: [] };
+  }
+  if (!worktreePath || typeof worktreePath !== 'string') {
+    return { wrote: false, reason: 'no-worktree', servers: [] };
+  }
+  const workspaceMcpPath = path.join(worktreePath, '.mcp.json');
+  if (!existsSync(workspaceMcpPath)) {
+    return { wrote: false, reason: 'no-workspace-mcp', servers: [] };
+  }
+  let workspaceMcp;
+  try {
+    workspaceMcp = JSON.parse(readFileSync(workspaceMcpPath, 'utf8'));
+  } catch {
+    return { wrote: false, reason: 'invalid-workspace-mcp', servers: [] };
+  }
+  const serversObj = workspaceMcp && typeof workspaceMcp === 'object' ? workspaceMcp.mcpServers : null;
+  const servers = serversObj && typeof serversObj === 'object' && !Array.isArray(serversObj)
+    ? Object.keys(serversObj).filter((k) => typeof k === 'string' && k.length > 0)
+    : [];
+  if (servers.length === 0) {
+    return { wrote: false, reason: 'no-servers', servers: [] };
+  }
+  if (!homeDir || typeof mutateJsonFileLocked !== 'function') {
+    return { wrote: false, reason: 'no-home-or-mutator', servers };
+  }
+  const claudeJsonPath = path.join(homeDir, '.claude.json');
+  let didWrite = false;
+  mutateJsonFileLocked(claudeJsonPath, (data) => {
+    const root = data && typeof data === 'object' ? data : {};
+    if (!root.projects || typeof root.projects !== 'object') root.projects = {};
+    const projectKey = worktreePath;
+    const proj = root.projects[projectKey] && typeof root.projects[projectKey] === 'object'
+      ? root.projects[projectKey]
+      : {};
+    // enabledMcpjsonServers is Claude's actual on-disk approval field
+    const enabled = Array.isArray(proj.enabledMcpjsonServers) ? proj.enabledMcpjsonServers.slice() : [];
+    const disabled = Array.isArray(proj.disabledMcpjsonServers) ? proj.disabledMcpjsonServers.slice() : [];
+    const enabledSet = new Set(enabled.filter((s) => typeof s === 'string'));
+    let mutated = false;
+    for (const name of servers) {
+      if (!enabledSet.has(name)) {
+        enabledSet.add(name);
+        mutated = true;
+      }
+    }
+    // If a server was previously explicitly disabled, lift the disabled mark when we
+    // re-approve it — otherwise Claude treats the disabled entry as authoritative.
+    const nextDisabled = disabled.filter((s) => typeof s === 'string' && !servers.includes(s));
+    if (nextDisabled.length !== disabled.length) mutated = true;
+    if (!mutated) return data;
+    proj.enabledMcpjsonServers = [...enabledSet];
+    proj.disabledMcpjsonServers = nextDisabled;
+    root.projects[projectKey] = proj;
+    didWrite = true;
+    return root;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+  return { wrote: didWrite, reason: 'ok', servers };
+}
+
 // ─── Main script execution ──────────────────────────────────────────────────
 
 function _installHint(name, runtime) {
@@ -345,7 +498,7 @@ function main() {
     console.error('Usage: node spawn-agent.js <prompt-file> <sysprompt-file> [--runtime <name>] [args...]');
     process.exit(1);
   }
-  const { promptFile, sysPromptFile, runtimeName, opts, passthrough } = parsed;
+  const { promptFile, sysPromptFile, runtimeName, opts, passthrough, projectHarnessDirs, hermetic } = parsed;
 
   const env = cleanChildEnv();
   injectAdoTokenEnvForRepoHost(env);
@@ -382,8 +535,21 @@ function main() {
   // Skill discovery dirs — agents run with CWD set to an external repo
   // worktree, so runtime-native global assets would otherwise be invisible.
   // The adapter owns both where those assets live and how to surface them.
+  // P-08b62d49: engine.js also forwards uncommitted project-local harness
+  // dirs from the operator's main checkout via `--project-harness-dir <path>`
+  // (one per dir, accumulated in `projectHarnessDirs`) so worktree-bound
+  // agents inherit them too. See docs/harness-propagation.md.
+  // P-49e1c8b7: when engine.js passes `--hermetic-harness`, computeAddDirs
+  // returns [minionsDir] only — both user-asset dirs and project harness
+  // dirs are dropped for a known-empty harness surface.
   const minionsDir = path.resolve(__dirname, '..');
-  const addDirs = computeAddDirs({ runtime, minionsDir, homeDir: os.homedir() });
+  const addDirs = computeAddDirs({
+    runtime,
+    minionsDir,
+    homeDir: os.homedir(),
+    projectHarnessDirs,
+    hermetic,
+  });
 
   let resolved;
   try { resolved = runtime.resolveBinary({ env }); }
@@ -639,6 +805,6 @@ function main() {
   });
 }
 
-module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs, createParentPipeForwarder, assertStaleHeadOk };
+module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs, preApproveWorkspaceMcps, createParentPipeForwarder, assertStaleHeadOk };
 
 if (require.main === module) main();