@the-open-engine/zeroshot 6.1.0 → 6.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
   "main": "src/orchestrator.js",
   "bin": {
@@ -19,7 +19,7 @@
     "test:all": "npm run test && 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 +94,7 @@
     "cli/",
     "task-lib/",
     "cluster-templates/",
-    "hooks/",
+    "cluster-hooks/",
     "docker/",
     "scripts/",
     "README.md",
@@ -110,7 +110,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-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 = '';

package/src/isolation-manager.js

@@ -20,6 +20,7 @@ const { normalizeProviderName } = require('../lib/provider-names');
 const { resolveMounts, resolveEnvs, expandEnvPatterns } = require('../lib/docker-config');
 const { getProvider } = require('./providers');
 const { readRepoSettings } = require('../lib/repo-settings');
+const { provisionClaudeCredentials } = require('./claude-credentials');
 
 const DEFAULT_WORKTREE_SETUP_TIMEOUT_MS = 15 * 60 * 1000;
 
@@ -1036,14 +1037,12 @@ class IsolationManager {
     const projectsDir = path.join(configDir, 'projects');
     fs.mkdirSync(projectsDir, { recursive: true });
 
-    // Copy only credentials file (essential for auth)
-    const credentialsFile = path.join(sourceDir, '.credentials.json');
-    if (fs.existsSync(credentialsFile)) {
-      fs.copyFileSync(credentialsFile, path.join(configDir, '.credentials.json'));
-    }
+    // Copy credentials file, or materialize from macOS Keychain if none exists
+    // (essential for auth; see src/claude-credentials.js)
+    provisionClaudeCredentials({ sourceDir, destDir: configDir });
 
     // Copy hook script to block AskUserQuestion (CRITICAL for autonomous execution)
-    const hookScriptSrc = path.join(__dirname, '..', 'hooks', 'block-ask-user-question.py');
+    const hookScriptSrc = path.join(__dirname, '..', 'cluster-hooks', 'block-ask-user-question.py');
     const hookScriptDst = path.join(hooksDir, 'block-ask-user-question.py');
     if (fs.existsSync(hookScriptSrc)) {
       fs.copyFileSync(hookScriptSrc, hookScriptDst);
@@ -1651,10 +1650,14 @@ class IsolationManager {
     // Tear down any Docker Compose services that may have been started in this worktree.
     // Without this, containers keep running with host port mappings after the worktree is deleted,
     // blocking port allocation for the main project or other worktrees.
-    const composePath = path.join(worktreeInfo.path, 'docker-compose.yml');
-    if (fs.existsSync(composePath)) {
+    // NEVER pass --volumes (irreversible data loss) and NEVER tear down a pinned/shared
+    // Compose project — only a project scoped to the worktree directory basename, which is
+    // the only kind zeroshot could itself have created, is touched.
+    const { resolveWorktreeComposeTeardown } = require('../lib/compose-utils');
+    const teardown = resolveWorktreeComposeTeardown(worktreeInfo.path);
+    if (teardown.shouldTeardown) {
       try {
-        runSync('docker', ['compose', 'down', '--remove-orphans', '--volumes', '--timeout', '10'], {
+        runSync('docker', teardown.args, {
           cwd: worktreeInfo.path,
           encoding: 'utf8',
           stdio: 'pipe',

package/src/issue-providers/README.md

@@ -1,15 +1,16 @@
 # Issue Providers
 
-Multi-platform issue support for Zeroshot. Fetch issues from GitHub, GitLab, Jira, and Azure DevOps.
+Multi-platform issue support for Zeroshot. Fetch issues from GitHub, GitLab, Jira, Azure DevOps, and Linear.
 
 ## Supported Providers
 
-| Provider         | CLI Tool | URL Pattern                                  | Issue Key Format      |
-| ---------------- | -------- | -------------------------------------------- | --------------------- |
-| **GitHub**       | `gh`     | `github.com/org/repo/issues/123`             | `123`, `org/repo#123` |
-| **GitLab**       | `glab`   | `gitlab.com/org/repo/-/issues/123`           | `123`, `org/repo#123` |
-| **Jira**         | `jira`   | `*.atlassian.net/browse/KEY-123`             | `KEY-123`             |
-| **Azure DevOps** | `az`     | `dev.azure.com/org/proj/_workitems/edit/123` | `123`                 |
+| Provider         | CLI Tool               | URL Pattern                                  | Issue Key Format      |
+| ---------------- | ---------------------- | -------------------------------------------- | --------------------- |
+| **GitHub**       | `gh`                   | `github.com/org/repo/issues/123`             | `123`, `org/repo#123` |
+| **GitLab**       | `glab`                 | `gitlab.com/org/repo/-/issues/123`           | `123`, `org/repo#123` |
+| **Jira**         | `jira`                 | `*.atlassian.net/browse/KEY-123`             | `KEY-123`             |
+| **Azure DevOps** | `az`                   | `dev.azure.com/org/proj/_workitems/edit/123` | `123`                 |
+| **Linear**       | _(none — GraphQL API)_ | `linear.app/ws/issue/ENG-42`                 | `ENG-42`              |
 
 ## Quick Start
 
@@ -30,6 +31,11 @@ zeroshot run https://company.atlassian.net/browse/PROJ-123
 # Azure DevOps
 zeroshot run https://dev.azure.com/org/project/_workitems/edit/123
 zeroshot run 123 --devops
+
+# Linear
+zeroshot run ENG-42
+zeroshot run https://linear.app/workspace/issue/ENG-42/some-title
+zeroshot run 42 --linear
 ```
 
 ## Automatic Git Remote Detection
@@ -59,6 +65,7 @@ Override auto-detection with explicit provider flags:
 -L, --gitlab    # Force GitLab as issue source
 -J, --jira      # Force Jira as issue source
 -D, --devops    # Force Azure DevOps as issue source
+-N, --linear    # Force Linear as issue source
 ```
 
 **Example:**
@@ -100,18 +107,24 @@ zeroshot settings set jiraProject MYPROJECT  # Default project for bare numbers
 # Azure DevOps configuration
 zeroshot settings set azureOrg mycompany
 zeroshot settings set azureProject myproject  # Default project for bare numbers
+
+# Linear configuration
+zeroshot settings set linearApiKey lin_api_...  # API key (falls back to LINEAR_API_KEY env var)
+zeroshot settings set linearTeam ENG  # Default team key for bare numbers (auto-derived on first use if unset)
 ```
 
 ### Settings Reference
 
-| Setting              | Type   | Default | Description                                |
-| -------------------- | ------ | ------- | ------------------------------------------ |
-| `defaultIssueSource` | string | github  | Provider for bare numbers (123)            |
-| `gitlabInstance`     | string | null    | Self-hosted GitLab URL                     |
-| `jiraInstance`       | string | null    | Self-hosted Jira URL                       |
-| `jiraProject`        | string | null    | Default Jira project key for bare numbers  |
-| `azureOrg`           | string | null    | Azure DevOps organization name             |
-| `azureProject`       | string | null    | Azure DevOps project name for bare numbers |
+| Setting              | Type   | Default | Description                                                                                         |
+| -------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------- |
+| `defaultIssueSource` | string | github  | Provider for bare numbers (123)                                                                     |
+| `gitlabInstance`     | string | null    | Self-hosted GitLab URL                                                                              |
+| `jiraInstance`       | string | null    | Self-hosted Jira URL                                                                                |
+| `jiraProject`        | string | null    | Default Jira project key for bare numbers                                                           |
+| `azureOrg`           | string | null    | Azure DevOps organization name                                                                      |
+| `azureProject`       | string | null    | Azure DevOps project name for bare numbers                                                          |
+| `linearApiKey`       | string | null    | Linear personal API key (falls back to `LINEAR_API_KEY` env var)                                    |
+| `linearTeam`         | string | null    | Default Linear team key for bare numbers (auto-derived from the workspace if unset and unambiguous) |
 
 ## CLI Tool Setup
 
@@ -166,6 +179,23 @@ az login
 az devops configure --defaults organization=https://dev.azure.com/yourorg
 ```
 
+### Linear
+
+No CLI install needed — Linear is accessed directly via its GraphQL API.
+
+```bash
+# Create a personal API key at https://linear.app/settings/api
+zeroshot settings set linearApiKey lin_api_...
+
+# Or, as a fallback, export it as an env var (checked if linearApiKey is unset):
+export LINEAR_API_KEY=lin_api_...
+```
+
+Note: `KEY-NUMBER` input (e.g. `ENG-42`) is ambiguous between Jira and Linear.
+It's routed to Linear automatically when Linear is configured
+(`linearApiKey`/`linearTeam`) and Jira isn't; otherwise Jira wins. Use
+`--linear`/`--jira` to force a specific provider.
+
 ## Self-Hosted Instances
 
 ### GitLab Self-Hosted

package/src/issue-providers/index.js

@@ -7,6 +7,7 @@
 const GitHubProvider = require('./github-provider');
 const GitLabProvider = require('./gitlab-provider');
 const JiraProvider = require('./jira-provider');
+const LinearProvider = require('./linear-provider');
 const AzureDevOpsProvider = require('./azure-devops-provider');
 const { detectGitContext } = require('../../lib/git-remote-utils');
 
@@ -180,6 +181,7 @@ function validateIssueProviderSetting(key, value) {
 registerProvider(GitHubProvider);
 registerProvider(GitLabProvider);
 registerProvider(JiraProvider);
+registerProvider(LinearProvider);
 registerProvider(AzureDevOpsProvider);
 
 module.exports = {