@the-open-engine/zeroshot 6.2.0 → 6.4.0

package/lib/start-cluster.js

@@ -3,7 +3,10 @@ const { spawnSync } = require('child_process');
 const chalk = require('chalk');
 const { normalizeProviderName } = require('./provider-names');
 const { getProvider } = require('../src/providers');
+const { detectProvider } = require('../src/issue-providers');
 const TemplateResolver = require('../src/template-resolver');
+const { runModeFromPlan } = require('./run-mode');
+const { resolveRunPlan } = require('./run-plan');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 
@@ -96,35 +99,44 @@ function buildFileInput(file) {
   return { file };
 }
 
-function detectRunInput(inputArg) {
-  const isGitHubUrl = /^https?:\/\/github\.com\/[\w-]+\/[\w-]+\/issues\/\d+/.test(inputArg);
-  const isGitLabUrl = /gitlab\.(com|[\w.-]+)\/[\w-]+\/[\w-]+\/-\/issues\/\d+/.test(inputArg);
-  const isJiraUrl = /(atlassian\.net|jira\.[\w.-]+)\/browse\/[A-Z][A-Z0-9]+-\d+/.test(inputArg);
-  const isAzureUrl =
-    /dev\.azure\.com\/.*\/_workitems\/edit\/\d+/.test(inputArg) ||
-    /visualstudio\.com\/.*\/_workitems\/edit\/\d+/.test(inputArg);
-  const isJiraKey = /^[A-Z][A-Z0-9]+-\d+$/.test(inputArg);
-  const isIssueNumber = /^\d+$/.test(inputArg);
-  const isRepoIssue = /^[\w-]+\/[\w-]+#\d+$/.test(inputArg);
+function detectRunInput(inputArg, settings = {}, forceProvider = null) {
   const isMarkdownFile = /\.(md|markdown)$/i.test(inputArg);
-
-  if (
-    isGitHubUrl ||
-    isGitLabUrl ||
-    isJiraUrl ||
-    isAzureUrl ||
-    isJiraKey ||
-    isIssueNumber ||
-    isRepoIssue
-  ) {
-    return buildIssueInput(inputArg);
-  }
   if (isMarkdownFile) {
     return buildFileInput(inputArg);
   }
+
+  const ProviderClass = detectProvider(inputArg, settings, forceProvider);
+  if (ProviderClass) {
+    return buildIssueInput(inputArg);
+  }
+
   return buildTextInput(inputArg);
 }
 
+const STDIN_MARKER = '-';
+
+function isStdinInput(inputArg) {
+  return inputArg === STDIN_MARKER;
+}
+
+async function readStdinText(stream = process.stdin) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks.map((chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))))
+    .toString('utf8')
+    .trim();
+}
+
+function encodeStdinEnv(text) {
+  return Buffer.from(text, 'utf8').toString('base64');
+}
+
+function decodeStdinEnv(value) {
+  return Buffer.from(value, 'base64').toString('utf8');
+}
+
 function resolveProviderOverride(options = {}) {
   const override = options.provider || options.envProvider || process.env.ZEROSHOT_PROVIDER;
   if (!override || (typeof override === 'string' && !override.trim())) {
@@ -187,8 +199,20 @@ function mergeRunOptions(options) {
   return envRunOptions ? { ...envRunOptions, ...options } : options;
 }
 
-function resolveIsolation(mergedOptions, settings) {
-  return mergedOptions.docker || process.env.ZEROSHOT_DOCKER === '1' || settings.defaultDocker;
+// The single producer of the run plan for a cluster start: fold env + settings
+// into the flags, then resolve the canonical isolation/delivery/autoMerge plan.
+// buildStartOptions reads EVERY mode field off this one plan — no field
+// (isolation, worktree, autoPr, autoMerge, runMode) is derived independently.
+function resolveEffectiveRunPlan(mergedOptions, settings) {
+  return resolveRunPlan({
+    ...mergedOptions,
+    docker: anyTruthy(
+      mergedOptions.docker,
+      process.env.ZEROSHOT_DOCKER === '1',
+      settings.defaultDocker
+    ),
+    worktree: anyTruthy(mergedOptions.worktree, process.env.ZEROSHOT_WORKTREE === '1'),
+  });
 }
 
 function resolveMergeQueue(mergedOptions) {
@@ -227,14 +251,15 @@ function buildStartOptions({
   forceProvider,
 }) {
   const mergedOptions = mergeRunOptions(options);
+  const plan = resolveEffectiveRunPlan(mergedOptions, settings);
   return {
     clusterId,
     cwd: resolveTargetCwd(),
-    isolation: resolveIsolation(mergedOptions, settings),
+    isolation: plan.isolation === 'docker',
     isolationImage: firstTruthy(mergedOptions.dockerImage, process.env.ZEROSHOT_DOCKER_IMAGE),
-    worktree: anyTruthy(mergedOptions.worktree, process.env.ZEROSHOT_WORKTREE === '1'),
-    autoPr: anyTruthy(mergedOptions.pr, process.env.ZEROSHOT_PR === '1'),
-    autoMerge: process.env.ZEROSHOT_MERGE === '1',
+    worktree: plan.isolation === 'worktree',
+    autoPr: plan.delivery !== 'none',
+    autoMerge: plan.autoMerge,
     autoPush: process.env.ZEROSHOT_PUSH === '1',
     modelOverride: optionalValue(modelOverride),
     providerOverride: optionalValue(providerOverride),
@@ -246,6 +271,7 @@ function buildStartOptions({
     mergeQueue: resolveMergeQueue(mergedOptions),
     closeIssue: resolveCloseIssue(mergedOptions),
     ship: mergedOptions.ship,
+    runMode: runModeFromPlan(plan),
     requiredQualityGates: mergedOptions.requiredQualityGates,
     settings,
   };
@@ -310,6 +336,10 @@ module.exports = {
   buildIssueInput,
   buildFileInput,
   detectRunInput,
+  isStdinInput,
+  readStdinText,
+  encodeStdinEnv,
+  decodeStdinEnv,
   resolveProviderOverride,
   resolveConfigPath,
   loadClusterConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
   "main": "src/orchestrator.js",
   "bin": {
@@ -15,11 +15,13 @@
     "pretest": "npm run build:agent-cli-provider",
     "test": "node tests/run-tests.js",
     "test:unit": "node tests/run-tests.js",
-    "test:slow": "mocha 'tests/integration/**/*.test.js' --timeout 180000",
-    "test:all": "npm run test && npm run test:slow",
+    "test:e2e": "mocha 'tests/e2e/**/*.test.js' --timeout 120000",
+    "test:e2e:docker": "bash tests/integration/e2e-isolation-and-auto.test.sh",
+    "test:slow": "mocha 'tests/integration/**/*.test.js' 'tests/providers/**/*.test.js' --timeout 180000",
+    "test:all": "npm run test && npm run test:e2e && npm run test:slow",
     "test:coverage": "c8 npm run test:unit",
     "test:coverage:report": "c8 --reporter=html npm run test:unit && echo 'Coverage report generated at coverage/index.html'",
-    "postinstall": "node scripts/fix-node-pty-permissions.js",
+    "postinstall": "node scripts/fix-node-pty-permissions.js && node scripts/check-path.js",
     "start": "node cli/index.js",
     "typecheck": "tsc --noEmit",
     "typecheck:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.json",
@@ -94,7 +96,7 @@
     "cli/",
     "task-lib/",
     "cluster-templates/",
-    "hooks/",
+    "cluster-hooks/",
     "docker/",
     "scripts/",
     "README.md",
@@ -110,7 +112,6 @@
     "node-pty": "^1.1.0",
     "omelette": "^0.4.17",
     "pidusage": "^4.0.1",
-    "puppeteer": "^24.34.0",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {

package/scripts/check-path.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Postinstall check: warn if the npm global bin dir isn't on PATH.
+ *
+ * Runs after `npm install -g` regardless of whether the user can invoke
+ * `zeroshot` afterward (this is the only guaranteed-execution point in
+ * that failure scenario).
+ */
+
+const { checkBinDirOnPath, printPathWarning } = require('../lib/path-check');
+
+try {
+  const { onPath, binDir } = checkBinDirOnPath();
+  if (!onPath && binDir) {
+    printPathWarning(binDir);
+  }
+} catch (err) {
+  console.warn(`[postinstall] Warning: PATH check failed: ${err.message}`);
+}

package/scripts/validate-templates.js

@@ -8,11 +8,15 @@
  */
 
 const path = require('path');
-const { validateTemplates } = require('../src/template-validation');
+const { validateTemplates, formatValidationReport } = require('../src/template-validation');
 
 const TEMPLATES_DIR = path.join(__dirname, '../cluster-templates');
 
 function parseArgs(argv) {
+  const changedArg = argv.find((arg) => arg.startsWith('--changed='));
+  const changedFiles = changedArg
+    ? new Set(changedArg.split('=').slice(1).join('=').split(',').filter(Boolean))
+    : null;
   const simModeArg = argv.find((arg) => arg.startsWith('--sim='));
   const simMode = simModeArg ? simModeArg.split('=')[1] : process.env.ZEROSHOT_TEMPLATE_SIM;
   const randomScopeArg = argv.find((arg) => arg.startsWith('--random-scope='));
@@ -49,13 +53,16 @@ function parseArgs(argv) {
       maxSteps: Number.isFinite(sampleSteps) && sampleSteps > 0 ? sampleSteps : undefined,
       maxScenarioMs: Number.isFinite(sampleMs) && sampleMs > 0 ? sampleMs : undefined,
     },
+    changedFiles,
   };
 }
 
 async function main() {
   console.log('Validating cluster templates...\n');
 
-  const { deep, randomSampling, randomScope, randomOptions } = parseArgs(process.argv.slice(2));
+  const { deep, randomSampling, randomScope, randomOptions, changedFiles } = parseArgs(
+    process.argv.slice(2)
+  );
   const report = await validateTemplates({
     templatesDir: TEMPLATES_DIR,
     deep,
@@ -64,33 +71,8 @@ async function main() {
     randomOptions,
   });
 
-  let hasErrors = false;
-
-  for (const { filePath, result } of report.results) {
-    const relativePath = path.relative(process.cwd(), filePath);
-
-    if (!result.valid) {
-      hasErrors = true;
-      console.error(`\n❌ ${relativePath}`);
-      for (const error of result.errors) {
-        console.error(`   ERROR: ${error}`);
-      }
-      continue;
-    }
-
-    if (result.warnings.length > 0) {
-      console.warn(`\n⚠️  ${relativePath}`);
-      for (const warning of result.warnings) {
-        console.warn(`   WARN: ${warning}`);
-      }
-      continue;
-    }
-
-    console.log(`✓ ${relativePath}`);
-  }
-
-  console.log(`\n${'='.repeat(60)}`);
-  console.log(`Validated: ${report.validated} templates, Skipped: ${report.skipped} files`);
+  const { lines, hasErrors } = formatValidationReport(report, { changedFiles });
+  console.log(lines.join('\n'));
 
   if (hasErrors) {
     console.error('\n❌ VALIDATION FAILED - Fix errors above before merging\n');

package/src/agent/agent-hook-executor.js

@@ -141,7 +141,7 @@ async function executeHook(params) {
   }
 
   if (hook.action === 'verify_pull_request') {
-    await verifyPullRequest({ result, agent });
+    await verifyPullRequest({ result, agent, autoMerge: hook.config?.autoMerge });
     return;
   }
 

package/src/agent/agent-lifecycle.js

@@ -200,6 +200,8 @@ function start(agent) {
  * @returns {Promise<void>}
  */
 async function stop(agent) {
+  stopLivenessCheck(agent);
+
   if (!agent.running) {
     return;
   }

package/src/agent/agent-task-executor.js

@@ -118,7 +118,7 @@ function buildClaudeEnv(modelSpec, options = {}) {
     env.ANTHROPIC_MODEL = modelSpec.model;
   }
 
-  // Activate AskUserQuestion blocking hook (see hooks/block-ask-user-question.py)
+  // Activate AskUserQuestion blocking hook (see cluster-hooks/block-ask-user-question.py)
   env.ZEROSHOT_BLOCK_ASK_USER = '1';
 
   return env;
@@ -446,7 +446,7 @@ function ensureAskUserQuestionHook(targetClaudeDir = null) {
   }
 
   // Copy hook script if not present or outdated
-  const hookScriptSrc = path.join(__dirname, '..', '..', 'hooks', hookScriptName);
+  const hookScriptSrc = path.join(__dirname, '..', '..', 'cluster-hooks', hookScriptName);
   if (fs.existsSync(hookScriptSrc)) {
     // Always copy to ensure latest version
     fs.copyFileSync(hookScriptSrc, hookScriptDst);
@@ -524,7 +524,7 @@ function ensureDangerousGitHook(targetClaudeDir = null) {
   }
 
   // Copy hook script if not present or outdated
-  const hookScriptSrc = path.join(__dirname, '..', '..', 'hooks', hookScriptName);
+  const hookScriptSrc = path.join(__dirname, '..', '..', 'cluster-hooks', hookScriptName);
   if (fs.existsSync(hookScriptSrc)) {
     // Always copy to ensure latest version
     fs.copyFileSync(hookScriptSrc, hookScriptDst);
@@ -834,6 +834,7 @@ function spawnTaskProcess({ agent, ctPath, args, cwd, spawnEnv }) {
       cwd,
       stdio: ['ignore', 'pipe', 'pipe'],
       env: spawnEnv,
+      windowsHide: true,
     });
 
     // NOTE: Don't emit PROCESS_SPAWNED here - proc.pid is a wrapper that exits immediately.

package/src/agent/pr-verification.js

@@ -579,7 +579,9 @@ function shouldSkipVerification(adapter) {
   return skipVars.some((name) => process.env[name] === '1');
 }
 
-async function verifyPullRequest({ result, agent }) {
+async function verifyPullRequest({ result, agent, autoMerge }) {
+  // Default to true (merge required) so existing callers/tests and --ship semantics stay fail-closed.
+  const requireMerge = autoMerge !== false;
   const platform = resolveVerificationPlatform(agent);
   const adapter = getVerificationAdapter(platform);
   const providerName =
@@ -622,6 +624,30 @@ async function verifyPullRequest({ result, agent }) {
     );
   }
 
+  if (!requireMerge) {
+    // --pr mode: the PR/MR was created and verified to exist. It's left OPEN for human
+    // review - do NOT poll for merge or treat an unmerged PR as a failure.
+    if (adapter.isMerged(prData)) {
+      throw new Error(
+        `VERIFICATION FAILED: ${adapter.itemName} #${prData.number} is already merged, ` +
+          'but this run was started in review mode (autoMerge=false).'
+      );
+    }
+
+    agent._log(
+      `✅ VERIFICATION PASSED: ${adapter.itemName} #${prData.number} created (open for human review)`
+    );
+    publishClusterComplete(agent, {
+      ...buildVerificationPayload({
+        platform,
+        prData,
+        reason: 'git-pusher-complete-verified',
+      }),
+      merged: adapter.isMerged(prData),
+    });
+    return;
+  }
+
   if (!adapter.isMerged(prData)) {
     prData = await pollForMerge({ adapter, prData, agent, cwd: agent.workingDirectory });
   }

package/src/agents/git-pusher-template.js

@@ -341,7 +341,13 @@ function resolveGitHubConfig(options = {}) {
     (parseBool(repoGithub.closeIssue) === true ? 'always' : null) ||
     'never';
 
-  return { prBase, useMergeQueue, closeIssueMode };
+  // --ship (or explicit autoMerge) merges automatically; --pr alone stops after PR creation
+  // for human review. Repo settings can opt in to auto-merge when the caller hasn't decided.
+  const autoMerge =
+    options.autoMerge === true ||
+    (options.autoMerge !== false && parseBool(repoGithub.autoMerge) === true);
+
+  return { prBase, useMergeQueue, closeIssueMode, autoMerge };
 }
 
 /**
@@ -352,7 +358,7 @@ function resolveGitHubConfig(options = {}) {
  * @returns {Object|null} Platform configuration or null if unsupported
  */
 function getPlatformConfig(platform, config = {}) {
-  const { prBase, useMergeQueue, closeIssueMode } = config;
+  const { prBase, useMergeQueue, closeIssueMode, autoMerge } = config;
 
   const PLATFORM_CONFIGS = {
     github: {
@@ -373,6 +379,7 @@ for i in $(seq 1 90); do if timeout 30 gh pr view --json mergedAt --jq .mergedAt
       rebaseBranch: prBase || 'main',
       usesMergeQueue: useMergeQueue,
       closeIssueMode: closeIssueMode || 'never',
+      autoMerge: Boolean(autoMerge),
     },
     gitlab: {
       prName: 'MR',
@@ -384,6 +391,7 @@ for i in $(seq 1 90); do if timeout 30 gh pr view --json mergedAt --jq .mergedAt
       prUrlExample: 'https://gitlab.com/owner/repo/-/merge_requests/123',
       outputFields: { urlField: 'mr_url', numberField: 'mr_number', mergedField: 'merged' },
       closeIssueMode: closeIssueMode || 'never',
+      autoMerge: Boolean(autoMerge),
     },
     'azure-devops': {
       prName: 'PR',
@@ -402,6 +410,7 @@ for i in $(seq 1 90); do if timeout 30 gh pr view --json mergedAt --jq .mergedAt
       // Azure requires extracting PR ID from create output
       requiresPrIdExtraction: true,
       closeIssueMode: closeIssueMode || 'never',
+      autoMerge: Boolean(autoMerge),
     },
   };
 
@@ -414,6 +423,107 @@ for i in $(seq 1 90); do if timeout 30 gh pr view --json mergedAt --jq .mergedAt
  */
 const SUPPORTED_PLATFORMS = ['github', 'gitlab', 'azure-devops'];
 
+/**
+ * Generate the review-mode prompt (--pr without --ship): create the PR/MR and STOP.
+ * No merge step, no issue-closing - the PR is left open for human review.
+ * @param {Object} config - Platform configuration from PLATFORM_CONFIGS
+ * @returns {string} The complete review-mode prompt
+ */
+function generateReviewModePrompt(config) {
+  const { prName, prNameLower, createCmd, prUrlExample, outputFields, requiresPrIdExtraction } =
+    config;
+
+  return `CRITICAL: ALL VALIDATORS APPROVED. YOU ARE A TRANSPORT-ONLY GIT PUSHER.
+
+Your job is to preserve validator ownership: stage, commit, push, and create the ${prName} for HUMAN REVIEW.
+
+Do NOT edit source files, tests, configs, generated artifacts, or lockfiles.
+Do NOT inspect CI logs to debug product code.
+Do NOT resolve merge conflicts or rebase conflicts.
+Do NOT run implementation/debugging workflows after validators hand off.
+Do NOT merge the ${prName} - it is left OPEN for human review.
+Do NOT close the linked issue - it stays open until a human merges the ${prName}.
+
+Allowed after validation:
+- git add/status/commit/push
+- ${createCmd.split(' ').slice(0, 3).join(' ')}
+- status-only commands such as ${prName === 'PR' ? 'gh pr view/gh pr checks' : 'the platform PR/MR status command'}
+
+If commit hooks, push, ${prName} creation, or conflict handling requires code changes, STOP and report the blocked state in JSON. The implementation and validator agents must fix code and rerun quality gates.
+
+## MANDATORY STEPS - EXECUTE EACH ONE IN ORDER - DO NOT SKIP ANY STEP
+
+### STEP 1: Stage ALL changes (MANDATORY)
+\`\`\`bash
+git add -A
+\`\`\`
+Run this command. Do not skip it. If commit fails because hooks/checks fail, do not edit files. Output blocked JSON with the failure summary.
+
+### STEP 2: Check what's staged
+\`\`\`bash
+git status
+\`\`\`
+Run this. If nothing to commit, output JSON with ${outputFields.urlField}: null and stop.
+
+### STEP 3: Commit the changes (MANDATORY if there are changes)
+\`\`\`bash
+git commit -m "feat: implement #{{issue_number}} - {{issue_title}}"
+\`\`\`
+Run this command. Do not skip it.
+
+### STEP 4: Push to origin (MANDATORY)
+\`\`\`bash
+git push -u origin HEAD
+\`\`\`
+Run this. If it fails, do not edit files, rebase, or resolve conflicts. Output blocked JSON with the failure summary.
+
+⚠️ AFTER PUSH YOU ARE NOT DONE! CONTINUE TO STEP 5! ⚠️
+
+### STEP 5: CREATE THE ${prName.toUpperCase()} (MANDATORY - YOU MUST RUN THIS COMMAND)
+\`\`\`bash
+${createCmd}
+\`\`\`
+🚨 YOU MUST RUN \`${createCmd.split(' ').slice(0, 3).join(' ')}\`! Outputting a link is NOT creating a ${prName}! 🚨
+The push output shows a "Create a ${prNameLower}" link - IGNORE IT.
+You MUST run the \`${createCmd.split(' ').slice(0, 3).join(' ')}\` command above.${requiresPrIdExtraction ? '' : ` Save the actual ${prName} URL from the output.`}
+
+⚠️ AFTER THE ${prName} IS CREATED, YOU ARE DONE. DO NOT MERGE. DO NOT CLOSE THE ISSUE. ⚠️
+
+## CRITICAL RULES
+- Execute EVERY step in order (1, 2, 3, 4, 5)
+- Do NOT skip git add -A
+- Do NOT skip git commit
+- Do NOT skip ${createCmd.split(' ').slice(0, 3).join(' ')} - THE TASK IS NOT DONE UNTIL ${prName} EXISTS
+- Do NOT merge the ${prName} - this run is for human review only
+- Do NOT close the issue - it stays open until a human merges the ${prName}
+- Do NOT edit files after validator handoff
+- Do NOT debug product failures after validator handoff
+- If push or ${prName} creation fails, report it instead of fixing code
+- Output JSON as soon as the ${prName} is created (OPEN, unmerged), or a non-code transport failure blocks progress
+- A link from git push is NOT a ${prName} - you must run ${createCmd.split(' ').slice(0, 3).join(' ')}
+
+## Final Output
+ONLY after the ${prName} is CREATED (left OPEN for review), output:
+\`\`\`json
+{"${outputFields.urlField}": "${prUrlExample}", "${outputFields.numberField}": 123, "merged": false}
+\`\`\`
+
+If truly no changes exist, output:
+\`\`\`json
+{"${outputFields.urlField}": null, "${outputFields.numberField}": null, "merged": false}
+\`\`\`
+
+If blocked after creating a ${prName}, output:
+\`\`\`json
+{"${outputFields.urlField}": "${prUrlExample}", "${outputFields.numberField}": 123, "merged": false, "blocked": true, "blocked_reason": "ci_failed: test job failed"}
+\`\`\`
+
+If blocked before creating a ${prName}, output:
+\`\`\`json
+{"${outputFields.urlField}": null, "${outputFields.numberField}": null, "merged": false, "blocked": true, "blocked_reason": "commit_failed: pre-commit hook failed"}
+\`\`\``;
+}
+
 /**
  * Generate the prompt for a specific platform
  * @param {Object} config - Platform configuration from PLATFORM_CONFIGS
@@ -432,8 +542,13 @@ function generatePrompt(config) {
     rebaseBranch,
     usesMergeQueue,
     closeIssueMode,
+    autoMerge,
   } = config;
 
+  if (!autoMerge) {
+    return generateReviewModePrompt(config);
+  }
+
   // Azure-specific instructions for PR ID extraction
   const azurePrIdNote = requiresPrIdExtraction
     ? `\n\n💡 IMPORTANT: The output will contain the PR ID. You MUST extract it for the next step.
@@ -614,6 +729,7 @@ If blocked before creating a ${prName}, output:
  * @param {boolean} [options.mergeQueue] - Use GitHub merge queue
  * @param {string} [options.closeIssue] - When to close issue: auto|always|never
  * @param {Array} [options.requiredQualityGates] - Required handoff quality gates
+ * @param {boolean} [options.autoMerge] - Merge the PR (--ship). False stops after PR creation (--pr).
  * @returns {Object} Agent configuration object
  * @throws {Error} If platform is not supported
  */
@@ -647,8 +763,9 @@ function generateGitPusherAgent(platform, options = {}) {
     hooks: {
       onComplete: {
         action: 'verify_pull_request',
-        // No config needed - verification reads from result.structured_output
-        // and publishes CLUSTER_COMPLETE only if verification passes
+        // Verification reads PR data from result.structured_output; autoMerge controls
+        // whether an OPEN unmerged PR counts as success (--pr) or must be merged (--ship).
+        config: { autoMerge: Boolean(platformConfig.autoMerge) },
       },
     },
     output: {

package/src/attach/socket-discovery.js

@@ -11,10 +11,10 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 const net = require('net');
+const { readClustersFileSync } = require('../../lib/clusters-registry');
 
 const ZEROSHOT_DIR = path.join(os.homedir(), '.zeroshot');
 const SOCKET_DIR = path.join(ZEROSHOT_DIR, 'sockets');
-const CLUSTERS_FILE = path.join(ZEROSHOT_DIR, 'clusters.json');
 
 /**
  * Check if an ID is a known cluster by looking up clusters.json
@@ -24,8 +24,7 @@ const CLUSTERS_FILE = path.join(ZEROSHOT_DIR, 'clusters.json');
  */
 function isKnownCluster(id) {
   try {
-    if (!fs.existsSync(CLUSTERS_FILE)) return false;
-    const clusters = JSON.parse(fs.readFileSync(CLUSTERS_FILE, 'utf8'));
+    const clusters = readClustersFileSync(ZEROSHOT_DIR);
     return id in clusters;
   } catch {
     return false;

package/src/claude-credentials.js

@@ -0,0 +1,75 @@
+/**
+ * Provisions Claude Code credentials into an isolated CLAUDE_CONFIG_DIR.
+ *
+ * Claude Code only reads the macOS Keychain when using the DEFAULT config dir.
+ * Isolated agent runs (--worktree, --docker) use a custom CLAUDE_CONFIG_DIR, so
+ * a Keychain-only (OAuth subscription) login must be materialized to a file or
+ * every isolated agent fails auth even though the host is logged in.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('./lib/safe-exec');
+
+const CREDENTIALS_BASENAME = '.credentials.json';
+const KEYCHAIN_SERVICE = 'Claude Code-credentials';
+
+/**
+ * Read the Claude Code OAuth credentials JSON from the macOS Keychain.
+ * @returns {string|null} Raw credentials JSON, or null if unavailable/invalid/non-darwin.
+ */
+function readKeychainCredentials() {
+  if (os.platform() !== 'darwin') {
+    return null;
+  }
+
+  try {
+    const output = execSync(`security find-generic-password -s "${KEYCHAIN_SERVICE}" -w`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2000,
+    });
+    const trimmed = output.trim();
+    if (!trimmed) {
+      return null;
+    }
+    JSON.parse(trimmed); // reject garbage output that isn't real credentials
+    return trimmed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Copy an existing credentials file into an isolated config dir, or materialize
+ * one from the macOS Keychain when no source file exists. Resynced on every call
+ * so an expired-then-refreshed OAuth token in the Keychain is picked up per run.
+ * @param {{ sourceDir: string, destDir: string }} options
+ * @returns {boolean} true if a credentials file was written into destDir
+ */
+function provisionClaudeCredentials({ sourceDir, destDir }) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const destPath = path.join(destDir, CREDENTIALS_BASENAME);
+  const sourcePath = path.join(sourceDir, CREDENTIALS_BASENAME);
+
+  if (fs.existsSync(sourcePath)) {
+    fs.copyFileSync(sourcePath, destPath);
+    fs.chmodSync(destPath, 0o600);
+    return true;
+  }
+
+  const keychainCredentials = readKeychainCredentials();
+  if (keychainCredentials) {
+    fs.writeFileSync(destPath, keychainCredentials, { mode: 0o600 });
+    return true;
+  }
+
+  return false;
+}
+
+module.exports = {
+  readKeychainCredentials,
+  provisionClaudeCredentials,
+};

package/src/claude-task-runner.js

@@ -287,6 +287,7 @@ class ClaudeTaskRunner extends TaskRunner {
         cwd,
         stdio: ['ignore', 'pipe', 'pipe'],
         env: spawnEnv,
+        windowsHide: true,
       });
 
       let stdout = '';