agl 1.0.17 → 21.0.2

package/ts/flexharness.child.ts

@@ -0,0 +1,35 @@
+import * as plugins from './plugins.js';
+import { FlexFramedTransport } from './classes.flexframedtransport.js';
+import { FlexService } from './classes.flexservice.js';
+import {
+  type TFlexChildMessage,
+  type TFlexParentMessage,
+  parseFlexChildMessage,
+  parseFlexParentMessage,
+} from './interfaces.flexipc.js';
+
+const readable = plugins.fs.createReadStream('', { fd: 3, autoClose: false });
+const writable = plugins.fs.createWriteStream('', { fd: 4, autoClose: false });
+const transport = new FlexFramedTransport<TFlexParentMessage, TFlexChildMessage>({
+  readable,
+  writable,
+  parseIncoming: parseFlexParentMessage,
+  validateOutgoing: parseFlexChildMessage,
+});
+const service = new FlexService({ transport });
+
+let shutdownStarted = false;
+const shutdown = (): void => {
+  if (shutdownStarted) return;
+  shutdownStarted = true;
+  void service.dispose().finally(() => {
+    process.exitCode = 0;
+  });
+};
+
+process.once('SIGTERM', shutdown);
+process.once('SIGINT', shutdown);
+process.once('uncaughtException', shutdown);
+process.once('unhandledRejection', shutdown);
+
+await service.start();

package/ts/functions.canonicaldirectory.ts

