@the-open-engine/zeroshot 6.31.3 → 6.32.0

package/lib/setup-apply.js

@@ -14,7 +14,7 @@
 const { resolveDecisionPath, domainFor, isConsumedPath, CONSUMED_PATHS } = require('./setup-plan');
 const { validateMountConfig, validateEnvPassthrough } = require('./docker-config');
 const { VALID_PROVIDERS } = require('./provider-names');
-const { VALID_MODELS, mapLegacyModelToLevel } = require('./settings');
+const VALID_LEVELS = Object.freeze(['level1', 'level2', 'level3']);
 const {
   loadJournal,
   saveJournal,
@@ -38,10 +38,8 @@ function domainError(decisionId, value) {
   );
 }
 
-// Resolves a submitted decision value into the raw form actually stored at
-// its target settings path, validating it against #A's domain first.
-// (defaultIsolation's domain is worktree|docker|none, but its target path is
-// the boolean settings.defaultDocker — this is where that translation lives.)
+// Resolve a submitted decision into the exact value stored at its canonical
+// settings path, validating its decision domain before any write occurs.
 function convertDecisionValue({ decisionId, value, globalSettings, deps }) {
   switch (decisionId) {
     case 'defaultProvider':
@@ -52,7 +50,7 @@ function convertDecisionValue({ decisionId, value, globalSettings, deps }) {
 
     case 'defaultIsolation':
       if (!['worktree', 'docker', 'none'].includes(value)) throw domainError(decisionId, value);
-      return value === 'docker';
+      return value;
 
     case 'allowLocalNoIsolation':
       if (typeof value !== 'boolean') throw domainError(decisionId, value);
@@ -88,24 +86,34 @@ function convertDecisionValue({ decisionId, value, globalSettings, deps }) {
       if (!['off', 'notify', 'auto'].includes(value)) throw domainError(decisionId, value);
       return value;
 
-    default:
-      if (decisionId.startsWith('providerLevel.')) {
-        if (!value || typeof value !== 'object' || Array.isArray(value)) {
-          throw domainError(decisionId, value);
-        }
-        for (const key of ['min', 'default', 'max']) {
-          if (!VALID_MODELS.includes(value[key])) throw domainError(decisionId, value);
-        }
-        const providerName = decisionId.slice('providerLevel.'.length);
-        const existing = getNestedValue(globalSettings, `providerSettings.${providerName}`) || {};
-        return {
-          ...existing,
-          minLevel: mapLegacyModelToLevel(value.min),
-          defaultLevel: mapLegacyModelToLevel(value.default),
-          maxLevel: mapLegacyModelToLevel(value.max),
-        };
+    default: {
+      if (!decisionId.startsWith('providerLevel.')) {
+        throw new Error(`Unknown decision ID: ${decisionId}`);
       }
-      throw new Error(`Unknown decision ID: ${decisionId}`);
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw domainError(decisionId, value);
+      }
+      const keys = Object.keys(value).sort();
+      const expectedKeys = ['defaultLevel', 'maxLevel', 'minLevel'];
+      if (
+        keys.length !== expectedKeys.length ||
+        keys.some((key, index) => key !== expectedKeys[index]) ||
+        expectedKeys.some((key) => !VALID_LEVELS.includes(value[key]))
+      ) {
+        throw domainError(decisionId, value);
+      }
+      const providerName = decisionId.slice('providerLevel.'.length);
+      if (!deps.VALID_PROVIDERS.includes(providerName)) throw domainError(decisionId, value);
+      const rank = (level) => VALID_LEVELS.indexOf(level);
+      if (
+        rank(value.minLevel) > rank(value.defaultLevel) ||
+        rank(value.defaultLevel) > rank(value.maxLevel)
+      ) {
+        throw domainError(decisionId, value);
+      }
+      const existing = getNestedValue(globalSettings, `providerSettings.${providerName}`) || {};
+      return { ...existing, ...value };
+    }
   }
 }
 
@@ -194,7 +202,6 @@ function applyWrite(write, { repoRoot, journal, deps }) {
   return write.scope;
 }
 
-
 // Phase 2: resolve each global outcome against the locked, freshly read state.
 // Repo-local settings remain intentionally outside the global settings lock.
 function writeResolvedDecisions(
@@ -252,35 +259,20 @@ function writeResolvedDecisions(
   return resolved.map((decision) => resultsById.get(decision.decisionId));
 }
 
-/**
- * Apply a decisions file `{ "<decisionId>": <value>, ... }` to settings.
- *
- * @param {Object} params
- * @param {string} params.decisionsPath - Path to the decisions JSON file.
- * @param {string} params.cwd - Working directory (for repo-scope settings lookup).
- * @param {boolean} [params.allowRiskyDefaults] - Required to store defaultDelivery='ship'.
- * @param {Object} [params.deps] - Injected dependencies (for testing).
- * @returns {Array<{decisionId: string, applied: boolean, from: *, to: *, skippedReason?: string}>}
- */
-function applyDecisions({ decisionsPath, cwd, allowRiskyDefaults = false, deps = {} }) {
-  const resolvedDeps = { ...defaultApplyDeps(), ...deps };
-
-  let input;
-  try {
-    input = JSON.parse(resolvedDeps.readFile(decisionsPath));
-  } catch (err) {
-    throw new Error(`Failed to read decisions file "${decisionsPath}": ${err.message}`);
-  }
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new Error('Decisions file must be a JSON object of { decisionId: value }');
+function assertDecisionObject(decisions, label) {
+  if (!decisions || typeof decisions !== 'object' || Array.isArray(decisions)) {
+    throw new Error(`${label} must be a JSON object of { decisionId: value }`);
   }
+}
 
+/** Apply an in-memory decision object without temporary files. */
+function applyDecisionValues({ decisions, cwd, allowRiskyDefaults = false, deps = {} }) {
+  assertDecisionObject(decisions, 'Decisions');
+  const resolvedDeps = { ...defaultApplyDeps(), ...deps };
   const globalSettings = resolvedDeps.loadSettings();
   const { repoRoot, settings: repoSettingsRaw } = resolvedDeps.readRepoSettings(cwd);
   const repoSettings = repoSettingsRaw || {};
-
-  const resolved = resolveAndValidateDecisions(input, globalSettings, resolvedDeps);
-
+  const resolved = resolveAndValidateDecisions(decisions, globalSettings, resolvedDeps);
   const results = writeResolvedDecisions(resolved, {
     repoSettings,
     repoRoot,
@@ -289,22 +281,37 @@ function applyDecisions({ decisionsPath, cwd, allowRiskyDefaults = false, deps =
     deps: resolvedDeps,
   });
 
-  // Never store provider-auth secrets: print the login command instead.
   const issueSourceApplied = results.find(
-    (r) => r.decisionId === 'defaultIssueSource' && r.applied
+    (result) => result.decisionId === 'defaultIssueSource' && result.applied
   );
-  if (issueSourceApplied && issueSourceApplied.to === 'github') {
+  if (issueSourceApplied?.to === 'github') {
     const auth = resolvedDeps.checkGhAuth();
-    if (!auth || !auth.authenticated) {
-      console.log('Run: gh auth login');
-    }
+    if (!auth?.authenticated) console.log('Run: gh auth login');
   }
-
   return results;
 }
 
+/** Apply a decisions JSON file through the shared object API. */
+function applyDecisions({ decisionsPath, cwd, allowRiskyDefaults = false, deps = {} }) {
+  const resolvedDeps = { ...defaultApplyDeps(), ...deps };
+  let decisions;
+  try {
+    decisions = JSON.parse(resolvedDeps.readFile(decisionsPath));
+  } catch (error) {
+    throw new Error(`Failed to read decisions file "${decisionsPath}": ${error.message}`);
+  }
+  assertDecisionObject(decisions, 'Decisions file');
+  return applyDecisionValues({
+    decisions,
+    cwd,
+    allowRiskyDefaults,
+    deps: resolvedDeps,
+  });
+}
+
 module.exports = {
   applyDecisions,
+  applyDecisionValues,
   resolveAndValidateDecisions,
   writeResolvedDecisions,
   assertSecretSafePath,

package/lib/setup-plan.js

@@ -11,15 +11,13 @@
 
 const path = require('path');
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 
-// Canonical settings key each decision maps to. `defaultIsolation` and
-// `defaultDelivery` MUST stay pinned to the keys resolveEffectiveRunPlan
-// already reads (today: settings.defaultDocker) — see the canonical-path
-// rule in issue #605. Never introduce a second parallel key here.
+// Canonical settings keys consumed by resolveEffectiveRunPlan. Never introduce
+// a parallel setting or translate a decision into a differently named key.
 const DECISION_PATHS = {
   defaultProvider: { scope: 'global', path: 'defaultProvider' },
-  defaultIsolation: { scope: 'global', path: 'defaultDocker' },
+  defaultIsolation: { scope: 'global', path: 'defaultIsolation' },
   allowLocalNoIsolation: { scope: 'global', path: 'allowLocalNoIsolation' },
   defaultDelivery: { scope: 'global', path: 'defaultDelivery' },
   defaultIssueSource: { scope: 'global', path: 'defaultIssueSource' },
@@ -33,13 +31,11 @@ function providerLevelDecisionId(providerName) {
   return `providerLevel.${providerName}`;
 }
 
-// Settings keys a run-mode resolver actually reads today. Shared by
-// buildProposedWrites below (never propose a write nobody will read) and by
-// lib/setup-apply.js (never perform a write nobody will read) — one
-// canonical answer to "is this key consumed?" so the two can't drift.
+// Settings keys consumed by runtime resolvers. Shared by buildProposedWrites
+// and setup apply so neither surface can advertise dead configuration.
 const CONSUMED_PATHS = new Set([
   'global:defaultProvider',
-  'global:defaultDocker',
+  'global:defaultIsolation',
   'global:defaultDelivery',
   'global:defaultIssueSource',
   'global:dockerMounts',
@@ -77,7 +73,7 @@ function defaultDeps() {
   const { execSync } = require('../src/lib/safe-exec');
   const { listProviders, getProvider } = require('../src/providers');
   const { getProviderDefaults } = require('./provider-defaults');
-  const { getDefaultProviderId } = require('./provider-names');
+  const { getDefaultProviderId, getProviderMetadata } = require('./provider-names');
   const packageJson = require('../package.json');
 
   return {
@@ -90,6 +86,7 @@ function defaultDeps() {
     getProvider,
     getProviderDefaults,
     getDefaultProviderId,
+    getProviderMetadata,
     getNodeVersion: () => process.version,
     getPackageVersion: () => packageJson.version,
   };
@@ -98,14 +95,8 @@ function defaultDeps() {
 function detectInstallSource(cwd, env) {
   if (env.npm_config_global === 'true') return 'npm-global';
   if (env.npm_execpath && /_npx|npx/.test(env.npm_execpath)) return 'npx';
-  try {
-    const ownNodeModules = path.join(__dirname, '..', 'node_modules');
-    if (cwd && (cwd === path.join(__dirname, '..') || cwd.startsWith(ownNodeModules))) {
-      return 'local';
-    }
-  } catch {
-    // fall through to unknown
-  }
+  const ownNodeModules = path.join(__dirname, '..', 'node_modules');
+  if (cwd && (cwd === path.join(__dirname, '..') || cwd.startsWith(ownNodeModules))) return 'local';
   return 'unknown';
 }
 
@@ -120,16 +111,20 @@ function buildNodeFacts({ cwd, env, deps }) {
 function buildProviderFacts(deps) {
   const providers = {};
   for (const name of deps.listProviders()) {
-    let cliCommand = name;
+    const metadata = deps.getProviderMetadata(name);
+    const provider = deps.getProvider(name);
+    let available = false;
     try {
-      cliCommand = deps.getProvider(name).cliCommand || name;
+      available = provider.isAvailable() === true;
     } catch {
-      // Provider metadata unavailable — fall back to the provider name as the CLI command.
+      available = false;
     }
-    const cliAvailable = deps.commandExists(cliCommand);
+    const cliCommand = provider.cliCommand || metadata.binary;
     providers[name] = {
-      cliAvailable,
-      path: cliAvailable ? deps.getCommandPath(cliCommand) : null,
+      available,
+      displayName: metadata.displayName,
+      installInstructions: metadata.installInstructions,
+      path: available && deps.commandExists(cliCommand) ? deps.getCommandPath(cliCommand) : null,
     };
   }
   return providers;
@@ -185,30 +180,19 @@ function inferPrBase(cwd, deps) {
 
 function buildProviderLevelRecommendation(name, deps) {
   const providerDefaults = deps.getProviderDefaults()[name] || {};
-  const minLevel = providerDefaults.minLevel;
-  const defaultLevel = providerDefaults.defaultLevel;
-  const maxLevel = providerDefaults.maxLevel;
-  const overrides = providerDefaults.levelOverrides || {};
-
-  try {
-    const provider = deps.getProvider(name);
-    return {
-      min: provider.resolveModelSpec(minLevel, overrides).model,
-      default: provider.resolveModelSpec(defaultLevel, overrides).model,
-      max: provider.resolveModelSpec(maxLevel, overrides).model,
-    };
-  } catch {
-    return { min: null, default: null, max: null };
-  }
+  return {
+    minLevel: providerDefaults.minLevel || 'level1',
+    defaultLevel: providerDefaults.defaultLevel || 'level2',
+    maxLevel: providerDefaults.maxLevel || 'level3',
+  };
 }
 
 function buildRecommendedAndRisk({ cwd, facts, env, deps }) {
   const recommended = {};
   const risk = {};
-
   const registryDefault = deps.getDefaultProviderId();
   recommended.defaultProvider = registryDefault;
-  risk.defaultProvider = facts.providers[registryDefault]?.cliAvailable ? 'low' : 'medium';
+  risk.defaultProvider = facts.providers[registryDefault]?.available ? 'low' : 'medium';
 
   for (const name of Object.keys(facts.providers)) {
     recommended[providerLevelDecisionId(name)] = buildProviderLevelRecommendation(name, deps);
@@ -228,7 +212,6 @@ function buildRecommendedAndRisk({ cwd, facts, env, deps }) {
 
   recommended.allowLocalNoIsolation = false;
   risk.allowLocalNoIsolation = 'low';
-
   recommended.defaultDelivery = 'none';
   risk.defaultDelivery = 'low';
 
@@ -239,10 +222,8 @@ function buildRecommendedAndRisk({ cwd, facts, env, deps }) {
   const inferredPrBase = inferPrBase(cwd, deps);
   recommended.prBase = inferredPrBase || 'main';
   risk.prBase = inferredPrBase ? 'low' : 'medium';
-
   recommended.dockerMounts = ['gh', 'git', 'ssh'];
   risk.dockerMounts = 'low';
-
   recommended.dockerEnvPassthrough = [];
   risk.dockerEnvPassthrough = 'low';
 
@@ -301,9 +282,11 @@ function buildDecisions({ facts, settings, repoSettings, inferredIssueSource, in
 }
 
 function domainFor(decisionId) {
-  if (decisionId.startsWith('providerLevel.')) return '{ min, default, max } of haiku|sonnet|opus';
+  if (decisionId.startsWith('providerLevel.')) {
+    return '{ minLevel, defaultLevel, maxLevel } of level1|level2|level3';
+  }
   const domains = {
-    defaultProvider: 'claude | codex | gemini | opencode',
+    defaultProvider: 'registry provider id',
     defaultIsolation: 'worktree | docker | none',
     allowLocalNoIsolation: 'boolean',
     defaultDelivery: 'none | pr | ship',
@@ -326,10 +309,7 @@ function buildProposedWrites({ decisions, recommended }) {
     // no resolver reads would advertise a write that apply will always skip —
     // dead config. Only propose writes apply will actually perform.
     if (!isConsumedPath(target.scope, target.path)) continue;
-    let to = recommended[decision.decisionId];
-    if (decision.decisionId === 'defaultIsolation') {
-      to = to === 'docker';
-    }
+    const to = recommended[decision.decisionId];
     if (to === decision.currentValue) continue;
     writes.push({
       scope: target.scope,

package/lib/start-cluster.js

@@ -198,24 +198,74 @@ function loadClusterConfig(orchestrator, configPath, settings = {}, providerOver
   return prepareClusterConfig(orchestrator.loadConfig(configPath), settings, providerOverride);
 }
 
+const RUN_MODE_KEYS = ['docker', 'worktree', 'pr', 'ship', 'noIsolation', 'isolation'];
+
+function hasExplicitRunMode(options) {
+  return RUN_MODE_KEYS.some(
+    (key) => options[key] === true || (key === 'isolation' && options[key] === false)
+  );
+}
+
 function mergeRunOptions(options) {
   const envRunOptions = parseRunOptionsEnv();
-  return envRunOptions ? { ...envRunOptions, ...options } : options;
+  if (!envRunOptions) return options;
+  if (!hasExplicitRunMode(options)) return { ...envRunOptions, ...options };
+  const withoutEnvMode = { ...envRunOptions };
+  for (const key of RUN_MODE_KEYS) delete withoutEnvMode[key];
+  return { ...withoutEnvMode, ...options };
+}
+
+function validateSavedRunModes(settings) {
+  const isolation = settings.defaultIsolation || 'none';
+  const delivery = settings.defaultDelivery || 'none';
+  if (!['none', 'worktree', 'docker'].includes(isolation)) {
+    throw new Error(`Invalid saved isolation mode: ${isolation}`);
+  }
+  if (!['none', 'pr', 'ship'].includes(delivery)) {
+    throw new Error(`Invalid saved delivery mode: ${delivery}`);
+  }
+  return { isolation, delivery };
+}
+
+function resolveEffectiveIsolation(options, savedIsolation) {
+  if (options.noIsolation === true || options.isolation === false) return 'none';
+  if (options.docker === true) return 'docker';
+  if (options.worktree === true || options.pr === true || options.ship === true) return 'worktree';
+  if (resolveEnvBool(process.env.ZEROSHOT_DOCKER) === true) return 'docker';
+  if (resolveEnvBool(process.env.ZEROSHOT_WORKTREE) === true) return 'worktree';
+  return savedIsolation;
+}
+
+function resolveEffectiveDelivery(options, savedDelivery) {
+  if (options.ship === true || options.autoMerge === true) return 'ship';
+  if (options.pr === true || resolveEnvBool(process.env.ZEROSHOT_PR) === true) return 'pr';
+  return savedDelivery;
 }
 
-// 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) {
+function resolveEffectiveRunPlan(options = {}, settings = {}) {
+  const mergedOptions = mergeRunOptions(options);
+  const noIsolation = mergedOptions.noIsolation === true || mergedOptions.isolation === false;
+  const conflicts = ['docker', 'worktree', 'pr', 'ship'].filter(
+    (key) => mergedOptions[key] === true
+  );
+  if (noIsolation && conflicts.length > 0) {
+    throw new Error(`--no-isolation conflicts with --${conflicts.join(', --')}`);
+  }
+
+  const saved = validateSavedRunModes(settings);
+  let isolation = resolveEffectiveIsolation(mergedOptions, saved.isolation);
+  const delivery = resolveEffectiveDelivery(mergedOptions, saved.delivery);
+  if (delivery !== 'none' && isolation === 'none') {
+    if (noIsolation) {
+      throw new Error(`--no-isolation conflicts with saved delivery mode "${delivery}"`);
+    }
+    isolation = 'worktree';
+  }
   return resolveRunPlan({
-    ...mergedOptions,
-    docker: anyTruthy(
-      mergedOptions.docker,
-      process.env.ZEROSHOT_DOCKER === '1',
-      settings.defaultDocker
-    ),
-    worktree: anyTruthy(mergedOptions.worktree, process.env.ZEROSHOT_WORKTREE === '1'),
+    docker: isolation === 'docker',
+    worktree: isolation === 'worktree',
+    pr: delivery === 'pr',
+    ship: delivery === 'ship',
   });
 }
 
@@ -255,7 +305,7 @@ function buildStartOptions({
   forceProvider,
 }) {
   const mergedOptions = mergeRunOptions(options);
-  const plan = resolveEffectiveRunPlan(mergedOptions, settings);
+  const plan = resolveEffectiveRunPlan(options, settings);
   return buildStartOptionsFromPlan({
     clusterId,
     plan,
@@ -368,16 +418,6 @@ function resolveConfigOrThrow({
   return loadClusterConfig(orchestrator, resolvedPath, settings, providerOverride);
 }
 
-function applyDefaultDeliveryOptions(options, settings) {
-  if (settings.defaultDelivery === 'pr') {
-    return { ...options, pr: true };
-  }
-  if (settings.defaultDelivery === 'ship') {
-    return { ...options, ship: true };
-  }
-  return options;
-}
-
 function startClusterWithInput(args, input) {
   const { orchestrator, config, configPath, configName, settings, providerOverride } = args;
   if (!orchestrator) {
@@ -393,7 +433,7 @@ function startClusterWithInput(args, input) {
   });
   const startOptions = buildStartOptions({
     clusterId: args.clusterId,
-    options: applyDefaultDeliveryOptions(args.options || {}, settings),
+    options: args.options || {},
     settings,
     providerOverride,
     modelOverride: args.modelOverride,

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.31.3",
+  "version": "6.32.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@the-open-engine/zeroshot",
-      "version": "6.31.3",
+      "version": "6.32.0",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.31.3",
-  "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
+  "version": "6.32.0",
+  "description": "Independent executor–verifier orchestration for software changes.",
   "main": "src/orchestrator.js",
   "bin": {
     "zeroshot": "./cli/index.js",
@@ -38,7 +38,7 @@
     "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",
+    "postinstall": "node scripts/postinstall.js",
     "start": "node cli/index.js",
     "typecheck": "tsc --noEmit && npm run typecheck:cluster && npm run typecheck:hosted-target && npm run typecheck:hosted-session && npm run typecheck:target",
     "typecheck:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.json",

package/scripts/postinstall.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const LIFECYCLE_SCRIPTS = ['fix-node-pty-permissions.js', 'check-path.js'];
+const SETUP_INVITATION = 'Run zeroshot to finish setup.\n';
+
+function isTruthyEnvironmentFlag(value) {
+  if (typeof value !== 'string') return false;
+  return !['', '0', 'false'].includes(value.trim().toLowerCase());
+}
+
+function shouldPrintSetupInvitation(env) {
+  const globalInstall = env.npm_config_global === 'true' || env.npm_config_location === 'global';
+  return globalInstall && !isTruthyEnvironmentFlag(env.CI);
+}
+
+function runLifecycleScript(scriptName) {
+  const result = spawnSync(process.execPath, [path.join(__dirname, scriptName)], {
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+}
+
+function runPostinstall({
+  env = process.env,
+  stdout = process.stdout,
+  runScript = runLifecycleScript,
+} = {}) {
+  for (const scriptName of LIFECYCLE_SCRIPTS) {
+    const status = runScript(scriptName);
+    if (status !== 0) return status;
+  }
+  if (shouldPrintSetupInvitation(env)) stdout.write(SETUP_INVITATION);
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = runPostinstall();
+  } catch (error) {
+    console.warn(`[postinstall] Warning: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  LIFECYCLE_SCRIPTS,
+  SETUP_INVITATION,
+  runPostinstall,
+  shouldPrintSetupInvitation,
+};

package/src/preflight.js

@@ -468,6 +468,31 @@ function validateProviderIsolationCapabilities(providerName, options) {
   return errors;
 }
 
+function validateProviderExecutionSettings(providerName, settings, options) {
+  const metadata = getProviderMetadata(providerName);
+  if (!metadata.settingsValidator) return [];
+
+  const providerSettings = settings.providerSettings?.[providerName];
+  if (
+    !providerSettings ||
+    typeof providerSettings !== 'object' ||
+    Array.isArray(providerSettings)
+  ) {
+    return [];
+  }
+
+  const executionContext = options.requireDocker ? 'docker' : 'detached';
+  const error = metadata.settingsValidator(providerSettings, { executionContext });
+  if (!error) return [];
+
+  return [
+    formatError(`${metadata.displayName} configuration cannot run cluster agents`, error, [
+      metadata.authInstructions,
+      'Or select a different provider with: zeroshot providers set-default <provider>',
+    ]),
+  ];
+}
+
 function validateProvider(providerName, options) {
   let metadata;
   try {
@@ -623,7 +648,7 @@ async function runPreflight(options = {}) {
   const errors = [];
   const warnings = [];
 
-  const settings = loadSettings();
+  const settings = options.settings || loadSettings();
 
   if (process.platform === 'win32') {
     return {
@@ -648,6 +673,7 @@ async function runPreflight(options = {}) {
 
   const providerResult = validateProvider(providerName, options);
   errors.push(...providerResult.errors);
+  errors.push(...validateProviderExecutionSettings(providerName, settings, options));
   warnings.push(...providerResult.warnings);
 
   // 4. Check issue provider CLI (if required)

package/src/status-footer.js

@@ -151,21 +151,29 @@ class StatusFooter {
   }
 
   /**
-   * Print text to stdout, coordinating with the render cycle.
-   * When a render is in progress, queues output to prevent cursor corruption.
-   * When no render is active, writes immediately.
-   *
-   * MUST be used instead of console.log() when status footer is active.
-   * @param {string} text - Text to print (newline will be added)
+   * Print one logical line while coordinating with footer rendering.
+   * The caller owns line normalization; this method appends one newline.
+   * @param {string} text
    */
   print(text) {
+    this._queueOrWrite(`${text}\n`);
+  }
+
+  /**
+   * Write an exact streaming chunk while coordinating with footer rendering.
+   * @param {string} text
+   */
+  write(text) {
+    this._queueOrWrite(String(text));
+  }
+
+  /** @private */
+  _queueOrWrite(text) {
     if (this.isRendering) {
-      // Queue for later - render() will flush after restoring cursor
       this.printQueue.push(text);
-    } else {
-      // Write immediately - no render in progress
-      process.stdout.write(text + '\n');
+      return;
     }
+    process.stdout.write(text);
   }
 
   /**
@@ -176,8 +184,7 @@ class StatusFooter {
   _flushPrintQueue() {
     if (this.printQueue.length === 0) return;
 
-    // Write all queued output
-    const output = this.printQueue.map((text) => text + '\n').join('');
+    const output = this.printQueue.join('');
     this.printQueue = [];
     process.stdout.write(output);
   }