agl 40.5.1 → 41.0.0

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.mcptickettools.ts

@@ -4,7 +4,7 @@ import type { TTicketOperation } from '../ts_interfaces/tickets.js';
 const workflow = ' Caller identity comes from AGL, never a supplied name. Unidentified callers may list/get tickets with empty mine; every mutation requires a verified caller. Workers create in backlog and may update/move only their assigned tickets within ready, in_progress, needs_input and review. Link a branch with a full sha before Review. Only the driver or owner assigns, lands or releases tickets.';
 export const ticketToolDefinitions = [
   { name: 'tickets_list', operation: 'list', description: 'Read the shared board across all projects. Filter by mine, project, status, label or text. mine uses your verified session. label also matches AutoLabels, which AGL computes and nobody sets: openQuestion marks a ticket with an unanswered question.' },
-  { name: 'ticket_get', operation: 'get', description: 'Read a ticket by its AGL-<n> key, with markdown comments, source, links, its questions and their answers, and the complete activity log.' },
+  { name: 'ticket_get', operation: 'get', description: 'Read a ticket by its AGL-<n> key: source, links, all its questions and their answers, and the newest page of its history, oldest first: up to limit entries (default 50, at most 500), fewer when the entries and their comments would pass 256 KiB. activity is the page; comments are the markdown comments it names, and a commented entry names its comment by id. historyBefore is present while older history exists: pass it as before for the next older page. commentId instead reads the one comment an activity entry or fleet event names (without before or limit).' },
   { name: 'ticket_create', operation: 'create', description: 'Capture discussed work as a ticket. Include project, title, description and sourceText (the original words); optional attachments are named URLs. Worker-created tickets start in backlog for driver triage.' },
   { name: 'ticket_update', operation: 'update', description: 'Update the title, markdown description, priority, labels, project or parent of your assigned ticket. Supply expectedRevision from the ticket you read; stale edits return TICKET_REVISION_CONFLICT with currentRevision. Reload before editing again. Status is changed only with ticket_move; assignment is driver/owner-only.' },
   { name: 'ticket_move', operation: 'move', description: 'Atomically move/reorder your assigned ticket. Omit beforeTicketId to append. Returns every record whose column or order changed. Review requires a linked branch and sha. Use needs_input to report a blocker.' },

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.ticketcli.ts

@@ -8,7 +8,10 @@ import type { ITicketChanges, ITicketPerson, TTicketOperation, TTicketRequest, T
 export const ticketCliHelp = `Usage: agl ticket <list|get|create|update|move|comment|link|assign|ask|answer> [AGL-<n>] [options]
   list    [--mine] [--project ID] [--status COLUMN] [--label LABEL] [--text TEXT]
           --label also matches AutoLabels, which AGL computes: openQuestion (an unanswered question)
-  get     AGL-<n>
+  get     AGL-<n> [--limit N] [--before HISTORY-ID] [--comment COMMENT-ID]
+          The ticket, its questions and the newest N history entries (default 50, at most 500, within 256 KiB);
+          historyBefore names the next older page: pass it as --before.
+          --comment reads the one comment an activity entry names instead (not with --limit or --before)
   create  --project ID --title TEXT [--description MARKDOWN] [--kind epic|task|subtask]
           [--parent AGL-<n>] [--priority none|low|normal|high|urgent] [--labels a,b]
           [--source TEXT] [--attachments JSON] [--column COLUMN]
@@ -38,7 +41,7 @@ export interface ITicketCliArguments {
 }
 const common = ['port', 'json'];
 const actionOptions: Record<string, string[]> = {
-  list: ['mine', 'project', 'status', 'label', 'text'], get: [],
+  list: ['mine', 'project', 'status', 'label', 'text'], get: ['limit', 'before', 'comment'],
   create: ['project', 'title', 'description', 'kind', 'parent', 'priority', 'labels', 'source', 'attachments', 'column'],
   update: ['expected-revision', 'changes', 'title', 'description', 'priority', 'project', 'labels', 'parent', 'clear-parent'],
   move: ['column', 'before'], comment: ['body'], link: ['repo', 'branch', 'sha', 'package', 'version'],
@@ -78,7 +81,8 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
   const operation = action === 'assign' ? 'update' : action as TTicketOperation;
   if (action === 'list') request = { ...(options.has('mine') ? { mine: true } : {}), ...optional('project'),
     ...optional('status'), ...optional('label'), ...optional('text') };
-  else if (action === 'get') request = { ticketId };
+  else if (action === 'get') request = { ticketId, ...optional('before'), ...optional('comment', 'commentId'),
+    ...(options.has('limit') ? { limit: Number(required('limit')) } : {}) };
   else if (action === 'create') request = { project: required('project'), title: required('title'), ...optional('description'),
     ...optional('kind'), ...optional('parent', 'parentId'), ...optional('priority'), ...labels(), ...optional('source', 'sourceText'),
     ...optional('column', 'columnId'), ...(options.has('attachments') ? { attachments: JSON.parse(required('attachments')) } : {}) };

package/ts/functions.ticketvalidation.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import { ticketAutoLabels, ticketColumns, type TTicketOperation, type TTicketRequest } from '../ts_interfaces/tickets.js';
+import { ticketAutoLabels, ticketColumns, ticketHistoryPage, type TTicketOperation, type TTicketRequest } from '../ts_interfaces/tickets.js';
 
 const text = (maximumArg: number) => plugins.z.string().max(maximumArg);
 const identifier = text(1024).min(1).refine((valueArg) => !/[\x00-\x1f\x7f]/u.test(valueArg));
@@ -38,7 +38,11 @@ const changes = plugins.z.object({
 export const ticketInputSchemas = {
   list: filters, board: filters,
   search: plugins.z.object({ query: text(1024), label: text(100).min(1).optional() }).strict(),
-  get: plugins.z.object({ ticketId }).strict(), comments: plugins.z.object({ ticketId }).strict(),
+  get: plugins.z.object({ ticketId, before: identifier.optional(),
+    limit: plugins.z.number().int().min(1).max(ticketHistoryPage.maximum).optional(), commentId: identifier.optional() }).strict()
+    .refine((valueArg) => valueArg.commentId === undefined || (valueArg.before === undefined && valueArg.limit === undefined),
+      'commentId reads one comment and excludes before and limit.'),
+  comments: plugins.z.object({ ticketId }).strict(),
   create: plugins.z.object({ project: identifier, kind: kind.optional(), title: text(200).trim().min(1),
     description: text(64 * 1024).optional(), columnId: plugins.z.enum(ticketColumns).optional(), parentId: ticketId.optional(),
     priority: priority.optional(), assignee: person.optional(), labels: labels.optional(), sourceText: text(64 * 1024).optional(),
@@ -117,7 +121,7 @@ export const assertTicketResponse = (methodArg: string, valueArg: unknown): void
       id: plugins.z.enum(ticketColumns), title: plugins.z.string(), done: plugins.z.boolean().optional() }).strict()), tickets: plugins.z.array(ticket),
       viewer: person }).strict(),
     get: plugins.z.object({ ticket, comments: plugins.z.array(ticketCommentSchema), activity: plugins.z.array(ticketActivitySchema),
-      questions: plugins.z.array(ticketQuestionSchema) }).strict(),
+      questions: plugins.z.array(ticketQuestionSchema), historyBefore: identifier.optional() }).strict(),
     comments: plugins.z.object({ comments: plugins.z.array(ticketCommentSchema) }).strict(),
     create: plugins.z.object({ ticket }).strict(), update: plugins.z.object({ ticket }).strict(),
     link: plugins.z.object({ ticket }).strict(), move: plugins.z.object({ tickets: plugins.z.array(ticket) }).strict(),

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/interfaces.flexipc.ts

@@ -23,6 +23,7 @@ import {
 type TFlexCreateSessionOptions = plugins.flexharness.IFlexCreateSessionOptions;
 type TFlexMessage = plugins.flexharness.IFlexMessage;
 type TFlexMessagePage = plugins.flexharness.IFlexMessagePage;
+type TFlexMessageMetadataPage = plugins.flexharness.IFlexMessageMetadataPage;
 type TFlexPermissionRequest = plugins.flexharness.IFlexPermissionRequest;
 export type TFlexPromptQueueEntry = plugins.flexharness.IFlexPromptQueueEntry;
 type TFlexPromptOptions = plugins.flexharness.IFlexPromptOptions;
@@ -67,7 +68,7 @@ export type TFlexTurnReversionCaptureInspectionV2 =
 export type TFlexTurnReversionApplyInspection =
   plugins.flexharness.IFlexTurnReversionApplyInspection;
 
-export const flexIpcProtocolVersion = 38 as const;
+export const flexIpcProtocolVersion = 39 as const;
 /**
  * The installation's own Flex runs, which belong to no project: the configuration projection's adapting run, and
  * Session Intelligence over a session outside every project.
@@ -307,6 +308,8 @@ export interface IFlexDriverRequest {
 export interface IFlexDriverResolution {
   instructions: string;
   notes: string;
+  /** The revision of the session scratchpad that holds the notes; names them as the driver's pinned context. */
+  notesRevision: number;
 }
 export const flexDriverToolNamePattern = /^[a-z][a-z0-9_]{0,63}$/u;
 export const flexDriverToolInputMaxBytes = 2 * 1024 * 1024;
@@ -363,7 +366,7 @@ export interface IFlexHostRequestMap {
     request: IFlexTurnReversionReleaseRequest;
     response: { released: true };
   };
-  /** The controller-owned driver session's instructions and notes; null for every other session. */
+  /** The controller-owned driver session's instructions and notes with their revision; null for every other session. */
   'driver.resolve': {
     request: IFlexDriverRequest;
     response: { driver: IFlexDriverResolution | null };
@@ -836,6 +839,14 @@ export interface IFlexRequestMap {
     request: { scopeId: string; sessionId: string; limit?: number; before?: string; includeUndone?: boolean };
     response: TFlexMessagePage;
   };
+  /**
+   * The same pages with each message's identity and state only (no parts, model, usage or error):
+   * a whole transcript is scanned without reading its text or tool output.
+   */
+  'message.metadata.page': {
+    request: { scopeId: string; sessionId: string; limit?: number; before?: string; includeUndone?: boolean };
+    response: TFlexMessageMetadataPage;
+  };
   'message.get': {
     request: { scopeId: string; sessionId: string; messageId: string; includeUndone?: boolean };
     response: TFlexMessage;
@@ -1358,6 +1369,7 @@ export const readOnlyFlexRequestMethods: ReadonlySet<TFlexRequestMethod> = new S
   'session.reversion.info',
   'slash.list',
   'message.page',
+  'message.metadata.page',
   'message.get',
   'prompt.get',
   'prompt.list',
@@ -1387,6 +1399,7 @@ const requestMethods: ReadonlySet<string> = new Set<TFlexRequestMethod>([
   'slash.list',
   'slash.execute',
   'message.page',
+  'message.metadata.page',
   'message.get',
   'prompt.start',
   'prompt.continue',
@@ -1919,28 +1932,22 @@ const isFlexModelLimit = (valueArg: unknown): valueArg is TFlexModelLimit => (
   isFlexPlainObject(valueArg) && plugins.flexModels.isModelLimitInfo(valueArg)
 );
 
-export const isFlexPublicMessage = (valueArg: unknown): valueArg is TFlexMessage =>
-  isFlexPlainObject(valueArg)
-  && hasFlexExactKeys(
-    valueArg,
-    ['messageId', 'sessionId', 'runId', 'role', 'status', 'createdAt', 'parts'],
-    ['completedAt', 'model', 'usage', 'error', 'limit', 'rejectedPermissionId', 'steerId', 'cacheWarm', 'promptId', 'keptInContext', 'undone'],
-  )
-  && isIdentifier(valueArg.messageId)
+const flexMessageIdentityKeys = ['messageId', 'sessionId', 'runId', 'role', 'status', 'createdAt'] as const;
+const flexMessageOptionalIdentityKeys = ['completedAt', 'steerId', 'promptId', 'keptInContext', 'undone', 'cacheWarm'] as const;
+const flexMessageKeys = [...flexMessageIdentityKeys, 'parts'] as const;
+const flexMessageOptionalKeys = [
+  ...flexMessageOptionalIdentityKeys, 'model', 'usage', 'error', 'limit', 'rejectedPermissionId',
+] as const;
+
+/** The identity and state a transcript message and its metadata share (`TFlexMessageMetadata`). */
+const hasFlexMessageIdentity = (valueArg: Record<string, unknown>): boolean =>
+  isIdentifier(valueArg.messageId)
   && isIdentifier(valueArg.sessionId)
   && isIdentifier(valueArg.runId)
   && ['user', 'assistant'].includes(String(valueArg.role))
   && ['streaming', 'completed', 'failed', 'cancelled'].includes(String(valueArg.status))
   && isIsoDate(valueArg.createdAt)
   && (valueArg.completedAt === undefined || isIsoDate(valueArg.completedAt))
-  && Array.isArray(valueArg.parts)
-  && valueArg.parts.length <= 2000
-  && valueArg.parts.every((partArg) => isMessagePart(partArg))
-  && (valueArg.model === undefined || isModelIdentity(valueArg.model))
-  && (valueArg.usage === undefined || isUsage(valueArg.usage))
-  && (valueArg.error === undefined || isBoundedString(valueArg.error, 2048))
-  && (valueArg.limit === undefined || isFlexModelLimit(valueArg.limit))
-  && (valueArg.rejectedPermissionId === undefined || isIdentifier(valueArg.rejectedPermissionId))
   && (valueArg.steerId === undefined || (valueArg.role === 'user' && isIdentifier(valueArg.steerId)))
   && (valueArg.promptId === undefined || (valueArg.role === 'user' && isBoundedString(valueArg.promptId, 512)))
   && !(valueArg.promptId !== undefined && valueArg.steerId !== undefined)
@@ -1949,6 +1956,25 @@ export const isFlexPublicMessage = (valueArg: unknown): valueArg is TFlexMessage
   && (valueArg.undone === undefined || valueArg.undone === true)
   && (valueArg.cacheWarm === undefined || valueArg.cacheWarm === true);
 
+export const isFlexPublicMessage = (valueArg: unknown): valueArg is TFlexMessage =>
+  isFlexPlainObject(valueArg)
+  && hasFlexExactKeys(valueArg, flexMessageKeys, flexMessageOptionalKeys)
+  && hasFlexMessageIdentity(valueArg)
+  && Array.isArray(valueArg.parts)
+  && valueArg.parts.length <= 2000
+  && valueArg.parts.every((partArg) => isMessagePart(partArg))
+  && (valueArg.model === undefined || isModelIdentity(valueArg.model))
+  && (valueArg.usage === undefined || isUsage(valueArg.usage))
+  && (valueArg.error === undefined || isBoundedString(valueArg.error, 2048))
+  && (valueArg.limit === undefined || isFlexModelLimit(valueArg.limit))
+  && (valueArg.rejectedPermissionId === undefined || isIdentifier(valueArg.rejectedPermissionId));
+
+/** A transcript message's identity and state as `message.metadata.page` carries it: no content. */
+export const isFlexMessageMetadata = (valueArg: unknown): valueArg is plugins.flexharness.TFlexMessageMetadata =>
+  isFlexPlainObject(valueArg)
+  && hasFlexExactKeys(valueArg, flexMessageIdentityKeys, flexMessageOptionalIdentityKeys)
+  && hasFlexMessageIdentity(valueArg);
+
 export const isFlexPublicSession = (valueArg: unknown): valueArg is TFlexSession => {
   if (
     !isFlexPlainObject(valueArg)
@@ -2573,6 +2599,7 @@ export const isFlexRequestPayload = <TMethod extends TFlexRequestMethod>(
         && isScopeAndSession(valueArg)
         && isUpdateSessionOptions(valueArg.options);
     case 'message.page':
+    case 'message.metadata.page':
       return hasFlexExactKeys(valueArg, ['scopeId', 'sessionId'], ['limit', 'before', 'includeUndone'])
         && isScopeAndSession(valueArg)
         && (valueArg.limit === undefined
@@ -3118,10 +3145,11 @@ export const isFlexHostResponseResult = <TMethod extends TFlexHostRequestMethod>
     if (!hasFlexExactKeys(valueArg, ['driver'])) return false;
     const driver = valueArg.driver;
     return driver === null || (isFlexPlainObject(driver)
-      && hasFlexExactKeys(driver, ['instructions', 'notes'])
+      && hasFlexExactKeys(driver, ['instructions', 'notes', 'notesRevision'])
       && isBoundedString(driver.instructions, 64 * 1024)
       && isBoundedString(driver.notes, 128 * 1024, true)
-      && driver.notes.length <= 32_768);
+      && driver.notes.length <= 32_768
+      && isNonNegativeInteger(driver.notesRevision));
   }
   if (methodArg === 'driver.tool') {
     if (Object.hasOwn(valueArg, 'error')) {
@@ -3441,11 +3469,12 @@ export const isFlexResponseResult = <TMethod extends TFlexRequestMethod>(
     case 'slash.execute':
       return isSlashExecutionResult(valueArg);
     case 'message.page':
+    case 'message.metadata.page':
       return isFlexPlainObject(valueArg)
         && hasFlexExactKeys(valueArg, ['messages', 'startIndex'], ['nextCursor'])
         && Array.isArray(valueArg.messages) && valueArg.messages.length <= 50
         && Number.isSafeInteger(valueArg.startIndex) && (valueArg.startIndex as number) >= 0
-        && valueArg.messages.every(isFlexPublicMessage)
+        && valueArg.messages.every(methodArg === 'message.page' ? isFlexPublicMessage : isFlexMessageMetadata)
         && (valueArg.nextCursor === undefined || isBoundedString(valueArg.nextCursor, 4096));
     case 'message.get':
       return isFlexPublicMessage(valueArg);

package/ts_interfaces/fleetworkers.ts

@@ -228,6 +228,12 @@ export interface IFleetEvent {
   /** The native session (`harness:nativeId`) a ticket notice addressed. */
   sessionId?: string;
   reportId?: string;
+  /**
+   * The comment on `ticketKey` that holds this event's whole text, by the id the ticket board returned: a worker's report
+   * the fleet commented (`worker.report.mid_turn`, `worker.turn.ended`), the board pump's stall notice, a commented
+   * `ticket.changed`. Read it with `ticket_get` and `commentId`. Absent when no comment holds the text.
+   */
+  commentId?: string;
   turnId?: string;
   status?: string;
   text?: string;

package/ts_interfaces/interfaces.ts

@@ -5,7 +5,7 @@ import type {
   TControllerBrowserPaintAvailability,
   TControllerBrowserPaintTermination,
 } from './browserpaint.js';
-export const controllerProtocolVersion = 45 as const;
+export const controllerProtocolVersion = 46 as const;
 export const controllerUpgradeManagementVersion = 2 as const;
 export const controllerPackageName = 'agl' as const;
 /** The systemd user unit `agl service install` writes; a controller it runs reports it in its status. */