agl 40.5.0 → 40.6.0

package/ts/classes.workercallers.ts

@@ -4,14 +4,19 @@ import {
   controllerMcpCallerCredentialEnvironmentVariable,
   type IFleetWorkerCallerHooks, type TFleetWorkerCallerLaunch, type TFleetWorkerCallerBinding,
   type IWorkerCallerReadiness, type TWorkerCallerEnrollment, type IWorkerCallerEnrollmentResponse,
-  type IConfigurationMaster, type IControllerMcpCaller, type IControllerMcpWireCaller,
+  type IConfigurationMaster, type IConfigurationMcpStdioServer, type IControllerMcpCaller, type IControllerMcpWireCaller,
+  type IWorkerClaudeJobRequest, type TWorkerClaudeJobObservation,
 } from '../ts_interfaces/index.js';
 import { anonymousControllerMcpCaller, ControllerMcpCallerRegistry } from './classes.mcpcallerregistry.js';
 import {
   resolveWorkerBridgeCommand, resolveClaudeWorkerExecutable, verifyClaudeWorkerProcess,
-  verifyWorkerBridge, workerSnapshotsEqual, WorkerCallerProofError, isWorkerCallerProofRefusal,
+  readWorkerBridge, verifyWorkerBridge, workerSnapshotsEqual, WorkerCallerProofError, isWorkerCallerProofRefusal,
   type IWorkerCallerConnection, type IWorkerProcessSnapshot, type IWorkerBridgeCommand,
 } from './functions.workerprocessproof.js';
