@yemi33/minions 0.1.2178 → 0.1.2180

package/engine/shared.js

@@ -484,18 +484,99 @@ function resolveEngineCacheDir(fallbackEngineDir) {
 // Cross-platform URL opener. Uses execSync so failures fall through the
 // try/catch and the caller sees them. Dashboard self-open and `minions dash`
 // / `minions restart` post-health open all funnel through here.
-function openUrlInBrowser(url) {
+//
+// Every call writes a structured `event: 'browser-open'` entry to log.json
+// (via shared.log) and bumps a per-reason counter in `_engine.browserOpens`
+// in metrics.json. Callers MUST pass `opts.reason` so the log/metric is
+// attributable; a missing reason is logged at `warn` level with
+// `reason: 'unknown'` to make a regression loud rather than silent.
+//
+// `MINIONS_NO_AUTO_OPEN=1` short-circuits the open and writes a debug-level
+// SUPPRESSED entry instead — this lets us prove the kill-switch is firing
+// in production (absence of opens otherwise looks identical whether the
+// guard worked, nobody tried to open, or the guard regressed).
+//
+// Note: browser windows opened by external MCP servers (e.g. @playwright/mcp)
+// do NOT funnel through this primitive and are therefore NOT logged. See
+// MTG-mqam2mjs000e39d7.
+//
+// @param {string} url - URL to open in the user's default browser.
+// @param {Object} [opts]
+// @param {string} [opts.reason] - Why we are opening (e.g. 'cli-dash-warm',
+//   'cli-start-force-open', 'dashboard-self-open'). Required-in-practice;
+//   missing values are logged at warn level.
+// @param {string} [opts.callerHint] - Optional `file:line` to disambiguate
+//   when one reason has multiple call sites.
+// @returns {{ok: boolean, error?: string, suppressed?: boolean}}
+function openUrlInBrowser(url, opts = {}) {
+  const reason = (opts && typeof opts.reason === 'string' && opts.reason) ? opts.reason : 'unknown';
+  const callerHint = (opts && typeof opts.callerHint === 'string') ? opts.callerHint : null;
+  // Heuristic-driven opens (no explicit user action this dispatch) log at warn
+  // so a leak shows up as a warn cluster in the dashboard log filter.
+  const HEURISTIC_REASONS = new Set(['cli-restart-no-beacon', 'dashboard-self-open']);
+  let level = HEURISTIC_REASONS.has(reason) ? 'warn' : 'info';
+  if (reason === 'unknown') level = 'warn';
+  const callerStack = (new Error()).stack.split('\n').slice(2, 5).map(s => s.trim()).join(' | ');
+  const baseMeta = {
+    event: 'browser-open',
+    url,
+    reason,
+    callerHint,
+    callerStack,
+    pid: process.pid,
+    platform: process.platform,
+  };
+
+  // Kill-switch: log SUPPRESSED at debug level and skip execSync. Centralizing
+  // the check here means every caller (existing + future) is observable, and
+  // outer guards (e.g. ralph's W-mqb9y83o000le41e leak fixes) become belt-and-
+  // suspenders without breaking the log audit trail.
+  if (process.env.MINIONS_NO_AUTO_OPEN) {
+    log('debug', `[browser-open] SUPPRESSED reason=${reason} url=${url} (MINIONS_NO_AUTO_OPEN=1)`, {
+      ...baseMeta,
+      suppressed: true,
+    });
+    _bumpBrowserOpenMetric(reason, { suppressed: true });
+    return { ok: false, suppressed: true };
+  }
+
+  log(level, `[browser-open] reason=${reason} url=${url}`, baseMeta);
+  _bumpBrowserOpenMetric(reason);
+
   const { execSync } = require('child_process');
   try {
     if (process.platform === 'win32') execSync(`start "" "${url}"`, { stdio: 'ignore', windowsHide: true });
     else if (process.platform === 'darwin') execSync(`open "${url}"`, { stdio: 'ignore' });
     else execSync(`xdg-open "${url}"`, { stdio: 'ignore' });
+    log(level, `[browser-open] ok reason=${reason}`, { ...baseMeta, ok: true });
     return { ok: true };
   } catch (e) {
-    return { ok: false, error: e && e.message ? e.message : String(e) };
+    const errMsg = e && e.message ? e.message : String(e);
+    log(level, `[browser-open] failed reason=${reason} error=${errMsg}`, { ...baseMeta, ok: false, error: errMsg });
+    return { ok: false, error: errMsg };
   }
 }
 
+// Bump per-reason counter under metrics._engine.browserOpens. Best-effort —
+// metrics.json writes must never throw out of openUrlInBrowser. Schema:
+//   _engine.browserOpens.<reason> = { count, suppressedCount, lastAt }
+function _bumpBrowserOpenMetric(reason, { suppressed = false } = {}) {
+  try {
+    mutateMetrics((metrics) => {
+      if (!metrics._engine || typeof metrics._engine !== 'object') metrics._engine = {};
+      if (!metrics._engine.browserOpens || typeof metrics._engine.browserOpens !== 'object') {
+        metrics._engine.browserOpens = {};
+      }
+      const slot = metrics._engine.browserOpens[reason] || { count: 0, suppressedCount: 0, lastAt: null };
+      if (suppressed) slot.suppressedCount = (slot.suppressedCount || 0) + 1;
+      else slot.count = (slot.count || 0) + 1;
+      slot.lastAt = new Date().toISOString();
+      metrics._engine.browserOpens[reason] = slot;
+      return metrics;
+    });
+  } catch { /* metric best-effort — never throw out of openUrlInBrowser */ }
+}
+
 function _flushLogBuffer() {
   if (_logBuffer.length === 0) return;
   const drained = _logBuffer.splice(0);
@@ -2533,6 +2614,11 @@ const ENGINE_DEFAULTS = {
   cleanupEvery: 60,                  // runCleanup + MCP sync every N ticks (~10 min at default 10s tick)
   planCompletionScanEvery: 60,       // periodic PRD completion sweep (~10 min at default 10s tick) — catches plans completed while engine was down
   watchPollEvery: 18,                // checkWatches every N ticks (~3 min at default 10s tick)
+  // P-b2c3d4e5: cadence for MEMORY_BASELINE log line + diagnostics-memory.json
+  // sidecar write driven from engine.js tickInner. Defaults to 6 ticks ≈ 60s
+  // at the default 10s tickInterval. Set to 0 (or any non-positive integer)
+  // to disable both the log emission and sidecar write cleanly (operator opt-out).
+  memoryBaselineEveryTicks: 6,
   stalledDispatchSweepEvery: 120,    // stalled-dispatch retry sweep (~20 min at default 10s tick) — only fires when all agents idle
   // W-mp5trwh60008386d: per-PR 404 must repeat across N consecutive successful base-repo probes
   // before flipping a PR to `abandoned`. A single 404 on `repos/{slug}/pulls/{n}` can be a transient
@@ -2613,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)
@@ -3065,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
@@ -3935,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.
@@ -4284,6 +4427,30 @@ function getProjects(config) {
   return [];
 }
 
+// Generic, ambiguous project-name tokens that read poorly as a bare label in
+// the dashboard. For these, projectDisplayName derives a `<parentFolder>/<name>`
+// label from the project's localPath. `src` is the required case. DISPLAY ONLY —
+// the project `name` field is a load-bearing identifier and is never mutated.
+const GENERIC_PROJECT_NAME_TOKENS = new Set(['src', 'source', 'repo']);
+
+// Human-facing label for a project. Returns `project.name` unchanged for normal
+// names. When the name is a generic token (e.g. `src`), derives the parent
+// folder one level up from localPath and returns `<parentBasename>/<name>` —
+// e.g. name `src` at localPath `C:/office/src` → `office/src`. Falls back to the
+// bare name when localPath is missing or the parent can't be derived. Never
+// mutates the project; preserves the original name casing.
+function projectDisplayName(project) {
+  if (!project || typeof project !== 'object') return '';
+  const name = project.name == null ? '' : String(project.name);
+  if (!GENERIC_PROJECT_NAME_TOKENS.has(name.trim().toLowerCase())) return name;
+  const localPath = project.localPath == null ? '' : String(project.localPath);
+  const normalized = localPath.replace(/\\/g, '/').replace(/\/+$/, '');
+  if (!normalized) return name;
+  const parent = path.basename(path.dirname(normalized));
+  if (!parent || parent === '.') return name;
+  return `${parent}/${name}`;
+}
+
 function formatUnknownProjectError(projectName, projects = []) {
   const known = projects.map(p => p.name).filter(Boolean).join(', ') || '(none configured)';
   return `Project "${projectName}" not found. Known projects: ${known}`;
@@ -5168,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
@@ -5196,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,
     };
@@ -5205,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 ─────────────────────────────────
@@ -7695,6 +8065,7 @@ module.exports = {
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentModel, resolveCcModel,
   resolveAgentMaxBudget, resolveAgentBareMode,
   resolveCopilotAgentDisabledMcpServers,
+  resolveAgentHermeticHarness,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   applyCcWorkerPoolForceOnMigration,
   runtimeConfigWarnings,
@@ -7721,6 +8092,7 @@ module.exports = {
   mergeManifestAllowedTools,
   formatManifestRejection,
   getProjects,
+  projectDisplayName,
   formatUnknownProjectError,
   findProjectByName,
   findProjectByNameOrPath,
@@ -7786,6 +8158,9 @@ module.exports = {
   assertWorktreeOutsideProject,
   resolveProjectRootDir,
   resolveSpawnPaths,
+  validateWorkItemWorkdir,
+  applyWorkdir,
+  filterProjectHarnessDirsForWorkdir,
   READ_ONLY_ROOT_TASK_TYPES,
   isLiveCommandCenterPath,
   describeCcProtectedPaths,