agl 22.0.1 → 22.0.2

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: 'agl',
-  version: '22.0.1',
+  version: '22.0.2',
   description: 'Agent Gateway Layer for OpenCode and FlexHarness sessions'
 }

package/ts/classes.cli.ts

@@ -39,20 +39,30 @@ import {
 } from './classes.processinspection.js';
 import {
   createUpgradeToken,
+  normalizeUpgradeRegistryUrl,
   parseUpgradeWorkerPayload,
   UpgradeCoordinator,
   upgradePackageTransitionSource,
   upgradePackageTransitionTarget,
+  upgradeTransactionTargetVersion,
   type UpgradeStartLease,
 } from './classes.upgradecoordinator.js';
 import { upgradeTokenEnvironmentVariable } from './constants.upgradeenvironment.js';
 import {
+  adoptOrphanedUpgradeUnderLock,
   createUpgradeWorkerPayload,
+  handoffLaunchedUpgradeWorkerUnderLock,
+  handoffStalledUpgradeRecoveryUnderLock,
+  type IUpgradeWorkerLaunchCandidate,
+  inspectOrphanedUpgradeForAdoption,
   launchDetachedUpgradeWorker,
   resolveCurrentCliPath,
   resolveCurrentPnpmGlobalInstallation,
   runUpgradeWorker,
+  terminalizeUpgradeWorkerHandoffFailure,
   tryResolveCurrentPnpmGlobalInstallation,
+  UpgradeWorkerCandidateDrainageError,
+  UpgradeWorkerHandoffError,
 } from './classes.upgradetransaction.js';
 import { followUpgradeTransaction } from './functions.upgradefollower.js';
 
@@ -64,6 +74,10 @@ const currentCliName = commitinfo.name === upgradePackageTransitionSource.packag
 const currentRuntimeName = currentCliName === upgradePackageTransitionTarget.cliName
   ? 'AGL'
   : currentCliName;
+const upgradeRegistryUsage = currentRuntimeName === 'AGL' ? ' [--registry <url>]' : '';
+const upgradeRegistryHelp = currentRuntimeName === 'AGL'
+  ? '  --registry <url>              Override pnpm\'s configured registry for this upgrade\n'
+  : '';
 
 const helpText = `
 ${currentRuntimeName === 'AGL' ? 'AGL - Agent Gateway Layer' : currentRuntimeName}
@@ -72,7 +86,7 @@ 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} upgrade [--port 4097]${upgradeRegistryUsage} [--grace-period-seconds 300] [--continue-sessions] [--json]
   ${currentCliName} foreground [options]
   ${currentCliName} temp-password [--port 4097] [--ttl-hours 24]
 
@@ -100,7 +114,7 @@ Startup options:
                                  characters; short codes weaken brute-force resistance)
 
 Upgrade options:
-  --grace-period-seconds <n>    Maximum graceful pause time (default: 300)
+${upgradeRegistryHelp}  --grace-period-seconds <n>    Maximum graceful pause time (default: 300)
   --continue-sessions           Continue sessions paused for the upgrade
 
 Temp password options:
@@ -956,46 +970,70 @@ const stopController = async (argvArg: TParsedArguments): Promise<void> => {
   process.stdout.write(`${currentRuntimeName} stopped.\n`);
 };
 
+export interface ICreateCurrentPackageUpgradeTransactionOptions {
+  token: string;
+  port: number;
+  sourceVersion: string;
+  registryUrl?: string;
+  controllerWasRunning: boolean;
+  continueSessions: boolean;
+  gracePeriodMs: number;
+}
+
 export const createCurrentPackageUpgradeTransaction = async (
   coordinatorArg: UpgradeCoordinator,
-  optionsArg: {
-    token: string;
-    port: number;
-    sourceVersion: string;
-    controllerWasRunning: boolean;
-    continueSessions: boolean;
-    gracePeriodMs: number;
-  },
+  optionsArg: ICreateCurrentPackageUpgradeTransactionOptions,
 ) => {
   if (
     commitinfo.name === upgradePackageTransitionSource.packageName
     && optionsArg.sourceVersion === upgradePackageTransitionSource.version
   ) {
+    if (optionsArg.registryUrl !== undefined) {
+      throw new Error(
+        'The legacy hcon package transition uses pnpm registry configuration and cannot retain --registry.',
+      );
+    }
     return await coordinatorArg.createPackageTransitionTransaction(optionsArg);
   }
   return await coordinatorArg.createTransaction(optionsArg);
 };
 
 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.`);
   }
   const port = readPortOption(argvArg, 'port', 'port', defaultControllerPort)!;