+import {
+  workerCallerDigest, workerProcessSnapshotDigest, type IWorkerCallerBindingStore, type IWorkerCallerBindingProcess,
+  type TWorkerCallerBindingRecord,
+} from './classes.workercallerbindings.js';
 
 export interface IWorkerCodexCallerOrigin {
   parent: IWorkerProcessSnapshot;
@@ -47,24 +52,59 @@ interface IWorkerLaunch {
   leases: number;
   drained?: () => void;
   serial: Promise<unknown>;
+  /**
+   * Bridge process images a job re-proof refused, by the digest of their whole snapshot, until when: a refused bridge is
+   * not proved again at every call. A bridge re-executes itself in place onto an upgraded build (same PID and start,
+   * another image), and the image it became is proved afresh.
+   */
+  refusals: Map<string, number>;
+  /** The pending reasons already logged for this launch. */
+  logged: Set<string>;
+  /**
+   * Whether this controller proved the binding: false for a launch restored from its kept binding until a fresh
+   * inventory shows its job still belongs to the worker, so a launch of an archived or moved worker is never taken over.
+   */
+  verified: boolean;
 }
 
+/**
+ * The outcome of a job re-proof: the launch is bound to the bridge's process, the bridge is refused (or was refused
+ * before and is not proved again yet), or the job ended for the worker.
+ */
+type TReproof = { kind: 'rebound' } | { kind: 'refused'; reason: string } | { kind: 'remembered' } | { kind: 'ended'; reason: string };
+
 export interface IControllerWorkerCallerOptions {
   controllerGeneration: string;
   registry: ControllerMcpCallerRegistry;
   readMaster(): Promise<IConfigurationMaster>;
   captureCodexOrigin(launch: Extract<TFleetWorkerCallerLaunch, { harnessId: 'codex' }>): Promise<IWorkerCodexCallerOrigin>;
   processProof?: IWorkerCallerProcessProof;
+  /** Keeps the bindings of fleet Claude launches, so a restarted controller proves their bridges again; absent keeps them in memory. */
+  bindings?: IWorkerCallerBindingStore;
+  /**
+   * A fresh read of the Claude background job a launch is bound to, from the fleet's own inventory, one read at a time.
+   * Without it a bridge of a process that replaced the bound one stays pending.
+   */
+  observeClaudeJob?(request: IWorkerClaudeJobRequest): Promise<TWorkerClaudeJobObservation>;
+  /** Where the reason a worker enrollment stays pending is written once; the controller log by default. */
+  log?(line: string): void;
 }
 
 export interface IWorkerCallerProcessProof {
   resolveCommand: typeof resolveWorkerBridgeCommand;
   resolveClaude: typeof resolveClaudeWorkerExecutable;
   verifyClaude: typeof verifyClaudeWorkerProcess;
+  readBridge: typeof readWorkerBridge;
   verifyBridge: typeof verifyWorkerBridge;
 }
 
 const pending = (): IWorkerCallerEnrollmentResponse => ({ callerPending: true, bindingRevision: 0 });
+/** How long a bridge refused for a reason that may pass (an unread inventory, a job not yet in its process) waits before its next proof. */
+const transientRefusalMs = 5_000;
+const maximumRefusals = 64;
+const maximumLoggedReasons = 4096;
+const proofReason = (errorArg: unknown): string => errorArg instanceof WorkerCallerProofError
+  ? errorArg.message : `a process could not be read (${(errorArg as NodeJS.ErrnoException).code ?? 'unknown'})`;
 const assertIdentifier = (valueArg: string): void => {
   if (typeof valueArg !== 'string' || !/^[A-Za-z0-9_.:-]{1,256}$/u.test(valueArg)) throw new Error('Invalid worker launch identifier.');
 };
@@ -73,41 +113,51 @@ export class ControllerWorkerCallers implements IFleetWorkerCallerHooks {
   private readonly launches = new Map<string, IWorkerLaunch>();
   private readonly sessions = new Map<string, IWorkerLaunch>();
   private readonly challenges = new Map<string, IWorkerLaunch>();
+  /** Each worker's current launch, prepared by this controller or kept from before its restart. */
+  private readonly workers = new Map<string, IWorkerLaunch>();
+  /** Per worker, the chain its kept binding's writes, deletion and restoration run on, one at a time. */
+  private readonly workerTails = new Map<string, Promise<unknown>>();
+  /** Pending reasons logged for launches this controller does not hold, by launch digest and reason. */
+  private readonly loggedUnknown = new Set<string>();
   private closed = false;
   private readonly proof: IWorkerCallerProcessProof;
+  private readonly log: (lineArg: string) => void;
 
   constructor(private readonly options: IControllerWorkerCallerOptions) {
-    this.proof = options.processProof ?? { resolveCommand: resolveWorkerBridgeCommand,
-      resolveClaude: resolveClaudeWorkerExecutable, verifyClaude: verifyClaudeWorkerProcess, verifyBridge: verifyWorkerBridge };
+    this.proof = options.processProof ?? { resolveCommand: resolveWorkerBridgeCommand, resolveClaude: resolveClaudeWorkerExecutable,
+      verifyClaude: verifyClaudeWorkerProcess, readBridge: readWorkerBridge, verifyBridge: verifyWorkerBridge };
+    this.log = options.log ?? ((lineArg) => console.warn(lineArg));
   }
 
   public async prepareWorkerCaller(launchArg: TFleetWorkerCallerLaunch): ReturnType<IFleetWorkerCallerHooks['prepareWorkerCaller']> {
     assertIdentifier(launchArg.launchId);
     assertIdentifier(launchArg.projectId);
+    if (typeof launchArg.workerId !== 'string' || launchArg.workerId.length > 1024 || !launchArg.workerId.startsWith(`${launchArg.projectId}:`)) {
+      throw new Error('Invalid worker launch identifier.');
+    }
+    const refusable = () => this.closed || this.launches.has(launchArg.launchId) || !['claude', 'codex'].includes(launchArg.harnessId);
+    if (refusable()) throw new Error('Worker launch cannot be prepared.');
+    // A worker holds one current launch; one kept from before a restart gives way like any other.
+    const previous = this.workers.get(launchArg.workerId);
+    if (previous && previous.state !== 'revoked') await this.revokeWorkerCaller({ launchId: previous.launch.launchId, reason: 'replacement' });
     // A revoked launch stays as a tombstone so its id is never prepared again; the oldest give way to new launches.
     for (const [launchId, record] of this.launches) {
       if (this.launches.size < 65536) break;
       if (record.state === 'revoked' && launchId !== launchArg.launchId) this.launches.delete(launchId);
     }
-    if (this.closed || this.launches.has(launchArg.launchId) || this.launches.size >= 65536
-      || !['claude', 'codex'].includes(launchArg.harnessId)) throw new Error('Worker launch cannot be prepared.');
+    if (refusable() || this.launches.size >= 65536) throw new Error('Worker launch cannot be prepared.');
     const record: IWorkerLaunch = { launch: structuredClone(launchArg), generation: plugins.crypto.randomBytes(24).toString('base64url'),
-      state: 'prepared', revision: 0, credentials: new Map(), leases: 0, serial: Promise.resolve() };
+      state: 'prepared', revision: 0, credentials: new Map(), leases: 0, serial: Promise.resolve(), refusals: new Map(), logged: new Set(), verified: true };
     this.launches.set(launchArg.launchId, record);
+    this.workers.set(launchArg.workerId, record);
     try {
-      const master = await this.options.readMaster();
-      const servers = master.mcpServers.filter(server => server.name === 'agl'
-        && (!server.targets || server.targets.includes(launchArg.harnessId)));
-      if (servers.length !== 1 || servers[0].transport !== 'stdio'
-        || Object.keys(servers[0].envFrom).length > 0
-        || Object.hasOwn(servers[0].env, controllerMcpCallerCredentialEnvironmentVariable)) {
-        throw new Error('The Configuration master must define one non-secret stdio agl server for this harness.');
-      }
-      const server = servers[0];
+      const server = await this.approvedServer(launchArg.harnessId);
       record.command = await this.proof.resolveCommand(server);
       if (launchArg.harnessId === 'claude') record.claudeExecutable = await this.proof.resolveClaude();
       else record.codex = await this.options.captureCodexOrigin(launchArg);
       this.requireState(record, 'prepared');
+      await this.keep(record, 0);
+      this.requireState(record, 'prepared');
       return { launchGeneration: record.generation, bindingRevision: 0, callerPending: true,
         ...(launchArg.harnessId === 'claude' ? { claudeMcpConfig: { mcpServers: { agl: {
           ...structuredClone(server.native?.claude ?? {}), type: 'stdio', command: server.command, args: [...server.args],
@@ -126,42 +176,7 @@ export class ControllerWorkerCallers implements IFleetWorkerCallerHooks {
   public async bindWorkerCaller(bindingArg: TFleetWorkerCallerBinding): ReturnType<IFleetWorkerCallerHooks['bindWorkerCaller']> {
     const record = this.launches.get(bindingArg.launchId);
     if (!record) throw new Error('The worker launch is unavailable.');
-    await this.serialize(record, async () => {
-      if (this.closed || !['prepared', 'bound'].includes(record.state)
-        || bindingArg.projectId !== record.launch.projectId || bindingArg.harnessId !== record.launch.harnessId
-        || bindingArg.expectedBindingRevision !== record.revision || !record.command
-        || (record.binding && bindingArg.nativeSessionId !== record.binding.nativeSessionId)
-        || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(bindingArg.nativeSessionId)) {
-        throw new Error('The worker binding is stale or inconsistent.');
-      }
-      const ticketSessionId = `${bindingArg.harnessId}:${bindingArg.nativeSessionId}`;
-      const existing = this.sessions.get(ticketSessionId);
-      if (existing && existing !== record) throw new Error('The native worker session already belongs to another launch.');
-      let parent: IWorkerProcessSnapshot;
-      if (bindingArg.harnessId === 'claude') {
-        parent = await this.proof.verifyClaude(bindingArg.claudeProcess, record.claudeExecutable!);
-        if (record.binding?.harnessId === 'claude' && record.binding.claudeProcess.jobId !== bindingArg.claudeProcess.jobId) {
-          throw new Error('A worker binding cannot change its native job.');
-        }
-      } else {
-        if (!record.codex || !await record.codex.isCurrent()) throw new Error('The Codex launch origin is no longer current.');
-        parent = record.codex.parent;
-      }
-      if (this.closed || record.state === 'revoked' || record.state === 'quiescing') throw new Error('The worker launch was revoked.');
-      const other = this.sessions.get(ticketSessionId);
-      if (other && other !== record) throw new Error('The native worker session already belongs to another launch.');
-      this.sessions.set(ticketSessionId, record);
-      record.state = 'quiescing';
-      this.clearCredentials(record);
-      this.clearChallenge(record);
-      await this.drain(record);
-      this.requireState(record, 'quiescing');
-      record.binding = structuredClone(bindingArg);
-      record.parent = parent;
-      record.ticketSessionId = ticketSessionId;
-      record.revision += 1;
-      record.state = 'bound';
-    });
+    await this.serialize(record, () => this.bind(record, bindingArg));
     if (bindingArg.harnessId === 'codex') {
       try { await this.challenge(record); } catch (errorArg) {
         if (record.revision === bindingArg.expectedBindingRevision + 1) {
@@ -183,21 +198,35 @@ export class ControllerWorkerCallers implements IFleetWorkerCallerHooks {
   }
 
   public async revokeWorkerCaller(requestArg: Parameters<IFleetWorkerCallerHooks['revokeWorkerCaller']>[0]): Promise<void> {
+    const forGood = requestArg.reason !== 'generation_change';
+    if ('workerId' in requestArg) {
+      const workerId = requestArg.workerId;
+      // Marked revoked and deleted in one step of the worker's chain, so no restoration or bind of it can follow.
+      const current = await this.withWorker(workerId, async () => {
+        const record = this.workers.get(workerId);
+        if (record) this.markRevoked(record);
+        if (forGood) await this.options.bindings?.delete(workerId);
+        return record;
+      });
+      if (current) await this.settleRevocation(current);
+      return;
+    }
     const record = this.launches.get(requestArg.launchId);
     if (!record) return;
-    record.state = 'revoked';
-    this.clearChallenge(record);
-    this.clearCredentials(record);
-    await this.drain(record);
-    await record.serial.catch(() => undefined);
-    if (record.ticketSessionId && this.sessions.get(record.ticketSessionId) === record) this.sessions.delete(record.ticketSessionId);
+    this.markRevoked(record);
+    await this.settleRevocation(record);
+    const bindings = this.options.bindings;
+    if (forGood && bindings && record.launch.harnessId === 'claude') {
+      await this.withWorker(record.launch.workerId, () => bindings.delete(record.launch.workerId, workerCallerDigest(record.launch.launchId)));
+    }
   }
 
   public async enroll(requestArg: TWorkerCallerEnrollment, connectionArg?: IWorkerCallerConnection): Promise<IWorkerCallerEnrollmentResponse> {
     let record: IWorkerLaunch | undefined;
     if ('launchId' in requestArg) {
-      record = this.launches.get(requestArg.launchId);
+      record = this.launches.get(requestArg.launchId) ?? await this.restore(requestArg);
       if (!record || record.launch.harnessId !== 'claude' || record.generation !== requestArg.launchGeneration) return pending();
+      return this.enrollClaude(record, requestArg.bridgePid, connectionArg);
     } else if ('challenge' in requestArg) {
       record = this.challenges.get(requestArg.challenge);
       if (!record || record.binding?.nativeSessionId !== requestArg.nativeThreadId || record.launch.harnessId !== 'codex') return pending();
@@ -252,6 +281,328 @@ export class ControllerWorkerCallers implements IFleetWorkerCallerHooks {
     await Promise.all([...this.launches.keys()].map(launchId => this.revokeWorkerCaller({ launchId, reason: 'generation_change' })));
   }
 
+  /**
+   * Binds `recordArg` to `bindingArg`, inside its serial chain: a Claude launch to its background job and, when it has
+   * one, the job's process; a Codex launch to its thread on the proved origin. The kept binding is written first.
+   */
+  private async bind(record: IWorkerLaunch, bindingArg: TFleetWorkerCallerBinding, commandArg?: IWorkerBridgeCommand): Promise<void> {
+    if (this.closed || !['prepared', 'bound'].includes(record.state)
+      || bindingArg.projectId !== record.launch.projectId || bindingArg.harnessId !== record.launch.harnessId
+      || bindingArg.expectedBindingRevision !== record.revision || !record.command
+      || (record.binding && bindingArg.nativeSessionId !== record.binding.nativeSessionId)
+      || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(bindingArg.nativeSessionId)
+      || (bindingArg.harnessId === 'claude' && (typeof bindingArg.claudeJobId !== 'string' || !bindingArg.claudeJobId
+        || (bindingArg.claudeProcess && bindingArg.claudeProcess.jobId !== bindingArg.claudeJobId)))) {
+      throw new Error('The worker binding is stale or inconsistent.');
+    }
+    const ticketSessionId = `${bindingArg.harnessId}:${bindingArg.nativeSessionId}`;
+    const existing = this.sessions.get(ticketSessionId);
+    if (existing && existing !== record) throw new Error('The native worker session already belongs to another launch.');
+    let parent: IWorkerProcessSnapshot | undefined;
+    if (bindingArg.harnessId === 'claude') {
+      if (record.binding?.harnessId === 'claude' && record.binding.claudeJobId !== bindingArg.claudeJobId) {
+        throw new Error('A worker binding cannot change its native job.');
+      }
+      // A job whose process already exited binds without one; the job's next process proves itself as its bridge enrolls.
+      parent = bindingArg.claudeProcess ? await this.proof.verifyClaude(bindingArg.claudeProcess, record.claudeExecutable!) : undefined;
+    } else {
+      if (!record.codex || !await record.codex.isCurrent()) throw new Error('The Codex launch origin is no longer current.');
+      parent = record.codex.parent;
+    }
+    if (this.closed || record.state === 'revoked' || record.state === 'quiescing') throw new Error('The worker launch was revoked.');
+    const other = this.sessions.get(ticketSessionId);
+    if (other && other !== record) throw new Error('The native worker session already belongs to another launch.');
+    if (bindingArg.harnessId === 'claude') {
+      await this.keep(record, record.revision + 1, { nativeSessionId: bindingArg.nativeSessionId, jobId: bindingArg.claudeJobId,
+        ...(parent ? { process: { pid: parent.pid, startTicks: parent.startTicks, snapshotDigest: workerProcessSnapshotDigest(parent) } } : {}) },
+      commandArg);
+      if (this.closed || record.state !== 'prepared' && record.state !== 'bound') throw new Error('The worker launch was revoked.');
+    }
+    this.sessions.set(ticketSessionId, record);
+    record.state = 'quiescing';
+    this.clearCredentials(record);
+    this.clearChallenge(record);
+    await this.drain(record);
+    this.requireState(record, 'quiescing');
+    record.binding = structuredClone(bindingArg);
+    record.parent = parent;
+    if (commandArg) record.command = structuredClone(commandArg);
+    record.ticketSessionId = ticketSessionId;
+    record.revision += 1;
+    record.state = 'bound';
+    record.verified = true;
+  }
+
+  /**
+   * Enrolls the bridge of a Claude launch: against the process the launch is bound to, or, when that process is gone or
+   * replaced, after the fleet proved the bridge's process to be the next process of the same job.
+   */
+  private async enrollClaude(recordArg: IWorkerLaunch, bridgePidArg: number, connectionArg?: IWorkerCallerConnection): Promise<IWorkerCallerEnrollmentResponse> {
+    if (recordArg.state === 'bound' && recordArg.parent && recordArg.verified) {
+      try {
+        const response = await this.enrollCredential(recordArg, bridgePidArg, connectionArg);
+        if (!response.callerPending) return response;
+      } catch (errorArg) {
+        if (!isWorkerCallerProofRefusal(errorArg)) throw errorArg;
+      }
+    }
+    if (recordArg.state !== 'bound') {
+      this.logPending(recordArg, recordArg.state === 'revoked' ? 'its launch was revoked' : 'its launch is not bound to a Claude job yet');
+      return pending();
+    }
+    const outcome = await this.reprove(recordArg, bridgePidArg, connectionArg);
+    if (outcome.kind === 'ended') {
+      this.logPending(recordArg, `${outcome.reason}; its launch is revoked`);
+      await this.revokeWorkerCaller({ launchId: recordArg.launch.launchId, reason: 'failure' });
+      return pending();
+    }
+    if (outcome.kind === 'refused' || outcome.kind === 'remembered') {
+      if (outcome.kind === 'refused') this.logPending(recordArg, outcome.reason);
+      return pending();
+    }
+    try {
+      return await this.enrollCredential(recordArg, bridgePidArg, connectionArg);
+    } catch (errorArg) {
+      if (!isWorkerCallerProofRefusal(errorArg)) throw errorArg;
+      this.logPending(recordArg, proofReason(errorArg));
+      return pending();
+    }
+  }
+
+  /**
+   * Proves the bridge's process to be the current process of the job the launch is bound to, from a fresh inventory the
+   * fleet reads, and binds the launch to it at the current revision. A bridge refused for good is remembered for its
+   * process's life, one refused for a reason that may pass for a short while; neither is proved again at every call.
+   */
+  private async reprove(recordArg: IWorkerLaunch, bridgePidArg: number, connectionArg?: IWorkerCallerConnection): Promise<TReproof> {
+    const observe = this.options.observeClaudeJob;
+    if (!observe) return { kind: 'refused', reason: 'the process its launch is bound to is gone, and no fleet proves the job\'s next process' };
+    let bridge: IWorkerProcessSnapshot, command = recordArg.command!;
+    try { bridge = await this.proof.readBridge(connectionArg, bridgePidArg, command); } catch (errorArg) {
+      if (!isWorkerCallerProofRefusal(errorArg)) throw errorArg;
+      // An upgrade re-executes a bridge in place onto the build the controller runs now: it runs the command this
+      // controller resolves from its own configured `agl` entry, never one the bridge names.
+      let current: IWorkerBridgeCommand;
+      try { current = await this.currentCommand(); } catch (resolveArg) {
+        return { kind: 'refused', reason: `${proofReason(errorArg)} (the approved bridge command cannot be resolved now: ${resolveArg instanceof Error ? resolveArg.message : 'unknown failure'})` };
+      }
+      if (plugins.util.isDeepStrictEqual(current, command)) return { kind: 'refused', reason: proofReason(errorArg) };
+      try { bridge = await this.proof.readBridge(connectionArg, bridgePidArg, current); } catch (currentArg) {
+        if (!isWorkerCallerProofRefusal(currentArg)) throw currentArg;
+        return { kind: 'refused', reason: proofReason(errorArg) };
+      }
+      command = current;
+    }
+    const key = workerProcessSnapshotDigest(bridge);
+    if ((recordArg.refusals.get(key) ?? 0) > Date.now()) return { kind: 'remembered' };
+    return this.serialize(recordArg, async (): Promise<TReproof> => {
+      const record = recordArg, binding = record.binding;
+      if (this.closed || record.state !== 'bound' || binding?.harnessId !== 'claude' || !record.command) {
+        return { kind: 'refused', reason: 'its launch is no longer bound' };
+      }
+      // Read in the serial chain: an enrollment that ran before may have kept the bridge's new command already.
+      const sameCommand = plugins.util.isDeepStrictEqual(command, record.command);
+      // An enrollment that waited here finds the launch bound to this bridge's process already.
+      if (sameCommand && record.verified && record.parent && record.parent.pid === bridge.parentPid
+        && await this.processStands(record, record.parent)) return { kind: 'rebound' };
+      const refuse = (reasonArg: string, forGoodArg: boolean): TReproof => {
+        if (record.refusals.size >= maximumRefusals) record.refusals.delete(record.refusals.keys().next().value!);
+        record.refusals.set(key, forGoodArg ? Number.POSITIVE_INFINITY : Date.now() + transientRefusalMs);
+        return { kind: 'refused', reason: reasonArg };
+      };
+      const observed = await observe({ workerId: record.launch.workerId, projectId: record.launch.projectId,
+        nativeSessionId: binding.nativeSessionId, jobId: binding.claudeJobId });
+      if (observed.state === 'ended') return { kind: 'ended', reason: observed.reason };
+      if (observed.state === 'unproven') return refuse(observed.reason, false);
+      if (observed.state === 'settled') return refuse('its Claude job lists no running process', false);
+      if (this.closed || record.state !== 'bound') return { kind: 'refused', reason: 'its launch is no longer bound' };
+      if (observed.process.jobId !== binding.claudeJobId) return { kind: 'ended', reason: 'its session continues as another Claude job' };
+      // The inventory can still list the process Claude Code just replaced, so this refusal may pass.
+      if (observed.process.pid !== bridge.parentPid) return refuse('its bridge does not run under the process of its Claude job', false);
+      // A restored launch whose kept process is still the job's: the inventory confirmed it, and nothing is bound again.
+      if (sameCommand && record.parent && record.parent.pid === observed.process.pid && record.parent.startTicks === observed.process.startTicks
+        && await this.processStands(record, record.parent)) {
+        record.verified = true;
+        return { kind: 'rebound' };
+      }
+      let executable: string, parent: IWorkerProcessSnapshot;
+      try { executable = await this.proof.resolveClaude(); } catch {
+        return refuse('the approved Claude Code executable cannot be resolved', false);
+      }
+      try { parent = await this.proof.verifyClaude(observed.process, executable); } catch (errorArg) {
+        if (!isWorkerCallerProofRefusal(errorArg)) throw errorArg;
+        return refuse('the process of its Claude job is not the approved Claude Code executable', false);
+      }
+      try { await this.proof.verifyBridge(connectionArg, bridge.pid, command, parent); } catch (errorArg) {
+        if (!isWorkerCallerProofRefusal(errorArg)) throw errorArg;
+        return refuse('its bridge is not proved to be a direct child of the process of its Claude job', true);
+      }
+      record.claudeExecutable = executable;
+      try {
+        await this.bind(record, { launchId: record.launch.launchId, projectId: record.launch.projectId, harnessId: 'claude',
+          nativeSessionId: binding.nativeSessionId, expectedBindingRevision: record.revision, claudeJobId: binding.claudeJobId,
+          claudeProcess: observed.process }, sameCommand ? undefined : command);
+      } catch (errorArg) {
+        // Revoked while it was proved: the revocation wins.
+        if (this.revoked(record)) return { kind: 'refused', reason: 'its launch was revoked' };
+        throw errorArg;
+      }
+      return { kind: 'rebound' };
+    });
+  }
+
+  /** Whether the Claude process `processArg` the launch was proved against still runs, unchanged. */
+  private async processStands(recordArg: IWorkerLaunch, processArg: IWorkerProcessSnapshot): Promise<boolean> {
+    if (recordArg.binding?.harnessId !== 'claude' || !recordArg.claudeExecutable) return false;
+    try {
+      return workerSnapshotsEqual(processArg, await this.proof.verifyClaude({ jobId: recordArg.binding.claudeJobId,
+        pid: processArg.pid, startTicks: processArg.startTicks }, recordArg.claudeExecutable));
+    } catch (errorArg) {
+      if (isWorkerCallerProofRefusal(errorArg)) return false;
+      throw errorArg;
+    }
+  }
+
+  /**
+   * The launch a restarted controller kept for a bridge that presents it, as it was bound: found by its id's digest,
+   * checked against its generation's, and only while it is still its worker's current launch. It is restored
+   * unverified: its bridge enrolls only after a fresh inventory shows the job still the worker's, in the kept process
+   * when that still runs unchanged, or in the bridge's process, which then proves itself as the job's next process.
+   */
+  private async restore(requestArg: { launchId: string; launchGeneration: string }): Promise<IWorkerLaunch | undefined> {
+    const store = this.options.bindings;
+    if (!store || this.closed) return undefined;
+    const launchDigest = workerCallerDigest(requestArg.launchId);
+    const found = await store.find(launchDigest);
+    const refusal = !found ? 'its launch is not the current launch of a fleet worker'
+      : found.generationDigest !== workerCallerDigest(requestArg.launchGeneration) ? 'its launch generation does not match'
+      : !found.binding ? 'its launch was never bound to a Claude job' : undefined;
+    if (!found || refusal) {
+      this.logUnknown(launchDigest, refusal!);
+      return undefined;
+    }
+    return this.withWorker(found.id, async () => {
+      const kept = await store.find(launchDigest);
+      if (!kept?.binding || kept.id !== found.id || kept.generationDigest !== found.generationDigest) {
+        this.logUnknown(launchDigest, 'its worker holds another launch now');
+        return undefined;
+      }
+      const ticketSessionId = `claude:${kept.binding.nativeSessionId}`;
+      const record: IWorkerLaunch = { launch: { launchId: requestArg.launchId, projectId: kept.projectId, workerId: kept.id, harnessId: 'claude' },
+        generation: requestArg.launchGeneration, state: 'bound', revision: kept.revision, command: structuredClone(kept.command),
+        claudeExecutable: kept.claudeExecutable, binding: { launchId: requestArg.launchId, projectId: kept.projectId, harnessId: 'claude',
+          nativeSessionId: kept.binding.nativeSessionId, expectedBindingRevision: kept.revision - 1, claudeJobId: kept.binding.jobId },
+        ticketSessionId, credentials: new Map(), leases: 0, serial: Promise.resolve(), refusals: new Map(), logged: new Set(), verified: false };
+      const parent = kept.binding.process ? await this.keptProcess(record, kept.binding.process) : undefined;
+      if (parent) record.parent = parent;
+      // Decided in one step after the last await: a launch prepared or restored meanwhile wins.
+      const held = this.launches.get(requestArg.launchId);
+      if (held) return held;
+      const current = this.workers.get(kept.id), other = this.sessions.get(ticketSessionId);
+      if (this.closed || current && current.state !== 'revoked' || this.launches.size >= 65536) {
+        this.logUnknown(launchDigest, 'its worker holds another launch now');
+        return undefined;
+      }
+      if (other && other.state !== 'revoked') {
+        this.logUnknown(launchDigest, 'its session belongs to another launch');
+        return undefined;
+      }
+      this.launches.set(requestArg.launchId, record);
+      this.workers.set(kept.id, record);
+      this.sessions.set(ticketSessionId, record);
+      return record;
+    });
+  }
+
+  /** The kept process of a restored launch while it still runs as it was proved: the same PID, start and snapshot. */
+  private async keptProcess(recordArg: IWorkerLaunch, processArg: IWorkerCallerBindingProcess): Promise<IWorkerProcessSnapshot | undefined> {
+    if (recordArg.binding?.harnessId !== 'claude') return undefined;
+    try {
+      const snapshot = await this.proof.verifyClaude({ jobId: recordArg.binding.claudeJobId, pid: processArg.pid, startTicks: processArg.startTicks },
+        recordArg.claudeExecutable!);
+      return workerProcessSnapshotDigest(snapshot) === processArg.snapshotDigest ? snapshot : undefined;
+    } catch (errorArg) {
+      if (isWorkerCallerProofRefusal(errorArg)) return undefined;
+      throw errorArg;
+    }
+  }
+
+  /** Keeps the binding of a Claude launch at `revisionArg`: prepared, or bound to `bindingArg`. Refused once the launch is revoked. */
+  private async keep(recordArg: IWorkerLaunch, revisionArg: number, bindingArg?: TWorkerCallerBindingRecord['binding'],
+    commandArg: IWorkerBridgeCommand = recordArg.command!): Promise<void> {
+    const store = this.options.bindings;
+    if (!store || recordArg.launch.harnessId !== 'claude') return;
+    await this.withWorker(recordArg.launch.workerId, async () => {
+      if (this.closed || recordArg.state === 'revoked') throw new Error('The worker launch was revoked.');
+      await store.save({ id: recordArg.launch.workerId, projectId: recordArg.launch.projectId, harnessId: 'claude',
+        launchDigest: workerCallerDigest(recordArg.launch.launchId), generationDigest: workerCallerDigest(recordArg.generation),
+        command: structuredClone(commandArg), claudeExecutable: recordArg.claudeExecutable!, revision: revisionArg,
+        ...(bindingArg ? { binding: structuredClone(bindingArg) } : {}) });
+    });
+  }
+
+  /** The one non-secret stdio `agl` MCP server the Configuration master defines for `harnessArg`. */
+  private async approvedServer(harnessArg: 'claude' | 'codex'): Promise<IConfigurationMcpStdioServer> {
+    const master = await this.options.readMaster();
+    const servers = master.mcpServers.filter(server => server.name === 'agl' && (!server.targets || server.targets.includes(harnessArg)));
+    const server = servers[0];
+    if (servers.length !== 1 || server?.transport !== 'stdio' || Object.keys(server.envFrom).length > 0
+      || Object.hasOwn(server.env, controllerMcpCallerCredentialEnvironmentVariable)) {
+      throw new Error('The Configuration master must define one non-secret stdio agl server for this harness.');
+    }
+    return server;
+  }
+
+  /** The bridge command this controller approves now for Claude launches, resolved from its own configured `agl` entry. */
+  private async currentCommand(): Promise<IWorkerBridgeCommand> {
+    return this.proof.resolveCommand(await this.approvedServer('claude'));
+  }
+
+  /** Runs `operationArg` on the worker's chain: kept-binding writes, deletion and restoration of one worker never interleave. */
+  private withWorker<T>(workerIdArg: string, operationArg: () => Promise<T>): Promise<T> {
+    const task = (this.workerTails.get(workerIdArg) ?? Promise.resolve()).then(operationArg);
+    const tail = task.then(() => undefined, () => undefined);
+    this.workerTails.set(workerIdArg, tail);
+    void tail.then(() => { if (this.workerTails.get(workerIdArg) === tail) this.workerTails.delete(workerIdArg); });
+    return task;
+  }
+
+  /** Whether the launch was revoked, also by this controller closing; a method, so a check after an await reads the state again. */
+  private revoked(recordArg: IWorkerLaunch): boolean {
+    return this.closed || recordArg.state === 'revoked';
+  }
+
+  private markRevoked(recordArg: IWorkerLaunch): void {
+    recordArg.state = 'revoked';
+    this.clearChallenge(recordArg);
+    this.clearCredentials(recordArg);
+  }
+
+  private async settleRevocation(recordArg: IWorkerLaunch): Promise<void> {
+    await this.drain(recordArg);
+    await recordArg.serial.catch(() => undefined);
+    if (recordArg.ticketSessionId && this.sessions.get(recordArg.ticketSessionId) === recordArg) this.sessions.delete(recordArg.ticketSessionId);
+    if (this.workers.get(recordArg.launch.workerId) === recordArg) this.workers.delete(recordArg.launch.workerId);
+  }
+
+  /** Writes once per launch and reason why its bridge's enrollment stays pending; never a credential or the launch id. */
+  private logPending(recordArg: IWorkerLaunch, reasonArg: string): void {
+    if (recordArg.logged.has(reasonArg)) return;
+    if (recordArg.logged.size >= 32) recordArg.logged.clear();
+    recordArg.logged.add(reasonArg);
+    this.log(`The MCP caller of fleet worker ${recordArg.launch.workerId}${recordArg.ticketSessionId ? ` (${recordArg.ticketSessionId})` : ''} `
+      + `stays unverified: ${reasonArg}.`);
+  }
+
+  /** As `logPending`, for a launch this controller does not hold. */
+  private logUnknown(launchDigestArg: string, reasonArg: string): void {
+    const key = `${launchDigestArg}:${reasonArg}`;
+    if (this.loggedUnknown.has(key)) return;
+    if (this.loggedUnknown.size >= maximumLoggedReasons) this.loggedUnknown.clear();
+    this.loggedUnknown.add(key);
+    this.log(`A fleet worker's MCP caller stays unverified: ${reasonArg}.`);
+  }
+
   private async enrollCredential(recordArg: IWorkerLaunch, bridgePidArg: number,
     connectionArg?: IWorkerCallerConnection, challengeArg?: string): Promise<IWorkerCallerEnrollmentResponse> {
     return this.serialize(recordArg, async () => {