@@ -0,0 +1,213 @@
+import * as plugins from './plugins.js';
+import {
+  controllerFilesystemIdentityMaximumComponents,
+  type IControllerFilesystemIdentity,
+  type IControllerFilesystemIdentityComponent,
+  type IControllerProjectFilesystemIdentity,
+  type TControllerFilesystemObjectType,
+} from './interfaces.projects.js';
+
+export class CanonicalDirectoryError extends Error {
+  constructor(messageArg: string, optionsArg?: ErrorOptions) {
+    super(messageArg, optionsArg);
+    this.name = 'CanonicalDirectoryError';
+  }
+}
+
+export interface ICanonicalDirectoryResolution extends IControllerProjectFilesystemIdentity {
+  directory: string;
+}
+
+export interface ICanonicalFilesystemObjectResolution extends IControllerFilesystemIdentity {
+  path: string;
+}
+
+export interface ICanonicalFilesystemObjectExpectation {
+  path: string;
+  targetType: TControllerFilesystemObjectType;
+  expectedIdentity: IControllerFilesystemIdentity;
+}
+
+interface ICanonicalFilesystemObjectRequest {
+  path: string;
+  targetType: TControllerFilesystemObjectType;
+}
+
+const filesystemIdentityComponent = (
+  statArg: plugins.fs.BigIntStats,
+): IControllerFilesystemIdentityComponent => ({
+  device: statArg.dev.toString(10),
+  inode: statArg.ino.toString(10),
+  type: statArg.isDirectory() ? 'directory' : 'file',
+});
+
+const pathComponents = (pathArg: string): string[] => {
+  if (
+    !plugins.path.isAbsolute(pathArg)
+    || pathArg.includes('\0')
+    || plugins.path.normalize(pathArg) !== pathArg
+  ) {
+    throw new CanonicalDirectoryError('The filesystem path is not canonical and absolute.');
+  }
+  const root = plugins.path.parse(pathArg).root;
+  const relative = pathArg.slice(root.length);
+  const components = [
+    root,
+    ...relative.split(plugins.path.sep).filter((component) => component.length > 0),
+  ];
+  if (components.length > controllerFilesystemIdentityMaximumComponents) {
+    throw new CanonicalDirectoryError('The filesystem path exceeds the identity component limit.');
+  }
+  return components;
+};
+
+const componentPaths = (pathArg: string): string[] => {
+  const components = pathComponents(pathArg);
+  const paths = [components[0]!];
+  for (const component of components.slice(1)) {
+    paths.push(plugins.path.join(paths.at(-1)!, component));
+  }
+  return paths;
+};
+
+const statComponentPath = async (
+  pathArg: string,
+  targetTypeArg: TControllerFilesystemObjectType,
+): Promise<IControllerFilesystemIdentityComponent> => {
+  const stat = await plugins.fs.promises.lstat(pathArg, { bigint: true });
+  if (stat.isSymbolicLink()) {
+    throw new CanonicalDirectoryError('The filesystem path contains a symbolic link.');
+  }
+  const type = stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : undefined;
+  if (!type || type !== targetTypeArg) {
+    throw new CanonicalDirectoryError(`The filesystem path is not a canonical ${targetTypeArg}.`);
+  }
+  return filesystemIdentityComponent(stat);
+};
+
+export const filesystemIdentitiesEqual = (
+  leftArg: IControllerFilesystemIdentity,
+  rightArg: IControllerFilesystemIdentity,
+): boolean => leftArg.ancestry.length === rightArg.ancestry.length
+  && leftArg.ancestry.every((component, index) => {
+    const other = rightArg.ancestry[index];
+    return component.device === other?.device
+      && component.inode === other.inode
+      && component.type === other.type;
+  });
+
+const resolveCanonicalFilesystemObjects = async (
+  requestsArg: readonly ICanonicalFilesystemObjectRequest[],
+): Promise<ICanonicalFilesystemObjectResolution[]> => {
+  try {
+    const requests = requestsArg.map((request) => ({
+      ...request,
+      componentPaths: componentPaths(request.path),
+    }));
+    const componentTypes = new Map<string, TControllerFilesystemObjectType>();
+    for (const request of requests) {
+      for (let index = 0; index < request.componentPaths.length; index += 1) {
+        const path = request.componentPaths[index]!;
+        const type = index === request.componentPaths.length - 1
+          ? request.targetType
+          : 'directory';
+        const existing = componentTypes.get(path);
+        if (existing && existing !== type) {
+          throw new CanonicalDirectoryError(
+            'Overlapping filesystem paths require conflicting object types.',
+          );
+        }
+        componentTypes.set(path, type);
+      }
+    }
+    const collect = async (): Promise<Map<string, IControllerFilesystemIdentityComponent>> => {
+      const identities = new Map<string, IControllerFilesystemIdentityComponent>();
+      for (const [path, type] of componentTypes) {
+        identities.set(path, await statComponentPath(path, type));
+      }
+      return identities;
+    };
+    const before = await collect();
+    const after = await collect();
+    for (const [path, beforeIdentity] of before) {
+      const afterIdentity = after.get(path)!;
+      if (!filesystemIdentitiesEqual(
+        { ancestry: [beforeIdentity] },
+        { ancestry: [afterIdentity] },
+      )) {
+        throw new CanonicalDirectoryError(
+          'The filesystem ancestry changed during identity validation.',
+        );
+      }
+    }
+    return requests.map((request) => ({
+      path: request.path,
+      ancestry: request.componentPaths.map((path) => after.get(path)!),
+    }));
+  } catch (errorArg) {
+    if (errorArg instanceof CanonicalDirectoryError) throw errorArg;
+    throw new CanonicalDirectoryError('The canonical filesystem path is unavailable.', {
+      cause: errorArg,
+    });
+  }
+};
+
+export const resolveCanonicalFilesystemObject = async (
+  pathArg: string,
+  targetTypeArg: TControllerFilesystemObjectType,
+): Promise<ICanonicalFilesystemObjectResolution> => {
+  return (await resolveCanonicalFilesystemObjects([
+    { path: pathArg, targetType: targetTypeArg },
+  ]))[0]!;
+};
+
+export const assertCanonicalFilesystemObject = async (
+  pathArg: string,
+  targetTypeArg: TControllerFilesystemObjectType,
+  expectedIdentityArg: IControllerFilesystemIdentity,
+): Promise<string> => {
+  const resolved = await resolveCanonicalFilesystemObject(pathArg, targetTypeArg);
+  if (!filesystemIdentitiesEqual(resolved, expectedIdentityArg)) {
+    throw new CanonicalDirectoryError(
+      'The filesystem ancestry no longer matches its registered identity.',
+    );
+  }
+  return resolved.path;
+};
+
+export const assertCanonicalFilesystemObjects = async (
+  expectationsArg: readonly ICanonicalFilesystemObjectExpectation[],
+): Promise<void> => {
+  try {
+    const resolved = await resolveCanonicalFilesystemObjects(expectationsArg);
+    for (let index = 0; index < expectationsArg.length; index += 1) {
+      if (!filesystemIdentitiesEqual(resolved[index]!, expectationsArg[index]!.expectedIdentity)) {
+        throw new CanonicalDirectoryError(
+          'The filesystem ancestry no longer matches its registered identity.',
+        );
+      }
+    }
+  } catch (errorArg) {
+    if (errorArg instanceof CanonicalDirectoryError) throw errorArg;
+    throw new CanonicalDirectoryError('The canonical filesystem path is unavailable.', {
+      cause: errorArg,
+    });
+  }
+};
+
+export const resolveCanonicalDirectory = async (
+  directoryArg: string,
+): Promise<ICanonicalDirectoryResolution> => {
+  const resolved = await resolveCanonicalFilesystemObject(directoryArg, 'directory');
+  return { directory: resolved.path, ancestry: resolved.ancestry };
+};
+
+export const assertCanonicalDirectory = async (
+  directoryArg: string,
+  expectedIdentityArg?: IControllerProjectFilesystemIdentity,
+): Promise<string> => {
+  if (expectedIdentityArg) {
+    return assertCanonicalFilesystemObject(directoryArg, 'directory', expectedIdentityArg);
+  }
+  return (await resolveCanonicalDirectory(directoryArg)).directory;
+};

