@pellux/goodvibes-agent 0.1.56 → 0.1.58

package/src/runtime/cloudflare-control-plane.ts

@@ -1,350 +0,0 @@
-import { join } from 'node:path';
-import { getOrCreateCompanionToken } from '@pellux/goodvibes-sdk/platform/pairing';
-import type { ConfigManager } from '../config/index.ts';
-import { GOODVIBES_AGENT_PAIRING_SURFACE } from '../config/surface.ts';
-
-export const CLOUDFLARE_COMPONENT_IDS = [
-  'workers',
-  'queues',
-  'zeroTrustTunnel',
-  'zeroTrustAccess',
-  'dns',
-  'kv',
-  'durableObjects',
-  'secretsStore',
-  'r2',
-] as const;
-
-export type CloudflareComponent = typeof CLOUDFLARE_COMPONENT_IDS[number];
-export type CloudflareComponentSelection = Partial<Record<CloudflareComponent, boolean>>;
-export type CloudflareBatchMode = 'off' | 'explicit' | 'eligible-by-default';
-
-export const DEFAULT_CLOUDFLARE_COMPONENT_SELECTION: Readonly<Record<CloudflareComponent, boolean>> = {
-  workers: true,
-  queues: true,
-  zeroTrustTunnel: false,
-  zeroTrustAccess: false,
-  dns: false,
-  kv: false,
-  durableObjects: false,
-  secretsStore: false,
-  r2: false,
-};
-
-export const CLOUDFLARE_COMPONENT_LABELS: Readonly<Record<CloudflareComponent, string>> = {
-  workers: 'Workers',
-  queues: 'Queues',
-  zeroTrustTunnel: 'Zero Trust Tunnel',
-  zeroTrustAccess: 'Zero Trust Access',
-  dns: 'DNS hostname',
-  kv: 'KV',
-  durableObjects: 'Durable Objects',
-  secretsStore: 'Secrets Store',
-  r2: 'R2 artifacts',
-};
-
-export interface CloudflareProvisionStep {
-  readonly name: string;
-  readonly status: 'ok' | 'skipped' | 'warning';
-  readonly message?: string;
-  readonly resourceId?: string;
-}
-
-export interface CloudflareControlPlaneStatus {
-  readonly enabled: boolean;
-  readonly ready: boolean;
-  readonly configured: Record<string, boolean>;
-  readonly config: Record<string, unknown>;
-  readonly warnings: readonly string[];
-}
-
-export interface CloudflareTokenRequirement {
-  readonly component: CloudflareComponent | 'bootstrap';
-  readonly scope: 'account' | 'zone' | 'user' | 'r2';
-  readonly permission: string;
-  readonly alternatives?: readonly string[];
-  readonly reason: string;
-}
-
-export interface CloudflareTokenRequirementsResult {
-  readonly ok: true;
-  readonly components: Readonly<Record<CloudflareComponent, boolean>>;
-  readonly permissions: readonly CloudflareTokenRequirement[];
-  readonly bootstrapToken: {
-    readonly requiredForSdkCreation: boolean;
-    readonly storeInGoodVibes: false;
-    readonly instructions: readonly string[];
-  };
-}
-
-export interface CloudflareValidateResult {
-  readonly ok: boolean;
-  readonly account?: {
-    readonly id: string;
-    readonly name: string;
-    readonly type?: string;
-  };
-  readonly tokenSource: string;
-}
-
-export interface CloudflareOperationalTokenResult {
-  readonly ok: true;
-  readonly tokenId?: string;
-  readonly tokenName: string;
-  readonly tokenSource: 'bootstrap';
-  readonly apiTokenRef?: string;
-  readonly generatedToken?: string;
-  readonly accountId: string;
-  readonly zoneId?: string;
-  readonly permissions: readonly CloudflareTokenRequirement[];
-}
-
-export interface CloudflareDiscoverResult {
-  readonly ok: true;
-  readonly tokenSource: string;
-  readonly accounts: ReadonlyArray<{ readonly id: string; readonly name: string; readonly type?: string }>;
-  readonly selectedAccount?: { readonly id: string; readonly name: string; readonly type?: string };
-  readonly zones: ReadonlyArray<{ readonly id: string; readonly name: string; readonly status?: string; readonly type?: string }>;
-  readonly selectedZone?: { readonly id: string; readonly name: string; readonly status?: string; readonly type?: string };
-  readonly workerSubdomain?: string;
-  readonly queues?: ReadonlyArray<{ readonly queue_id?: string; readonly queue_name?: string }>;
-  readonly kvNamespaces?: ReadonlyArray<{ readonly id?: string; readonly title?: string }>;
-  readonly durableObjectNamespaces?: ReadonlyArray<{ readonly id?: string; readonly name?: string; readonly class?: string }>;
-  readonly r2Buckets?: ReadonlyArray<{ readonly name?: string; readonly storage_class?: string }>;
-  readonly secretsStores?: ReadonlyArray<{ readonly id: string; readonly name: string }>;
-  readonly tunnels?: ReadonlyArray<{ readonly id?: string; readonly name?: string; readonly status?: string }>;
-  readonly accessApplications?: ReadonlyArray<{ readonly id?: string; readonly name?: string; readonly domain?: string; readonly type?: string }>;
-  readonly warnings: readonly string[];
-}
-
-export interface CloudflareProvisionResult {
-  readonly ok: boolean;
-  readonly dryRun: false;
-  readonly steps: readonly CloudflareProvisionStep[];
-  readonly account?: { readonly id: string; readonly name: string };
-  readonly worker?: { readonly name: string; readonly baseUrl?: string; readonly subdomain?: string; readonly hostname?: string; readonly cron?: string };
-  readonly queues?: { readonly queueName: string; readonly queueId: string; readonly deadLetterQueueName: string; readonly deadLetterQueueId: string; readonly consumerId?: string };
-  readonly tunnel?: { readonly id: string; readonly name: string; readonly hostname?: string; readonly tokenRef?: string };
-  readonly access?: { readonly appId?: string; readonly serviceTokenId?: string; readonly serviceTokenRef?: string };
-  readonly dns?: {
-    readonly zoneId: string;
-    readonly zoneName?: string;
-    readonly records: ReadonlyArray<{ readonly id?: string; readonly name?: string; readonly type?: string; readonly content?: string }>;
-  };
-  readonly kv?: { readonly namespaceName: string; readonly namespaceId: string };
-  readonly durableObjects?: { readonly namespaceName: string; readonly namespaceId?: string };
-  readonly r2?: { readonly bucketName: string; readonly storageClass: 'Standard' };
-  readonly secretsStore?: { readonly storeName: string; readonly storeId: string };
-  readonly verification?: CloudflareVerifyResult;
-  readonly generatedSecrets?: {
-    readonly workerClientToken?: string;
-    readonly tunnelToken?: string;
-    readonly accessServiceTokenClientId?: string;
-    readonly accessServiceTokenClientSecret?: string;
-  };
-}
-
-export interface CloudflareVerifyResult {
-  readonly ok: boolean;
-  readonly workerHealth: {
-    readonly ok: boolean;
-    readonly status: number;
-    readonly error?: string;
-  };
-  readonly daemonBatchProxy?: {
-    readonly ok: boolean;
-    readonly status: number;
-    readonly error?: string;
-  };
-}
-
-export interface CloudflareDisableResult {
-  readonly ok: boolean;
-  readonly steps: readonly CloudflareProvisionStep[];
-}
-
-export interface CloudflareTokenRequirementsRequest {
-  readonly components?: CloudflareComponentSelection;
-  readonly includeBootstrap?: boolean;
-}
-
-export interface CloudflareOperationalTokenRequest extends CloudflareTokenRequirementsRequest {
-  readonly accountId?: string;
-  readonly zoneId?: string;
-  readonly zoneName?: string;
-  readonly bootstrapToken?: string;
-  readonly tokenName?: string;
-  readonly expiresOn?: string;
-  readonly persistConfig?: boolean;
-  readonly storeApiToken?: boolean;
-  readonly returnGeneratedToken?: boolean;
-}
-
-export interface CloudflareValidateRequest {
-  readonly accountId?: string;
-  readonly apiToken?: string;
-  readonly apiTokenRef?: string;
-}
-
-export interface CloudflareDiscoverRequest extends CloudflareValidateRequest {
-  readonly components?: CloudflareComponentSelection;
-  readonly zoneId?: string;
-  readonly zoneName?: string;
-  readonly includeResources?: boolean;
-}
-
-export interface CloudflareProvisionRequest extends CloudflareDiscoverRequest {
-  readonly workerName?: string;
-  readonly workerSubdomain?: string;
-  readonly workerHostname?: string;
-  readonly workerBaseUrl?: string;
-  readonly daemonBaseUrl?: string;
-  readonly daemonHostname?: string;
-  readonly queueName?: string;
-  readonly deadLetterQueueName?: string;
-  readonly tunnelName?: string;
-  readonly tunnelId?: string;
-  readonly tunnelServiceUrl?: string;
-  readonly tunnelTokenRef?: string;
-  readonly accessAppId?: string;
-  readonly accessServiceTokenId?: string;
-  readonly accessServiceTokenRef?: string;
-  readonly kvNamespaceName?: string;
-  readonly kvNamespaceId?: string;
-  readonly durableObjectNamespaceName?: string;
-  readonly durableObjectNamespaceId?: string;
-  readonly r2BucketName?: string;
-  readonly secretsStoreName?: string;
-  readonly secretsStoreId?: string;
-  readonly workerCron?: string;
-  readonly operatorToken?: string;
-  readonly operatorTokenRef?: string;
-  readonly workerClientToken?: string;
-  readonly workerClientTokenRef?: string;
-  readonly storeApiToken?: boolean;
-  readonly storeOperatorToken?: boolean;
-  readonly storeWorkerClientToken?: boolean;
-  readonly returnGeneratedSecrets?: boolean;
-  readonly enableWorkersDev?: boolean;
-  readonly queueJobPayloads?: boolean;
-  readonly verify?: boolean;
-  readonly persistConfig?: boolean;
-  readonly batchMode?: CloudflareBatchMode;
-}
-
-export interface CloudflareVerifyRequest {
-  readonly workerBaseUrl?: string;
-  readonly workerClientToken?: string;
-  readonly workerClientTokenRef?: string;
-}
-
-export interface CloudflareDisableRequest extends CloudflareValidateRequest {
-  readonly workerName?: string;
-  readonly disableWorkerSubdomain?: boolean;
-  readonly disableCron?: boolean;
-  readonly persistConfig?: boolean;
-}
-
-export class CloudflareDaemonRouteError extends Error {
-  readonly status: number;
-  readonly code: string;
-
-  constructor(message: string, status: number, code: string) {
-    super(message);
-    this.name = 'CloudflareDaemonRouteError';
-    this.status = status;
-    this.code = code;
-  }
-}
-
-export interface CloudflareDaemonClient {
-  status(): Promise<CloudflareControlPlaneStatus>;
-  tokenRequirements(input?: CloudflareTokenRequirementsRequest): Promise<CloudflareTokenRequirementsResult>;
-  createOperationalToken(input: CloudflareOperationalTokenRequest): Promise<CloudflareOperationalTokenResult>;
-  discover(input?: CloudflareDiscoverRequest): Promise<CloudflareDiscoverResult>;
-  validate(input?: CloudflareValidateRequest): Promise<CloudflareValidateResult>;
-  provision(input: CloudflareProvisionRequest): Promise<CloudflareProvisionResult>;
-  verify(input?: CloudflareVerifyRequest): Promise<CloudflareVerifyResult>;
-  disable(input?: CloudflareDisableRequest): Promise<CloudflareDisableResult>;
-}
-
-export interface CloudflareDaemonClientOptions {
-  readonly configManager: Pick<ConfigManager, 'get'>;
-  readonly homeDirectory: string;
-}
-
-function connectHostForBindHost(host: string): string {
-  if (host === '0.0.0.0' || host === '::' || host.trim().length === 0) return '127.0.0.1';
-  return host;
-}
-
-function hostForUrl(host: string): string {
-  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
-}
-
-export function resolveCloudflareDaemonBaseUrl(configManager: Pick<ConfigManager, 'get'>): string {
-  const configuredBaseUrl = String(configManager.get('controlPlane.baseUrl' as never) ?? '').trim();
-  if (configuredBaseUrl) return configuredBaseUrl.replace(/\/+$/, '');
-  const host = hostForUrl(connectHostForBindHost(String(configManager.get('controlPlane.host' as never) ?? '127.0.0.1')));
-  const portValue = Number(configManager.get('controlPlane.port' as never) ?? 3421);
-  const port = Number.isFinite(portValue) && portValue > 0 ? portValue : 3421;
-  return `http://${host}:${port}`;
-}
-
-export function buildDefaultCloudflareDaemonBaseUrl(configManager: Pick<ConfigManager, 'get'>): string {
-  return resolveCloudflareDaemonBaseUrl(configManager);
-}
-
-function readDaemonToken(homeDirectory: string): string {
-  const daemonHomeDir = join(homeDirectory, '.goodvibes', 'daemon');
-  return getOrCreateCompanionToken(GOODVIBES_AGENT_PAIRING_SURFACE, { daemonHomeDir }).token;
-}
-
-async function readJsonResponse<T>(response: Response): Promise<T> {
-  const text = await response.text();
-  const body = text.trim().length > 0 ? JSON.parse(text) as unknown : {};
-  if (!response.ok) {
-    const record = body && typeof body === 'object' ? body as Record<string, unknown> : {};
-    const message = typeof record.error === 'string' ? record.error : `Cloudflare daemon route failed with HTTP ${response.status}`;
-    const code = typeof record.code === 'string' ? record.code : 'CLOUDFLARE_DAEMON_ROUTE_ERROR';
-    throw new CloudflareDaemonRouteError(message, response.status, code);
-  }
-  return body as T;
-}
-
-export function createCloudflareDaemonClient(options: CloudflareDaemonClientOptions): CloudflareDaemonClient {
-  const baseUrl = resolveCloudflareDaemonBaseUrl(options.configManager);
-  const token = readDaemonToken(options.homeDirectory);
-
-  const requestJson = async <T>(path: string, init: RequestInit = {}): Promise<T> => {
-    const headers = new Headers(init.headers);
-    headers.set('Authorization', `Bearer ${token}`);
-    if (init.body !== undefined) headers.set('Content-Type', 'application/json');
-    const response = await fetch(`${baseUrl}${path}`, { ...init, headers });
-    return await readJsonResponse<T>(response);
-  };
-
-  const postJson = <T>(path: string, body: unknown): Promise<T> => requestJson<T>(path, {
-    method: 'POST',
-    body: JSON.stringify(body ?? {}),
-  });
-
-  return {
-    status: () => requestJson<CloudflareControlPlaneStatus>('/api/cloudflare/status'),
-    tokenRequirements: (input = {}) => postJson<CloudflareTokenRequirementsResult>('/api/cloudflare/token/requirements', input),
-    createOperationalToken: (input) => postJson<CloudflareOperationalTokenResult>('/api/cloudflare/token/create', input),
-    discover: (input = {}) => postJson<CloudflareDiscoverResult>('/api/cloudflare/discover', input),
-    validate: (input = {}) => postJson<CloudflareValidateResult>('/api/cloudflare/validate', input),
-    provision: (input) => postJson<CloudflareProvisionResult>('/api/cloudflare/provision', input),
-    verify: (input = {}) => postJson<CloudflareVerifyResult>('/api/cloudflare/verify', input),
-    disable: (input = {}) => postJson<CloudflareDisableResult>('/api/cloudflare/disable', input),
-  };
-}
-
-export function normalizeCloudflareComponents(selection: CloudflareComponentSelection | undefined): Record<CloudflareComponent, boolean> {
-  const result: Record<CloudflareComponent, boolean> = { ...DEFAULT_CLOUDFLARE_COMPONENT_SELECTION };
-  for (const component of CLOUDFLARE_COMPONENT_IDS) {
-    if (typeof selection?.[component] === 'boolean') result[component] = selection[component] === true;
-  }
-  return result;
-}

