@the-open-engine/zeroshot 6.10.0 → 6.10.2

package/src/agent-cli-provider/adapters/claude.ts

@@ -1,4 +1,5 @@
 import { getString, isRecord, stringifyJson, tryParseJson } from '../json';
+import { contractError } from '../contract-errors';
 import {
   type BuildProviderCommandOptions,
   type ClaudeCliFeatures,
@@ -66,6 +67,10 @@ function detectCliFeatures(helpText?: string | null): ClaudeCliFeatures {
     supportsVerbose: unknown ? true : /--verbose/.test(help),
     supportsModel: unknown ? true : /--model/.test(help),
     supportsEffort: unknown ? true : /--effort/.test(help),
+    // Settings carry mandatory safety hooks, so an unprobed or old CLI must
+    // fail closed before a provider process is spawned.
+    supportsSettings: !unknown && /--settings/.test(help),
+    supportsMcpConfig: !unknown && /--mcp-config/.test(help),
     supportsResume: unknown ? true : /--resume/.test(help),
     unknown,
   };
@@ -131,6 +136,40 @@ function addSessionArgs(args: string[], options: BuildProviderCommandOptions): v
   }
 }
 
+function addSettingsArgs(args: string[], options: BuildProviderCommandOptions): void {
+  const settingsPath = options.claudeSettingsFile?.trim();
+  if (settingsPath) {
+    args.push('--settings', settingsPath);
+  }
+}
+
+function addMcpConfigArgs(args: string[], options: BuildProviderCommandOptions): void {
+  if (!options.mcpConfig?.length) return;
+  args.push('--mcp-config', ...options.mcpConfig);
+}
+
+function failClosedUnsupportedRunConfig(options: BuildProviderCommandOptions): void {
+  const features = optionFeatures(options);
+  if (options.claudeSettingsFile?.trim() && features.supportsSettings === false) {
+    throw contractError({
+      code: 'invalid-field',
+      field: 'options.cliFeatures.supportsSettings',
+      exitCode: 2,
+      message:
+        'Claude CLI does not advertise --settings support required for Zeroshot safety hooks. Upgrade Claude Code before running this task.',
+    });
+  }
+  if (options.mcpConfig?.length && features.supportsMcpConfig === false) {
+    throw contractError({
+      code: 'invalid-field',
+      field: 'options.cliFeatures.supportsMcpConfig',
+      exitCode: 2,
+      message:
+        'Claude CLI does not advertise --mcp-config support required to preserve repository MCP tools. Upgrade Claude Code before running this task.',
+    });
+  }
+}
+
 function extractSessionId(line: string): string | null {
   const event = tryParseJson(line.trim());
   if (!isRecord(event)) return null;
@@ -185,15 +224,21 @@ function collectWarnings(options: BuildProviderCommandOptions): WarningMetadata[
 }
 
 function buildCommand(context: string, options: BuildProviderCommandOptions = {}): CommandSpec {
+  failClosedUnsupportedRunConfig(options);
   const { command, args: commandPrefix } = resolveClaudeCommand();
-  const args: string[] = [...commandPrefix, '--print', '--input-format', 'text'];
+  const args: string[] = [...commandPrefix, '--print'];
   const authEnv = options.authEnv ?? {};
 
+  // --mcp-config is variadic. A following option terminates its values before
+  // the positional prompt.
+  addMcpConfigArgs(args, options);
+  args.push('--input-format', 'text');
   addOutputArgs(args, options);
   addSchemaArgs(args, options);
   addModelArgs(args, options);
   addAutoApproveArgs(args, options);
   addSessionArgs(args, options);
+  addSettingsArgs(args, options);
 
   args.push(context);
 

package/src/agent-cli-provider/contract-options.ts

@@ -23,6 +23,7 @@ const CLI_FEATURE_FIELDS = [
   'supportsVerbose',
   'supportsModel',
   'supportsEffort',
+  'supportsSettings',
   'supportsJson',
   'supportsOutputSchema',
   'supportsDir',
@@ -209,6 +210,11 @@ function normalizeBuildOptions(value: Record<string, unknown>): BuildProviderCom
     'continueSession',
     optionalBooleanValue(value.continueSession, 'options.continueSession')
   );
+  addDefined(
+    result,
+    'claudeSettingsFile',
+    optionalStringValue(value.claudeSettingsFile, 'options.claudeSettingsFile')
+  );
   addDefined(result, 'cliFeatures', optionalCliFeatures(value.cliFeatures));
   addDefined(result, 'mcpConfig', optionalMcpConfig(value.mcpConfig));
   addDefined(

package/src/agent-cli-provider/types.ts

@@ -101,6 +101,8 @@ export interface ClaudeCliFeatures extends BaseCliFeatures {
   readonly supportsVerbose: boolean;
   readonly supportsModel: boolean;
   readonly supportsEffort: boolean;
+  readonly supportsSettings: boolean;
+  readonly supportsMcpConfig: boolean;
   readonly supportsResume: boolean;
 }
 
@@ -195,6 +197,7 @@ export interface CliFeatureOverrides {
   readonly supportsVerbose?: boolean;
   readonly supportsModel?: boolean;
   readonly supportsEffort?: boolean;
+  readonly supportsSettings?: boolean;
   readonly supportsJson?: boolean;
   readonly supportsOutputSchema?: boolean;
   readonly supportsDir?: boolean;
@@ -231,10 +234,10 @@ export interface CliFeatureOverrides {
 }
 
 export interface CleanupMetadata {
-  readonly kind: 'temp-file';
+  readonly kind: 'temp-file' | 'temp-directory';
   readonly provider: ProviderId;
   readonly path: string;
-  readonly reason: 'output-schema';
+  readonly reason: 'output-schema' | 'settings-overlay';
 }
 
 export interface WarningMetadata {
@@ -268,14 +271,14 @@ export interface BuildProviderCommandOptions {
   readonly autoApprove?: boolean;
   readonly resumeSessionId?: string;
   readonly continueSession?: boolean;
+  readonly claudeSettingsFile?: string;
   readonly cliFeatures?: CliFeatureOverrides;
   readonly authEnv?: Readonly<Record<string, string>>;
   readonly strictSchema?: boolean;
   readonly gateway?: GatewayBuildOptions;
-  // MCP server configs forwarded to providers that accept an MCP config CLI flag (currently
-  // Copilot's `--additional-mcp-config`). Each entry is an inline JSON string (the standard
-  // `{"mcpServers": {...}}` envelope) or an `@<path>` file reference; adapters emit one flag per
-  // entry. Providers whose adapter models no MCP flag ignore this field.
+  // MCP server configs forwarded to providers that accept an MCP config CLI flag. Claude accepts
+  // one variadic `--mcp-config` followed by file paths; adapters such as Copilot accept repeated
+  // flags with inline JSON so configs survive container path translation.
   readonly mcpConfig?: readonly string[];
 }
 

package/src/claude-task-runner.js

@@ -12,7 +12,24 @@ const { loadSettings } = require('../lib/settings');
 const { normalizeProviderName } = require('../lib/provider-names');
 const { getProvider } = require('./providers');
 const { prependWorktreeToolBinToEnv } = require('./worktree-tooling-env');
-const { prepareClaudeConfigDir } = require('./worktree-claude-config');
+const { applyDarwinKeychainBoundaryToEnv } = require('./darwin-keychain-boundary');
+const { getTask, getTaskBySpawnOwnershipToken } = require('../task-lib/store.js');
+const {
+  TASK_SPAWN_OWNERSHIP_TOKEN_ENV,
+  cleanupCallerOwnedCommand,
+  callerOwnsCommandCleanup,
+  createTaskSpawnOwnershipToken,
+  requireTaskIdFromWrapperResult,
+  trackTaskWrapperCleanupOwnership,
+} = require('./task-spawn-cleanup-ownership');
+const {
+  CLAUDE_MCP_CONFIG_ENV,
+  CLAUDE_SETTINGS_ENV,
+  cleanupClaudeSettingsOverlay,
+  prepareClaudeSettingsOverlay,
+  resolveContainerMcpConfigPath,
+  resolveRepoMcpConfigPath,
+} = require('./worktree-claude-config');
 const {
   appendTaskRunModelArgs,
   wrapTaskRunWithIsolatedSettings,
@@ -80,6 +97,28 @@ function runCommand(command, args, options = {}, callback = null) {
   });
 }
 
+const TASK_TERMINAL_STATUSES = new Set(['completed', 'failed', 'killed', 'stale', 'cancelled']);
+
+async function cleanupPersistedTaskAfterLaunchFailure(ctPath, taskId) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    let commandError = null;
+    try {
+      await runCommand(ctPath, ['kill', taskId], { timeout: 10000 });
+    } catch (error) {
+      commandError = error;
+    }
+    const task = getTask(taskId);
+    if (!task || (TASK_TERMINAL_STATUSES.has(task.status) && !task.commandCleanup)) {
+      return;
+    }
+    lastError =
+      commandError ||
+      new Error(`Task ${taskId} termination and command cleanup were not confirmed`);
+  }
+  throw lastError || new Error(`Task ${taskId} cleanup failed`);
+}
+
 function runCommandSync(command, args, options = {}) {
   const timeout = options.timeout ?? 30000;
   const result = spawnSync(command, args, { ...options, timeout });
@@ -95,6 +134,17 @@ function runCommandSync(command, args, options = {}) {
   return result.stdout?.toString() || '';
 }
 
+function appendIsolatedMcpConfigArgs(command, provider, options) {
+  if (provider !== 'claude') return;
+  const mcpConfigPath = resolveContainerMcpConfigPath({
+    cwd: options.cwd || process.cwd(),
+    worktreePath: options.worktreePath || null,
+  });
+  if (mcpConfigPath) {
+    command.push('--mcp-config', mcpConfigPath);
+  }
+}
+
 class ClaudeTaskRunner extends TaskRunner {
   /**
    * @param {Object} options
@@ -102,6 +152,7 @@ class ClaudeTaskRunner extends TaskRunner {
    * @param {boolean} [options.quiet] - Suppress console logging
    * @param {number} [options.timeout] - Task timeout in ms (default: 1 hour)
    * @param {Function} [options.onOutput] - Callback for output lines
+   * @param {Function} [options.applyDarwinKeychainBoundary] - Boundary injection seam for tests
    */
   constructor(options = {}) {
     super();
@@ -109,6 +160,8 @@ class ClaudeTaskRunner extends TaskRunner {
     this.quiet = options.quiet || false;
     this.timeout = options.timeout || 60 * 60 * 1000;
     this.onOutput = options.onOutput || null;
+    this.applyDarwinKeychainBoundary =
+      options.applyDarwinKeychainBoundary || applyDarwinKeychainBoundaryToEnv;
   }
 
   /**
@@ -191,14 +244,20 @@ class ClaudeTaskRunner extends TaskRunner {
       worktreePath,
     });
 
-    const taskId = await this._spawnAndGetTaskId(ctPath, args, cwd, spawnEnv, agentId);
+    let taskId;
+    try {
+      taskId = await this._spawnAndGetTaskId(ctPath, args, cwd, spawnEnv, agentId);
+    } catch (error) {
+      cleanupCallerOwnedCommand(error, () =>
+        cleanupClaudeSettingsOverlay(spawnEnv[CLAUDE_SETTINGS_ENV])
+      );
+      throw error;
+    }
 
+    // Once a task ID is returned, the detached watcher owns provider
+    // termination and command cleanup.
     this._log(`📋 [${agentId}]: Following zeroshot logs for ${taskId}`);
-
-    // Wait for task registration
     await this._waitForTaskReady(ctPath, taskId);
-
-    // Follow logs until completion
     return this._followLogs(ctPath, taskId, agentId);
   }
 
@@ -321,16 +380,30 @@ class ClaudeTaskRunner extends TaskRunner {
     const spawnEnv = {
       ...process.env,
     };
+    let claudeSettingsPath = null;
     if (providerName === 'claude' && resolvedModelSpec?.model) {
       spawnEnv.ANTHROPIC_MODEL = resolvedModelSpec.model;
     }
     if (providerName === 'claude') {
-      const claudeConfigDir = prepareClaudeConfigDir({ cwd, worktreePath });
-      if (claudeConfigDir) {
-        spawnEnv.CLAUDE_CONFIG_DIR = claudeConfigDir;
+      claudeSettingsPath = prepareClaudeSettingsOverlay({
+        includeDangerousGit: Boolean(worktreePath),
+      });
+      spawnEnv[CLAUDE_SETTINGS_ENV] = claudeSettingsPath;
+      const mcpConfigPath = resolveRepoMcpConfigPath({ cwd, worktreePath });
+      if (mcpConfigPath) {
+        spawnEnv[CLAUDE_MCP_CONFIG_ENV] = mcpConfigPath;
       }
     }
 
+    // KEYCHAIN BOUNDARY (darwin only): keep non-interactive worker descendants
+    // away from the user's GUI Keychain session (issue #704).
+    try {
+      this.applyDarwinKeychainBoundary(spawnEnv);
+    } catch (error) {
+      if (claudeSettingsPath) cleanupClaudeSettingsOverlay(claudeSettingsPath);
+      throw error;
+    }
+
     prependWorktreeToolBinToEnv(spawnEnv, { cwd, worktreePath });
 
     return spawnEnv;
@@ -345,16 +418,49 @@ class ClaudeTaskRunner extends TaskRunner {
    * @returns {Promise<string>}
    */
   _spawnAndGetTaskId(ctPath, args, cwd, spawnEnv, _agentId) {
+    const ownershipToken = createTaskSpawnOwnershipToken();
+    const findPersistedTaskId = () => getTaskBySpawnOwnershipToken(ownershipToken)?.id || null;
     return new Promise((resolve, reject) => {
       const proc = spawn(ctPath, args, {
         cwd,
         stdio: ['ignore', 'pipe', 'pipe'],
-        env: spawnEnv,
+        env: { ...spawnEnv, [TASK_SPAWN_OWNERSHIP_TOKEN_ENV]: ownershipToken },
         windowsHide: true,
       });
 
       let stdout = '';
       let stderr = '';
+      let settled = false;
+      const classifyCleanupOwnership = trackTaskWrapperCleanupOwnership(findPersistedTaskId);
+      const rejectWithOwnership = async (error) => {
+        if (settled) return;
+        settled = true;
+        const classifiedError = classifyCleanupOwnership(error);
+        if (!callerOwnsCommandCleanup(classifiedError)) {
+          classifiedError.spawnOwnershipToken = ownershipToken;
+          let persistedTaskId = null;
+          let lookupError = null;
+          try {
+            persistedTaskId = findPersistedTaskId();
+          } catch (lookupFailure) {
+            lookupError = lookupFailure;
+          }
+          classifiedError.taskId = persistedTaskId;
+          try {
+            if (lookupError) throw lookupError;
+            if (persistedTaskId) {
+              await cleanupPersistedTaskAfterLaunchFailure(ctPath, persistedTaskId);
+            }
+          } catch (cleanupError) {
+            classifiedError.message += ` Task cleanup was not confirmed: ${cleanupError.message}`;
+            classifiedError.permanent = true;
+            classifiedError.restartExhausted = true;
+            classifiedError.terminationExhausted = true;
+            classifiedError.terminationAttempts = persistedTaskId ? 3 : 1;
+          }
+        }
+        reject(classifiedError);
+      };
 
       proc.stdout.on('data', (data) => {
         stdout += data.toString();
@@ -364,21 +470,26 @@ class ClaudeTaskRunner extends TaskRunner {
         stderr += data.toString();
       });
 
-      proc.on('close', (code) => {
-        if (code === 0) {
-          const match = stdout.match(/Task spawned: ((?:task-)?[a-z]+-[a-z]+-[a-z0-9]+)/);
-          if (match) {
-            resolve(match[1]);
-          } else {
-            reject(new Error(`Could not parse task ID from output: ${stdout}`));
-          }
-        } else {
-          reject(new Error(`zeroshot task run failed with code ${code}: ${stderr}`));
+      proc.on('close', async (code) => {
+        if (settled) return;
+        try {
+          const taskId = requireTaskIdFromWrapperResult({
+            code,
+            stdout,
+            stderr,
+            parseTaskId: (output) =>
+              output.match(/Task spawned: ((?:task-)?[a-z]+-[a-z]+-[a-z0-9]+)/)?.[1],
+            persistedTaskId: findPersistedTaskId(),
+          });
+          settled = true;
+          resolve(taskId);
+        } catch (error) {
+          await rejectWithOwnership(error);
         }
       });
 
-      proc.on('error', (error) => {
-        reject(error);
+      proc.on('error', async (error) => {
+        await rejectWithOwnership(error);
       });
     });
   }
@@ -424,6 +535,7 @@ class ClaudeTaskRunner extends TaskRunner {
       let statusCheckInterval = null;
       let resolved = false;
       let lineBuffer = '';
+      let cleanupRecoveryPending = false;
 
       // Get log file path
       try {
@@ -558,33 +670,43 @@ class ClaudeTaskRunner extends TaskRunner {
 
       statusCheckInterval = setInterval(() => {
         runCommand(ctPath, ['status', taskId], {}, (error, stdout) => {
-          if (resolved) return;
-
-          if (
-            !error &&
-            (stdout.includes('Status:     completed') || stdout.includes('Status:     failed'))
-          ) {
-            const success = stdout.includes('Status:     completed');
+          if (resolved || error) return;
+          const terminalMatch = stdout.match(/Status:\s+(completed|failed)/i);
+          if (!terminalMatch) return;
+          if (/Cleanup:\s+pending/i.test(stdout)) {
+            if (!cleanupRecoveryPending) {
+              cleanupRecoveryPending = true;
+              runCommand(ctPath, ['kill', taskId], { timeout: 10000 }, (cleanupError) => {
+                cleanupRecoveryPending = false;
+                if (cleanupError) {
+                  this._log(
+                    `⚠️ [${agentId}]: Terminal cleanup recovery will retry: ${cleanupError.message}`
+                  );
+                }
+              });
+            }
+            return;
+          }
 
-            pollLogFile();
+          const success = terminalMatch[1].toLowerCase() === 'completed';
+          pollLogFile();
 
-            setTimeout(() => {
-              if (resolved) return;
-              resolved = true;
+          setTimeout(() => {
+            if (resolved) return;
+            resolved = true;
 
-              if (pollInterval) clearInterval(pollInterval);
-              if (statusCheckInterval) clearInterval(statusCheckInterval);
+            clearInterval(pollInterval);
+            clearInterval(statusCheckInterval);
 
-              const errorContext = extractErrorContext(success, stdout);
+            const errorContext = extractErrorContext(success, stdout);
 
-              resolve({
-                success,
-                output,
-                error: errorContext,
-                taskId,
-              });
-            }, 500);
-          }
+            resolve({
+              success,
+              output,
+              error: errorContext,
+              taskId,
+            });
+          }, 500);
         });
       }, 1000);
 
@@ -664,6 +786,8 @@ class ClaudeTaskRunner extends TaskRunner {
       command.push('--json-schema', JSON.stringify(jsonSchema));
     }
 
+    appendIsolatedMcpConfigArgs(command, provider, options);
+
     let finalContext = context;
     if (jsonSchema && desiredOutputFormat === 'json' && runOutputFormat === 'stream-json') {
       finalContext += `\n\n## Output Format (REQUIRED)\n\nReturn a JSON object that matches this schema exactly.\n\nSchema:\n\`\`\`json\n${JSON.stringify(

package/src/darwin-keychain-boundary.js

@@ -0,0 +1,174 @@
+/**
+ * Darwin worker Keychain boundary (issue #704).
+ *
+ * Non-interactive local/worktree workers are spawned with the host environment,
+ * so worker descendants (e.g. `claude doctor` probing Keychain writes through
+ * `security -i`) reach the logged-in user's GUI Keychain session and launch
+ * SecurityAgent dialogs from a supposedly non-interactive cluster.
+ *
+ * On darwin, worker spawn envs get a managed shim directory prepended to PATH
+ * containing a `security` wrapper that fails closed on interactive invocations
+ * (`-i`, `-p`, or no arguments) with a deterministic diagnostic, and execs the
+ * real /usr/bin/security for every other subcommand so provider authentication
+ * (e.g. `security find-generic-password`) keeps working.
+ *
+ * Docker isolation never reaches this code path, and non-darwin platforms are
+ * left untouched. Set ZEROSHOT_ALLOW_INTERACTIVE_KEYCHAIN=1 to opt out.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { randomUUID } = require('node:crypto');
+
+const SHIM_DIR_RELATIVE_PATH = path.join('.zeroshot', 'keychain-shim');
+const REAL_SECURITY_PATH = '/usr/bin/security';
+const OPT_OUT_ENV_VAR = 'ZEROSHOT_ALLOW_INTERACTIVE_KEYCHAIN';
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function buildSecurityShimScript(realSecurityPath) {
+  return `#!/bin/sh
+# Managed by Zeroshot (src/darwin-keychain-boundary.js). Do not edit.
+#
+# Non-interactive Zeroshot workers must not open the logged-in user's GUI
+# Keychain session (SecurityAgent). Interactive \`security\` invocations fail
+# closed here; every other subcommand is passed through to the real binary so
+# provider authentication keeps working.
+
+REAL_SECURITY=${shellQuote(realSecurityPath)}
+
+if [ "\${${OPT_OUT_ENV_VAR}:-0}" = "1" ]; then
+  exec "$REAL_SECURITY" "$@"
+fi
+
+fail_closed() {
+  echo "zeroshot: blocked interactive 'security' invocation from a non-interactive worker (argv: $*)." >&2
+  echo "zeroshot: this cluster has no interactive Keychain session, so SecurityAgent prompts are disabled." >&2
+  echo "zeroshot: run the cluster with Docker isolation or configure explicit credentials for the tool that attempted Keychain access." >&2
+  echo "zeroshot: set ${OPT_OUT_ENV_VAR}=1 to restore interactive Keychain access." >&2
+  exit 1
+}
+
+# \`security\` without arguments enters interactive mode.
+[ "$#" -eq 0 ] && fail_closed
+
+# Global options precede the subcommand. -i (interactive) and -p (prompt,
+# implies -i) must not reach the real binary; option letters may be bundled
+# (e.g. -qi). Scanning stops at the first non-option token (the subcommand).
+for arg in "$@"; do
+  case "$arg" in
+    -*i*|-*p*) fail_closed "$@" ;;
+    -*) ;;
+    *) break ;;
+  esac
+done
+
+exec "$REAL_SECURITY" "$@"
+`;
+}
+
+/**
+ * Create (or refresh) the managed shim directory containing the `security`
+ * wrapper. Idempotent: the script is only rewritten when its content changes.
+ *
+ * @param {object} [options]
+ * @param {string} [options.shimBaseDir] - Shim directory (tests only); defaults to ~/.zeroshot/keychain-shim.
+ * @param {string} [options.realSecurityPath] - Real binary to exec (tests only); defaults to /usr/bin/security.
+ * @returns {string} Absolute path of the shim directory.
+ */
+function ensureDarwinKeychainShimDir(options = {}) {
+  const shimDir = options.shimBaseDir || path.join(os.homedir(), SHIM_DIR_RELATIVE_PATH);
+  const script = buildSecurityShimScript(options.realSecurityPath || REAL_SECURITY_PATH);
+  const shimPath = path.join(shimDir, 'security');
+
+  fs.mkdirSync(shimDir, { recursive: true });
+
+  let existing = null;
+  try {
+    existing = fs.readFileSync(shimPath, 'utf8');
+  } catch {
+    // Missing or unreadable: (re)write below.
+  }
+  if (existing !== script) {
+    const tempPath = path.join(shimDir, `.security.${process.pid}.${randomUUID()}.tmp`);
+    try {
+      fs.writeFileSync(tempPath, script, { mode: 0o755, flag: 'wx' });
+      // The creation mode is subject to umask. Set the final mode before the
+      // rename so the live path is never observable as non-executable.
+      fs.chmodSync(tempPath, 0o755);
+      fs.renameSync(tempPath, shimPath);
+    } catch (error) {
+      try {
+        // Remove any unpublished partial file without masking the publication
+        // failure that caused this cleanup path.
+        fs.rmSync(tempPath, { force: true });
+      } catch (cleanupError) {
+        error.message += ` Cleanup also failed: ${cleanupError.message}.`;
+      }
+      throw error;
+    }
+  } else {
+    // An existing matching shim may have drifted permissions.
+    fs.chmodSync(shimPath, 0o755);
+  }
+
+  return shimDir;
+}
+
+/**
+ * Prepend the Keychain boundary shim to a worker spawn env's PATH.
+ *
+ * No-op off darwin and when the operator opted out via
+ * ZEROSHOT_ALLOW_INTERACTIVE_KEYCHAIN=1. Fails closed (throws) when the shim
+ * cannot be installed: spawning the worker anyway would silently re-expose the
+ * interactive Keychain session.
+ *
+ * @param {object} env - Spawn env to mutate (also returned).
+ * @param {object} [options]
+ * @param {string} [options.platform] - Platform override (tests only).
+ * @param {string} [options.shimBaseDir] - See ensureDarwinKeychainShimDir.
+ * @param {string} [options.realSecurityPath] - See ensureDarwinKeychainShimDir.
+ * @returns {object} The same env object.
+ */
+function applyDarwinKeychainBoundaryToEnv(env, options = {}) {
+  const platform = options.platform || process.platform;
+  if (platform !== 'darwin') {
+    return env;
+  }
+  if (env[OPT_OUT_ENV_VAR] === '1' || process.env[OPT_OUT_ENV_VAR] === '1') {
+    return env;
+  }
+
+  let shimDir;
+  try {
+    shimDir = ensureDarwinKeychainShimDir(options);
+  } catch (error) {
+    throw new Error(
+      `Failed to install the darwin Keychain boundary shim: ${error.message}. ` +
+        `Non-interactive workers must not reach the interactive Keychain session; ` +
+        `use Docker isolation or set ${OPT_OUT_ENV_VAR}=1 to opt out.`
+    );
+  }
+
+  // Darwin environment keys are case-sensitive: descendants consult PATH,
+  // never a differently-cased key such as Path. Preserve empty components
+  // because POSIX interprets them as the current directory. An absent PATH
+  // retains Node/libuv's default Unix search path after the shim, while an
+  // explicitly empty PATH retains its empty component (`<shim>:`).
+  const existingEntries =
+    env.PATH === undefined
+      ? ['/usr/bin', '/bin']
+      : String(env.PATH)
+          .split(path.delimiter)
+          .filter((entry) => entry !== shimDir);
+  env.PATH = [shimDir, ...existingEntries].join(path.delimiter);
+  return env;
+}
+
+module.exports = {
+  applyDarwinKeychainBoundaryToEnv,
+  ensureDarwinKeychainShimDir,
+};