+  const registryValue = readStringOption(argvArg, 'registry', 'registry');
+  const registryUrl = registryValue === undefined
+    ? undefined
+    : normalizeUpgradeRegistryUrl(registryValue);
   const gracePeriodMs = readUpgradeGracePeriodMs(argvArg);
   const continueSessions = readBooleanOption(argvArg, 'continueSessions', 'continue-sessions');
   const installation = await resolveCurrentPnpmGlobalInstallation();
+  const coordinator = new UpgradeCoordinator(installation.globalRoot);
+  await coordinator.initializeExistingCanonicalState();
+  const orphaned = await inspectOrphanedUpgradeForAdoption({
+    coordinator,
+    installation,
+    port,
+    ...(registryUrl === undefined ? {} : { registryUrl }),
+  });
+  if (!orphaned) await preflightAGLHomeMigration();
   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.`,
     );
   }
-  if (!status) await ensureControllerDataRoot();
+  if (orphaned && status) {
+    throw new Error('An orphaned upgrade cannot be adopted while a controller is running.');
+  }
+  if (!status && !orphaned) await ensureControllerDataRoot();
+  const retainedTransaction = orphaned?.transaction;
   const payload = createUpgradeWorkerPayload({
     port,
-    gracePeriodMs,
-    continueSessions,
+    gracePeriodMs: retainedTransaction?.gracePeriodMs ?? gracePeriodMs,
+    continueSessions: retainedTransaction?.continueSessions ?? continueSessions,
     ...(status
       ? {
           expectedController: {
@@ -1006,88 +1044,147 @@ const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
         }
       : {}),
   });
-  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 invocationLeaseHandled = 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({
+    let worker: IUpgradeWorkerLaunchCandidate;
+    let controllerWasRunning = status !== undefined;
+    if (orphaned) {
+      const adopted = await adoptOrphanedUpgradeUnderLock({
+        coordinator,
+        lock: invocationLease,
+        token: payload.token,
+        expected: orphaned,
+        installation,
+        port,
+        ...(registryUrl === undefined ? {} : { registryUrl }),
+      });
+      controllerWasRunning = adopted.controllerWasRunning;
+      let launched: Awaited<ReturnType<typeof handoffStalledUpgradeRecoveryUnderLock>>;
+      try {
+        launched = await handoffStalledUpgradeRecoveryUnderLock({
+          coordinator,
           token: payload.token,
-          port,
-          packageName: controllerPackageName,
-          packageVersion: commitinfo.version,
-          cliPath: installation.cliPath,
-          controller: payload.expectedController!,
+          installation,
+          command: 'upgrade',
+          lock: invocationLease,
         });
-        try {
-          worker = await requestControllerUpgradeLaunch(port, payload.token);
-        } finally {
-          await coordinator.removeLaunchGrant(payload.token);
+      } finally {
+        invocationLeaseHandled = true;
+      }
+      if (!launched) throw new Error('The adopted upgrade became terminal before recovery launch.');
+      worker = launched;
+    } else {
+      const racedOrphan = await inspectOrphanedUpgradeForAdoption({
+        coordinator,
+        installation,
+        port,
+        ...(registryUrl === undefined ? {} : { registryUrl }),
+      });
+      if (racedOrphan) {
+        throw new Error('An orphaned upgrade appeared after normal upgrade preflight.');
+      }
+      await createCurrentPackageUpgradeTransaction(coordinator, {
+        token: payload.token,
+        port,
+        sourceVersion: installation.packageVersion,
+        ...(registryUrl === undefined ? {} : { registryUrl }),
+        controllerWasRunning,
+        continueSessions,
+        gracePeriodMs: payload.gracePeriodMs,
+      });
+      try {
+        if (status) {
+          await coordinator.createLaunchGrant({
+            token: payload.token,
+            port,
+            packageName: controllerPackageName,
+            packageVersion: commitinfo.version,
+            cliPath: installation.cliPath,
+            controller: payload.expectedController!,
+          });
+          try {
+            const launched = await requestControllerUpgradeLaunch(port, payload.token);
+            worker = {
+              pid: launched.workerPid,
+              cliPath: installation.cliPath,
+              logFilePath: launched.logFilePath,
+            };
+          } finally {
+            await coordinator.removeLaunchGrant(payload.token);
+          }
+        } else {
+          const launched = await launchDetachedUpgradeWorker({ installation, payload });
+          worker = launched;
+        }
+      } catch (errorArg) {
+        if (errorArg instanceof UpgradeWorkerCandidateDrainageError || status) {
+          invocationLeaseHandled = true;
+          throw errorArg instanceof UpgradeWorkerCandidateDrainageError
+            ? errorArg
+            : new UpgradeWorkerCandidateDrainageError(
+                'The controller upgrade launch failed and candidate drainage cannot be proven by the CLI.',
+                errorArg,
+              );
+        }
+        const transaction = await coordinator.readTransaction(payload.token);
+        if (transaction.worker?.logFilePath) {
+          worker = {
+            pid: transaction.worker.pid,
+            processGroupId: transaction.worker.processGroupId,
+            fingerprint: transaction.worker.fingerprint,
+            cliPath: transaction.worker.cliPath,
+            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;
         }
-      } 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;
+      try {
+        try {
+          worker = await handoffLaunchedUpgradeWorkerUnderLock({
+            coordinator,
+            token: payload.token,
+            installation,
+            command: 'upgrade',
+            lock: invocationLease,
+            candidate: worker,
+            retainLockOnFailure: true,
+          });
+        } catch (errorArg) {
+          if (!(errorArg instanceof UpgradeWorkerHandoffError)) throw errorArg;
+          await terminalizeUpgradeWorkerHandoffFailure({
+            coordinator,
+            token: payload.token,
+            error: errorArg,
+          });
+        }
+      } finally {
+        invocationLeaseHandled = true;
       }
     }
-    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}).`,
+        `Upgrade worker started (PID ${worker.pid}).`,
         `Logs: ${worker.logFilePath}`,
