agl 21.0.2 → 22.0.0

package/ts/classes.cli.ts

@@ -7,10 +7,13 @@ import {
   type IControllerStatus,
 } from '../ts_interfaces/index.js';
 import {
-  controllerDataDirectory,
   defaultControllerPort,
 } from './classes.config.js';
-import { ensureControllerDataRoot } from './functions.controllerdataroot.js';
+import { resolveAGLHomePaths } from './classes.aglhome.js';
+import {
+  ensureControllerDataRoot,
+  preflightAGLHomeMigration,
+} from './functions.controllerdataroot.js';
 import type { IControllerRuntimeOverrides } from './interfaces.config.js';
 import type {
   IControllerReadyIpcMessage,
@@ -41,8 +44,8 @@ import {
   upgradePackageTransitionSource,
   upgradePackageTransitionTarget,
   type UpgradeStartLease,
-  upgradeTokenEnvironmentVariable,
 } from './classes.upgradecoordinator.js';
+import { upgradeTokenEnvironmentVariable } from './constants.upgradeenvironment.js';
 import {
   createUpgradeWorkerPayload,
   launchDetachedUpgradeWorker,
@@ -82,13 +85,14 @@ Commands:
   temp-password  Mint a temporary browser login password (max 24 hours)
   help           Show this help
 
-First-start options:
+Startup options:
   --port <port>                 Controller port (default: 4097)
   --opencode-port <port>        Local-only OpenCode port (default: 4098)
-  --directory <path>            Fixed OpenCode workspace (default: current directory)
+  --directory <path>            Transiently register this existing directory on this start
+                                (also valid later; omitted: do not create a project)
   --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)
+                                (default: user home; explicitly typed absolute projects may
+                                be outside it; immutable after initialization)
   --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
@@ -107,11 +111,10 @@ Upgrade requirements:
   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 /
+${currentRuntimeName} owns one private AGL_HOME (default
+$XDG_CONFIG_HOME/agl, normally ~/.config/agl; repository checkouts use
+./.nogit/agl). The embedded database lives under $AGL_HOME/database; override
+the database 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
@@ -120,10 +123,10 @@ 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.
+--directory is transient and may be supplied on any stopped start.
+Detached starts append ${currentRuntimeName} errors to
+$AGL_HOME/logs/controller-<port>.log. Upgrade workers write a separate private
+log in $AGL_HOME/logs and print its path before work begins.
 In --json mode the path is retained before work begins and emitted at completion.
 `.trim();
 
@@ -258,17 +261,23 @@ const readPortOption = (
 
 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'),
-});
+): IControllerRuntimeOverrides => {
+  const initialProjectDirectory = readStringOption(argvArg, 'directory', 'directory');
+  const projectsRoot = readStringOption(argvArg, 'projectsRoot', 'projects-root');
+  return {
+    controllerPort: readPortOption(argvArg, 'port', 'port', defaultControllerPort)!,
+    publicOrigin: readStringOption(argvArg, 'publicOrigin', 'public-origin'),
+    rpId: readStringOption(argvArg, 'rpId', 'rp-id'),
+    initialProjectDirectory: initialProjectDirectory === undefined
+      ? undefined
+      : plugins.path.resolve(initialProjectDirectory),
+    projectsRoot: projectsRoot === undefined ? undefined : plugins.path.resolve(projectsRoot),
+    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,
@@ -341,7 +350,7 @@ const detachedLogRotateBytes = 1024 * 1024;
 class RetainedControllerStartupError extends Error {}
 
 const resolveDetachedLogFilePath = (portArg: number): string => {
-  return plugins.path.join(controllerDataDirectory(), `controller-${portArg}.log`);
+  return plugins.path.join(resolveAGLHomePaths().logs, `controller-${portArg}.log`);
 };
 
 const openDetachedLogFile = async (
@@ -397,12 +406,13 @@ const acquireStartAdmission = async (
   if (process.platform === 'win32') return undefined;
   const installation = await tryResolveCurrentPnpmGlobalInstallation();
   if (!installation) return undefined;
+  const upgradeToken = process.env[upgradeTokenEnvironmentVariable];
   const coordinator = new UpgradeCoordinator(installation.globalRoot);
   return await coordinator.acquireStartLease({
     token: createUpgradeToken(),
     cliPath: installation.cliPath,
     command: commandArg,
-    upgradeToken: process.env[upgradeTokenEnvironmentVariable],
+    upgradeToken,
   });
 };
 
@@ -410,7 +420,9 @@ const serializeRuntimeOptions = (overridesArg: IControllerRuntimeOverrides): str
   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.initialProjectDirectory !== undefined) {
+    args.push('--directory', overridesArg.initialProjectDirectory);
+  }
   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');
@@ -609,6 +621,7 @@ const startDetachedWithoutAdmission = async (argvArg: TParsedArguments): Promise
       `An ${currentRuntimeName} process is already starting or running (PID ${existingProcess.identity.pid}).`,
     );
   }
+  await ensureControllerDataRoot();
   const upgradeToken = process.env[upgradeTokenEnvironmentVariable];
   let upgradeGlobalRoot: string | undefined;
   if (upgradeToken) {
@@ -616,7 +629,8 @@ const startDetachedWithoutAdmission = async (argvArg: TParsedArguments): Promise
   }
   const logFilePath = resolveDetachedLogFilePath(overrides.controllerPort);
   const logFileHandle = await openDetachedLogFile(logFilePath);
-  let child: plugins.childProcess.ChildProcess;
+  let child: plugins.childProcess.ChildProcess | undefined;
+  let spawnError: unknown;
   try {
     const childEnvironment = { ...process.env };
     delete childEnvironment[upgradeTokenEnvironmentVariable];
@@ -624,7 +638,7 @@ const startDetachedWithoutAdmission = async (argvArg: TParsedArguments): Promise
       process.execPath,
       [cliPath, '__serve', ...serializeRuntimeOptions(overrides)],
       {
-        cwd: process.cwd(),
+        cwd: plugins.os.homedir(),
         detached: true,
         env: childEnvironment,
         shell: false,
@@ -633,10 +647,45 @@ const startDetachedWithoutAdmission = async (argvArg: TParsedArguments): Promise
         stdio: ['ignore', 'ignore', logFileHandle.fd, 'ipc'],
       },
     );
-  } finally {
+  } catch (errorArg) {
+    spawnError = errorArg;
+  }
+  let logCloseError: unknown;
+  try {
     await logFileHandle.close();
+  } catch (errorArg) {
+    try {
+      await logFileHandle.close();
+    } catch (retryErrorArg) {
+      logCloseError = new AggregateError(
+        [errorArg, retryErrorArg],
+        'The detached controller log handle could not be closed.',
+      );
+    }
   }
-  if (!child.pid) throw new Error('Detached controller did not provide a process ID.');
+  if (spawnError !== undefined || logCloseError !== undefined) {
+    const errors: unknown[] = [spawnError, logCloseError]
+      .filter((errorArg) => errorArg !== undefined);
+    if (child) {
+      try {
+        if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+        if (!await waitForSpawnedChildExit(child, 2_000)) {
+          throw new Error('The gated detached controller survived startup-handle cleanup.');
+        }
+      } catch (errorArg) {
+        errors.push(errorArg);
+      } finally {
+        if (child.connected) child.disconnect();
+        child.unref();
+      }
+    }
+    if (errors.length === 1) throw errors[0];
+    throw new AggregateError(
+      errors,
+      'Detached controller spawn or log-handle cleanup failed.',
+    );
+  }
+  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++) {
@@ -718,6 +767,7 @@ const startDetachedWithoutAdmission = async (argvArg: TParsedArguments): Promise
 };
 
 const startDetached = async (argvArg: TParsedArguments): Promise<void> => {
+  await preflightAGLHomeMigration();
   const lease = await acquireStartAdmission('start');
   try {
     await startDetachedWithoutAdmission(argvArg);
@@ -727,6 +777,7 @@ const startDetached = async (argvArg: TParsedArguments): Promise<void> => {
 };
 
 const runForegroundWithAdmission = async (argvArg: TParsedArguments): Promise<void> => {
+  await preflightAGLHomeMigration();
   const lease = await acquireStartAdmission('foreground');
   delete process.env[upgradeTokenEnvironmentVariable];
   try {
@@ -761,6 +812,9 @@ const runControllerProcess = async (
   } else {
     providedSetupCode = readProvidedSetupCode();
   }
+  if (upgradeToken !== undefined) {
+    process.env[upgradeTokenEnvironmentVariable] = upgradeToken;
+  }
   const controller = new OpenCodeController({
     processMode: detachedArg ? 'detached' : 'foreground',
     runtimeOverrides: parseRuntimeOverrides(argvArg),
@@ -923,6 +977,7 @@ export const createCurrentPackageUpgradeTransaction = async (
 };
 
 const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
+  await preflightAGLHomeMigration();
   if (process.platform !== 'linux' && process.platform !== 'darwin') {
     throw new Error(`${currentCliName} upgrade is currently supported on Linux and macOS only.`);
   }
@@ -936,6 +991,7 @@ const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
       `Port ${port} is occupied by an incompatible service or controller version; refusing to upgrade.`,
     );
   }
+  if (!status) await ensureControllerDataRoot();
   const payload = createUpgradeWorkerPayload({
     port,
     gracePeriodMs,
@@ -1196,6 +1252,7 @@ const mintTempPasswordWithoutAdmission = async (argvArg: TParsedArguments): Prom
 };
 
 const mintTempPassword = async (argvArg: TParsedArguments): Promise<void> => {
+  await preflightAGLHomeMigration();
   const lease = await acquireStartAdmission('temp-password');
   try {
     await mintTempPasswordWithoutAdmission(argvArg);
@@ -1205,6 +1262,7 @@ const mintTempPassword = async (argvArg: TParsedArguments): Promise<void> => {
 };
 
 export const runCli = async (testArgvArg?: string[]): Promise<void> => {
+  process.env.AGL_HOME = resolveAGLHomePaths().root;
   activeRuntimeArguments = (testArgvArg ?? process.argv).slice(2);
   if (
     activeRuntimeArguments.some((argumentArg) => argumentArg === '--help' || argumentArg === '-h')

package/ts/classes.config.ts

@@ -1,4 +1,8 @@
 import * as plugins from './plugins.js';
+import {
+  resolveAGLHomePaths,
+  type IAGLHomeOptions,
+} from './classes.aglhome.js';
 import type {
   IControllerDatabaseConfig,
   IControllerRuntimeConfig,
@@ -10,22 +14,7 @@ export const defaultControllerPort = 4097;
 export const defaultOpenCodePort = 4098;
 export const trustedProxySecretEnvironmentVariable = 'HARNESS_CONTROLLER_TRUSTED_PROXY_SECRET';
 
-export interface IControllerDataDirectoryOptions {
-  packageRoot?: string;
-  homeDirectory?: string;
-  environment?: NodeJS.ProcessEnv;
-}
-
-export interface IControllerDataRootPaths {
-  legacyRoot: string;
-  targetRoot: string;
-  migrationRequired: boolean;
-}
-
-const modulePackageRoot = plugins.path.resolve(
-  plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url)),
-  '..',
-);
+export interface IControllerDataDirectoryOptions extends IAGLHomeOptions {}
 
 const assertPort = (valueArg: number, nameArg: string): number => {
   if (!Number.isSafeInteger(valueArg) || valueArg < 1 || valueArg > 65535) {
@@ -105,73 +94,18 @@ const resolveDirectory = async (directoryArg: string): Promise<string> => {
   const resolved = await plugins.fs.promises.realpath(plugins.path.resolve(directoryArg));
   const stats = await plugins.fs.promises.stat(resolved);
   if (!stats.isDirectory()) {
-    throw new Error(`OpenCode workspace is not a directory: ${resolved}`);
+    throw new Error(`Configured path is not a directory: ${resolved}`);
   }
   return resolved;
 };
 
-const isDevelopmentCheckout = (packageRootArg: string): boolean => {
-  try {
-    const stats = plugins.fs.lstatSync(plugins.path.join(packageRootArg, '.git'));
-    return stats.isDirectory() || stats.isFile();
-  } catch {
-    return false;
-  }
-};
-
-const xdgRoot = (
-  environmentValueArg: string | undefined,
-  fallbackArg: string,
-): string => {
-  const candidate = environmentValueArg?.trim();
-  return candidate && plugins.path.isAbsolute(candidate) ? candidate : fallbackArg;
-};
-
-export const controllerDataRootPaths = (
-  optionsArg: IControllerDataDirectoryOptions = {},
-): IControllerDataRootPaths => {
-  const packageRoot = optionsArg.packageRoot ?? modulePackageRoot;
-  if (isDevelopmentCheckout(packageRoot)) {
-    const checkoutRoot = plugins.path.join(packageRoot, '.nogit');
-    return {
-      legacyRoot: checkoutRoot,
-      targetRoot: checkoutRoot,
-      migrationRequired: false,
-    };
-  }
-  const environment = optionsArg.environment ?? process.env;
-  const homeDirectory = optionsArg.homeDirectory ?? plugins.os.homedir();
-  const configHome = xdgRoot(
-    environment.XDG_CONFIG_HOME,
-    plugins.path.join(homeDirectory, '.config'),
-  );
-  return {
-    legacyRoot: plugins.path.join(configHome, 'harness-controller'),
-    targetRoot: plugins.path.join(configHome, 'hcon'),
-    migrationRequired: true,
-  };
-};
-
-/** Retained location for controller and upgrade logs across the A to B transition. */
 export const controllerDataDirectory = (
   optionsArg: IControllerDataDirectoryOptions = {},
-): string => controllerDataRootPaths(optionsArg).legacyRoot;
+): string => resolveAGLHomePaths(optionsArg).root;
 
 /** @deprecated Use controllerDataDirectory(). */
 export const controllerStateDirectory = controllerDataDirectory;
 
-const legacyControllerStateDirectory = (
-  optionsArg: IControllerDataDirectoryOptions,
-): string => {
-  const environment = optionsArg.environment ?? process.env;
-  const homeDirectory = optionsArg.homeDirectory ?? plugins.os.homedir();
-  const stateHome = xdgRoot(
-    environment.XDG_STATE_HOME,
-    plugins.path.join(homeDirectory, '.local', 'state'),
-  );
-  return plugins.path.join(stateHome, 'harness-controller');
-};
-
 export const readDatabaseConfig = (
   optionsArg: IControllerDataDirectoryOptions = {},
 ): IControllerDatabaseConfig => {
@@ -187,22 +121,13 @@ export const readDatabaseConfig = (
   }
   const embeddedDataDirectoryOverride = environment.HARNESS_CONTROLLER_DB_DIR?.trim();
   const embeddedDataDirectory = embeddedDataDirectoryOverride
-    || plugins.path.join(controllerDataRootPaths(optionsArg).targetRoot, 'smartdb');
+    || resolveAGLHomePaths(optionsArg).database;
   if (!plugins.path.isAbsolute(embeddedDataDirectory)) {
     throw new Error('HARNESS_CONTROLLER_DB_DIR must be an absolute path.');
   }
-  const packageRoot = optionsArg.packageRoot ?? modulePackageRoot;
   return {
     mongoDbName,
     embeddedDataDirectory,
-    ...(!embeddedDataDirectoryOverride && !isDevelopmentCheckout(packageRoot)
-      ? {
-          legacyEmbeddedDataDirectory: plugins.path.join(
-            legacyControllerStateDirectory(optionsArg),
-            'smartdb',
-          ),
-        }
-      : {}),
   };
 };
 
@@ -240,17 +165,13 @@ export const resolveInitialRuntimeConfig = async (
     throw new Error('Local public-origin port must match the controller listening port.');
   }
   const rpId = normalizeRpId(overridesArg.rpId ?? origin.hostname, origin.hostname);
-  const workspaceDirectory = await resolveDirectory(
-    overridesArg.workspaceDirectory ?? process.cwd(),
-  );
   const projectsRoot = await resolveDirectory(
-    overridesArg.projectsRoot ?? workspaceDirectory,
+    overridesArg.projectsRoot ?? plugins.os.homedir(),
   );
   return {
     controllerPort,
     publicOrigin: origin.origin,
     rpId,
-    workspaceDirectory,
     projectsRoot,
     opencodePort,
     tlsMode,
@@ -308,16 +229,6 @@ export const resolveStoredRuntimeConfig = async (
   if (overridesArg.opencodePort !== undefined && overridesArg.opencodePort !== storedArg.opencodePort) {
     throw new Error('opencodePort is immutable after controller initialization.');
   }
-  if (overridesArg.workspaceDirectory !== undefined) {
-    const requestedDirectory = await resolveDirectory(overridesArg.workspaceDirectory);
-    if (requestedDirectory !== storedArg.workspaceDirectory) {
-      throw new Error('The OpenCode workspace is immutable after controller initialization.');
-    }
-  }
-  const storedDirectory = await resolveDirectory(storedArg.workspaceDirectory);
-  if (storedDirectory !== storedArg.workspaceDirectory) {
-    throw new Error('Stored OpenCode workspace is no longer its canonical real path.');
-  }
   if (storedArg.tlsMode === 'proxy') {
     if (overridesArg.behindTlsProxy === false) {
       throw new Error('Stored TLS proxy mode is immutable.');
@@ -327,25 +238,17 @@ export const resolveStoredRuntimeConfig = async (
       throw new Error('Stored localhost mode cannot be changed to TLS mode.');
     }
   }
-  // Pre-v2 documents carry no projectsRoot: the first v2 start adopts one —
-  // from --projects-root when given, else the workspace — and it is immutable
-  // from then on like every other stored boundary.
-  let projectsRoot: string;
-  if (storedArg.projectsRoot === undefined) {
-    projectsRoot = await resolveDirectory(
-      overridesArg.projectsRoot ?? storedArg.workspaceDirectory,
-    );
-  } else {
-    projectsRoot = await resolveDirectory(storedArg.projectsRoot);
-    if (projectsRoot !== storedArg.projectsRoot) {
-      throw new Error('Stored projects root is no longer its canonical real path.');
-    }
-    if (overridesArg.projectsRoot !== undefined) {
-      const requestedProjectsRoot = await resolveDirectory(overridesArg.projectsRoot);
-      if (requestedProjectsRoot !== storedArg.projectsRoot) {
-        throw new Error('The projects root is immutable after it has been adopted.');
-      }
+  if (
+    !plugins.path.isAbsolute(storedArg.projectsRoot)
+    || plugins.path.normalize(storedArg.projectsRoot) !== storedArg.projectsRoot
+  ) {
+    throw new Error('Stored projects root is not an absolute normalized path.');
+  }
+  if (overridesArg.projectsRoot !== undefined) {
+    const requestedProjectsRoot = await resolveDirectory(overridesArg.projectsRoot);
+    if (requestedProjectsRoot !== storedArg.projectsRoot) {
+      throw new Error('The projects root is immutable after it has been adopted.');
     }
   }
-  return { ...storedArg, projectsRoot };
+  return { ...storedArg };
 };