@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/legacy-lib/setup-undo.ts

@@ -0,0 +1,142 @@
+/**
+ * `zeroshot setup undo` — reverts writes made by `zeroshot setup apply` using
+ * the journal recorded at apply time (lib/setup-journal.js).
+ *
+ * Three-way conflict rule per journaled write, comparing `current` against
+ * `appliedValue`:
+ *   - current === appliedValue      -> restore priorValue (delete if null)
+ *   - current === priorValue        -> already-restored (no-op)
+ *   - otherwise (changed elsewhere) -> skipped-modified, never clobbered
+ */
+
+import setupJournal = require('./setup-journal');
+
+type SettingsRecord = Record<string, unknown>;
+type UndoStatus = 'already-restored' | 'skipped-modified' | 'deleted' | 'restored';
+
+interface JournalEntry {
+  readonly appliedAt: string;
+  readonly appliedValue: unknown;
+  readonly path: string;
+  readonly priorValue: unknown;
+  readonly repoRoot: string | null;
+  readonly scope: string;
+  readonly [key: string]: unknown;
+}
+
+interface SetupJournalFacade {
+  deepEqual(left: unknown, right: unknown): boolean;
+  deleteNestedKey(target: SettingsRecord, pathStr: string): void;
+  getNestedValue(source: SettingsRecord, pathStr: string): unknown;
+  loadJournal(): { entries: JournalEntry[] };
+  setNestedValue(target: SettingsRecord, pathStr: string, value: unknown): void;
+}
+
+const {
+  loadJournal,
+  getNestedValue,
+  setNestedValue,
+  deleteNestedKey,
+  deepEqual,
+}: SetupJournalFacade = setupJournal;
+
+interface UndoResult extends JournalEntry {
+  current?: unknown;
+  status: UndoStatus;
+  wouldRestore?: unknown;
+}
+
+interface UndoDependencies {
+  mutateSettings<T>(mutator: (settings: SettingsRecord) => T): T;
+  readRepoSettings(repoRoot: string | null): { settings: SettingsRecord | null };
+  writeRepoSettings(repoRoot: string | null, settings: SettingsRecord): unknown;
+}
+
+interface UndoParams {
+  deps?: Partial<UndoDependencies>;
+}
+
+function defaultUndoDeps(): UndoDependencies {
+  // These CommonJS paths intentionally resolve beside the emitted module in lib/.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  const { mutateSettings }: Pick<UndoDependencies, 'mutateSettings'> = require('./settings');
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  const {
+    readRepoSettings,
+    writeRepoSettings,
+  }: Pick<UndoDependencies, 'readRepoSettings' | 'writeRepoSettings'> =
+    require('./repo-settings');
+
+  return { mutateSettings, readRepoSettings, writeRepoSettings };
+}
+
+/**
+ * Undo every journaled write, per the three-way conflict rule.
+ */
+function undo({ deps = {} }: UndoParams = {}): Array<UndoResult | undefined> {
+  const resolvedDeps: UndoDependencies = { ...defaultUndoDeps(), ...deps };
+  const journal = loadJournal();
+
+  const repoSettingsCache = new Map<string | null, SettingsRecord>();
+  const dirtyRepoRoots = new Set<string | null>();
+
+  function repoSettingsFor(repoRoot: string | null): SettingsRecord {
+    const cachedSettings = repoSettingsCache.get(repoRoot);
+    if (cachedSettings) {
+      return cachedSettings;
+    }
+    const { settings } = resolvedDeps.readRepoSettings(repoRoot);
+    const resolvedSettings = settings || {};
+    repoSettingsCache.set(repoRoot, resolvedSettings);
+    return resolvedSettings;
+  }
+
+  function restoreEntry(entry: JournalEntry, settingsObj: SettingsRecord): UndoResult {
+    const current = getNestedValue(settingsObj, entry.path) ?? null;
+    if (deepEqual(current, entry.priorValue)) {
+      return { ...entry, status: 'already-restored' };
+    }
+    if (!deepEqual(current, entry.appliedValue)) {
+      return { ...entry, status: 'skipped-modified', current, wouldRestore: entry.priorValue };
+    }
+    if (entry.priorValue === null) {
+      deleteNestedKey(settingsObj, entry.path);
+    } else {
+      setNestedValue(settingsObj, entry.path, entry.priorValue);
+    }
+    return { ...entry, status: entry.priorValue === null ? 'deleted' : 'restored' };
+  }
+
+  const resultsByIndex = new Map<number, UndoResult | undefined>();
+  const globalEntries = journal.entries
+    .map((entry, index) => ({ entry, index }))
+    .filter(({ entry }) => entry.scope === 'global');
+
+  if (globalEntries.length > 0) {
+    const globalResults = resolvedDeps.mutateSettings((freshGlobalSettings) => {
+      return globalEntries.map(({ entry }) => restoreEntry(entry, freshGlobalSettings));
+    });
+    globalEntries.forEach(({ index }, resultIndex) => {
+      resultsByIndex.set(index, globalResults[resultIndex]);
+    });
+  }
+
+  journal.entries.forEach((entry, index) => {
+    if (entry.scope !== 'repo') return;
+    const result = restoreEntry(entry, repoSettingsFor(entry.repoRoot));
+    resultsByIndex.set(index, result);
+    if (result.status === 'restored' || result.status === 'deleted') {
+      dirtyRepoRoots.add(entry.repoRoot);
+    }
+  });
+
+  for (const repoRoot of dirtyRepoRoots) {
+    resolvedDeps.writeRepoSettings(repoRoot, repoSettingsFor(repoRoot));
+  }
+
+  // Journal entries are left in place (not cleared) so a re-run reports
+  // 'already-restored' instead of finding nothing to undo.
+  return journal.entries.map((_, index) => resultsByIndex.get(index));
+}
+
+export = { undo };