package/ts/functions.controllerdataroot.ts

@@ -0,0 +1,107 @@
+import * as plugins from './plugins.js';
+import {
+  controllerDataRootPaths,
+  readDatabaseConfig,
+  type IControllerDataDirectoryOptions,
+} from './classes.config.js';
+import {
+  listControllerDataWriterProcessesForCliPaths,
+} from './classes.processinspection.js';
+import { embeddedDatabaseSocketPath } from './functions.embeddeddb.js';
+import {
+  ControllerDataRootMigrationRunner,
+  type IControllerDataRootMigrationResult,
+  type IControllerDataWriterProcessRecord,
+} from '../ts_migration/v2_controllerdataroot.js';
+
+export interface IEnsureControllerDataRootOptions extends IControllerDataDirectoryOptions {
+  listDataWriterProcesses?: () => Promise<readonly IControllerDataWriterProcessRecord[]>;
+  signal?: AbortSignal;
+}
+
+export const ensureControllerDataRoot = async (
+  optionsArg: IEnsureControllerDataRootOptions = {},
+): Promise<IControllerDataRootMigrationResult> => {
+  const roots = controllerDataRootPaths(optionsArg);
+  const databaseConfig = readDatabaseConfig(optionsArg);
+  if (!roots.migrationRequired) {
+    return { directoryPath: roots.targetRoot, databaseConfig };
+  }
+  const listDataWriterProcesses = optionsArg.listDataWriterProcesses ?? (async () => {
+    const cliPath = await plugins.fs.promises.realpath(
+      plugins.url.fileURLToPath(new URL('../cli.js', import.meta.url)),
+    );
+    return await listControllerDataWriterProcessesForCliPaths([cliPath], {
+      includeInstalledPackagePaths: true,
+    });
+  });
+  return await new ControllerDataRootMigrationRunner({
+    oldRoot: roots.legacyRoot,
+    newRoot: roots.targetRoot,
+    databaseConfig,
+    oldEmbeddedSocketPath: embeddedDatabaseSocketPath(
+      plugins.path.join(roots.legacyRoot, 'smartdb'),
+    ),
+    newEmbeddedSocketPath: embeddedDatabaseSocketPath(
+      plugins.path.join(roots.targetRoot, 'smartdb'),
+    ),
+    invokerPid: process.pid,
+    listDataWriterProcesses,
+    ...(optionsArg.signal ? { signal: optionsArg.signal } : {}),
+  }).run();
+};
+
+export interface IEnsureControllerDataRootForStartupOptions
+  extends IEnsureControllerDataRootOptions {
+  retainOnFailure: boolean;
+  onBlocked?: (errorArg: Error) => Promise<void>;
+  retryDelayMs?: number;
+  ensureDataRoot?: typeof ensureControllerDataRoot;
+  reportBlocked?: (errorArg: Error) => void;
+}
+
+export const ensureControllerDataRootForStartup = async (
+  optionsArg: IEnsureControllerDataRootForStartupOptions,
+): Promise<IControllerDataRootMigrationResult> => {
+  const ensureDataRoot = optionsArg.ensureDataRoot ?? ensureControllerDataRoot;
+  let lastFailureLogAt = 0;
+  while (true) {
+    try {
+      return await ensureDataRoot(optionsArg);
+    } catch (errorArg) {
+      if (!optionsArg.retainOnFailure) throw errorArg;
+      const error = errorArg instanceof Error ? errorArg : new Error(String(errorArg));
+      if (Date.now() - lastFailureLogAt >= 30_000) {
+        lastFailureLogAt = Date.now();
+        try {
+          (optionsArg.reportBlocked ?? ((reportedErrorArg) => console.error(
+            'Controller data-root migration is blocked; startup remains fail-closed.',
+            reportedErrorArg,
+          )))(error);
+        } catch (reportErrorArg) {
+          console.error('Reporting the blocked controller startup failed.', reportErrorArg);
+        }
+      }
+      try {
+        await optionsArg.onBlocked?.(error);
+      } catch (reportErrorArg) {
+        console.error('Publishing the blocked controller startup state failed.', reportErrorArg);
+      }
+      await new Promise<void>((resolve, reject) => {
+        const signal = optionsArg.signal;
+        const timeout = setTimeout(finish, optionsArg.retryDelayMs ?? 5_000);
+        const onAbort = () => finish(signal?.reason instanceof Error
+          ? signal.reason
+          : new Error('Controller startup was cancelled by shutdown.'));
+        function finish(errorArg?: Error): void {
+          clearTimeout(timeout);
+          signal?.removeEventListener('abort', onAbort);
+          if (errorArg) reject(errorArg);
+          else resolve();
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted) onAbort();
+      });
+    }
+  }
+};