-        status
+        controllerWasRunning
           ? `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 {
@@ -1105,16 +1202,17 @@ const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
         tokenHash: '',
         revision: 0,
         port,
-        sourceVersion: installation.packageVersion,
-        controllerWasRunning: status !== undefined,
-        continueSessions,
+        sourceVersion: retainedTransaction?.sourceVersion ?? installation.packageVersion,
+        ...(registryUrl === undefined ? {} : { registryUrl }),
+        controllerWasRunning,
+        continueSessions: payload.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: [],
+        sessions: retainedTransaction?.sessions ?? [],
         terminal: {
           success: false,
           error: errorArg instanceof Error ? errorArg.message : String(errorArg),
@@ -1127,7 +1225,7 @@ const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
             workerPid: finalTransaction.worker.pid,
             logFilePath: finalTransaction.worker.logFilePath,
           }
-        : worker;
+        : { workerPid: worker.pid, logFilePath: worker.logFilePath };
       const sessionSummary = finalTransaction.sessions.reduce((summary, session) => {
         summary.pause[session.pauseState] = (summary.pause[session.pauseState] ?? 0) + 1;
         if (session.continueState) {
@@ -1142,9 +1240,9 @@ const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
       process.stdout.write(JSON.stringify({
         accepted: true,
         ...reportedWorker,
-        controllerWasRunning: status !== undefined,
+        controllerWasRunning,
         fromVersion: finalTransaction.sourceVersion,
-        toVersion: finalTransaction.targetVersion,
+        toVersion: upgradeTransactionTargetVersion(finalTransaction),
         phase: finalTransaction.phase,
         success: finalTransaction.terminal?.success === true && followError === undefined,
         error: finalTransaction.terminal?.error
@@ -1156,13 +1254,16 @@ const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
     }
     if (followError) throw followError;
     if (!finalTransaction.terminal?.success) {
-      throw new Error(finalTransaction.terminal?.error ?? `${currentCliName} upgrade failed.`);
+      const terminalError = new Error(
+        finalTransaction.terminal?.error ?? `${currentCliName} upgrade failed.`,
+      );
+      throw terminalError;
     }
   } catch (errorArg) {
     invocationError = errorArg;
   }
   let releaseError: unknown;
-  if (!handoffStarted) {
+  if (!invocationLeaseHandled) {
     try {
       await invocationLease.release();
     } catch (errorArg) {

package/ts/classes.controller.ts

@@ -291,6 +291,7 @@ import {
   upgradePackageTransitionTarget,
   upgradePackageTransitionTransactionVersion,
   upgradeTransactionIsStalled,
+  upgradeTransactionTargetVersion,
   type UpgradeInstallationLock,
   type IUpgradeSessionState,
   type TUpgradeTransaction,
@@ -301,6 +302,8 @@ import {
   launchDetachedUpgradeWorker,
   resolveCurrentPnpmGlobalInstallation,
   resolveInheritedUpgradeTargetInstallation,
+  terminateUpgradeWorkerCandidateUntilDrained,
+  type IDetachedUpgradeWorker,
 } from './classes.upgradetransaction.js';
 import {
   upgradeCoordinationRootEnvironmentVariable,
@@ -3368,10 +3371,12 @@ export class OpenCodeController {
           );
         }
         return this.runOperation(peer, async (signalArg) => {
+          let coordinator: UpgradeCoordinator | undefined;
+          let worker: IDetachedUpgradeWorker | undefined;
           try {
             const installation = await resolveCurrentPnpmGlobalInstallation();
             const status = this.getStatus();
-            const coordinator = this.coordinatorForUpgradeToken(
+            coordinator = this.coordinatorForUpgradeToken(
               requestArg.token,
               installation.globalRoot,
             );
@@ -3388,7 +3393,7 @@ export class OpenCodeController {
               },
             });
             const transaction = await coordinator.readTransaction(requestArg.token);
-            const worker = await launchDetachedUpgradeWorker({
+            worker = await launchDetachedUpgradeWorker({
               installation,
               payload: {
                 version: upgradeCoordinationVersion,
@@ -3415,7 +3420,18 @@ export class OpenCodeController {
               logFilePath: worker.logFilePath,
             };
           } catch (errorArg) {
-            console.error(`${currentCliName} upgrade worker launch failed:`, errorArg);
+            let reportedError: unknown = errorArg;
+            if (worker && coordinator) {
+              try {
+                await terminateUpgradeWorkerCandidateUntilDrained(coordinator, worker);
+              } catch (cleanupErrorArg) {
+                reportedError = new AggregateError(
+                  [errorArg, cleanupErrorArg],
+                  `${currentCliName} upgrade worker launch failed and its candidate did not drain.`,
+                );
+              }
+            }
+            console.error(`${currentCliName} upgrade worker launch failed:`, reportedError);
             throw new plugins.typedrequest.TypedResponseError(
               `The ${currentCliName} upgrade launch was not authorized or could not be started.`,
               { code: 'upgrade_launch_failed' },
@@ -13731,9 +13747,10 @@ export class OpenCodeController {
             || session.continueState === 'pending'
             || session.continueState === 'failed')
         ));
-        this.upgradeStatus = transaction.targetVersion ? {
+        const targetVersion = upgradeTransactionTargetVersion(transaction);
+        this.upgradeStatus = targetVersion ? {
           fromVersion: transaction.sourceVersion,
-          toVersion: transaction.targetVersion,
+          toVersion: targetVersion,
           phase: 'continuing',
         } : this.upgradeStatus;
         await coordinatorArg.mutateTransaction(tokenArg, (current) => ({
@@ -13778,9 +13795,10 @@ export class OpenCodeController {
         this.harnessOperationManager.endUpgradeBarrier(this.upgradeBarrier);
         this.upgradeBarrier = undefined;
       }
-      this.upgradeStatus = transaction.targetVersion ? {
+      const targetVersion = upgradeTransactionTargetVersion(transaction);
+      this.upgradeStatus = targetVersion ? {
         fromVersion: transaction.sourceVersion,
-        toVersion: transaction.targetVersion,
+        toVersion: targetVersion,
         phase: failed > 0 || modeArg === 'compensate' ? 'failed' : 'completed',
       } : this.upgradeStatus;
       if (this.upgradeStatus) {