feat: release deterministic e2e and run-plan hardening

.github/workflows/ci.yml

@@ -82,7 +82,11 @@ jobs:
         run: npm run test:coverage
         timeout-minutes: 3
 
-      - name: Integration tests (slow, Docker)
+      - name: E2E tests (fake provider)
+        run: npm run test:e2e
+        timeout-minutes: 5
+
+      - name: Integration tests (slow)
         run: npm run test:slow
         timeout-minutes: 15
 
@@ -96,6 +100,29 @@ jobs:
           fail_ci_if_error: false
         continue-on-error: true
 
+  # Tier 2: worktree/container isolation e2e (real Docker). Non-blocking and
+  # opt-in via workflow_dispatch - the Docker sub-tests in `check`'s
+  # "Integration tests (slow)" step self-skip under CI (this is what that
+  # step's Docker coverage was previously silently missing).
+  e2e-docker:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Docker isolation e2e
+        run: npm run test:e2e:docker
+        timeout-minutes: 15
+
   # Cross-platform/version compatibility (main only)
   # NOTE: macOS runners cost 10x Linux minutes - keep this scoped to main.
   install-matrix:

cli/index.js

@@ -189,7 +189,9 @@
   if (options.docker) {
     options.worktree = false;
   }
-  options.autoMerge = Boolean(options.ship);
+  // autoMerge is NOT stored here — it is derived from the run plan (delivery ===
+  // 'ship') at every consumer. Writing it here unconditionally would clobber an
+  // explicit autoMerge intent (e.g. a future `--auto-merge` flag) back to false.
 }
 
 async function runClusterPreflight({ input, options, providerOverride, settings, forceProvider }) {
@@ -2469,7 +2471,7 @@
 Force provider flags: -G (GitHub), -L (GitLab), -J (Jira), -D (DevOps), -N (Linear)
 `
   )
   .action(async (inputArg, options) => {
     try {
       // Normalize options (--ship → --pr → --worktree flags)
       normalizeRunOptions(options);
@@ -2610,6 +2612,7 @@
 
       if (!process.env.ZEROSHOT_DAEMON) {
         await streamClusterInForeground(cluster, orchestrator, clusterId, options);
+        orchestrator.close();
       }
 
       setupDaemonCleanup(orchestrator, clusterId);
@@ -2955,7 +2958,7 @@
   .command('kill-all')
   .description('Kill all running tasks and clusters')
   .option('-y, --yes', 'Skip confirmation')
   .action(async (options) => {
     try {
       // Get counts first
       const orchestrator = await getOrchestrator();
@@ -3179,7 +3182,7 @@
   .command('resume <id> [prompt]')
   .description('Resume a failed task or cluster')
   .option('-d, --detach', 'Resume in background (daemon mode)')
   .action(async (id, prompt, options) => {
     try {
       // Try cluster first, then task (both use same ID format: "adjective-noun-number")
       const OrchestratorModule = require('../src/orchestrator');
@@ -4390,7 +4393,7 @@
     }
   });
 
 function outputAgent(agent, options) {
   if (options.json) {
     console.log(JSON.stringify(agent, null, 2));
     return;
@@ -4558,7 +4561,7 @@
 }
 
 // Format tool result for display
 function formatToolResult(content, isError, toolName, toolInput) {
   if (!content) return isError ? 'error' : 'done';
 
   // For errors, show full message
@@ -5238,7 +5241,7 @@
 
 // Accumulate text and print complete lines only
 // Word wrap long lines, aligning continuation with message column
 function accumulateText(prefix, sender, text) {
   if (!text) return;
   const buf = getLineBuffer(sender);
 
@@ -5301,7 +5304,7 @@
 }
 
 // Stream thinking text immediately with word wrapping
 function accumulateThinking(prefix, sender, text) {
   if (!text) return;
   const buf = getLineBuffer(sender);
 
@@ -5360,7 +5363,7 @@
 }
 
 // Flush pending content - just add newline if we have pending text
 function flushLineBuffer(prefix, sender) {
   const buf = lineBuffers.get(sender);
   if (!buf) return;
 

lib/detached-startup.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const lockfile = require('proper-lockfile');
+const { resolveRunPlan } = require('./run-plan');
 
 const DEFAULT_WAIT_TIMEOUT_SECONDS = 180;
 const DEFAULT_WAIT_POLL_MS = 1000;
@@ -116,6 +117,7 @@ async function registerDetachedSetupCluster({
   runOptions = {},
   cwd,
 }) {
+  const plan = resolveRunPlan(runOptions);
   await updateClustersFile(storageDir, (clusters) => {
     clusters[clusterId] = {
       id: clusterId,
@@ -125,13 +127,13 @@ async function registerDetachedSetupCluster({
       setupLogPath: logPath || null,
       setupStartedAt: Date.now(),
       setupStage: 'starting',
-      autoPr: Boolean(runOptions.pr || runOptions.ship),
+      autoPr: plan.delivery !== 'none',
       prOptions: runOptions.prBase
         ? {
             prBase: runOptions.prBase,
             mergeQueue: runOptions.mergeQueue || false,
             closeIssue: runOptions.closeIssue || null,
-            autoMerge: Boolean(runOptions.ship),
+            autoMerge: plan.autoMerge,
             cwd: cwd || null,
           }
         : null,

lib/run-mode.js

@@ -1,11 +1,23 @@
-function resolveRunMode(options) {
-  if (options.ship) return options.docker ? 'ship+docker' : 'ship';
-  if (options.pr) return options.docker ? 'pr+docker' : 'pr';
-  if (options.docker) return 'docker';
-  if (options.worktree) return 'worktree';
+const { resolveRunPlan } = require('./run-plan');
+
+// The run-mode label is a VIEW of the canonical plan, never an independent
+// cascade. Deriving it from the plan is what keeps the user-facing label and the
+// actual isolation/delivery/autoMerge behavior from drifting apart. Callers that
+// already hold a plan (e.g. the effective plan with env/settings folded in) use
+// runModeFromPlan directly so the label reflects the SAME plan as behavior.
+function runModeFromPlan({ isolation, delivery }) {
+  const dockerSuffix = isolation === 'docker' ? '+docker' : '';
+  if (delivery === 'ship') return `ship${dockerSuffix}`;
+  if (delivery === 'pr') return `pr${dockerSuffix}`;
+  if (isolation === 'docker') return 'docker';
+  if (isolation === 'worktree') return 'worktree';
   return null;
 }
 
+function resolveRunMode(options) {
+  return runModeFromPlan(resolveRunPlan(options));
+}
+
 const RUN_MODE_LABELS = {
   ship: 'ship (worktree + PR + auto-merge)',
   'ship+docker': 'ship (docker + PR + auto-merge)',
@@ -19,4 +31,4 @@ function describeRunMode(mode) {
   return RUN_MODE_LABELS[mode] || 'local (no isolation)';
 }
 
-module.exports = { resolveRunMode, describeRunMode };
+module.exports = { resolveRunMode, runModeFromPlan, describeRunMode };

lib/run-plan.js

@@ -0,0 +1,32 @@
+/**
+ * The single canonical run-mode resolver.
+ *
+ * Every consumer (orchestrator, daemon startup, CLI label) derives isolation,
+ * delivery, and autoMerge from THIS function and nowhere else. The raw
+ * worktree/docker/pr/ship/autoMerge booleans are inputs; the frozen plan is the
+ * one truth. Deriving autoMerge separately (the old `Boolean(ship)` scatter) is
+ * what let `--pr` merge and let the run-mode label drift from behavior.
+ */
+
+function resolveIsolation(options) {
+  if (options.docker) return 'docker';
+  if (options.worktree || options.pr || options.ship) return 'worktree';
+  return 'none';
+}
+
+function resolveDelivery(options) {
+  // Explicit autoMerge (e.g. a future `--auto-merge` flag) is ship-equivalent:
+  // "merge it" implies the ship delivery. This is the ONLY place that intent is
+  // interpreted, so it can never be silently overwritten downstream.
+  if (options.ship || options.autoMerge === true) return 'ship';
+  if (options.pr) return 'pr';
+  return 'none';
+}
+
+function resolveRunPlan(options = {}) {
+  const isolation = resolveIsolation(options);
+  const delivery = resolveDelivery(options);
+  return Object.freeze({ isolation, delivery, autoMerge: delivery === 'ship' });
+}
+
+module.exports = { resolveRunPlan };

lib/start-cluster.js

@@ -5,7 +5,8 @@ const { normalizeProviderName } = require('./provider-names');
 const { getProvider } = require('../src/providers');
 const { detectProvider } = require('../src/issue-providers');
 const TemplateResolver = require('../src/template-resolver');
-const { resolveRunMode } = require('./run-mode');
+const { runModeFromPlan } = require('./run-mode');
+const { resolveRunPlan } = require('./run-plan');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 
@@ -198,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) {
@@ -238,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: Boolean(mergedOptions.ship),
+    worktree: plan.isolation === 'worktree',
+    autoPr: plan.delivery !== 'none',
+    autoMerge: plan.autoMerge,
     autoPush: process.env.ZEROSHOT_PUSH === '1',
     modelOverride: optionalValue(modelOverride),
     providerOverride: optionalValue(providerOverride),
@@ -257,7 +271,7 @@ function buildStartOptions({
     mergeQueue: resolveMergeQueue(mergedOptions),
     closeIssue: resolveCloseIssue(mergedOptions),
     ship: mergedOptions.ship,
-    runMode: resolveRunMode(mergedOptions) || null,
+    runMode: runModeFromPlan(plan),
     requiredQualityGates: mergedOptions.requiredQualityGates,
     settings,
   };

package.json

@@ -15,8 +15,10 @@
     "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 && node scripts/check-path.js",

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;
   }

src/ledger.js

@@ -715,6 +715,9 @@ class Ledger extends EventEmitter {
    * Close the database connection
    */
   close() {
+    if (this._closed) {
+      return;
+    }
     this._closed = true; // Set flag BEFORE closing to prevent race conditions
     this.db.close();
   }