package/src/legacy-lib/start-cluster-config.ts

@@ -0,0 +1,124 @@
+import path = require('path');
+
+interface ClusterConfig extends Record<string, unknown> {
+  defaultLevel?: unknown;
+  defaultProvider?: string;
+  forceLevel?: unknown;
+  forceProvider?: string;
+  params?: Record<string, unknown>;
+}
+
+interface ProviderSettings {
+  defaultLevel?: unknown;
+}
+
+interface Settings {
+  defaultProvider?: string;
+  providerSettings?: Record<string, ProviderSettings>;
+}
+
+interface ProviderNamesFacade {
+  getDefaultProviderId(): string;
+  normalizeProviderName(name: string): string;
+}
+
+interface ProviderFacade {
+  getDefaultLevel(): unknown;
+}
+
+interface ProvidersFacade {
+  getProvider(providerId: string): ProviderFacade;
+}
+
+interface TemplateResolverFacade {
+  resolveTemplate(config: ClusterConfig, params: Record<string, unknown>): ClusterConfig;
+}
+
+interface TemplateResolverConstructor {
+  new (templatesRoot: string): TemplateResolverFacade;
+}
+
+interface OrchestratorFacade {
+  loadConfig(configPath: string): ClusterConfig;
+}
+
+interface ChalkFacade {
+  dim(message: string): string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const chalk: ChalkFacade = require('chalk');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const providerNames: ProviderNamesFacade = require('./provider-names');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const providers: ProvidersFacade = require('../src/providers');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const TemplateResolver: TemplateResolverConstructor = require('../src/template-resolver');
+
+const { normalizeProviderName, getDefaultProviderId } = providerNames;
+const { getProvider } = providers;
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+function resolveConfigPath(configName: string): string {
+  if (path.isAbsolute(configName) || configName.startsWith('./') || configName.startsWith('../')) {
+    return path.resolve(process.cwd(), configName);
+  }
+  if (configName.endsWith('.json')) {
+    return path.join(PACKAGE_ROOT, 'cluster-templates', configName);
+  }
+  return path.join(PACKAGE_ROOT, 'cluster-templates', `${configName}.json`);
+}
+
+function ensureConfigProviderDefaults(config: ClusterConfig, settings: Settings): void {
+  if (!config.defaultProvider) {
+    config.defaultProvider = settings.defaultProvider || getDefaultProviderId();
+  }
+  config.defaultProvider = normalizeProviderName(config.defaultProvider) || getDefaultProviderId();
+}
+
+function applyProviderOverrideToConfig(
+  config: ClusterConfig,
+  providerOverride: string,
+  settings: Settings
+): void {
+  const provider = getProvider(providerOverride);
+  const providerSettings = settings.providerSettings?.[providerOverride] || {};
+  config.forceProvider = providerOverride;
+  config.defaultProvider = providerOverride;
+  config.forceLevel = providerSettings.defaultLevel || provider.getDefaultLevel();
+  config.defaultLevel = config.forceLevel;
+  console.log(chalk.dim(`Provider override: ${providerOverride} (all agents)`));
+}
+
+function resolveParameterizedConfigFile(config: ClusterConfig): ClusterConfig {
+  if (!config?.params || Object.keys(config.params).length === 0) {
+    return config;
+  }
+
+  const resolver = new TemplateResolver(path.join(PACKAGE_ROOT, 'cluster-templates'));
+  return resolver.resolveTemplate(config, {});
+}
+
+function prepareClusterConfig(
+  config: ClusterConfig,
+  settings: Settings = {},
+  providerOverride?: string | null
+): ClusterConfig {
+  const prepared = resolveParameterizedConfigFile(config);
+  ensureConfigProviderDefaults(prepared, settings);
+  if (providerOverride) {
+    applyProviderOverrideToConfig(prepared, providerOverride, settings);
+  }
+  return prepared;
+}
+
+function loadClusterConfig(
+  orchestrator: OrchestratorFacade,
+  configPath: string,
+  settings: Settings = {},
+  providerOverride?: string | null
+): ClusterConfig {
+  return prepareClusterConfig(orchestrator.loadConfig(configPath), settings, providerOverride);
+}
+
+export = { resolveConfigPath, prepareClusterConfig, loadClusterConfig };

package/src/legacy-lib/start-cluster-environment.ts

@@ -0,0 +1,165 @@
+import { spawnSync } from 'child_process';
+
+type CloseIssueMode = 'auto' | 'always' | 'never';
+
+interface RunOptions extends Record<string, unknown> {
+  closeIssue?: unknown;
+  dockerImage?: unknown;
+  isolation?: unknown;
+  mergeQueue?: unknown;
+  mount?: readonly string[] | null;
+  noIsolation?: unknown;
+  prBase?: unknown;
+}
+
+interface MountSpec {
+  host: string;
+  container: string;
+  readonly: boolean;
+}
+
+function firstTruthy<T>(...values: T[]): T | undefined {
+  return values.find(Boolean);
+}
+
+function anyTruthy(...values: unknown[]): boolean {
+  return values.some(Boolean);
+}
+
+function optionalValue<T>(value: T): T | undefined {
+  return value || undefined;
+}
+
+function detectGitRepoRoot(): string {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+      return process.cwd();
+    }
+    return result.stdout.trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+function resolveTargetCwd(): string | undefined {
+  return firstTruthy(process.env.ZEROSHOT_CWD, detectGitRepoRoot());
+}
+
+function resolveOptionalString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function resolveEnvBool(value: unknown): boolean | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim().toLowerCase();
+  if (trimmed === '1' || trimmed === 'true' || trimmed === 'yes') return true;
+  if (trimmed === '0' || trimmed === 'false' || trimmed === 'no') return false;
+  return undefined;
+}
+
+function resolveCloseIssueMode(value: unknown): CloseIssueMode | undefined {
+  const trimmed = resolveOptionalString(value);
+  if (!trimmed) return undefined;
+  const normalized = trimmed.toLowerCase();
+  if (normalized === 'auto' || normalized === 'always' || normalized === 'never') {
+    return normalized;
+  }
+  return undefined;
+}
+
+function isRunOptions(value: unknown): value is RunOptions {
+  return Boolean(value) && typeof value === 'object';
+}
+
+function parseRunOptionsEnv(): RunOptions | null {
+  const raw = resolveOptionalString(process.env.ZEROSHOT_RUN_OPTIONS);
+  if (!raw) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!isRunOptions(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function parseMountSpecs(specs: readonly string[]): MountSpec[] {
+  return specs.map((spec) => {
+    const parts = spec.split(':');
+    if (parts.length < 2) {
+      throw new Error(`Invalid mount spec: "${spec}". Format: host:container[:ro]`);
+    }
+    const [host, container] = parts;
+    if (host === undefined || container === undefined) {
+      throw new Error(`Invalid mount spec: "${spec}". Format: host:container[:ro]`);
+    }
+    const readonly = parts[2] === 'ro';
+    return { host, container, readonly };
+  });
+}
+
+const RUN_MODE_KEYS = ['docker', 'worktree', 'pr', 'ship', 'noIsolation', 'isolation'] as const;
+
+function hasExplicitRunMode(options: RunOptions): boolean {
+  return RUN_MODE_KEYS.some(
+    (key) => options[key] === true || (key === 'isolation' && options[key] === false)
+  );
+}
+
+function mergeRunOptions(options: RunOptions): RunOptions {
+  const envRunOptions = parseRunOptionsEnv();
+  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 resolveMergeQueue(options: RunOptions): boolean | undefined {
+  if (typeof options.mergeQueue === 'boolean') {
+    return options.mergeQueue;
+  }
+  return resolveEnvBool(process.env.ZEROSHOT_MERGE_QUEUE);
+}
+
+function resolvePrBase(options: RunOptions): string | undefined {
+  return (
+    resolveOptionalString(options.prBase) ||
+    resolveOptionalString(process.env.ZEROSHOT_PR_BASE) ||
+    undefined
+  );
+}
+
+function resolveCloseIssue(options: RunOptions): CloseIssueMode | undefined {
+  return (
+    resolveCloseIssueMode(options.closeIssue) ||
+    resolveCloseIssueMode(process.env.ZEROSHOT_CLOSE_ISSUE) ||
+    undefined
+  );
+}
+
+function resolveMounts(options: RunOptions): MountSpec[] | undefined {
+  return options.mount ? parseMountSpecs(options.mount) : undefined;
+}
+
+export = {
+  firstTruthy,
+  anyTruthy,
+  optionalValue,
+  detectGitRepoRoot,
+  resolveTargetCwd,
+  resolveEnvBool,
+  mergeRunOptions,
+  resolveMergeQueue,
+  resolvePrBase,
+  resolveCloseIssue,
+  resolveMounts,
+};

package/src/legacy-lib/start-cluster-run-options.ts

@@ -0,0 +1,279 @@
+type RunIsolation = 'none' | 'worktree' | 'docker';
+type RunDelivery = 'none' | 'pr' | 'ship';
+
+interface RunPlan {
+  isolation: RunIsolation;
+  delivery: RunDelivery;
+  autoMerge: boolean;
+}
+
+interface Settings extends Record<string, unknown> {
+  defaultIsolation?: string;
+  defaultDelivery?: string;
+}
+
+interface RunOptions extends Record<string, unknown> {
+  autoMerge?: unknown;
+  autoPush?: unknown;
+  closeIssue?: unknown;
+  containerHome?: unknown;
+  cwd?: unknown;
+  docker?: unknown;
+  dockerImage?: unknown;
+  isolation?: unknown;
+  mergeQueue?: unknown;
+  mount?: readonly string[] | null;
+  mounts?: unknown;
+  noIsolation?: unknown;
+  noMounts?: unknown;
+  pr?: unknown;
+  prBase?: unknown;
+  preparedWorktree?: unknown;
+  requiredQualityGates?: unknown;
+  ship?: unknown;
+  worktree?: unknown;
+}
+
+interface RunPlanFacade {
+  resolveRunPlan(options?: RunOptions): Readonly<RunPlan>;
+}
+
+interface RunModeFacade {
+  runModeFromPlan(plan: RunPlan): string | null;
+}
+
+interface EnvironmentFacade {
+  firstTruthy<T>(...values: T[]): T | undefined;
+  anyTruthy(...values: unknown[]): boolean;
+  optionalValue<T>(value: T): T | undefined;
+  detectGitRepoRoot(): string;
+  resolveTargetCwd(): string | undefined;
+  resolveEnvBool(value: unknown): boolean | undefined;
+  mergeRunOptions(options: RunOptions): RunOptions;
+  resolveMergeQueue(options: RunOptions): boolean | undefined;
+  resolvePrBase(options: RunOptions): string | undefined;
+  resolveCloseIssue(options: RunOptions): 'auto' | 'always' | 'never' | undefined;
+  resolveMounts(options: RunOptions):
+    | Array<{ host: string; container: string; readonly: boolean }>
+    | undefined;
+}
+
+interface BuildStartOptionsArgs {
+  clusterId?: unknown;
+  options?: RunOptions;
+  settings?: Settings;
+  providerOverride?: unknown;
+  modelOverride?: unknown;
+  forceProvider?: unknown;
+}
+
+interface BuildTrustedStartOptionsArgs extends BuildStartOptionsArgs {
+  plan?: RunPlan | null;
+}
+
+interface BuildStartOptionsFromPlanArgs extends BuildStartOptionsArgs {
+  plan: RunPlan;
+  options: RunOptions;
+  settings: Settings;
+  preparedWorktree?: unknown;
+  environment: boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const runPlan: RunPlanFacade = require('./run-plan');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const runMode: RunModeFacade = require('./run-mode');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const environmentHelpers: EnvironmentFacade = require('./start-cluster-environment');
+
+const { resolveRunPlan } = runPlan;
+const { runModeFromPlan } = runMode;
+const {
+  firstTruthy,
+  anyTruthy,
+  optionalValue,
+  detectGitRepoRoot,
+  resolveTargetCwd,
+  resolveEnvBool,
+  mergeRunOptions,
+  resolveMergeQueue,
+  resolvePrBase,
+  resolveCloseIssue,
+  resolveMounts,
+} = environmentHelpers;
+
+function isRunIsolation(value: string): value is RunIsolation {
+  return value === 'none' || value === 'worktree' || value === 'docker';
+}
+
+function isRunDelivery(value: string): value is RunDelivery {
+  return value === 'none' || value === 'pr' || value === 'ship';
+}
+
+function validateSavedRunModes(settings: Settings): {
+  isolation: RunIsolation;
+  delivery: RunDelivery;
+} {
+  const isolation = settings.defaultIsolation || 'none';
+  const delivery = settings.defaultDelivery || 'none';
+  if (!isRunIsolation(isolation)) {
+    throw new Error(`Invalid saved isolation mode: ${isolation}`);
+  }
+  if (!isRunDelivery(delivery)) {
+    throw new Error(`Invalid saved delivery mode: ${delivery}`);
+  }
+  return { isolation, delivery };
+}
+
+function resolveEffectiveIsolation(options: RunOptions, savedIsolation: RunIsolation): RunIsolation {
+  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: RunOptions, savedDelivery: RunDelivery): RunDelivery {
+  if (options.ship === true || options.autoMerge === true) return 'ship';
+  if (options.pr === true || resolveEnvBool(process.env.ZEROSHOT_PR) === true) return 'pr';
+  return savedDelivery;
+}
+
+function resolveEffectiveRunPlan(
+  options: RunOptions = {},
+  settings: Settings = {}
+): Readonly<RunPlan> {
+  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({
+    docker: isolation === 'docker',
+    worktree: isolation === 'worktree',
+    pr: delivery === 'pr',
+    ship: delivery === 'ship',
+  });
+}
+
+function buildStartOptionsFromPlan({
+  clusterId,
+  plan,
+  options,
+  settings,
+  providerOverride,
+  modelOverride,
+  forceProvider,
+  preparedWorktree,
+  environment,
+}: BuildStartOptionsFromPlanArgs): Readonly<Record<string, unknown>> {
+  const targetCwd = environment ? resolveTargetCwd() : options.cwd;
+  return Object.freeze({
+    clusterId,
+    cwd: targetCwd,
+    isolation: plan.isolation === 'docker',
+    isolationImage: environment
+      ? firstTruthy(options.dockerImage, process.env.ZEROSHOT_DOCKER_IMAGE)
+      : optionalValue(options.dockerImage),
+    worktree: plan.isolation === 'worktree',
+    preparedWorktree: preparedWorktree || undefined,
+    autoPr: plan.delivery !== 'none',
+    autoMerge: plan.autoMerge,
+    autoPush: environment ? process.env.ZEROSHOT_PUSH === '1' : options.autoPush === true,
+    modelOverride: optionalValue(modelOverride),
+    providerOverride: optionalValue(providerOverride),
+    noMounts: anyTruthy(options.mounts === false, options.noMounts === true),
+    mounts: resolveMounts(options),
+    containerHome: optionalValue(options.containerHome),
+    forceProvider: optionalValue(forceProvider),
+    prBase: environment ? resolvePrBase(options) : optionalValue(options.prBase),
+    mergeQueue: environment ? resolveMergeQueue(options) : optionalValue(options.mergeQueue),
+    closeIssue: environment ? resolveCloseIssue(options) : optionalValue(options.closeIssue),
+    ship: plan.delivery === 'ship',
+    runMode: runModeFromPlan(plan),
+    requiredQualityGates: options.requiredQualityGates,
+    settings,
+  });
+}
+
+function buildStartOptions({
+  clusterId,
+  options = {},
+  settings = {},
+  providerOverride,
+  modelOverride,
+  forceProvider,
+}: BuildStartOptionsArgs): Readonly<Record<string, unknown>> {
+  const mergedOptions = mergeRunOptions(options);
+  const plan = resolveEffectiveRunPlan(options, settings);
+  return buildStartOptionsFromPlan({
+    clusterId,
+    plan,
+    options: mergedOptions,
+    settings,
+    providerOverride,
+    modelOverride,
+    forceProvider,
+    environment: true,
+  });
+}
+
+function buildTrustedStartOptions({
+  clusterId,
+  plan,
+  options = {},
+  settings = {},
+  providerOverride,
+  modelOverride,
+  forceProvider,
+}: BuildTrustedStartOptionsArgs): Readonly<Record<string, unknown>> {
+  if (!plan || !Object.isFrozen(plan)) {
+    throw new Error('Trusted start requires a frozen canonical run plan');
+  }
+  const canonical = resolveRunPlan({
+    docker: plan.isolation === 'docker',
+    worktree: plan.isolation === 'worktree',
+    pr: plan.delivery === 'pr',
+    ship: plan.delivery === 'ship',
+  });
+  if (
+    canonical.isolation !== plan.isolation ||
+    canonical.delivery !== plan.delivery ||
+    canonical.autoMerge !== plan.autoMerge
+  ) {
+    throw new Error('Trusted start plan is not canonical');
+  }
+  if (canonical.isolation === 'none') {
+    throw new Error('Trusted worker start requires worktree or docker isolation');
+  }
+  if (options.preparedWorktree && canonical.isolation !== 'worktree') {
+    throw new Error('Prepared worktree requires canonical worktree isolation');
+  }
+  return buildStartOptionsFromPlan({
+    clusterId,
+    plan: canonical,
+    options,
+    settings,
+    providerOverride,
+    modelOverride,
+    forceProvider,
+    preparedWorktree: options.preparedWorktree,
+    environment: false,
+  });
+}
+
+export = { buildStartOptions, buildTrustedStartOptions, resolveEffectiveRunPlan, detectGitRepoRoot };