package/src/runtime/sandbox-public-gaps.ts

@@ -1,358 +0,0 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
-import {
-  detectSandboxHostStatus,
-  getSandboxConfigSnapshot,
-  type ConfigManagerLike,
-  type SandboxBackendProbe,
-  type SandboxLaunchPlan,
-  type SandboxProfile,
-} from '@pellux/goodvibes-sdk/platform/runtime/sandbox';
-export interface SandboxGuestBundle {
-  readonly version: 1;
-  readonly exportedAt: number;
-  readonly guest: {
-    readonly qemuBinary: string;
-    readonly imagePath: string;
-    readonly wrapperPath: string;
-    readonly host: string;
-    readonly port: number;
-    readonly user: string;
-    readonly workspacePath: string;
-    readonly sessionMode: string;
-    readonly replJavaScriptCommand: string;
-  };
-  readonly nextSteps: readonly string[];
-}
-
-export interface SandboxQemuInitBundle {
-  readonly directory: string;
-  readonly wrapperPath: string;
-  readonly guestBundlePath: string;
-  readonly readmePath: string;
-}
-
-export interface SandboxQemuSetupBundle extends SandboxQemuInitBundle {
-  readonly imagePath: string;
-  readonly imageCreateScriptPath: string;
-  readonly guestBootstrapScriptPath: string;
-  readonly projectionPolicyPath: string;
-  readonly sshConfigPath: string;
-  readonly seedDirectory: string;
-  readonly seedIsoPath: string;
-  readonly sshKeyPath: string;
-  readonly sshPublicKeyPath: string;
-  readonly manifestPath: string;
-}
-
-export interface SandboxQemuSetupManifest {
-  readonly version: 1;
-  readonly createdAt: number;
-  readonly wrapperPath: string;
-  readonly imagePath: string;
-  readonly imageCreateScriptPath: string;
-  readonly guestBootstrapScriptPath: string;
-  readonly projectionPolicyPath: string;
-  readonly sshConfigPath: string;
-  readonly seedDirectory: string;
-  readonly seedIsoPath: string;
-  readonly sshKeyPath: string;
-  readonly sshPublicKeyPath: string;
-  readonly recommendedSettings: {
-    readonly backend: 'qemu';
-    readonly qemuBinary: string;
-    readonly wrapperPath: string;
-    readonly imagePath: string;
-    readonly guestHost: string;
-    readonly guestPort: number;
-    readonly guestUser: string;
-    readonly guestWorkspacePath: string;
-    readonly sessionMode: string;
-    readonly replJavaScriptCommand: string;
-  };
-}
-
-export interface SandboxProvisioningOptions {
-  readonly surfaceRoot: string;
-}
-
-export interface WritableConfigManagerLike extends ConfigManagerLike {
-  setDynamic(key: string, value: unknown): void;
-}
-
-export class AgentSandboxExternalizedError extends Error {
-  readonly code = 'sandbox_externalized_to_tui';
-  readonly action: string;
-
-  constructor(action: string) {
-    super(`Agent sandbox ${action} is externalized to GoodVibes TUI. Delegate build/sandbox/QEMU work to a GoodVibes TUI session instead.`);
-    this.name = 'AgentSandboxExternalizedError';
-    this.action = action;
-  }
-}
-
-function sandboxExternalized(action: string): never {
-  throw new AgentSandboxExternalizedError(action);
-}
-
-export function probeSandboxBackends(manager: ConfigManagerLike): SandboxBackendProbe {
-  const host = detectSandboxHostStatus(manager);
-  const config = getSandboxConfigSnapshot(manager);
-  const qemuBinary = config.qemuBinary || 'qemu-system-x86_64';
-  const qemuImage = config.qemuImagePath || '';
-  const qemuExecWrapper = config.qemuExecWrapper || '';
-  const qemuGuestHost = config.qemuGuestHost || '';
-  const qemuProbe = spawnSync(qemuBinary, ['--version'], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'buffer',
-    timeout: 1500,
-    windowsHide: true,
-  });
-  const qemuAvailable = qemuProbe.status === 0 || qemuProbe.status === 1;
-  const qemuBlockedReason = host.windows && !host.runningInWsl
-    ? 'QEMU sandboxing on Windows requires running GoodVibes inside WSL.'
-    : '';
-  const qemuDetail = qemuBlockedReason || (
-    qemuAvailable
-      ? `requires ${qemuBinary} on PATH`
-      : `requires ${qemuBinary} on PATH (${qemuProbe.error instanceof Error ? qemuProbe.error.message : `exit ${qemuProbe.status ?? 'unknown'}`})`
-  );
-  const warnings: string[] = [];
-  if (config.vmBackend === 'qemu' && !qemuAvailable) {
-    warnings.push(`Requested sandbox backend "${config.vmBackend}" is unavailable; local process isolation will not be used unless sandbox.vmBackend is set to "local".`);
-  }
-  if (config.vmBackend === 'qemu' && !qemuImage) {
-    warnings.push('QEMU backend selected without sandbox.qemuImagePath; sessions can be planned and reviewed, but guest execution remains disabled.');
-  }
-  if (config.vmBackend === 'qemu' && qemuImage && !qemuExecWrapper) {
-    warnings.push('QEMU image is configured without sandbox.qemuExecWrapper; guest launch planning is wired, but command execution remains disabled until a host bridge is configured.');
-  }
-  if (config.vmBackend === 'qemu' && qemuExecWrapper && !qemuGuestHost) {
-    warnings.push('QEMU wrapper is configured without sandbox.qemuGuestHost; host bridge mode is available, but real guest SSH transport remains disabled until the guest host is configured.');
-  }
-  if (config.vmBackend === 'qemu' && qemuExecWrapper && !existsSync(qemuExecWrapper)) {
-    warnings.push(`Configured sandbox.qemuExecWrapper does not exist: ${qemuExecWrapper}`);
-  }
-  if (config.vmBackend === 'qemu' && qemuExecWrapper && existsSync(qemuExecWrapper) && !isExecutableFile(qemuExecWrapper)) {
-    warnings.push(`Configured sandbox.qemuExecWrapper is not executable: ${qemuExecWrapper}`);
-  }
-  if (qemuBlockedReason) warnings.push(qemuBlockedReason);
-  return {
-    requestedBackend: config.vmBackend,
-    resolvedBackend: config.vmBackend,
-    backends: [
-      { id: 'local', available: true, detail: 'host-local process isolation is available when explicitly selected' },
-      { id: 'qemu', available: qemuAvailable && !qemuBlockedReason, detail: qemuDetail },
-    ],
-    warnings,
-  };
-}
-
-export function buildSandboxLaunchPlan(
-  profile: SandboxProfile,
-  label: string,
-  manager: ConfigManagerLike,
-  workspaceRoot: string,
-): SandboxLaunchPlan {
-  const config = getSandboxConfigSnapshot(manager);
-  const backendProbe = probeSandboxBackends(manager);
-  const backend = backendProbe.resolvedBackend === 'qemu' ? 'qemu' : 'local';
-  const safeWorkspaceRoot = resolve(workspaceRoot);
-  if (backend === 'qemu') {
-    void profile;
-    void label;
-    void config;
-    void safeWorkspaceRoot;
-    sandboxExternalized('QEMU launch planning');
-  }
-  return {
-    backend: 'local',
-    command: process.env.SHELL || 'bash',
-    args: ['-lc', `echo "goodvibes sandbox ${profile.id}: ${label}"`],
-    workspaceRoot: safeWorkspaceRoot,
-    summary: buildCommandSummary(process.env.SHELL || 'bash', ['-lc', `echo "goodvibes sandbox ${profile.id}: ${label}"`]),
-  };
-}
-
-export interface SandboxCommandPlan {
-  readonly command: string;
-  readonly args: readonly string[];
-  readonly summary: string;
-  readonly env?: NodeJS.ProcessEnv | undefined;
-}
-
-export interface SandboxCommandResult {
-  readonly status: number | null;
-  readonly stdout: string;
-  readonly stderr: string;
-}
-
-function buildCommandSummary(command: string, args: readonly string[]): string {
-  return [command, ...args].join(' ').trim();
-}
-
-function isExecutableFile(path: string): boolean {
-  try {
-    const stat = statSync(path);
-    return stat.isFile() && (stat.mode & 0o111) !== 0;
-  } catch {
-    return false;
-  }
-}
-
-export function resolveSandboxCommandPlan(
-  launchPlan: SandboxLaunchPlan,
-  command: string,
-  args: readonly string[],
-  manager?: ConfigManagerLike,
-): SandboxCommandPlan {
-  if (launchPlan.backend === 'qemu') {
-    void manager;
-    sandboxExternalized('QEMU command planning');
-  }
-  return {
-    command,
-    args,
-    summary: buildCommandSummary(command, args),
-  };
-}
-
-export function executeSandboxCommand(
-  launchPlan: SandboxLaunchPlan,
-  command: string,
-  args: readonly string[],
-  options: {
-    readonly cwd?: string;
-    readonly env?: NodeJS.ProcessEnv;
-    readonly inheritHostEnv?: boolean;
-    readonly timeoutMs?: number;
-    readonly input?: string;
-  } = {},
-): SandboxCommandResult {
-  void launchPlan;
-  void command;
-  void args;
-  void options;
-  sandboxExternalized('command execution');
-}
-
-export function executeSandboxManagedCommand(
-  launchPlan: SandboxLaunchPlan,
-  command: string,
-  args: readonly string[],
-  manager: ConfigManagerLike,
-  options: {
-    readonly cwd?: string;
-    readonly env?: NodeJS.ProcessEnv;
-    readonly inheritHostEnv?: boolean;
-    readonly timeoutMs?: number;
-    readonly input?: string;
-  } = {},
-): SandboxCommandResult {
-  void launchPlan;
-  void command;
-  void args;
-  void manager;
-  void options;
-  sandboxExternalized('managed command execution');
-}
-
-function resolveWorkspacePath(workspaceRoot: string, pathArg: string): string {
-  return resolve(workspaceRoot, pathArg);
-}
-
-export function scaffoldSandboxQemuInitBundle(
-  manager: ConfigManagerLike,
-  workspaceRoot: string,
-  pathArg: string,
-  _options: SandboxProvisioningOptions,
-): SandboxQemuInitBundle {
-  void manager;
-  void workspaceRoot;
-  void pathArg;
-  void _options;
-  sandboxExternalized('QEMU init bundle scaffolding');
-}
-
-export function scaffoldSandboxQemuSetupBundle(
-  manager: ConfigManagerLike,
-  workspaceRoot: string,
-  pathArg: string,
-  options: SandboxProvisioningOptions,
-): SandboxQemuSetupBundle {
-  void manager;
-  void workspaceRoot;
-  void pathArg;
-  void options;
-  sandboxExternalized('QEMU setup bundle scaffolding');
-}
-
-export function bootstrapSandboxQemuSetupBundle(
-  manager: WritableConfigManagerLike,
-  workspaceRoot: string,
-  pathArg: string,
-  _sizeGb: number,
-  options: SandboxProvisioningOptions,
-): SandboxQemuSetupBundle {
-  void manager;
-  void workspaceRoot;
-  void pathArg;
-  void _sizeGb;
-  void options;
-  sandboxExternalized('QEMU setup bootstrap');
-}
-
-export function inspectSandboxQemuSetupManifest(manifest: SandboxQemuSetupManifest): string {
-  return [
-    'QEMU sandbox setup manifest',
-    `  wrapper: ${manifest.wrapperPath}`,
-    `  image: ${manifest.imagePath}`,
-    `  guest: ${manifest.recommendedSettings.guestUser}@${manifest.recommendedSettings.guestHost}:${manifest.recommendedSettings.guestPort}`,
-    `  workspace: ${manifest.recommendedSettings.guestWorkspacePath}`,
-  ].join('\n');
-}
-
-export function loadSandboxQemuSetupManifest(workspaceRoot: string, pathArg: string): SandboxQemuSetupManifest {
-  return JSON.parse(readFileSync(resolveWorkspacePath(workspaceRoot, pathArg), 'utf8')) as SandboxQemuSetupManifest;
-}
-
-export function applySandboxQemuSetupManifest(manager: WritableConfigManagerLike, manifest: SandboxQemuSetupManifest): void {
-  void manager;
-  void manifest;
-  sandboxExternalized('QEMU manifest application');
-}
-
-export function exportSandboxGuestBundle(
-  manager: ConfigManagerLike,
-  workspaceRoot: string,
-  pathArg: string,
-  _options: SandboxProvisioningOptions,
-): { readonly path: string; readonly bundle: SandboxGuestBundle } {
-  void manager;
-  void workspaceRoot;
-  void pathArg;
-  void _options;
-  sandboxExternalized('guest bundle export');
-}
-
-export function inspectSandboxGuestBundle(bundle: SandboxGuestBundle): string {
-  return [
-    'Sandbox guest bundle',
-    `  wrapper: ${bundle.guest.wrapperPath}`,
-    `  image: ${bundle.guest.imagePath || '(not configured)'}`,
-    `  guest: ${bundle.guest.user}@${bundle.guest.host}:${bundle.guest.port}`,
-    `  workspace: ${bundle.guest.workspacePath}`,
-    ...bundle.nextSteps.map((step) => `  next: ${step}`),
-  ].join('\n');
-}
-
-export function renderSandboxDoctor(manager: ConfigManagerLike): string {
-  const probe = probeSandboxBackends(manager);
-  return [
-    'Sandbox doctor',
-    `  backend: ${probe.resolvedBackend}`,
-    ...probe.backends.map((backend) => `  ${backend.id}: ${backend.available ? 'available' : 'missing'} (${backend.detail})`),
-    ...probe.warnings.map((warning) => `  warning: ${warning}`),
-  ].join('\n');
-}