agl 1.0.17 → 21.0.2

package/ts/classes.cli.ts

@@ -0,0 +1,1254 @@
+import * as plugins from './plugins.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import {
+  controllerPackageName,
+  controllerProtocolVersion,
+  controllerUpgradeManagementVersion,
+  type IControllerStatus,
+} from '../ts_interfaces/index.js';
+import {
+  controllerDataDirectory,
+  defaultControllerPort,
+} from './classes.config.js';
+import { ensureControllerDataRoot } from './functions.controllerdataroot.js';
+import type { IControllerRuntimeOverrides } from './interfaces.config.js';
+import type {
+  IControllerReadyIpcMessage,
+  IControllerStartIpcMessage,
+  IControllerStartResult,
+  TControllerIpcMessage,
+} from './interfaces.lifecycle.js';
+import { assertProvidedSetupCode, SmartDataAuthStore } from './classes.authstore.js';
+import { OpenCodeController } from './classes.controller.js';
+import {
+  assertControllerStatus,
+  isLoopbackPortListening,
+  queryControllerStatus as queryManagedControllerStatus,
+  requestControllerUpgradeLaunch,
+  stopVerifiedController,
+  tryQueryControllerStatus as tryQueryManagedControllerStatus,
+  waitUntilControllerExited,
+} from './classes.controllermanagement.js';
+import {
+  inspectControllerProcess,
+  listControllerProcessesForCli,
+  signalVerifiedControllerProcess,
+} from './classes.processinspection.js';
+import {
+  createUpgradeToken,
+  parseUpgradeWorkerPayload,
+  UpgradeCoordinator,
+  upgradePackageTransitionSource,
+  upgradePackageTransitionTarget,
+  type UpgradeStartLease,
+  upgradeTokenEnvironmentVariable,
+} from './classes.upgradecoordinator.js';
+import {
+  createUpgradeWorkerPayload,
+  launchDetachedUpgradeWorker,
+  resolveCurrentCliPath,
+  resolveCurrentPnpmGlobalInstallation,
+  runUpgradeWorker,
+  tryResolveCurrentPnpmGlobalInstallation,
+} from './classes.upgradetransaction.js';
+import { followUpgradeTransaction } from './functions.upgradefollower.js';
+
+type TParsedArguments = Record<string, unknown> & { _: Array<string | number> };
+
+const currentCliName = commitinfo.name === upgradePackageTransitionSource.packageName
+  ? upgradePackageTransitionSource.cliName
+  : upgradePackageTransitionTarget.cliName;
+const currentRuntimeName = currentCliName === upgradePackageTransitionTarget.cliName
+  ? 'AGL'
+  : currentCliName;
+
+const helpText = `
+${currentRuntimeName === 'AGL' ? 'AGL - Agent Gateway Layer' : currentRuntimeName}
+
+Usage:
+  ${currentCliName} start [options]
+  ${currentCliName} status [--port 4097] [--json]
+  ${currentCliName} stop [--port 4097]
+  ${currentCliName} upgrade [--port 4097] [--grace-period-seconds 300] [--continue-sessions] [--json]
+  ${currentCliName} foreground [options]
+  ${currentCliName} temp-password [--port 4097] [--ttl-hours 24]
+
+Commands:
+  start          Start ${currentRuntimeName} as a detached process (Linux and macOS)
+  status         Read live ${currentRuntimeName} and harness status over loopback
+  stop           Verify and stop the live ${currentRuntimeName} process
+  upgrade        Upgrade the pnpm-global package and preserve running state
+  foreground     Run ${currentRuntimeName} attached to this terminal
+  temp-password  Mint a temporary browser login password (max 24 hours)
+  help           Show this help
+
+First-start options:
+  --port <port>                 Controller port (default: 4097)
+  --opencode-port <port>        Local-only OpenCode port (default: 4098)
+  --directory <path>            Fixed OpenCode workspace (default: current directory)
+  --projects-root <path>        Default base for relative project paths and suggestions
+                                (default: workspace; explicitly typed absolute projects may
+                                be outside it; adopted once, then immutable)
+  --public-origin <origin>      Browser origin used for WebAuthn
+  --rp-id <hostname>            WebAuthn relying-party ID
+  --behind-tls-proxy            Trust an explicitly configured TLS reverse proxy
+  --setup-code <code>           Operator-chosen setup code (4-256 printable ASCII
+                                 characters; short codes weaken brute-force resistance)
+
+Upgrade options:
+  --grace-period-seconds <n>    Maximum graceful pause time (default: 300)
+  --continue-sessions           Continue sessions paused for the upgrade
+
+Temp password options:
+  --ttl-hours <hours>           Temporary password lifetime in hours (max 24, default 24)
+
+Upgrade requirements:
+  The command requires the active pnpm-global installation and currently runs
+  on Linux and macOS. Normal progress mode prints the detached worker log before
+  stopping anything; --json emits it in the terminal document.
+
+${currentRuntimeName} stores its data in an embedded database engine by default
+(under $XDG_CONFIG_HOME/hcon/smartdb, default
+~/.config/hcon/smartdb; repository checkouts use ./.nogit/smartdb;
+override the directory
+with HARNESS_CONTROLLER_DB_DIR). Set HARNESS_CONTROLLER_MONGO_URL /
+HARNESS_CONTROLLER_MONGO_DB to use an external MongoDB-compatible server
+instead. temp-password writes to the controller database directly, so run
+it with the same database environment as the running controller; in
+embedded mode it attaches to the running controller's engine socket. The
+password authenticates the browser UI without a passkey until it expires.
+
+The first successful start prints a one-time setup code. Runtime configuration
+is immutable after initialization; use the same --port for later management.
+Detached starts append ${currentRuntimeName} errors to a log file under
+$XDG_CONFIG_HOME/harness-controller (default ~/.config/harness-controller;
+repository checkouts use ./.nogit). Upgrade workers write a separate private
+log under that retained legacy root and print its path before work begins.
+In --json mode the path is retained before work begins and emitted at completion.
+`.trim();
+
+const publicCliCommands = new Set([
+  'start',
+  'status',
+  'stop',
+  'upgrade',
+  'foreground',
+  'temp-password',
+  'help',
+]);
+
+export const formatCliError = (errorArg: unknown): string => {
+  const messages: string[] = [];
+  const seen = new Set<unknown>();
+  const visit = (valueArg: unknown, depthArg: number): void => {
+    if (depthArg > 8 || seen.has(valueArg)) return;
+    if ((typeof valueArg === 'object' && valueArg !== null) || typeof valueArg === 'function') {
+      seen.add(valueArg);
+    }
+    if (valueArg instanceof Error) {
+      if (valueArg.message && !messages.includes(valueArg.message)) messages.push(valueArg.message);
+      if (valueArg instanceof AggregateError) {
+        for (const nestedError of valueArg.errors) visit(nestedError, depthArg + 1);
+      }
+      if (valueArg.cause !== undefined) visit(valueArg.cause, depthArg + 1);
+      return;
+    }
+    const message = String(valueArg);
+    if (message && !messages.includes(message)) messages.push(message);
+  };
+  visit(errorArg, 0);
+  const formatted = messages.join(' Cause: ') || 'An unknown error occurred.';
+  return Buffer.byteLength(formatted, 'utf8') <= 8 * 1024
+    ? formatted
+    : `${Buffer.from(formatted, 'utf8').subarray(0, (8 * 1024) - 16).toString('utf8')} [truncated]`;
+};
+
+const readOption = (
+  argvArg: TParsedArguments,
+  keyArg: string,
+  alternateKeyArg?: string,
+): unknown => argvArg[keyArg] ?? (alternateKeyArg ? argvArg[alternateKeyArg] : undefined);
+
+const readStringOption = (
+  argvArg: TParsedArguments,
+  keyArg: string,
+  alternateKeyArg?: string,
+): string | undefined => {
+  const value = readOption(argvArg, keyArg, alternateKeyArg);
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !value) throw new Error(`--${alternateKeyArg ?? keyArg} requires a value.`);
+  return value;
+};
+
+const readBooleanOption = (
+  argvArg: TParsedArguments,
+  keyArg: string,
+  alternateKeyArg?: string,
+): boolean => {
+  const value = readOption(argvArg, keyArg, alternateKeyArg);
+  if (value === undefined) return false;
+  if (typeof value !== 'boolean') throw new Error(`--${alternateKeyArg ?? keyArg} must be a boolean flag.`);
+  return value;
+};
+
+// The parsed argv mangles numeric-looking values (12345 → number, 0123 → 123),
+// so the setup code is read from the raw runtime arguments instead.
+let activeRuntimeArguments: string[] = [];
+
+const readProvidedSetupCode = (): string | undefined => {
+  for (let index = 0; index < activeRuntimeArguments.length; index++) {
+    const token = activeRuntimeArguments[index];
+    if (token === '--setup-code') {
+      const value = activeRuntimeArguments[index + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error('--setup-code requires a value (use --setup-code=<code> for values starting with dashes).');
+      }
+      return assertProvidedSetupCode(value);
+    }
+    if (token.startsWith('--setup-code=')) {
+      return assertProvidedSetupCode(token.slice('--setup-code='.length));
+    }
+  }
+  return undefined;
+};
+
+const readNumberOption = (
+  argvArg: TParsedArguments,
+  keyArg: string,
+  alternateKeyArg: string,
+  fallbackArg: number | undefined,
+  minimumArg: number,
+  maximumArg: number,
+): number | undefined => {
+  const value = readOption(argvArg, keyArg, alternateKeyArg);
+  if (value === undefined) return fallbackArg;
+  const normalized = typeof value === 'number' ? value : Number(value);
+  if (!Number.isSafeInteger(normalized) || normalized < minimumArg || normalized > maximumArg) {
+    throw new Error(
+      `--${alternateKeyArg} must be an integer between ${minimumArg} and ${maximumArg}.`,
+    );
+  }
+  return normalized;
+};
+
+export const readUpgradeGracePeriodMs = (argvArg: TParsedArguments): number => (
+  readNumberOption(
+    argvArg,
+    'gracePeriodSeconds',
+    'grace-period-seconds',
+    300,
+    1,
+    3_600,
+  )! * 1_000
+);
+
+const readPortOption = (
+  argvArg: TParsedArguments,
+  keyArg: string,
+  alternateKeyArg: string,
+  fallbackArg?: number,
+): number | undefined => readNumberOption(
+  argvArg,
+  keyArg,
+  alternateKeyArg,
+  fallbackArg,
+  1,
+  65_535,
+);
+
+export const parseRuntimeOverrides = (
+  argvArg: TParsedArguments,
+): IControllerRuntimeOverrides => ({
+  controllerPort: readPortOption(argvArg, 'port', 'port', defaultControllerPort)!,
+  publicOrigin: readStringOption(argvArg, 'publicOrigin', 'public-origin'),
+  rpId: readStringOption(argvArg, 'rpId', 'rp-id'),
+  workspaceDirectory: readStringOption(argvArg, 'directory', 'directory'),
+  projectsRoot: readStringOption(argvArg, 'projectsRoot', 'projects-root'),
+  opencodePort: readPortOption(argvArg, 'opencodePort', 'opencode-port'),
+  behindTlsProxy: readOption(argvArg, 'behindTlsProxy', 'behind-tls-proxy') === undefined
+    ? undefined
+    : readBooleanOption(argvArg, 'behindTlsProxy', 'behind-tls-proxy'),
+});
+
+const currentStatusExpectation = {
+  packageName: controllerPackageName,
+  packageVersion: commitinfo.version,
+  protocolVersion: controllerProtocolVersion,
+  upgradeManagementVersion: controllerUpgradeManagementVersion,
+};
+
+const assertStatus = (statusArg: unknown): IControllerStatus => assertControllerStatus(
+  statusArg,
+  currentStatusExpectation,
+);
+
+export const queryControllerStatus = async (
+  portArg: number,
+  timeoutMsArg = 2_500,
+): Promise<IControllerStatus> => queryManagedControllerStatus(
+  portArg,
+  currentStatusExpectation,
+  timeoutMsArg,
+);
+
+const tryQueryControllerStatus = async (portArg: number): Promise<IControllerStatus | undefined> => {
+  return tryQueryManagedControllerStatus(portArg, currentStatusExpectation);
+};
+
+const statusJson = (statusArg: IControllerStatus): string => JSON.stringify(statusArg, null, 2);
+
+export const formatControllerStatus = (statusArg: IControllerStatus): string => {
+  const formatHarness = (harnessIdArg: 'opencode' | 'flex', labelArg: string): string => {
+    const harness = statusArg.harnesses.find((entryArg) => entryArg.harnessId === harnessIdArg);
+    if (!harness) throw new Error(`Controller status is missing the ${labelArg} harness.`);
+    const pid = harness.pid ? ` (PID ${harness.pid})` : '';
+    return `${labelArg}: ${harness.state}${pid}`;
+  };
+  return [
+    `${currentRuntimeName}: ${statusArg.lifecycleState} (PID ${statusArg.controllerPid}, ${statusArg.processMode})`,
+    formatHarness('opencode', 'OpenCode'),
+    formatHarness('flex', 'Flex'),
+    `Setup: ${statusArg.setupRequired ? 'required' : 'complete'}`,
+  ].join('\n');
+};
+
+const printStatus = (statusArg: IControllerStatus): void => {
+  process.stdout.write(formatControllerStatus(statusArg) + '\n');
+};
+
+const printStartResult = (
+  resultArg: IControllerStartResult,
+  jsonArg: boolean,
+  extrasArg: { logFilePath?: string } = {},
+): void => {
+  if (jsonArg) {
+    process.stdout.write(JSON.stringify({ ...resultArg, ...extrasArg }, null, 2) + '\n');
+    return;
+  }
+  process.stdout.write(`${currentRuntimeName} ready: ${resultArg.publicUrl}\n`);
+  printStatus(resultArg.status);
+  if (extrasArg.logFilePath) {
+    process.stdout.write(`Logs: ${extrasArg.logFilePath}\n`);
+  }
+  if (resultArg.setupCode) {
+    process.stdout.write(`Setup code: ${resultArg.setupCode}\n`);
+    process.stdout.write('Keep this code private; it expires after 30 minutes and is accepted only for passkey enrollment.\n');
+  }
+};
+
+const detachedLogRotateBytes = 1024 * 1024;
+
+class RetainedControllerStartupError extends Error {}
+
+const resolveDetachedLogFilePath = (portArg: number): string => {
+  return plugins.path.join(controllerDataDirectory(), `controller-${portArg}.log`);
+};
+
+const openDetachedLogFile = async (
+  logFilePathArg: string,
+): Promise<plugins.fs.promises.FileHandle> => {
+  await plugins.fs.promises.mkdir(
+    plugins.path.dirname(logFilePathArg),
+    { recursive: true, mode: 0o700 },
+  );
+  try {
+    const existing = await plugins.fs.promises.lstat(logFilePathArg);
+    if (existing.isFile() && existing.size > detachedLogRotateBytes) {
+      await plugins.fs.promises.rename(logFilePathArg, `${logFilePathArg}.old`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  // O_NOFOLLOW plus the checks below keep a pre-planted symlink or foreign file
+  // from silently receiving controller diagnostics.
+  const handle = await plugins.fs.promises.open(
+    logFilePathArg,
+    plugins.fs.constants.O_WRONLY
+    | plugins.fs.constants.O_APPEND
+    | plugins.fs.constants.O_CREAT
+    | plugins.fs.constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) {
+      throw new Error(`The controller log path is not a regular file: ${logFilePathArg}`);
+    }
+    if (typeof process.getuid === 'function' && stats.uid !== process.getuid()) {
+      throw new Error(`The controller log file is not owned by the current user: ${logFilePathArg}`);
+    }
+    if ((stats.mode & 0o077) !== 0) {
+      throw new Error(`The controller log file must not be group or world accessible: ${logFilePathArg}`);
+    }
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+  return handle;
+};
+
+const resolveCliPath = async (): Promise<string> => {
+  return await resolveCurrentCliPath();
+};
+
+const acquireStartAdmission = async (
+  commandArg: 'start' | 'foreground' | 'temp-password',
+): Promise<UpgradeStartLease | undefined> => {
+  if (process.platform === 'win32') return undefined;
+  const installation = await tryResolveCurrentPnpmGlobalInstallation();
+  if (!installation) return undefined;
+  const coordinator = new UpgradeCoordinator(installation.globalRoot);
+  return await coordinator.acquireStartLease({
+    token: createUpgradeToken(),
+    cliPath: installation.cliPath,
+    command: commandArg,
+    upgradeToken: process.env[upgradeTokenEnvironmentVariable],
+  });
+};
+
+const serializeRuntimeOptions = (overridesArg: IControllerRuntimeOverrides): string[] => {
+  const args = ['--port', String(overridesArg.controllerPort)];
+  if (overridesArg.publicOrigin !== undefined) args.push('--public-origin', overridesArg.publicOrigin);
+  if (overridesArg.rpId !== undefined) args.push('--rp-id', overridesArg.rpId);
+  if (overridesArg.workspaceDirectory !== undefined) args.push('--directory', overridesArg.workspaceDirectory);
+  if (overridesArg.projectsRoot !== undefined) args.push('--projects-root', overridesArg.projectsRoot);
+  if (overridesArg.opencodePort !== undefined) args.push('--opencode-port', String(overridesArg.opencodePort));
+  if (overridesArg.behindTlsProxy === true) args.push('--behind-tls-proxy');
+  if (overridesArg.behindTlsProxy === false) args.push('--no-behind-tls-proxy');
+  return args;
+};
+
+const stopJustSpawnedProcess = async (
+  childArg: plugins.childProcess.ChildProcess,
+  cliPathArg: string,
+  portArg: number,
+  fingerprintArg: string,
+): Promise<void> => {
+  if (!childArg.pid) return;
+  const releaseParentIpc = (): void => {
+    if (childArg.connected) childArg.disconnect();
+    childArg.unref();
+  };
+  const processIdentity = {
+    pid: childArg.pid,
+    cliPath: cliPathArg,
+    port: portArg,
+    expectedProcessGroupId: childArg.pid,
+    expectedFingerprint: fingerprintArg,
+    command: '__serve' as const,
+  };
+  if (!await inspectControllerProcess(processIdentity)) {
+    releaseParentIpc();
+    return;
+  }
+  try {
+    await signalVerifiedControllerProcess({
+      ...processIdentity,
+      signal: 'SIGTERM',
+      signalProcessGroup: true,
+    });
+  } catch (error) {
+    if (!await inspectControllerProcess(processIdentity)) return;
+    throw error;
+  } finally {
+    // Once cleanup has been requested, the parent must release the IPC channel.
+    // Otherwise both processes can remain alive solely waiting on each other.
+    releaseParentIpc();
+  }
+  if (await waitUntilControllerExited(processIdentity, 30_000)) return;
+  await signalVerifiedControllerProcess({
+    ...processIdentity,
+    signal: 'SIGTERM',
+    signalProcessGroup: true,
+  });
+  if (!await waitUntilControllerExited(processIdentity, 15_000)) {
+    throw new Error(
+      'The detached controller did not complete cooperative cleanup; it remains available for an exact stop retry.',
+    );
+  }
+};
+
+const sendIpcMessage = async (
+  childArg: plugins.childProcess.ChildProcess,
+  messageArg: TControllerIpcMessage,
+): Promise<void> => {
+  if (!childArg.connected) throw new Error('Detached controller IPC channel is unavailable.');
+  await new Promise<void>((resolve, reject) => {
+    childArg.send(messageArg, (errorArg) => errorArg ? reject(errorArg) : resolve());
+  });
+};
+
+const waitForSpawnedChildExit = async (
+  childArg: plugins.childProcess.ChildProcess,
+  timeoutMsArg: number,
+): Promise<boolean> => {
+  if (childArg.exitCode !== null || childArg.signalCode !== null) return true;
+  return await new Promise<boolean>((resolve) => {
+    let settled = false;
+    const finish = (exitedArg: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      childArg.removeListener('exit', onExit);
+      resolve(exitedArg);
+    };
+    const onExit = () => finish(true);
+    const timeout = setTimeout(() => finish(false), timeoutMsArg);
+    childArg.once('exit', onExit);
+  });
+};
+
+const waitForStartGate = async (): Promise<IControllerStartIpcMessage> => {
+  if (!process.connected) {
+    throw new Error('The detached controller start gate requires parent IPC.');
+  }
+  return await new Promise<IControllerStartIpcMessage>((resolve, reject) => {
+    let settled = false;
+    const finish = (errorArg?: Error, messageArg?: IControllerStartIpcMessage) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      process.removeListener('message', onMessage);
+      process.removeListener('disconnect', onDisconnect);
+      if (errorArg) reject(errorArg);
+      else resolve(messageArg!);
+    };
+    const onMessage = (messageArg: unknown) => {
+      const message = messageArg as Partial<TControllerIpcMessage>;
+      if (message?.type === 'start') {
+        finish(undefined, message as IControllerStartIpcMessage);
+      }
+    };
+    const onDisconnect = () => finish(new Error('Parent disconnected before authorizing startup.'));
+    const timeout = setTimeout(() => {
+      finish(new Error('Parent did not authorize detached startup within 5 seconds.'));
+    }, 5_000);
+    process.on('message', onMessage);
+    process.once('disconnect', onDisconnect);
+  });
+};
+
+const waitForDetachedReady = async (
+  childArg: plugins.childProcess.ChildProcess,
+): Promise<IControllerReadyIpcMessage> => {
+  return await new Promise<IControllerReadyIpcMessage>((resolve, reject) => {
+    let settled = false;
+    const finish = (errorArg?: Error, messageArg?: IControllerReadyIpcMessage) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      childArg.removeListener('message', onMessage);
+      childArg.removeListener('error', onError);
+      childArg.removeListener('exit', onExit);
+      if (errorArg) reject(errorArg);
+      else resolve(messageArg!);
+    };
+    const onMessage = (messageArg: unknown) => {
+      const message = messageArg as Partial<TControllerIpcMessage>;
+      if (message?.type === 'startupError' && typeof message.message === 'string') {
+        finish(message.retained === true
+          ? new RetainedControllerStartupError(message.message)
+          : new Error(message.message));
+        return;
+      }
+      if (
+        message?.type === 'ready'
+        && typeof message.publicUrl === 'string'
+        && typeof message.status === 'object'
+        && message.status !== null
+        && (message.setupCode === undefined || typeof message.setupCode === 'string')
+      ) {
+        try {
+          finish(undefined, {
+            type: 'ready',
+            publicUrl: message.publicUrl,
+            status: assertStatus(message.status),
+            ...(message.setupCode ? { setupCode: message.setupCode } : {}),
+          });
+        } catch (error) {
+          finish(error instanceof Error ? error : new Error(String(error)));
+        }
+      }
+    };
+    const onError = (errorArg: Error) => finish(errorArg);
+    const onExit = (codeArg: number | null, signalArg: NodeJS.Signals | null) => {
+      finish(new Error(`Detached controller exited during startup (${signalArg ?? codeArg ?? 'unknown'}).`));
+    };
+    const timeout = setTimeout(() => {
+      finish(new Error('Detached controller did not become ready within 45 seconds.'));
+    }, 45_000);
+    childArg.on('message', onMessage);
+    childArg.once('error', onError);
+    childArg.once('exit', onExit);
+  });
+};
+
+const startDetachedWithoutAdmission = async (argvArg: TParsedArguments): Promise<void> => {
+  if (process.platform === 'win32') {
+    throw new Error('Detached process management is currently supported on Linux and macOS only.');
+  }
+  const overrides = parseRuntimeOverrides(argvArg);
+  const providedSetupCode = readProvidedSetupCode();
+  const existing = await tryQueryControllerStatus(overrides.controllerPort);
+  const json = readBooleanOption(argvArg, 'json');
+  if (existing) {
+    if (providedSetupCode !== undefined && !json) {
+      process.stdout.write(`${currentRuntimeName} is already running; the provided --setup-code was not used.\n`);
+    }
+    if (json) process.stdout.write(statusJson(existing) + '\n');
+    else printStatus(existing);
+    return;
+  }
+  const cliPath = await resolveCliPath();
+  const existingProcesses = await listControllerProcessesForCli(cliPath);
+  const existingProcess = existingProcesses.find((candidateArg) => (
+    candidateArg.port === overrides.controllerPort
+  ));
+  if (existingProcess) {
+    throw new Error(
+      `An ${currentRuntimeName} process is already starting or running (PID ${existingProcess.identity.pid}).`,
+    );
+  }
+  const upgradeToken = process.env[upgradeTokenEnvironmentVariable];
+  let upgradeGlobalRoot: string | undefined;
+  if (upgradeToken) {
+    upgradeGlobalRoot = (await resolveCurrentPnpmGlobalInstallation()).globalRoot;
+  }
+  const logFilePath = resolveDetachedLogFilePath(overrides.controllerPort);
+  const logFileHandle = await openDetachedLogFile(logFilePath);
+  let child: plugins.childProcess.ChildProcess;
+  try {
+    const childEnvironment = { ...process.env };
+    delete childEnvironment[upgradeTokenEnvironmentVariable];
+    child = plugins.childProcess.spawn(
+      process.execPath,
+      [cliPath, '__serve', ...serializeRuntimeOptions(overrides)],
+      {
+        cwd: process.cwd(),
+        detached: true,
+        env: childEnvironment,
+        shell: false,
+        // stdout stays discarded: the transport logs every connection there,
+        // which would grow the file without bound. stderr carries diagnostics.
+        stdio: ['ignore', 'ignore', logFileHandle.fd, 'ipc'],
+      },
+    );
+  } finally {
+    await logFileHandle.close();
+  }
+  if (!child.pid) throw new Error('Detached controller did not provide a process ID.');
+  let spawnedIdentity: Awaited<ReturnType<typeof inspectControllerProcess>> = null;
+  try {
+    for (let attempt = 0; attempt < 20; attempt++) {
+      spawnedIdentity = await inspectControllerProcess({
+        pid: child.pid,
+        cliPath,
+        port: overrides.controllerPort,
+        expectedProcessGroupId: child.pid,
+        command: '__serve',
+      });
+      if (spawnedIdentity) break;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    if (!spawnedIdentity) {
+      throw new Error('Detached controller process identity could not be established.');
+    }
+  } catch (error) {
+    // The child is blocked on its IPC start gate here and owns no server,
+    // database, or OpenCode resources yet. Killing the exact spawned PID cannot
+    // orphan a descendant process.
+    if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+    if (!await waitForSpawnedChildExit(child, 2_000)) {
+      throw new AggregateError(
+        [error],
+        'Detached controller identity failed and the gated child did not exit after SIGKILL.',
+      );
+    }
+    throw error;
+  }
+  try {
+    const readyPromise = waitForDetachedReady(
+      child,
+    );
+    try {
+      await sendIpcMessage(child, {
+        type: 'start',
+        ...(providedSetupCode !== undefined ? { setupCode: providedSetupCode } : {}),
+        ...(upgradeToken === undefined ? {} : { upgradeToken }),
+        ...(upgradeGlobalRoot === undefined ? {} : { upgradeGlobalRoot }),
+      });
+    } catch (error) {
+      void readyPromise.catch(() => undefined);
+      throw error;
+    }
+    const readyMessage = await readyPromise;
+    const status = await queryControllerStatus(overrides.controllerPort);
+    child.disconnect();
+    child.unref();
+    printStartResult({
+      status,
+      publicUrl: readyMessage.publicUrl,
+      ...(readyMessage.setupCode ? { setupCode: readyMessage.setupCode } : {}),
+    }, json, { logFilePath });
+    if (providedSetupCode !== undefined && !readyMessage.setupCode && !json) {
+      process.stdout.write('Setup is already complete; the provided --setup-code was not used.\n');
+    }
+  } catch (error) {
+    if (error instanceof RetainedControllerStartupError) {
+      if (child.connected) child.disconnect();
+      child.unref();
+      process.stderr.write(`${error.message}\n`);
+      return;
+    }
+    try {
+      await stopJustSpawnedProcess(
+        child,
+        cliPath,
+        overrides.controllerPort,
+        spawnedIdentity.fingerprint,
+      );
+    } catch (cleanupErrorArg) {
+      throw new AggregateError(
+        [error, cleanupErrorArg],
+        `Detached controller startup failed (${formatCliError(error)}) and cleanup was incomplete (${formatCliError(cleanupErrorArg)}). Logs: ${logFilePath}`,
+      );
+    }
+    throw new Error(`${formatCliError(error)} Logs: ${logFilePath}`, { cause: error });
+  }
+};
+
+const startDetached = async (argvArg: TParsedArguments): Promise<void> => {
+  const lease = await acquireStartAdmission('start');
+  try {
+    await startDetachedWithoutAdmission(argvArg);
+  } finally {
+    await lease?.release();
+  }
+};
+
+const runForegroundWithAdmission = async (argvArg: TParsedArguments): Promise<void> => {
+  const lease = await acquireStartAdmission('foreground');
+  delete process.env[upgradeTokenEnvironmentVariable];
+  try {
+    await runControllerProcess(argvArg, false);
+  } finally {
+    await lease?.release();
+  }
+};
+
+const runControllerProcess = async (
+  argvArg: TParsedArguments,
+  detachedArg: boolean,
+): Promise<void> => {
+  if (detachedArg && process.platform === 'win32') {
+    throw new Error('Detached process management is currently supported on Linux and macOS only.');
+  }
+  if (detachedArg && !process.connected) {
+    throw new Error('The internal detached server command requires an attached parent IPC channel.');
+  }
+  let providedSetupCode: string | undefined;
+  let upgradeToken: string | undefined;
+  let upgradeGlobalRoot: string | undefined;
+  let startupRetained = false;
+  if (detachedArg) {
+    const gateMessage = await waitForStartGate();
+    // The gate payload crosses a process boundary; validate rather than trust.
+    if (gateMessage.setupCode !== undefined) {
+      providedSetupCode = assertProvidedSetupCode(gateMessage.setupCode);
+    }
+    upgradeToken = gateMessage.upgradeToken;
+    upgradeGlobalRoot = gateMessage.upgradeGlobalRoot;
+  } else {
+    providedSetupCode = readProvidedSetupCode();
+  }
+  const controller = new OpenCodeController({
+    processMode: detachedArg ? 'detached' : 'foreground',
+    runtimeOverrides: parseRuntimeOverrides(argvArg),
+    ...(providedSetupCode !== undefined ? { setupCode: providedSetupCode } : {}),
+    ...(upgradeToken === undefined ? {} : { upgradeToken }),
+    ...(upgradeGlobalRoot === undefined ? {} : { upgradeGlobalRoot }),
+    ...(upgradeToken === undefined
+      ? {}
+      : {
+          onStartupBlocked: async (errorArg: Error) => {
+            startupRetained = true;
+            if (!detachedArg || !process.connected) return;
+            await new Promise<void>((resolve) => {
+              process.send!({
+                type: 'startupError',
+                message: `${errorArg.message} The target controller remains fail-closed and will retry.`,
+                retained: true,
+              }, () => resolve());
+            });
+          },
+        }),
+  });
+  let ready = false;
+  let stopping: Promise<void> | undefined;
+  const stop = (): Promise<void> => {
+    if (stopping) return stopping;
+    let tracked: Promise<void>;
+    tracked = controller.stop().then(() => {
+      if (detachedArg) {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        process.removeListener('disconnect', onDisconnect);
+        if (process.connected && typeof process.disconnect === 'function') process.disconnect();
+      }
+      process.exitCode = 0;
+    }, (errorArg) => {
+      process.exitCode = 1;
+      throw errorArg;
+    }).finally(() => {
+      if (stopping === tracked) stopping = undefined;
+    });
+    stopping = tracked;
+    return tracked;
+  };
+  const onSignal = () => {
+    void stop().catch((errorArg) => {
+      process.exitCode = 1;
+      process.stderr.write(`${currentCliName}: ${formatCliError(errorArg)}\n`);
+    });
+  };
+  const onDisconnect = () => {
+    if (!ready && !startupRetained) {
+      void stop().catch((errorArg) => {
+        process.exitCode = 1;
+        process.stderr.write(`${currentCliName}: ${formatCliError(errorArg)}\n`);
+      });
+    }
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+  if (detachedArg) process.once('disconnect', onDisconnect);
+  try {
+    const result = await controller.start();
+    if (detachedArg) {
+      if (process.connected) {
+        await new Promise<void>((resolve, reject) => {
+          const message: IControllerReadyIpcMessage = {
+            type: 'ready',
+            status: result.status,
+            publicUrl: result.publicUrl,
+            ...(result.setupCode ? { setupCode: result.setupCode } : {}),
+          };
+          process.send!(message, (errorArg) => errorArg ? reject(errorArg) : resolve());
+        });
+      } else if (!startupRetained) {
+        throw new Error('Detached controller startup lost its parent IPC channel.');
+      }
+      ready = true;
+    } else {
+      ready = true;
+      const jsonOutput = readBooleanOption(argvArg, 'json');
+      printStartResult(result, jsonOutput);
+      if (providedSetupCode !== undefined && !result.setupCode && !jsonOutput) {
+        process.stdout.write('Setup is already complete; the provided --setup-code was not used.\n');
+      }
+    }
+  } catch (error) {
+    const normalized = error instanceof Error ? error : new Error(String(error));
+    let ipcError: unknown;
+    if (detachedArg && process.connected) {
+      try {
+        await new Promise<void>((resolve, reject) => {
+          process.send!({ type: 'startupError', message: formatCliError(normalized) }, (errorArg) => (
+            errorArg ? reject(errorArg) : resolve()
+          ));
+        });
+      } catch (errorArg) {
+        ipcError = errorArg;
+      }
+    }
+    let cleanupError: unknown;
+    try {
+      await stop();
+    } catch (errorArg) {
+      cleanupError = errorArg;
+    }
+    const errors = [normalized, ipcError, cleanupError].filter((valueArg) => valueArg !== undefined);
+    if (errors.length > 1) {
+      throw new AggregateError(
+        errors,
+        `Detached controller startup failed: ${formatCliError(normalized)}`,
+      );
+    }
+    throw normalized;
+  }
+};
+
+const showStatus = async (argvArg: TParsedArguments): Promise<void> => {
+  const port = readPortOption(argvArg, 'port', 'port', defaultControllerPort)!;
+  const status = await queryControllerStatus(port).catch(() => {
+    throw new Error(`No compatible ${currentRuntimeName} instance is responding on 127.0.0.1:${port}.`);
+  });
+  if (readBooleanOption(argvArg, 'json')) process.stdout.write(statusJson(status) + '\n');
+  else printStatus(status);
+};
+
+const stopController = async (argvArg: TParsedArguments): Promise<void> => {
+  if (process.platform !== 'linux' && process.platform !== 'darwin') {
+    throw new Error('CLI process stopping is currently supported on Linux and macOS only.');
+  }
+  const port = readPortOption(argvArg, 'port', 'port', defaultControllerPort)!;
+  const status = await tryQueryControllerStatus(port);
+  if (!status) {
+    process.stdout.write(`${currentRuntimeName} is not running.\n`);
+    return;
+  }
+  const cliPath = await resolveCliPath();
+  await stopVerifiedController({ status, cliPath, port });
+  process.stdout.write(`${currentRuntimeName} stopped.\n`);
+};
+
+export const createCurrentPackageUpgradeTransaction = async (
+  coordinatorArg: UpgradeCoordinator,
+  optionsArg: {
+    token: string;
+    port: number;
+    sourceVersion: string;
+    controllerWasRunning: boolean;
+    continueSessions: boolean;
+    gracePeriodMs: number;
+  },
+) => {
+  if (
+    commitinfo.name === upgradePackageTransitionSource.packageName
+    && optionsArg.sourceVersion === upgradePackageTransitionSource.version
+  ) {
+    return await coordinatorArg.createPackageTransitionTransaction(optionsArg);
+  }
+  return await coordinatorArg.createTransaction(optionsArg);
+};
+
+const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
+  if (process.platform !== 'linux' && process.platform !== 'darwin') {
+    throw new Error(`${currentCliName} upgrade is currently supported on Linux and macOS only.`);
+  }
+  const port = readPortOption(argvArg, 'port', 'port', defaultControllerPort)!;
+  const gracePeriodMs = readUpgradeGracePeriodMs(argvArg);
+  const continueSessions = readBooleanOption(argvArg, 'continueSessions', 'continue-sessions');
+  const installation = await resolveCurrentPnpmGlobalInstallation();
+  const status = await tryQueryControllerStatus(port);
+  if (!status && await isLoopbackPortListening(port)) {
+    throw new Error(
+      `Port ${port} is occupied by an incompatible service or controller version; refusing to upgrade.`,
+    );
+  }
+  const payload = createUpgradeWorkerPayload({
+    port,
+    gracePeriodMs,
+    continueSessions,
+    ...(status
+      ? {
+          expectedController: {
+            pid: status.controllerPid,
+            processGroupId: status.processGroupId,
+            processFingerprint: status.processFingerprint,
+          },
+        }
+      : {}),
+  });
+  const coordinator = new UpgradeCoordinator(installation.globalRoot);
+  const invocationToken = createUpgradeToken();
+  const invocationLease = await coordinator.acquireUpgradeLock({
+    token: invocationToken,
+    cliPath: installation.cliPath,
+    command: 'upgrade',
+  });
+  let handoffStarted = false;
+  let invocationError: unknown;
+  try {
+    await createCurrentPackageUpgradeTransaction(coordinator, {
+      token: payload.token,
+      port,
+      sourceVersion: installation.packageVersion,
+      controllerWasRunning: status !== undefined,
+      continueSessions,
+      gracePeriodMs: payload.gracePeriodMs,
+    });
+    let worker: { workerPid: number; logFilePath: string };
+    try {
+      if (status) {
+        await coordinator.createLaunchGrant({
+          token: payload.token,
+          port,
+          packageName: controllerPackageName,
+          packageVersion: commitinfo.version,
+          cliPath: installation.cliPath,
+          controller: payload.expectedController!,
+        });
+        try {
+          worker = await requestControllerUpgradeLaunch(port, payload.token);
+        } finally {
+          await coordinator.removeLaunchGrant(payload.token);
+        }
+      } else {
+        const launched = await launchDetachedUpgradeWorker({ installation, payload });
+        worker = { workerPid: launched.pid, logFilePath: launched.logFilePath };
+      }
+    } catch (errorArg) {
+      const transaction = await coordinator.readTransaction(payload.token);
+      if (transaction.worker?.logFilePath) {
+        worker = {
+          workerPid: transaction.worker.pid,
+          logFilePath: transaction.worker.logFilePath,
+        };
+      } else {
+        await coordinator.finishTransaction(
+          payload.token,
+          false,
+          'The upgrade worker could not be launched.',
+          errorArg instanceof Error ? errorArg.message : String(errorArg),
+        );
+        throw errorArg;
+      }
+    }
+    await coordinator.recordWorkerLaunch(
+      payload.token,
+      worker.workerPid,
+      installation.cliPath,
+      worker.logFilePath,
+    );
+    const json = readBooleanOption(argvArg, 'json');
+    if (!json) {
+      process.stdout.write([
+        `Upgrade worker started (PID ${worker.workerPid}).`,
+        `Logs: ${worker.logFilePath}`,
+        status
+          ? `Controller on port ${port} will restart after a successful upgrade.`
+          : 'No running controller was found; it will remain stopped.',
+      ].join('\n') + '\n');
+    }
+    const launchedTransaction = await coordinator.readTransaction(payload.token);
+    if (!launchedTransaction.worker) {
+      throw new Error('The launched upgrade worker identity was not retained.');
+    }
+    await coordinator.transferUpgradeLockToWorker({
+      lock: invocationLease,
+      token: payload.token,
+      worker: launchedTransaction.worker,
+    });
+    handoffStarted = true;
+    await coordinator.acknowledgeWorker(payload.token);
+    let finalTransaction: Awaited<ReturnType<UpgradeCoordinator['readTransaction']>>;
+    let followError: unknown;
+    try {
+      finalTransaction = await followUpgradeTransaction(
+        coordinator,
+        payload.token,
+        worker.logFilePath,
+        !json,
+        installation,
+      );
+    } catch (errorArg) {
+      followError = errorArg;
+      finalTransaction = await coordinator.readTransaction(payload.token).catch(() => ({
+        version: 2 as const,
+        tokenHash: '',
+        revision: 0,
+        port,
+        sourceVersion: installation.packageVersion,
+        controllerWasRunning: status !== undefined,
+        continueSessions,
+        gracePeriodMs: payload.gracePeriodMs,
+        phase: 'failed' as const,
+        message: errorArg instanceof Error ? errorArg.message : String(errorArg),
+        createdAt: Date.now(),
+        phaseStartedAt: Date.now(),
+        updatedAt: Date.now(),
+        sessions: [],
+        terminal: {
+          success: false,
+          error: errorArg instanceof Error ? errorArg.message : String(errorArg),
+        },
+      }));
+    }
+    if (json) {
+      const reportedWorker = finalTransaction.worker?.logFilePath
+        ? {
+            workerPid: finalTransaction.worker.pid,
+            logFilePath: finalTransaction.worker.logFilePath,
+          }
+        : worker;
+      const sessionSummary = finalTransaction.sessions.reduce((summary, session) => {
+        summary.pause[session.pauseState] = (summary.pause[session.pauseState] ?? 0) + 1;
+        if (session.continueState) {
+          summary.continue[session.continueState]
+            = (summary.continue[session.continueState] ?? 0) + 1;
+        }
+        return summary;
+      }, {
+        pause: {} as Record<string, number>,
+        continue: {} as Record<string, number>,
+      });
+      process.stdout.write(JSON.stringify({
+        accepted: true,
+        ...reportedWorker,
+        controllerWasRunning: status !== undefined,
+        fromVersion: finalTransaction.sourceVersion,
+        toVersion: finalTransaction.targetVersion,
+        phase: finalTransaction.phase,
+        success: finalTransaction.terminal?.success === true && followError === undefined,
+        error: finalTransaction.terminal?.error
+          ?? (followError instanceof Error ? followError.message : followError === undefined
+            ? undefined
+            : String(followError)),
+        sessions: sessionSummary,
+      }, null, 2) + '\n');
+    }
+    if (followError) throw followError;
+    if (!finalTransaction.terminal?.success) {
+      throw new Error(finalTransaction.terminal?.error ?? `${currentCliName} upgrade failed.`);
+    }
+  } catch (errorArg) {
+    invocationError = errorArg;
+  }
+  let releaseError: unknown;
+  if (!handoffStarted) {
+    try {
+      await invocationLease.release();
+    } catch (errorArg) {
+      releaseError = errorArg;
+    }
+  }
+  if (invocationError !== undefined && releaseError !== undefined) {
+    throw new AggregateError(
+      [invocationError, releaseError],
+      `The ${currentCliName} upgrade invocation failed and its ownership could not be released.`,
+    );
+  }
+  if (invocationError !== undefined) throw invocationError;
+  if (releaseError !== undefined) throw releaseError;
+};
+
+const runHiddenUpgradeWorker = async (): Promise<void> => {
+  if (activeRuntimeArguments.length !== 2 && activeRuntimeArguments.length !== 3) {
+    throw new Error(`The internal ${currentCliName} upgrade worker command requires a payload and optional recovery context.`);
+  }
+  const payload = parseUpgradeWorkerPayload(
+    activeRuntimeArguments[1],
+    process.env[upgradeTokenEnvironmentVariable],
+  );
+  if (activeRuntimeArguments.length === 2) {
+    await runUpgradeWorker(payload);
+    return;
+  }
+  const runWithRecoveryContext = runUpgradeWorker as unknown as (
+    payloadArg: typeof payload,
+    optionsArg: { recoveryContext: string },
+  ) => Promise<void>;
+  await runWithRecoveryContext(payload, { recoveryContext: activeRuntimeArguments[2] });
+};
+
+const mintTempPasswordWithoutAdmission = async (argvArg: TParsedArguments): Promise<void> => {
+  const port = readPortOption(argvArg, 'port', 'port', defaultControllerPort)!;
+  const ttlValue = readOption(argvArg, 'ttlHours', 'ttl-hours');
+  let ttlHours = 24;
+  if (ttlValue !== undefined) {
+    const normalized = typeof ttlValue === 'number' ? ttlValue : Number(ttlValue);
+    if (!Number.isFinite(normalized) || normalized <= 0 || normalized > 24) {
+      throw new Error('--ttl-hours must be a number above 0 and at most 24.');
+    }
+    ttlHours = normalized;
+  }
+  const authStore = new SmartDataAuthStore((await ensureControllerDataRoot()).databaseConfig);
+  let operationError: unknown;
+  try {
+    await authStore.init();
+    const runtimeConfig = await authStore.getRuntimeConfig(port);
+    if (!runtimeConfig) {
+      throw new Error(
+        `No controller configuration exists for port ${port}. Start the controller first, and run `
+        + 'temp-password with the same HARNESS_CONTROLLER_MONGO_URL / HARNESS_CONTROLLER_MONGO_DB '
+        + 'environment as the controller.',
+      );
+    }
+    const minted = await authStore.createTempPassword(Math.round(ttlHours * 60 * 60 * 1000));
+    await authStore.recordAuditEvent({
+      type: 'temppassword.create',
+      outcome: 'succeeded',
+      credentialId: minted.credentialId,
+    });
+    process.stdout.write([
+      `Temporary password: ${minted.password}`,
+      `Expires: ${minted.expiresAt.toISOString()}`,
+      `Sign in at ${runtimeConfig.publicOrigin} using "CLI temporary password".`,
+    ].join('\n') + '\n');
+  } catch (errorArg) {
+    operationError = errorArg;
+    throw errorArg;
+  } finally {
+    try {
+      await authStore.close();
+    } catch (cleanupErrorArg) {
+      if (operationError !== undefined) {
+        throw new AggregateError(
+          [operationError, cleanupErrorArg],
+          'Temporary password operation failed and SmartData cleanup was incomplete.',
+          { cause: operationError },
+        );
+      }
+      throw cleanupErrorArg;
+    }
+  }
+};
+
+const mintTempPassword = async (argvArg: TParsedArguments): Promise<void> => {
+  const lease = await acquireStartAdmission('temp-password');
+  try {
+    await mintTempPasswordWithoutAdmission(argvArg);
+  } finally {
+    await lease?.release();
+  }
+};
+
+export const runCli = async (testArgvArg?: string[]): Promise<void> => {
+  activeRuntimeArguments = (testArgvArg ?? process.argv).slice(2);
+  if (
+    activeRuntimeArguments.some((argumentArg) => argumentArg === '--help' || argumentArg === '-h')
+    && (
+      activeRuntimeArguments[0] === '--help'
+      || activeRuntimeArguments[0] === '-h'
+      || publicCliCommands.has(activeRuntimeArguments[0] ?? '')
+    )
+  ) {
+    process.stdout.write(helpText + '\n');
+    return;
+  }
+  const cli = new plugins.smartcli.Smartcli();
+  cli.addVersion(commitinfo.version);
+  let commandPromise: Promise<void> = Promise.resolve();
+  let commandDispatched = false;
+  const register = (commandArg: string, handlerArg: (argvArg: TParsedArguments) => Promise<void>) => {
+    cli.addCommand(commandArg).subscribe((argvArg: TParsedArguments) => {
+      commandDispatched = true;
+      commandPromise = handlerArg(argvArg);
+    });
+  };
+  register('start', startDetached);
+  register('status', showStatus);
+  register('stop', stopController);
+  register('upgrade', upgradeController);
+  register('foreground', runForegroundWithAdmission);
+  register('temp-password', mintTempPassword);
+  register('__serve', (argvArg) => runControllerProcess(argvArg, true));
+  register('__upgrade-worker', runHiddenUpgradeWorker);
+  cli.addCommand('help').subscribe(() => {
+    commandDispatched = true;
+    process.stdout.write(helpText + '\n');
+  });
+  cli.standardCommand().subscribe(() => {
+    commandDispatched = true;
+    process.stdout.write(helpText + '\n');
+  });
+  cli.startParse(testArgvArg);
+  const runtimeArguments = activeRuntimeArguments;
+  const versionOnly = runtimeArguments.length > 0
+    && runtimeArguments.every((argumentArg) => argumentArg === '-v' || argumentArg === '--version');
+  if (!commandDispatched && !versionOnly) {
+    throw new Error(`Unknown command. Run ${currentCliName} help for usage.`);
+  }
+  await commandPromise;
+};