@yemi33/minions 0.1.2179 → 0.1.2181

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)
@@ -2988,10 +3018,6 @@ function resolvePollFlag(engineCfg, granularKey, legacyMacroKey) {
 // (CLI chooses)" option (which submits an empty string) clears the override
 // instead of pinning the runtime to nothing.
 
-function _isMeaningful(v) {
-  return v !== undefined && v !== null && v !== '';
-}
-
 /**
  * Resolve the CLI runtime for a per-agent spawn. Priority:
  *   1. `agent.cli`              — per-agent override
@@ -3001,8 +3027,8 @@ function _isMeaningful(v) {
  * Does NOT fall through to `engine.ccCli`. CC and agents are independent paths.
  */
 function resolveAgentCli(agent, engine) {
-  if (agent && _isMeaningful(agent.cli)) return String(agent.cli);
-  if (engine && _isMeaningful(engine.defaultCli)) return String(engine.defaultCli);
+  if (agent && agent.cli !== undefined && agent.cli !== null && agent.cli !== '') return String(agent.cli);
+  if (engine && engine.defaultCli !== undefined && engine.defaultCli !== null && engine.defaultCli !== '') return String(engine.defaultCli);
   return ENGINE_DEFAULTS.defaultCli;
 }
 
@@ -3016,8 +3042,8 @@ function resolveAgentCli(agent, engine) {
  * it's a fleet-wide singleton.
  */
 function resolveCcCli(engine) {
-  if (engine && _isMeaningful(engine.ccCli)) return String(engine.ccCli);
-  if (engine && _isMeaningful(engine.defaultCli)) return String(engine.defaultCli);
+  if (engine && engine.ccCli !== undefined && engine.ccCli !== null && engine.ccCli !== '') return String(engine.ccCli);
+  if (engine && engine.defaultCli !== undefined && engine.defaultCli !== null && engine.defaultCli !== '') return String(engine.defaultCli);
   return ENGINE_DEFAULTS.defaultCli;
 }
 
@@ -3038,7 +3064,8 @@ function resolveCcCli(engine) {
  *   4. ENGINE_DEFAULTS.ccUseWorkerPool — final fallback
  *
  * Strict boolean check on the override so a literal `false` opts out even on
- * Copilot, matching `_isMeaningful` semantics for boolean flags.
+ * Copilot, matching the "treat empty/null/undefined as unset" semantics used
+ * throughout the resolve* helpers for boolean flags.
  */
 function resolveCcUseWorkerPool(engine) {
   // Guard 1 (W-mphlriic00095f69): pool transport is ACP-only. If CC runtime
@@ -3063,8 +3090,8 @@ function resolveCcUseWorkerPool(engine) {
  * to the user's `~/.copilot/settings.json` model).
  */
 function resolveAgentModel(agent, engine) {
-  if (agent && _isMeaningful(agent.model)) return String(agent.model);
-  if (engine && _isMeaningful(engine.defaultModel)) return String(engine.defaultModel);
+  if (agent && agent.model !== undefined && agent.model !== null && agent.model !== '') return String(agent.model);
+  if (engine && engine.defaultModel !== undefined && engine.defaultModel !== null && engine.defaultModel !== '') return String(engine.defaultModel);
   return undefined;
 }
 
@@ -3075,8 +3102,8 @@ function resolveAgentModel(agent, engine) {
  *   3. `undefined`              — let the runtime adapter pick
  */
 function resolveCcModel(engine) {
-  if (engine && _isMeaningful(engine.ccModel)) return String(engine.ccModel);
-  if (engine && _isMeaningful(engine.defaultModel)) return String(engine.defaultModel);
+  if (engine && engine.ccModel !== undefined && engine.ccModel !== null && engine.ccModel !== '') return String(engine.ccModel);
+  if (engine && engine.defaultModel !== undefined && engine.defaultModel !== null && engine.defaultModel !== '') return String(engine.defaultModel);
   return undefined;
 }
 
@@ -3151,6 +3178,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
@@ -3177,14 +3230,12 @@ let _legacyCcModelMigrationLogged = false;
 function applyLegacyCcModelMigration(config, { logger = log } = {}) {
   if (!config || !config.engine || typeof config.engine !== 'object') return false;
   const e = config.engine;
-  if (_isMeaningful(e.defaultModel)) return false;
-  if (!_isMeaningful(e.ccModel)) return false;
+  if (e.defaultModel !== undefined && e.defaultModel !== null && e.defaultModel !== '') return false;
+  if (!(e.ccModel !== undefined && e.ccModel !== null && e.ccModel !== '')) return false;
   e.defaultModel = e.ccModel;
   if (!_legacyCcModelMigrationLogged) {
     _legacyCcModelMigrationLogged = true;
-    try {
-      logger('warn', 'ccModel is now a CC-specific override; set defaultModel to apply fleet-wide');
-    } catch { /* logger may not be wired during tests — best-effort */ }
+    logger('warn', 'ccModel is now a CC-specific override; set defaultModel to apply fleet-wide');
   }
   return true;
 }
@@ -3276,7 +3327,7 @@ function runtimeConfigWarnings(config, registeredRuntimes) {
   // 1. Unknown CLI values across the fleet.
   const seen = new Set();
   const checkCli = (label, value) => {
-    if (!_isMeaningful(value)) return;
+    if (!(value !== undefined && value !== null && value !== '')) return;
     const key = `${label}:${value}`;
     if (seen.has(key)) return;
     seen.add(key);
@@ -3320,7 +3371,7 @@ function runtimeConfigWarnings(config, registeredRuntimes) {
     const ccCli = resolveCcCli(engine);
     let ccRuntime = null;
     try { ccRuntime = require('./runtimes').resolveRuntime(ccCli); } catch { /* unknown runtime — skip */ }
-    if (ccRuntime?.capabilities?.bareMode === true && !_isMeaningful(engine.ccSystemPrompt)) {
+    if (ccRuntime?.capabilities?.bareMode === true && !(engine.ccSystemPrompt !== undefined && engine.ccSystemPrompt !== null && engine.ccSystemPrompt !== '')) {
       warnings.push({
         id: 'bare-mode-misconfig',
         message: `engine.claudeBareMode is true but CC runs on ${ccCli} (which honours --bare) with no engine.ccSystemPrompt — CLAUDE.md auto-discovery is suppressed and CC will lose project context.`,
@@ -4021,6 +4072,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.
@@ -5045,11 +5097,7 @@ function sanitizeBranch(name) {
 // of side-effecting child_process imports at module load.
 
 function getOperatorLogin(config) {
-  try {
-    return require('./operator-identity').resolveOperatorLogin(config || {});
-  } catch {
-    return null;
-  }
+  return require('./operator-identity').resolveOperatorLogin(config || {});
 }
 
 function deriveWorkItemBranchName(item, config) {
@@ -5278,21 +5326,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 +5380,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 +5391,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 +8056,7 @@ module.exports = {
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentModel, resolveCcModel,
   resolveAgentMaxBudget, resolveAgentBareMode,
   resolveCopilotAgentDisabledMcpServers,
+  resolveAgentHermeticHarness,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   applyCcWorkerPoolForceOnMigration,
   runtimeConfigWarnings,
@@ -7897,6 +8149,9 @@ module.exports = {
   assertWorktreeOutsideProject,
   resolveProjectRootDir,
   resolveSpawnPaths,
+  validateWorkItemWorkdir,
+  applyWorkdir,
+  filterProjectHarnessDirsForWorkdir,
   READ_ONLY_ROOT_TASK_TYPES,
   isLiveCommandCenterPath,
   describeCcProtectedPaths,