package/ts/functions.embeddeddb.ts

@@ -0,0 +1,22 @@
+import * as plugins from './plugins.js';
+
+export const embeddedDatabaseSocketPath = (dataDirectoryArg: string): string => {
+  const directoryHash = plugins.crypto
+    .createHash('sha256')
+    .update(dataDirectoryArg)
+    .digest('hex')
+    .slice(0, 16);
+  return plugins.path.join(plugins.os.tmpdir(), `harness-controller-${directoryHash}.sock`);
+};
+
+export const isSocketListening = (socketPathArg: string): Promise<boolean> => new Promise((resolve) => {
+  const probe = plugins.net.createConnection({ path: socketPathArg }, () => {
+    probe.destroy();
+    resolve(true);
+  });
+  probe.on('error', () => resolve(false));
+  probe.setTimeout(500, () => {
+    probe.destroy();
+    resolve(false);
+  });
+});

package/ts/functions.flexcredentialstore.ts

@@ -0,0 +1,128 @@
+import * as plugins from './plugins.js';
+
+export interface IFlexCredentialRuntimeStore {
+  getEntry(accountArg: string): Promise<Uint8Array | null>;
+  setEntry(accountArg: string, valueArg: Uint8Array): Promise<void>;
+  deleteEntry(accountArg: string): Promise<boolean>;
+}
+
+export interface IFlexCredentialRuntimeStorePair<
+  TKernelStore extends IFlexCredentialRuntimeStore,
+  TSealedStore extends IFlexCredentialRuntimeStore,
+> {
+  kernelStore: TKernelStore;
+  sealedStore: TSealedStore;
+}
+
+interface IFlexCredentialRuntimeOperationOptions<
+  TKernelStore extends IFlexCredentialRuntimeStore,
+  TSealedStore extends IFlexCredentialRuntimeStore,
+> {
+  stores: IFlexCredentialRuntimeStorePair<TKernelStore, TSealedStore>;
+  recreateStores: (
+    storesArg: IFlexCredentialRuntimeStorePair<TKernelStore, TSealedStore>,
+  ) => Promise<IFlexCredentialRuntimeStorePair<TKernelStore, TSealedStore>>;
+}
+
+const maximumMutationAttempts = 2;
+
+const isMutationOutcomeUnknown = (errorArg: unknown): boolean => (
+  errorArg instanceof plugins.smartsecret.SmartSecretKernelStoreError
+  || errorArg instanceof plugins.smartsecret.SmartSecretSealedFileStoreError
+) && errorArg.code === 'MUTATION_OUTCOME_UNKNOWN';
+
+const bytesEqual = (leftArg: Uint8Array, rightArg: Uint8Array): boolean =>
+  leftArg.byteLength === rightArg.byteLength
+  && plugins.crypto.timingSafeEqual(leftArg, rightArg);
+
+const reconciliationError = (): Error =>
+  new Error('Flex provider credential mutation reconciliation failed.');
+
+export const writeFlexProviderCredentialEntry = async <
+  TKernelStore extends IFlexCredentialRuntimeStore,
+  TSealedStore extends IFlexCredentialRuntimeStore,
+>(
+  optionsArg: IFlexCredentialRuntimeOperationOptions<TKernelStore, TSealedStore>,
+  accountArg: string,
+  bytesArg: Uint8Array,
+): Promise<IFlexCredentialRuntimeStorePair<TKernelStore, TSealedStore>> => {
+  let stores = optionsArg.stores;
+  let previousBytes = await stores.sealedStore.getEntry(accountArg);
+  let requiresConfirmedRetry = false;
+  try {
+    for (let attempt = 0; attempt < maximumMutationAttempts; attempt += 1) {
+      let outcomeWasUnknown = false;
+      try {
+        await stores.sealedStore.setEntry(accountArg, bytesArg);
+      } catch (errorArg) {
+        if (!isMutationOutcomeUnknown(errorArg)) throw errorArg;
+        stores = await optionsArg.recreateStores(stores);
+        outcomeWasUnknown = true;
+        requiresConfirmedRetry = true;
+      }
+      const readback = await stores.sealedStore.getEntry(accountArg);
+      try {
+        if (readback && bytesEqual(readback, bytesArg)) {
+          if (!requiresConfirmedRetry || !outcomeWasUnknown) return stores;
+          previousBytes?.fill(0);
+          previousBytes = readback;
+          continue;
+        }
+        const unchanged = previousBytes
+          ? Boolean(readback && bytesEqual(readback, previousBytes))
+          : readback === null;
+        if (!outcomeWasUnknown || !unchanged || attempt === maximumMutationAttempts - 1) {
+          throw reconciliationError();
+        }
+        previousBytes?.fill(0);
+        previousBytes = readback;
+      } finally {
+        if (readback !== previousBytes) readback?.fill(0);
+      }
+    }
+    throw reconciliationError();
+  } finally {
+    previousBytes?.fill(0);
+  }
+};
+
+export const deleteFlexProviderCredentialEntry = async <
+  TKernelStore extends IFlexCredentialRuntimeStore,
+  TSealedStore extends IFlexCredentialRuntimeStore,
+>(
+  optionsArg: IFlexCredentialRuntimeOperationOptions<TKernelStore, TSealedStore>,
+  accountArg: string,
+): Promise<IFlexCredentialRuntimeStorePair<TKernelStore, TSealedStore>> => {
+  let stores = optionsArg.stores;
+  const previousBytes = await stores.sealedStore.getEntry(accountArg);
+  let requiresConfirmedRetry = false;
+  try {
+    for (let attempt = 0; attempt < maximumMutationAttempts; attempt += 1) {
+      let outcomeWasUnknown = false;
+      try {
+        await stores.sealedStore.deleteEntry(accountArg);
+      } catch (errorArg) {
+        if (!isMutationOutcomeUnknown(errorArg)) throw errorArg;
+        stores = await optionsArg.recreateStores(stores);
+        outcomeWasUnknown = true;
+        requiresConfirmedRetry = true;
+      }
+      const readback = await stores.sealedStore.getEntry(accountArg);
+      try {
+        if (!readback) {
+          if (!requiresConfirmedRetry || !outcomeWasUnknown) return stores;
+          continue;
+        }
+        const unchanged = Boolean(previousBytes && bytesEqual(readback, previousBytes));
+        if (!outcomeWasUnknown || !unchanged || attempt === maximumMutationAttempts - 1) {
+          throw reconciliationError();
+        }
+      } finally {
+        readback?.fill(0);
+      }
+    }
+    throw reconciliationError();
+  } finally {
+    previousBytes?.fill(0);
+  }
+};

