agl 40.5.0 → 40.6.0

package/ts/fleet/classes.workerlaunches.ts

@@ -24,11 +24,14 @@ type TRevokeReason = Parameters<IFleetWorkerCallerHooks['revokeWorkerCaller']>[0
 /**
  * The verified caller launch each fleet worker's native process holds. Every native start, revival or relaunch gets a
  * fresh launch that replaces the worker's previous one, and the process proves it holds it once the fleet identified
- * the process. Launches are in memory, as the controller's caller records are: a controller restart forgets them, and
- * a Claude worker regains its identity at its next native start.
+ * the process. The controller keeps a Claude launch's binding to its background job (never a credential): a process
+ * Claude Code starts for the same job later, and a bridge that outlived a controller restart, prove themselves again
+ * when they enroll. Codex launches stay in memory and are bound again before the next dispatch.
  */
 export class FleetWorkerLaunches {
   private readonly launches = new Map<string, ILaunch>();
+  /** Workers whose launch this fleet revoked and did not prepare again: the controller holds none for them to revoke. */
+  private readonly revoked = new Set<string>();
   private readonly codexRuntimes = new Map<string, IFleetCodexCallerRuntime>();
   constructor(private readonly options: IFleetWorkerLaunchesOptions) {}
   /** The owner part of a worker id, `${owner}:${name}`: the launch's project. */
@@ -41,7 +44,9 @@ export class FleetWorkerLaunches {
     return plugins.path.join(this.options.overlays, `${plugins.crypto.createHash('sha256').update(worker.id).digest('base64url')}.json`);
   }
   private async prepare(worker: IFleetWorker, launch: TFleetWorkerCallerLaunch): Promise<Awaited<ReturnType<IFleetWorkerCallerHooks['prepareWorkerCaller']>>> {
-    await this.revoke(worker, 'replacement');
+    // The controller replaces any other launch of the worker as it prepares this one, also one it kept from before a restart.
+    if (this.launches.has(worker.id)) await this.revoke(worker, 'replacement');
+    this.revoked.delete(worker.id);
     const ready = await this.options.hooks().prepareWorkerCaller(launch);
     this.launches.set(worker.id, { launchId: launch.launchId, projectId: launch.projectId, harnessId: launch.harnessId, bound: false,
       ...(launch.harnessId === 'codex' ? { supervisorGeneration: launch.codexOrigin.supervisorGeneration } : {}) });
@@ -62,7 +67,7 @@ export class FleetWorkerLaunches {
    * this start and at every later wake. Returns the overlay's path.
    */
   public async prepareClaude(worker: IFleetWorker): Promise<string> {
-    const ready = await this.prepare(worker, { launchId: plugins.crypto.randomUUID(), projectId: this.project(worker), harnessId: 'claude' });
+    const ready = await this.prepare(worker, { launchId: plugins.crypto.randomUUID(), projectId: this.project(worker), workerId: worker.id, harnessId: 'claude' });
     try {
       if (!ready.claudeMcpConfig) throw new Error('The Claude caller launch has no MCP configuration.');
       await this.overlayDirectory();
@@ -75,18 +80,19 @@ export class FleetWorkerLaunches {
     } catch (error) { await this.revoke(worker, 'failure'); throw error; }
   }
   /**
-   * Binds the worker's Claude launch to the background job the inventory shows for `nativeId`. A job whose process
-   * already exited holds no launch to prove; its launch is revoked and its next wake prepares another.
+   * Binds the worker's Claude launch to the background job the inventory shows for `nativeId`, and to the job's process.
+   * A job whose process already exited (a quick turn) is bound without one: the process Claude Code continues the job
+   * in later proves itself when its bridge enrolls.
    */
   public async bindClaude(worker: IFleetWorker, nativeId: string, agent: { id?: string; pid?: number }): Promise<void> {
     const launch = this.launches.get(worker.id);
     if (!launch || launch.harnessId !== 'claude' || launch.bound) throw new Error('The Claude worker has no prepared caller launch.');
-    if (agent.pid === undefined) { await this.revoke(worker, 'stop'); return; }
     try {
       if (!agent.id) throw new Error('The Claude background job has no agent id.');
-      const { startTicks } = await readWorkerProcessSnapshot(agent.pid);
+      const claudeProcess = agent.pid === undefined ? undefined
+        : { jobId: agent.id, pid: agent.pid, startTicks: (await readWorkerProcessSnapshot(agent.pid)).startTicks };
       await this.options.hooks().bindWorkerCaller({ launchId: launch.launchId, projectId: launch.projectId, harnessId: 'claude', nativeSessionId: nativeId,
-        expectedBindingRevision: 0, claudeProcess: { jobId: agent.id, pid: agent.pid, startTicks } });
+        expectedBindingRevision: 0, claudeJobId: agent.id, ...(claudeProcess ? { claudeProcess } : {}) });
       launch.bound = true;
     } catch (error) { await this.revoke(worker, 'failure'); throw error; }
   }
@@ -100,7 +106,7 @@ export class FleetWorkerLaunches {
   public async prepareCodex(worker: IFleetWorker, runtime: IFleetCodexCallerRuntime): Promise<NonNullable<Awaited<ReturnType<IFleetWorkerCallerHooks['prepareWorkerCaller']>>['codexConfig']>> {
     this.codexRuntimes.set(runtime.supervisor.generation, runtime);
     for (const [generation, known] of this.codexRuntimes) if (!known.isCurrent()) this.codexRuntimes.delete(generation);
-    const ready = await this.prepare(worker, { launchId: plugins.crypto.randomUUID(), projectId: this.project(worker), harnessId: 'codex',
+    const ready = await this.prepare(worker, { launchId: plugins.crypto.randomUUID(), projectId: this.project(worker), workerId: worker.id, harnessId: 'codex',
       codexOrigin: { source: 'fleet', supervisorGeneration: runtime.supervisor.generation } });
     if (!ready.codexConfig) {
       await this.revoke(worker, 'failure');
@@ -122,12 +128,14 @@ export class FleetWorkerLaunches {
     const runtime = this.codexRuntimes.get(supervisorGeneration);
     return runtime?.isCurrent() ? runtime : undefined;
   }
-  /** Revokes the worker's launch: its process stopped, failed or was replaced. */
+  /**
+   * Revokes the worker's current launch for good: the worker stopped or is archived, its launch failed, or another
+   * replaces it. That is also a launch the controller kept from before its restart, which this fleet never prepared.
+   */
   public async revoke(worker: IFleetWorker, reason: TRevokeReason): Promise<void> {
-    const launch = this.launches.get(worker.id);
-    if (!launch) return;
-    this.launches.delete(worker.id);
-    await this.options.hooks().revokeWorkerCaller({ launchId: launch.launchId, reason });
+    if (!this.launches.delete(worker.id) && this.revoked.has(worker.id)) return;
+    await this.options.hooks().revokeWorkerCaller({ workerId: worker.id, reason });
+    this.revoked.add(worker.id);
   }
   /** Revokes the worker's launch and removes its overlay, if it has one, once the worker is archived. */
   public async retire(worker: IFleetWorker): Promise<void> {

package/ts/fleet/classes.workers.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import { controllerRuntimeIdKey } from '../../ts_interfaces/index.js';
+import { controllerRuntimeIdKey, type IWorkerClaudeJobRequest, type TWorkerClaudeJobObservation } from '../../ts_interfaces/index.js';
 import type { IFleetWorker, IFleetWorkerProfile, IFleetWorkerJob, IFleetNativeMessageReceipt, TFleetEventKind, TFleetWorkerAction, TFleetWorkerRequest, TFleetWorkerResponse, TFleetWorkerJobAction, IFleetWorkerReport, IFleetWorkerDispatchHolder } from '../../ts_interfaces/fleetworkers.js';
 import type { IFleetConfiguration, IFleetOperation, IFleetTicketSync } from '../../ts_interfaces/fleet.js';
 import type { ITicketActor } from '../../ts_interfaces/tickets.js';
@@ -14,6 +14,7 @@ import { FleetDispatchError, fleetMessageDigest, fleetReportMarker, type IFleetW
 import { assertFleetWorkerRequest, validateFleetWorkerProfiles } from './functions.workervalidation.js';
 import { readControllerProcessIdentity, controllerProcessIdentityIsLive } from '../classes.processinspection.js';
 import { ticketActorSchema } from '../functions.ticketvalidation.js';
+import { isWorkerCallerProofRefusal, readWorkerProcessSnapshot } from '../functions.workerprocessproof.js';
 
 /** A binding that stayed on `workerName` though its native session lives on `nextName` now. */
 export interface IFleetSessionBindingFailure { workerName: string; nextName: string; error: string }
@@ -80,6 +81,10 @@ export class FleetWorkers {
   private lastLoad = 0;
   private readonly controllerId = plugins.crypto.randomUUID();
   private holder?: Promise<IFleetWorkerDispatchHolder>;
+  /** The chain the caller job re-proofs read their inventories on, one at a time. */
+  private callerJobs: Promise<unknown> = Promise.resolve();
+  /** Set once the controller began to stop: no new worker job is admitted. */
+  private admissionClosed = false;
   constructor(private readonly options: IFleetWorkersOptions = {}) {
     this.store = options.store ?? new FleetWorkerStore(); this.events = options.events ?? new FleetEvents();
     this.backends = options.backends ?? { claude: new FleetClaudeWorkers(this.abort.signal, undefined, undefined, options.callers, options.claudeReleases),
@@ -298,11 +303,43 @@ export class FleetWorkers {
   public async nativeAgents(home: string | undefined, maxAgeMs: number): Promise<IFleetNativeAgent[]> {
     return await this.backends.claude.inventory?.(home, plugins.os.homedir(), maxAgeMs) ?? [];
   }
+  /**
+   * What a fresh inventory shows of the Claude background job a worker's caller launch is bound to, for the controller
+   * to prove the job's next process. One read at a time, however many bridges ask.
+   */
+  public observeCallerJob(request: IWorkerClaudeJobRequest): Promise<TWorkerClaudeJobObservation> {
+    const task = this.callerJobs.then(() => this.readCallerJob(request));
+    this.callerJobs = task.then(() => undefined, () => undefined);
+    return task;
+  }
+  private async readCallerJob(request: IWorkerClaudeJobRequest): Promise<TWorkerClaudeJobObservation> {
+    if (this.abort.signal.aborted) return { state: 'unproven', reason: 'the fleet is closing' };
+    if (!request.workerId.startsWith(`${request.projectId}:`)) return { state: 'ended', reason: 'its launch names no worker of its project' };
+    let worker: IFleetWorker | undefined;
+    try { worker = (await this.store.list(request.projectId)).find((doc) => doc.id === request.workerId)?.worker; }
+    catch (error) { return { state: 'unproven', reason: `the fleet registry could not be read (${this.error(error)})` }; }
+    if (!worker || worker.state === 'archived') return { state: 'ended', reason: `fleet worker ${request.workerId} is ${worker ? 'archived' : 'gone'}` };
+    if (worker.harness !== 'claude' || worker.nativeId !== request.nativeSessionId) return { state: 'ended', reason: 'its worker continues in another session' };
+    let agents: IFleetNativeAgent[] | undefined;
+    try { agents = await this.backends.claude.inventory?.(worker.profile.home, plugins.os.homedir(), 0); }
+    catch (error) { return { state: 'unproven', reason: `the Claude inventory could not be read (${this.error(error)})` }; }
+    const listed = (agents ?? []).filter((agent) => agent.sessionId === request.nativeSessionId);
+    if (listed.length !== 1) return { state: 'unproven', reason: `the Claude inventory lists its session ${listed.length ? 'more than once' : 'nowhere'}` };
+    const agent = listed[0]!;
+    if (agent.kind !== 'background' || agent.id !== request.jobId) return { state: 'ended', reason: 'its session continues as another Claude job' };
+    if (agent.pid === undefined) return { state: 'settled' };
+    try { return { state: 'running', process: { jobId: request.jobId, pid: agent.pid, startTicks: (await readWorkerProcessSnapshot(agent.pid)).startTicks } }; }
+    catch (error) {
+      if (!isWorkerCallerProofRefusal(error)) throw error;
+      return { state: 'unproven', reason: 'the process of its Claude job could not be read' };
+    }
+  }
   /** The newest root threads on the host's shared Codex app-server, read at most `maxAgeMs` ago. */
   public async nativeThreads(maxAgeMs: number): Promise<IFleetNativeThread[]> {
     return await this.backends.codex.threads?.(plugins.os.homedir(), maxAgeMs) ?? [];
   }
   private admitJob(): void {
+    if (this.admissionClosed || this.abort.signal.aborted) throw new Error('The fleet is closing and admits no new worker job.');
     if (this.jobs.size < 512) return;
     for (const [id, job] of this.jobs) if (['succeeded', 'failed'].includes(job.snapshot.state)) { this.jobs.delete(id); break; }
     if (this.jobs.size >= 512) throw new Error('Fleet worker job capacity reached.');
@@ -779,6 +816,19 @@ export class FleetWorkers {
       throw error;
     }
   }
+  /**
+   * Admits no new worker job and lets the running ones finish, for at most `waitMs`; the ones still running then are
+   * aborted and settle. The controller calls it before it tears down the caller hooks the jobs prepare, bind and
+   * revoke launches through, so no job meets them gone.
+   */
+  public async closeAdmission(waitMs = 10_000): Promise<void> {
+    this.admissionClosed = true;
+    const settled = Promise.allSettled([...this.jobs.values()].map((job) => job.completion));
+    let timer: NodeJS.Timeout | undefined;
+    const waited = await Promise.race([settled.then(() => true), new Promise<false>((resolve) => { timer = setTimeout(() => resolve(false), waitMs); })]);
+    if (timer) clearTimeout(timer);
+    if (!waited) { this.abort.abort(); await settled; }
+  }
   public async close(): Promise<void> {
     if (this.pollTimer) clearInterval(this.pollTimer); this.abort.abort(); this.events.close(); this.viewListeners.clear();
     await Promise.allSettled([...this.jobs.values()].map((job) => job.completion)); await Promise.allSettled([this.polling]);

package/ts/functions.inferencecli.ts

@@ -3,13 +3,13 @@ import { commitinfo } from './00_commitinfo_data.js';
 import { ensureControllerDataRoot, preflightAGLHomeMigration } from './functions.controllerdataroot.js';
 import { resolveAGLHomePaths } from './classes.aglhome.js';
 import { resolveProductionAuthoritySocketPaths } from './classes.authorityclient.js';
-import { inferenceHarnessLaunch } from './functions.inferencelaunch.js';
+import { confinedDockerLaunch, inferenceHarnessLaunch } from './functions.inferencelaunch.js';
 import type { IAglProxyStatus } from './classes.proxycontrol.js';
 import { AglProxyControlClient, AglProxyUnavailableError } from './classes.proxycontrolclient.js';
-import { AglProxyLeaseHolder } from './classes.proxyleaseholder.js';
+import { AglProxyConfinedHolder, AglProxyLeaseHolder, type AglProxyLeaseLostError } from './classes.proxyleaseholder.js';
 import { AglProxyDaemon } from './classes.proxydaemon.js';
 import { AglProxyService, resolveAglExecutable } from './classes.proxyservice.js';
-import { aglProxyUnitName } from './functions.proxycontract.js';
+import { aglProxyConfinedMountPoint, aglProxyUnitName } from './functions.proxycontract.js';
 import { inferenceCliHelp, parseInferenceCliArguments, type IInferenceCliArguments } from './functions.inferencecliarguments.js';
 import { runProxyCredentialCommand } from './functions.proxycredentialcli.js';
 import { currentProxyCredentialHelper, writeProxyCredentialHelper } from './functions.proxycredentialhelper.js';
@@ -19,11 +19,12 @@ type TAccountPlacementKey = 'lifecycle' | 'lapsesAt' | 'placementScore' | 'place
 
 /**
  * The status a running proxy answers with: one started from an AGL before 38.3.0 reports no accounts and no usage
- * observations, and one before 38.4.0 no lifecycle, placement or placement journal.
+ * observations, one before 38.4.0 no lifecycle, placement or placement journal, and one before confined runs neither
+ * its confined listener nor its runs.
  */
 export type TReportedProxyStatus = Omit<IAglProxyStatus, 'accounts' | 'usageObservations' | 'nextPlacement'
-  | 'recentPlacements'>
-  & Partial<Pick<IAglProxyStatus, 'usageObservations' | 'nextPlacement' | 'recentPlacements'>>
+  | 'recentPlacements' | 'confinedSocketPath' | 'confinedRuns'>
+  & Partial<Pick<IAglProxyStatus, 'usageObservations' | 'nextPlacement' | 'recentPlacements' | 'confinedSocketPath' | 'confinedRuns'>>
   & { accounts?: Array<Omit<IAglProxyStatus['accounts'][number], TAccountPlacementKey>
     & Partial<Pick<IAglProxyStatus['accounts'][number], TAccountPlacementKey>>> };
 
@@ -69,6 +70,14 @@ export const formatProxyStatus = (unitArg: string, statusArg: TReportedProxyStat
       + `${client.generation}${client.delivery === 'file' ? ' (kept in a file)' : ''}, ${client.pending} in flight, `
       + `last used ${client.lastUsedAt ?? 'never'}`);
   }
+  if (statusArg.confinedSocketPath !== undefined) {
+    lines.push(`Confined listener: ${statusArg.confinedSocketPath ?? 'none'}`);
+    for (const run of statusArg.confinedRuns ?? []) {
+      lines.push(`Confined run ${run.id}: issued ${run.createdAt}`
+        + `${run.held ? '' : ', waiting for its launcher to take it back after a proxy restart'}`
+        + ` (end it with \`agl proxy confined end ${run.id}\`)`);
+    }
+  }
   if (!statusArg.accounts) {
     // The proxy runs the older AGL it was started from until it restarts, as after an upgrade it was not restarted by.
     lines.push(`Accounts: not reported, as the proxy runs AGL ${statusArg.version} and this command AGL ${commitinfo.version}. `
@@ -130,7 +139,7 @@ const serve = (portArg: number): Promise<void> => withSignals(async (signalArg)
   const credentialHelper = await currentProxyCredentialHelper(paths.root,
     () => resolveAglExecutable(process.env, plugins.os.homedir()));
   const daemon = new AglProxyDaemon({ socketPath: paths.proxySocket, dataDirectory: plugins.path.join(paths.proxy, 'nosqldb'),
-    credentialDirectory: paths.proxyCredentials,
+    credentialDirectory: paths.proxyCredentials, confinedSocketPath: paths.proxyConfinedSocket,
     authorityPaths: resolveProductionAuthoritySocketPaths(), port: portArg });
   const stopping = () => { void daemon.stop().catch(() => undefined); };
   signalArg.addEventListener('abort', stopping, { once: true });
@@ -196,6 +205,45 @@ const run = (optionsArg: IInferenceCliArguments): Promise<void> => withSignals(a
   if (lost) throw new Error(`${lost.message} Run \`agl proxy run ${optionsArg.harness}\` again to continue.`);
 });
 
+/**
+ * Runs a confined run's container (see `confinedDockerLaunch`) on a credential of its own, which ends when the container
+ * exits. A proxy that restarts meanwhile hands the credential back; one the proxy no longer hands back, or the operator
+ * ended, stops the container (`docker run` passes the signal on to it), and the run ends with the reason.
+ */
+const confinedRun = (optionsArg: IInferenceCliArguments): Promise<void> => withSignals(async (signalArg) => {
+  await preflightAGLHomeMigration();
+  const paths = resolveAGLHomePaths();
+  const run = await AglProxyConfinedHolder.take({ socketPath: paths.proxySocket }, AbortSignal.any([signalArg, AbortSignal.timeout(90_000)]));
+  let lost: AglProxyLeaseLostError | undefined;
+  try {
+    const launch = confinedDockerLaunch({ args: optionsArg.args, socketPath: run.confinedSocketPath, baseUrl: run.baseUrl,
+      token: run.token, environment: process.env });
+    process.stderr.write(`AGL proxy confined run ${run.id}: ${plugins.path.dirname(run.confinedSocketPath)} is mounted read-only `
+      + `at ${aglProxyConfinedMountPoint}; end it at once with \`agl proxy confined end ${run.id}\`.\n`);
+    signalArg.throwIfAborted();
+    const child = plugins.childProcess.spawn(launch.command, launch.args, { env: launch.environment, stdio: 'inherit', shell: false });
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+    const terminate = () => {
+      child.kill('SIGTERM');
+      killTimer ??= setTimeout(() => child.kill('SIGKILL'), 10_000);
+      killTimer.unref();
+    };
+    signalArg.addEventListener('abort', terminate, { once: true });
+    void run.lost.then((errorArg) => { lost = errorArg; terminate(); });
+    try {
+      if (signalArg.aborted) terminate();
+      process.exitCode = await new Promise<number>((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', (codeArg) => resolve(codeArg ?? 1));
+      });
+    } finally {
+      signalArg.removeEventListener('abort', terminate);
+      if (killTimer) clearTimeout(killTimer);
+    }
+  } finally { run.close(); }
+  if (lost) throw new Error(`${lost.message} The container was stopped; start the run again to continue.`);
+});
+
 const unitState = async (serviceArg: AglProxyService): Promise<string> => {
   try {
     const state = await serviceArg.inspect();
@@ -212,8 +260,14 @@ export const runInferenceCli = async (argvArg: readonly string[]): Promise<void>
   const options = parseInferenceCliArguments(argvArg);
   if (options.command === 'serve') { await preflightAGLHomeMigration(); await serve(options.port); return; }
   if (options.command === 'run') { await run(options); return; }
+  if (options.command === 'confined' && options.confinedAction === 'run') { await confinedRun(options); return; }
   const paths = resolveAGLHomePaths();
   const client = new AglProxyControlClient(paths.proxySocket);
+  if (options.command === 'confined') {
+    await client.endConfined(options.confinedId!, AbortSignal.timeout(10_000));
+    process.stdout.write(`Ended confined run ${options.confinedId}: the proxy refuses its credential from now on.\n`);
+    return;
+  }
   if (options.command === 'credential') {
     await runProxyCredentialCommand(options, (textArg) => process.stdout.write(textArg));
     return;

package/ts/functions.inferencecliarguments.ts

@@ -2,6 +2,8 @@ import * as path from 'node:path';
 import type { IInferenceRoutingPolicy } from './classes.inferencerouter.js';
 import type { TInferenceHarness } from './functions.inferencelaunch.js';
 import {
+  aglProxyConfinedIdPattern,
+  aglProxyConfinedMountPoint,
   aglProxyDefaultPort,
   aglProxyUnitName,
   defaultProxyClientProvider,
@@ -24,6 +26,8 @@ export const inferenceCliHelp = `Usage:
   agl proxy status [--json]
   agl proxy credential <client> [--provider openai|anthropic] [--delivery file|none] [--write <path>] [--rotate] | --version
   agl proxy run codex|claude|opencode [--provider openai|anthropic] [--account <id>] [--plan <name>] [--model <id>] -- [harness arguments]
+  agl proxy confined run -- docker run [docker options] <image> [command]
+  agl proxy confined end <run id>
 
 The proxy runs as the ${aglProxyUnitName} user unit (serve runs it in a terminal instead).
 Every client (codex, claude, opencode, or a name of your own) has one credential, sealed by the proxy.
@@ -35,6 +39,13 @@ Each client is served from one pool: ChatGPT accounts (openai) or Claude account
 client starts on Claude accounts, every other client on ChatGPT accounts; --provider moves a client.
 Run gives one child a private credential that ends when the child exits; run claude uses Claude accounts
 unless --provider openai asks for ChatGPT models behind Claude Code.
+confined run starts Claude Code's container on a credential of its own, accepted only on the proxy's confined
+listener: a Unix socket whose directory the run mounts read-only at ${aglProxyConfinedMountPoint}, served the Claude pool's
+three Claude Code endpoints alone. It adds the mount and Claude Code's settings (ANTHROPIC_UNIX_SOCKET, ANTHROPIC_BASE_URL,
+ANTHROPIC_AUTH_TOKEN) right after docker run, prints the run's id on standard error, and ends the credential when the
+container exits. The socket is the proxy user's (0600): run the container as that uid (--user), or as root under
+rootless Docker. Root of a rootful daemon connects as well while it keeps CAP_DAC_OVERRIDE (--cap-drop ALL takes it).
+confined end ends a run's credential at once, and its launcher stops the container; agl proxy status lists the runs.
 Repeat --account or --plan to restrict automatic routing. Only accounts the account service holds are eligible.
 ChatGPT pools: /openai/v1/responses, /anthropic/v1/messages (translated), and each prefix's /models.
 Claude pools: /anthropic/v1/messages, /anthropic/v1/messages/count_tokens and /anthropic/v1/models, sent on as Claude Code sent them.
@@ -44,14 +55,18 @@ Use x-agl-session-id for custom clients; native session headers and prompt_cache
 Switches use full history with a cold cache. Provider-only references require a full-history retry; opaque account state never crosses accounts.
 `;
 
-export type TInferenceCommand = 'serve' | 'run' | 'credential' | 'status' | 'service';
+export type TInferenceCommand = 'serve' | 'run' | 'credential' | 'status' | 'service' | 'confined';
 export type TInferenceServiceAction = 'install' | 'enable' | 'start' | 'stop' | 'status';
+export type TInferenceConfinedAction = 'run' | 'end';
 
 export interface IInferenceCliArguments {
   command: TInferenceCommand;
   harness?: TInferenceHarness;
   client?: string;
   serviceAction?: TInferenceServiceAction;
+  confinedAction?: TInferenceConfinedAction;
+  /** `confined end`: the run to end. */
+  confinedId?: string;
   port: number;
   policy: IInferenceRoutingPolicy;
   /** `--provider`, when given. */
@@ -72,6 +87,7 @@ const commandOptions: Record<TInferenceCommand, readonly string[]> = {
   credential: ['--provider', '--delivery', '--write', '--rotate'],
   status: ['--json'],
   service: ['--port'],
+  confined: [],
 };
 const flags = new Set(['--rotate', '--json']);
 
@@ -97,6 +113,21 @@ export const parseInferenceCliArguments = (argvArg: readonly string[]): IInferen
     const action = argv.shift();
     if (!['install', 'enable', 'start', 'stop', 'status'].includes(action ?? '')) throw new Error(inferenceCliHelp);
     result.serviceAction = action as TInferenceServiceAction;
+  } else if (command === 'confined') {
+    const action = argv.shift();
+    if (action === 'end') {
+      const id = argv.shift();
+      if (id === undefined || !aglProxyConfinedIdPattern.test(id) || argv.length) {
+        throw new Error('Name the confined run to end by its id: 12 hex characters, as `agl proxy status` lists it.');
+      }
+      result.confinedAction = 'end';
+      result.confinedId = id;
+      return result;
+    }
+    if (action !== 'run' || argv.shift() !== '--' || !argv.length) throw new Error(inferenceCliHelp);
+    result.confinedAction = 'run';
+    result.args = argv;
+    return result;
   }
   const accounts: string[] = [];
   const plans: string[] = [];

package/ts/functions.inferencelaunch.ts

@@ -1,7 +1,9 @@
+import * as path from 'node:path';
 import type { TInferenceModel } from './classes.inferencerouter.js';
 import type { TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
-import { aglProxyProviderId, claudeProxyEnvironment, claudeRoutingVariables, codexProxyProvider, openCodeProxyProvider,
-  proxyHarnessModels } from './functions.proxyharnessconfig.js';
+import { aglProxyConfinedMountPoint } from './functions.proxycontract.js';
+import { aglProxyProviderId, claudeProxyEnvironment, claudeProxyReservedVariables, claudeRoutingVariables, codexProxyProvider,
+  openCodeProxyProvider, proxyHarnessModels } from './functions.proxyharnessconfig.js';
 
 export type TInferenceHarness = 'codex' | 'claude' | 'opencode';
 export interface IInferenceLaunchOptions {
@@ -137,3 +139,48 @@ export const inferenceHarnessLaunch = (optionsArg: IInferenceLaunchOptions): { a
   if (args[0] === 'run') return { environment, args: ['run', ...selection, ...args.slice(1)] };
   return { environment, args: args[0] !== undefined && openCodeCommands.has(args[0]) ? args : [...selection, ...args] };
 };
+
+/**
+ * A confined run's `docker run`: the given command, with the confined listener's directory mounted read-only at
+ * `aglProxyConfinedMountPoint` and Claude Code's settings for it added right after `run`, before the launcher's own
+ * options and image. Claude Code inside reaches the proxy through the socket alone (`ANTHROPIC_UNIX_SOCKET`, which
+ * Claude Code sends its API requests through as plain HTTP to `ANTHROPIC_BASE_URL`'s path), on the run's credential
+ * (`ANTHROPIC_AUTH_TOKEN`), reads the pool's models from the proxy and sends nothing beyond its model requests. The
+ * container gets each variable by name from the docker command's environment, so the credential never appears on a
+ * command line; that environment drops every variable that would give Claude Code another login or route, so `-e NAME`
+ * of one of them passes nothing. The mount is the socket's own directory, which holds nothing else and survives a proxy
+ * restart, unlike a mount of the socket file. Only `docker run` and `docker container run` are taken.
+ */
+export const confinedDockerLaunch = (optionsArg: {
+  args: readonly string[];
+  /** The confined listener's socket on the host. */
+  socketPath: string;
+  /** The origin Claude Code names; see `IAglProxyConfinedGrant.baseUrl`. */
+  baseUrl: string;
+  token: string;
+  environment: NodeJS.ProcessEnv;
+}): { command: string; args: string[]; environment: NodeJS.ProcessEnv } => {
+  const [command, ...args] = optionsArg.args;
+  const runAt = args[0] === 'run' ? 1 : args[0] === 'container' && args[1] === 'run' ? 2 : 0;
+  if (command === undefined || path.basename(command) !== 'docker' || runAt === 0) {
+    throw new Error('A confined run starts its container with `docker run` (or `docker container run`) and its arguments.');
+  }
+  const directory = path.dirname(optionsArg.socketPath);
+  // `--mount` separates its fields with commas and reads quotes; a directory naming either cannot be passed safely.
+  if (/[,"'\n]/u.test(directory)) throw new Error(`The confined listener's directory ${directory} cannot be mounted: it holds a comma, quote or line break.`);
+  const variables: Record<string, string> = {
+    ...claudeProxyEnvironment(optionsArg.baseUrl),
+    ANTHROPIC_UNIX_SOCKET: `${aglProxyConfinedMountPoint}/${path.basename(optionsArg.socketPath)}`,
+    ANTHROPIC_AUTH_TOKEN: optionsArg.token,
+  };
+  const environment = { ...optionsArg.environment };
+  for (const name of claudeProxyReservedVariables) delete environment[name];
+  return {
+    command,
+    args: [...args.slice(0, runAt),
+      '--mount', `type=bind,source=${directory},target=${aglProxyConfinedMountPoint},readonly`,
+      ...Object.keys(variables).flatMap((nameArg) => ['--env', nameArg]),
+      ...args.slice(runAt)],
+    environment: { ...environment, ...variables },
+  };
+};

package/ts/functions.proxycontract.ts

@@ -33,3 +33,15 @@ export const proxyCredentialDeliveries: readonly TProxyCredentialDelivery[] = ['
 
 export const aglProxyUnitName = 'agl-proxy.service';
 export const aglProxyDefaultPort = 4100;
+
+/**
+ * Confined runs (`agl proxy confined run`): Claude Code in a container that reaches the proxy only through the confined
+ * listener, a Unix socket alone in its directory, which the run mounts read-only at `aglProxyConfinedMountPoint`. Their
+ * sessions are those of the client `aglProxyConfinedClient`, and Claude Code names `aglProxyConfinedOrigin` as its
+ * endpoint's origin, whose host the socket makes irrelevant.
+ */
+export const aglProxyConfinedClient = 'confined';
+export const aglProxyConfinedOrigin = 'http://localhost';
+export const aglProxyConfinedMountPoint = '/run/agl-proxy';
+/** A confined run's id: the first 12 hex characters of its credential's SHA-256 digest. */
+export const aglProxyConfinedIdPattern = /^[a-f0-9]{12}$/;

package/ts/functions.proxysocket.ts

@@ -0,0 +1,39 @@
+import * as plugins from './plugins.js';
+
+/**
+ * Claims the pathname of one of the proxy's Unix sockets: its directory is made private (0700, this user's, not a link),
+ * and a socket a killed proxy left there is removed, but only while it is an unchanged, owned socket nobody answers on.
+ * `nameArg` names the socket in the refusals; `busyArg` is the refusal for a socket another process answers on.
+ */
+export const claimProxySocketPath = async (socketPathArg: string, nameArg: string, busyArg: string): Promise<void> => {
+  const directory = plugins.path.dirname(socketPathArg);
+  await plugins.fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
+  const stat = await plugins.fs.promises.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()) {
+    throw new Error(`The ${nameArg} directory is not private.`);
+  }
+  await plugins.fs.promises.chmod(directory, 0o700);
+  let before: plugins.fs.Stats;
+  try { before = await plugins.fs.promises.lstat(socketPathArg); }
+  catch (errorArg) {
+    if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw errorArg;
+  }
+  if (!before.isSocket() || before.uid !== process.getuid?.()) throw new Error(`The ${nameArg} path is unsafe.`);
+  const refused = await new Promise<boolean>((resolve, reject) => {
+    const probe = plugins.net.createConnection(socketPathArg);
+    probe.setTimeout(1_000, () => { probe.destroy(); reject(new Error(`The ${nameArg} probe timed out.`)); });
+    probe.once('connect', () => { probe.destroy(); resolve(false); });
+    probe.once('error', (errorArg) => {
+      probe.destroy();
+      if ((errorArg as NodeJS.ErrnoException).code === 'ECONNREFUSED') resolve(true);
+      else reject(errorArg);
+    });
+  });
+  if (!refused) throw new Error(busyArg);
+  const after = await plugins.fs.promises.lstat(socketPathArg);
+  if (!after.isSocket() || after.dev !== before.dev || after.ino !== before.ino) {
+    throw new Error(`The ${nameArg} path changed during startup.`);
+  }
+  await plugins.fs.promises.unlink(socketPathArg);
+};

package/ts/functions.workerprocessproof.ts

@@ -142,21 +142,44 @@ const processOwnsLoopbackConnection = async (connectionArg: IWorkerCallerConnect
   return matches.length === 1 && await processOwnsInode(pidArg, matches[0][9]);
 };
 
-export const verifyWorkerBridge = async (
+/**
+ * The bridge process `bridgePidArg`, proved to hold the caller's end of the direct loopback connection and to run the
+ * approved command, whatever its parent. The command is the one recorded when the launch was prepared: an upgrade
+ * installs AGL under another path, and a command whose files are gone is refused as such.
+ */
+export const readWorkerBridge = async (
   connectionArg: IWorkerCallerConnection | undefined,
   bridgePidArg: number,
   commandArg: IWorkerBridgeCommand,
-  parentArg: IWorkerProcessSnapshot,
 ): Promise<IWorkerProcessSnapshot> => {
+  for (const file of [commandArg.executable, commandArg.entry]) {
+    let resolved: string;
+    try { resolved = await plugins.fs.promises.realpath(file); } catch (errorArg) {
+      if (isWorkerCallerProofRefusal(errorArg)) throw new WorkerCallerProofError('The approved bridge command no longer exists.');
+      throw errorArg;
+    }
+    if (resolved !== file) throw new WorkerCallerProofError('The approved bridge command no longer exists.');
+  }
   if (!await processOwnsLoopbackConnection(connectionArg, bridgePidArg)) {
     throw new WorkerCallerProofError('Worker transport ownership could not be proved.');
   }
   const bridge = await readWorkerProcessSnapshot(bridgePidArg);
   const entry = await plugins.fs.promises.realpath(bridge.arguments[1] ?? '');
-  if (bridge.parentPid !== parentArg.pid || bridge.executable !== commandArg.executable
-    || entry !== commandArg.entry || !plugins.util.isDeepStrictEqual(bridge.arguments.slice(2), commandArg.arguments)) {
+  if (bridge.executable !== commandArg.executable || entry !== commandArg.entry
+    || !plugins.util.isDeepStrictEqual(bridge.arguments.slice(2), commandArg.arguments)) {
     throw new WorkerCallerProofError('Worker bridge does not match the approved launch.');
   }
+  return bridge;
+};
+
+export const verifyWorkerBridge = async (
+  connectionArg: IWorkerCallerConnection | undefined,
+  bridgePidArg: number,
+  commandArg: IWorkerBridgeCommand,
+  parentArg: IWorkerProcessSnapshot,
+): Promise<IWorkerProcessSnapshot> => {
+  const bridge = await readWorkerBridge(connectionArg, bridgePidArg, commandArg);
+  if (bridge.parentPid !== parentArg.pid) throw new WorkerCallerProofError('Worker bridge does not match the approved launch.');
   if (!workerSnapshotsEqual(parentArg, await readWorkerProcessSnapshot(parentArg.pid))
     || !workerSnapshotsEqual(bridge, await readWorkerProcessSnapshot(bridge.pid))) {
     throw new WorkerCallerProofError('Worker transport or process incarnation could not be proved.');

package/ts_authswitch/authority-contract.ts

@@ -767,6 +767,27 @@ export interface IAuthSwitchClaudeSignInPrompt {
 /** The arguments a Claude sign-in runs Claude Code with, in the home its prompt names. */
 export const authSwitchClaudeSignInArguments: readonly string[] = ['auth', 'login'];
 
+/**
+ * A Claude Code process that keeps a sign-in from importing the login in its home, as the process table lists it:
+ * `on_home` when its home or credential store is the sign-in home, so it may still write there; `uninspectable` when
+ * its home or store could not be resolved and it did not start before the home was made, so it may run on it.
+ */
+export interface IAuthSwitchClaudeSignInHolder {
+  /** Null where the process table names none. */
+  pid: number | null;
+  /** When it started, to the second; null when the process table did not say. */
+  startedAt: string | null;
+  reason: 'on_home' | 'uninspectable';
+}
+
+/**
+ * The processes holding a sign-in, in the words the authswitch command line, the sign-in's own error and AGL's
+ * Accounts screen share: each by pid and start, and why it holds the sign-in.
+ */
+export const authSwitchClaudeSignInHoldersText = (holders: readonly IAuthSwitchClaudeSignInHolder[]): string =>
+  holders.map(holder => `pid ${holder.pid ?? 'unknown'}${holder.startedAt === null ? '' : ` (started ${holder.startedAt})`} `
+    + (holder.reason === 'on_home' ? 'runs on the sign-in home' : 'could not be inspected')).join('; ');
+
 /**
  * One Claude sign-in: Claude Code signs in to a Claude home the authority created for it alone, and once the login
  * is there and no Claude Code process runs on that home, the authority imports it with one rotating refresh -- the
@@ -775,16 +796,24 @@ export const authSwitchClaudeSignInArguments: readonly string[] = ['auth', 'logi
  * authority holds and which has ended (`needs_reauth`) signs that account in again; a working login, or one Claude
  * Code holds, is kept, and the sign-in fails saying so.
  *
- * `pending` while the authority waits for the login, with `prompt`; `committing` while it imports it; then
- * `complete` with `result`, `failed` or `outcome_unknown` with `error`, `cancelled`, or `interrupted` when the
- * authority stopped. A pending sign-in that holds no login at `expiresAt`, fifteen minutes after it started, fails.
- * A finished sign-in answers for ten minutes after `finishedAt`; after that its id is unknown (`not_found`).
- * Sign-ins live in the running authority only: after a restart their ids are unknown and their homes are gone.
+ * `pending` while the authority waits for the login, with `prompt`, and with `heldBy` once the login is there but
+ * Claude Code processes keep the authority from importing it; `committing` while it imports it; then `complete` with
+ * `result`, `failed` or `outcome_unknown` with `error`, `cancelled`, or `interrupted` when the authority stopped. A
+ * pending sign-in still pending at `expiresAt`, fifteen minutes after it started, fails and imports nothing: its error
+ * says whether a login had arrived and, if processes held it, names them. A finished sign-in answers for ten minutes
+ * after `finishedAt`; after that its id is unknown (`not_found`). Sign-ins live in the running authority only: after a
+ * restart their ids are unknown and their homes are gone.
  */
 export interface IAuthSwitchClaudeSignInOperation {
   id: string;
   state: 'pending' | 'committing' | 'complete' | 'failed' | 'cancelled' | 'interrupted' | 'outcome_unknown';
   prompt: IAuthSwitchClaudeSignInPrompt | null;
+  /**
+   * While `pending` with Claude Code's login in the home: the processes that keep the authority from importing it, as
+   * its last look found them; never empty. Null while no login is there, while nothing holds it, and once the sign-in
+   * is no longer pending.
+   */
+  heldBy: IAuthSwitchClaudeSignInHolder[] | null;
   result: { accountId: string; loginId: string } | null;
   error: string | null;
   createdAt: string;

package/ts_authswitch/classes.authoritycli.ts

@@ -2,7 +2,7 @@ import type { IAuthSwitchAccount, IAuthSwitchClaudeHostLogin, IAuthSwitchClaudeH
   IAuthSwitchDoctorPage, IAuthSwitchUsageRecheck, IAuthSwitchUsageSnapshot, IAuthSwitchOperation, IAuthSwitchPreuseOperation, IAuthSwitchSnapshot, IReq_AuthSwitchDoctor,
   IReq_AuthSwitchAddApiKey, IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchStartPreuse,
   IReq_AuthSwitchSwitchCodexNative, IReq_AuthSwitchReleaseCodexNative } from './authority-contract.js';
-import { asAuthSwitchRefusal, authSwitchClaudeSignInArguments, isAuthSwitchLapsesAt,
+import { asAuthSwitchRefusal, authSwitchClaudeSignInArguments, authSwitchClaudeSignInHoldersText, isAuthSwitchLapsesAt,
   type TAuthSwitchApiKeyProvider } from './authority-contract.js';
 import { authSwitchParseUsd, authSwitchUsdText } from './authority-spend.js';
 import type { IAuthSwitchImportInventory, IAuthSwitchImportResult, IAuthSwitchImportStatus,
@@ -812,6 +812,10 @@ const renderClaudeSignIn = (operation: IAuthSwitchClaudeSignInOperation, json: b
   if (json) return JSON.stringify(operation) + '\n';
   const lines = [`Claude sign-in ${safe(operation.id)} — ${safe(operation.state)}, revision ${operation.revision}`];
   if (operation.prompt) lines.push(`  Claude Code signs in with: ${safe(operation.prompt.command)}`);
+  if (operation.heldBy) {
+    lines.push('  Claude Code signed in; the login is added once these Claude Code processes have ended: '
+      + safe(authSwitchClaudeSignInHoldersText(operation.heldBy)));
+  }
   if (operation.result) {
     lines.push(`  signed in account=${safe(operation.result.accountId)}; login=${safe(operation.result.loginId)}`);
   }