package/ts/functions.opencodeauth.ts

@@ -0,0 +1,34 @@
+import * as plugins from './plugins.js';
+import type { IFlexOpenCodeOAuthAuth } from './interfaces.flexipc.js';
+
+const parseAccessTokenExpiry = (accessTokenArg: string): number => {
+  const payload = accessTokenArg.split('.')[1];
+  if (!payload || Buffer.byteLength(payload, 'utf8') > 32 * 1024) return 0;
+  try {
+    const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as unknown;
+    if (
+      !claims
+      || typeof claims !== 'object'
+      || Array.isArray(claims)
+      || !Number.isSafeInteger((claims as { exp?: unknown }).exp)
+      || Number((claims as { exp: number }).exp) < 0
+    ) return 0;
+    const expires = Number((claims as { exp: number }).exp) * 1_000;
+    return Number.isSafeInteger(expires) ? expires : 0;
+  } catch {
+    return 0;
+  }
+};
+
+export const openCodeOAuthAuthFromProviderCredential = (
+  credentialArg: plugins.smartaiProviders.IOpenAiChatGptOAuthCredential,
+): IFlexOpenCodeOAuthAuth => {
+  const auth = plugins.smartaiProviders.toOpenAiChatGptAuthCredentials(credentialArg);
+  return {
+    type: 'oauth',
+    access: credentialArg.accessToken,
+    refresh: credentialArg.refreshToken,
+    expires: parseAccessTokenExpiry(credentialArg.accessToken),
+    ...(auth.accountId ? { accountId: auth.accountId } : {}),
+  };
+};

package/ts/functions.runtimeenvironment.ts

@@ -0,0 +1,90 @@
+const controllerEnvironmentPrefix = 'HARNESS_CONTROLLER_';
+const forwardedEnvironmentVariable = 'HARNESS_CONTROLLER_FORWARD_ENV';
+const runtimeEnvironmentAllowlist = new Set([
+  'APPDATA', 'COLORTERM', 'COMSPEC', 'FORCE_COLOR', 'HOME', 'HOMEDRIVE',
+  'HOMEPATH', 'HTTP_PROXY', 'HTTPS_PROXY', 'LANG', 'LOCALAPPDATA', 'LOGNAME',
+  'NODE_EXTRA_CA_CERTS', 'NO_PROXY', 'PATH', 'PATHEXT', 'SHELL', 'SSL_CERT_DIR',
+  'SSL_CERT_FILE', 'SYSTEMROOT', 'TEMP', 'TERM', 'TMP', 'TMPDIR', 'TZ', 'USER',
+  'USERPROFILE', 'WINDIR', 'XDG_CACHE_HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME',
+  'XDG_RUNTIME_DIR', 'XDG_STATE_HOME',
+]);
+const environmentVariablePattern = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const proxyEnvironmentVariables = new Set(['HTTP_PROXY', 'HTTPS_PROXY']);
+const maxForwardedEnvironmentVariables = 64;
+const maxForwardingDirectiveBytes = 4096;
+
+const readExplicitlyForwardedEnvironmentNames = (environmentArg: NodeJS.ProcessEnv): string[] => {
+  const forwardingDirective = environmentArg[forwardedEnvironmentVariable];
+  if (!forwardingDirective) return [];
+  if (Buffer.byteLength(forwardingDirective, 'utf8') > maxForwardingDirectiveBytes) {
+    throw new Error(`${forwardedEnvironmentVariable} exceeds its size limit.`);
+  }
+  const requestedNames = forwardingDirective
+    .split(',')
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+  if (requestedNames.length > maxForwardedEnvironmentVariables) {
+    throw new Error(`${forwardedEnvironmentVariable} names too many variables.`);
+  }
+  const uniqueNames = [...new Set(requestedNames)];
+  for (const name of uniqueNames) {
+    if (!environmentVariablePattern.test(name)) {
+      throw new Error(`${forwardedEnvironmentVariable} contains an invalid variable name.`);
+    }
+    const normalizedName = name.toUpperCase();
+    if (
+      normalizedName === 'HARNESS_CONTROLLER'
+      || normalizedName.startsWith(controllerEnvironmentPrefix)
+      || normalizedName === 'OPENCODE_SERVER_USERNAME'
+      || normalizedName === 'OPENCODE_SERVER_PASSWORD'
+      || normalizedName === 'OPENCODE_AUTH_CONTENT'
+    ) {
+      throw new Error(`${forwardedEnvironmentVariable} cannot forward ${name}.`);
+    }
+  }
+  return uniqueNames;
+};
+
+const proxyValueRequiresExplicitForwarding = (valueArg: string): boolean => {
+  try {
+    const parsed = new URL(valueArg);
+    return parsed.username.length > 0 || parsed.password.length > 0;
+  } catch {
+    return true;
+  }
+};
+
+/** Environment safe to expose to controller-owned child runtimes and terminals. */
+export const createSanitizedRuntimeEnvironment = (
+  environmentArg: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv => {
+  if (Object.entries(environmentArg).some(([key, value]) => (
+    value !== undefined && key.toUpperCase() === 'OPENCODE_AUTH_CONTENT'
+  ))) {
+    throw new Error('OPENCODE_AUTH_CONTENT cannot be supplied to controller-owned runtimes.');
+  }
+  const environment: NodeJS.ProcessEnv = {};
+  const explicitlyForwardedNames = readExplicitlyForwardedEnvironmentNames(environmentArg);
+  const explicitlyForwardedNormalizedNames = new Set(
+    explicitlyForwardedNames.map((nameArg) => nameArg.toUpperCase()),
+  );
+  for (const [key, value] of Object.entries(environmentArg)) {
+    const normalizedKey = key.toUpperCase();
+    if (
+      value !== undefined
+      && (runtimeEnvironmentAllowlist.has(normalizedKey) || normalizedKey.startsWith('LC_'))
+      && (
+        !proxyEnvironmentVariables.has(normalizedKey)
+        || explicitlyForwardedNormalizedNames.has(normalizedKey)
+        || !proxyValueRequiresExplicitForwarding(value)
+      )
+    ) {
+      environment[key] = value;
+    }
+  }
+  for (const name of explicitlyForwardedNames) {
+    const value = environmentArg[name];
+    if (value !== undefined) environment[name] = value;
+  }
+  return environment;
+};