@ours.network/fleet 1.1.0-nightly.3 → 1.1.0-nightly.30

package/dist/runner.js

@@ -6,13 +6,15 @@ import { agentDir, stateRoot } from './paths.js';
 import { loadConfig, findRole, isolationContextFor, resolveMonitorConfig, resolvePermissions, } from './config.js';
 import { getAdapter } from './harness/registry.js';
 import { createMonitor, probeIdentityPresence, } from './monitor.js';
+import { DaemonGenerationObserver, RoleRecoveryController, probeDaemonGeneration, } from './daemon-recovery.js';
+import { recoverAgentIdentity } from './agent-recovery-gate.js';
 import { realExec } from './exec.js';
 import { resolveIsolation } from './isolation/policy.js';
 import { selectIsolationBackend } from './isolation/registry.js';
 import { resourceArgs, cpuControllerDelegated } from './isolation/resources.js';
 import { resolveLaunchRuntime } from './isolation/runtime.js';
 import { controlRequest, RoleControlServer } from './session/control.js';
-import { ACP_CANCEL_DEADLINE_EXCEEDED, classifyShellStatus } from './session/types.js';
+import { ACP_CANCEL_DEADLINE_EXCEEDED, CODEX_APP_SERVER_CANCEL_DEADLINE_EXCEEDED, classifyShellStatus, } from './session/types.js';
 import { effectiveModelForRole, modelRecoveryHeld, reconcileModelRecovery, recordModelFailure, classifyFailureText, } from './model-recovery.js';
 import { rotateWorklog } from './worklog.js';
 import { reconcilePermanentRoleIdentities } from './creation.js';
@@ -24,6 +26,15 @@ import { FLEET_PROXY_CALLER_ENV, FLEET_PROXY_STATE_DIR_ENV, } from './fleet-prox
 import { effectivePermissionMode } from './permissions.js';
 import { assertModelPinReachesChild, effectiveRoleModel, repinModelEnv } from './model-env.js';
 import { archiveTempState, markTempSupervisorActive, requestedTempStopReason, } from './temp-lifecycle.js';
+import { FleetCommandAuditStore } from './fleet-command-audit.js';
+export const SUPERVISOR_RECYCLE_REQUIRED = 'OWNER_CHANNEL_SUPERVISOR_RECYCLE_REQUIRED';
+export class SupervisorRecycleRequiredError extends Error {
+    code = SUPERVISOR_RECYCLE_REQUIRED;
+    constructor() {
+        super('owner channel requires a fresh supervisor process after unproven client quiescence');
+        this.name = 'SupervisorRecycleRequiredError';
+    }
+}
 const defaultDeps = () => ({
     exec: realExec,
     cpuDelegated: () => cpuControllerDelegated(),
@@ -38,10 +49,12 @@ const defaultDeps = () => ({
     now: () => Date.now(),
     log: line => process.stderr.write(line + '\n'),
     fetch: (url, init) => globalThis.fetch(url, init),
+    probeGeneration: env => probeDaemonGeneration((url, init) => globalThis.fetch(url, init), env),
     createMonitor: opts => createMonitor(opts),
     createOwnerChannel: opts => new OwnerChannel(opts),
     startAgentSession: (adapter, options) => adapter.start(options),
     createControlServer: (stateDir, session, log) => new RoleControlServer(stateDir, session, log),
+    createLoopManager: (...args) => new ScheduledLoopManager(...args),
     acquireOwnerBinder: (stateDir, role, identity) => acquireOwnerBinderLease(stateDir, role, identity),
     reportOwnerStartupFailure: async (stateDir) => {
         const response = await controlRequest(stateDir, {
@@ -58,6 +71,32 @@ const defaultDeps = () => ({
 });
 const MONITOR_OWNER_FILE = '.monitor-owner';
 const OBSOLETE_OURS_AUTOSTART_ENV = 'OURS_AUTOSTART';
+function localFleetAuditor(stateDir, caller, log) {
+    const store = new FleetCommandAuditStore(join(stateDir, '.fleet-command-audit.json'));
+    return {
+        async begin(requestId, argv) {
+            let attempt = store.begin(requestId, caller, argv);
+            if (attempt.invocation === 'sending') {
+                log(`[${caller}] fleet proxy command ${attempt.correlationId} `
+                    + `route=${attempt.classification.route} decision=${attempt.classification.decision}`);
+                attempt = store.invocation(attempt.correlationId, caller, 'delivered');
+            }
+            return attempt;
+        },
+        async finish(input) {
+            let attempt = store.finish(input.correlationId, caller, {
+                class: input.class, effect: input.effect,
+                ...(input.exitCode === undefined ? {} : { exitCode: input.exitCode }),
+                ...(input.resourceIds ? { resourceIds: input.resourceIds } : {}),
+                ...(input.presentations ? { presentations: input.presentations } : {}),
+            });
+            if (attempt.outcome?.delivery === 'sending')
+                attempt = store.outcome(attempt.correlationId, caller, 'delivered');
+            return attempt;
+        },
+        async present() { },
+    };
+}
 /** Environment injected only into the managed harness process. */
 export function managedFleetProxyEnv(role, stateDir) {
     const roleEnv = { ...(role.env ?? {}) };
@@ -453,6 +492,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     const runCwd = role.cwd && existsSync(role.cwd) ? role.cwd : dir;
     const prep = await adapter.prepareSession(role, { stateDir: dir, runCwd });
     const sessionBackend = role.session ?? 'acp';
+    const sessionLabel = sessionBackend === 'acp' ? 'ACP' : 'Codex app-server';
     let launch = adapter.agentSession.prepareLaunch(role, prep);
     // Isolation is additive: only roles that declare `isolation:` are wrapped.
     let wrappedArgv = launch.argv;
@@ -532,6 +572,9 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         name, identity: role.identity, agentDir: dir, cfg: role.monitor,
         deps: resolvedMonitorDeps,
     }) : null;
+    const daemonObserver = new DaemonGenerationObserver();
+    const initialDaemon = daemonObserver.observe(await deps.probeGeneration(resolvedMonitorDeps.env));
+    let sessionStartedWithoutDaemonBaseline = initialDaemon.kind !== 'baseline';
     if (monitor)
         await monitor.prime({ resetCursor: resetMonitorCursor });
     rmSync(exitFile, { force: true });
@@ -540,13 +583,13 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     let control;
     let unsubscribeRecovery;
     let monitorLoop;
-    let acpStartupComplete = false;
+    let sessionStartupComplete = false;
     let sessionClosed = false;
     let ownerChannel;
     let ownerBinder;
-    const pendingFleetSpawnNotices = [];
     let loopManager;
     let arbiter;
+    let recoveryController;
     let reloadLoopConfig;
     let loopGeneration = JSON.stringify((role.loops ?? []).map(loop => [
         loop.name, loop.definitionHash, loop.promptHash,
@@ -571,7 +614,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         unsubscribeRecovery = agentSession.subscribe(event => {
             if (event.kind !== 'error' || !event.text)
                 return;
-            const evidence = classifyFailureText(event.text, 'acp', new Date(deps.now()).toISOString());
+            const evidence = classifyFailureText(event.text, sessionBackend, new Date(deps.now()).toISOString());
             if (evidence)
                 resolvedMonitorDeps.onFailureEvidence?.(evidence);
         });
@@ -596,33 +639,50 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                     + `${error?.message ?? String(error)}`);
             }
         }
-        control = deps.createControlServer(dir, arbiter, deps.log);
         try {
+            if (role.owner_channel)
+                ownerChannel = deps.createOwnerChannel({
+                    role: name,
+                    harness: role.harness,
+                    config: role.owner_channel,
+                    session: arbiter,
+                    stateDir: dir,
+                    env: role.env,
+                    log: deps.log,
+                    ...(ownerBinder ? { binderLease: ownerBinder } : {}),
+                    ...(configPath ? { configPath } : {}),
+                });
+            control = deps.createControlServer(dir, arbiter, deps.log);
+            control.setFleetAuditor(ownerChannel ? {
+                begin: (requestId, argv) => ownerChannel.beginFleetCommandAudit(requestId, argv),
+                finish: input => ownerChannel.finishFleetCommandAudit(input),
+                present: presentations => ownerChannel.notifyFleetLifecycle(presentations),
+            } : localFleetAuditor(dir, name, deps.log));
             await control.start();
         }
         catch (error) {
+            await ownerChannel?.close().catch(() => undefined);
             ownerBinder?.release();
             await agentSession.close();
             unsubscribeRecovery?.();
             throw error;
         }
-        control.setFleetSpawner(async (requested) => {
-            const event = await executeManagedSpawn(role, configPath, requested, deps.log);
-            if (!role.owner_channel)
-                return event;
-            if (ownerChannel?.notifyFleetSpawn) {
-                try {
-                    await ownerChannel.notifyFleetSpawn(event);
-                }
-                catch (error) {
-                    deps.log(`[${name}] spawned-agent owner notice failed: `
-                        + `${error?.message ?? String(error)}`);
+        if (!role.roomMemberStartup)
+            control.setFleetSpawner(async (requested) => {
+                const event = await executeManagedSpawn(role, configPath, requested, deps.log);
+                // Room-member launches are collected with their Task/Room transaction so
+                // causal delivery is Task → Room → Agents → Room active → Task active.
+                if (!requested.roomMemberStartup && role.owner_channel && ownerChannel?.notifyFleetSpawn) {
+                    try {
+                        await ownerChannel.notifyFleetSpawn(event);
+                    }
+                    catch (error) {
+                        deps.log(`[${name}] Agent lifecycle notice delivery failed: `
+                            + `${error?.message ?? String(error)}`);
+                    }
                 }
-            }
-            else
-                pendingFleetSpawnNotices.push(event);
-            return event;
-        });
+                return event;
+            });
         resolvedMonitorDeps.delivery = {
             // A wake is only delivered when its turn TERMINATES successfully. A
             // refusal or a cancellation reached the agent and was not acted on, so
@@ -633,7 +693,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 // steer into the live turn instead; after it completes, honor the
                 // configured interrupt policy normally.
                 const policy = options?.interrupt;
-                const interrupt = policy === true && acpStartupComplete;
+                const interrupt = policy === true && sessionStartupComplete;
                 const promptOptions = {
                     interrupt, steer: true,
                     ...(interrupt ? { interruptSource: 'fleet-monitor' } : {}),
@@ -641,7 +701,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 };
                 // Startup is already a protected boundary: as with immediate mode,
                 // steer rather than waiting on/cancelling the runner-owned first turn.
-                const result = policy === 'after_tool' && acpStartupComplete
+                const result = policy === 'after_tool' && sessionStartupComplete
                     ? await arbiter.submitPromptAfterTool(text, promptOptions)
                     : await arbiter.submitPrompt(text, promptOptions);
                 const steered = result.accepted
@@ -702,32 +762,21 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                     exit: {
                         version: 1,
                         class: 'program-exit',
-                        detail: `ACP startup triggered model recovery (${modelRecovery})`,
+                        detail: `${sessionLabel} startup triggered model recovery (${modelRecovery})`,
                     },
                     rotated: false,
                     mode,
                     modelRecovery,
                 };
             }
-            throw new Error(`[${name}] ACP startup prompt ${started.outcome}` +
+            throw new Error(`[${name}] ${sessionLabel} startup prompt ${started.outcome}` +
                 `${started.detail ? `: ${started.detail}` : ''}`);
         }
         if (interruptedForWake)
-            deps.log(`[${name}] ACP startup prompt cancelled by ${started.cancellationSource}; `
+            deps.log(`[${name}] ${sessionLabel} startup prompt cancelled by ${started.cancellationSource}; `
                 + 'keeping temporary supervisor alive');
-        acpStartupComplete = true;
-        if (role.owner_channel) {
-            ownerChannel = deps.createOwnerChannel({
-                role: name,
-                harness: role.harness,
-                config: role.owner_channel,
-                session: arbiter,
-                stateDir: dir,
-                env: role.env,
-                log: deps.log,
-                ...(ownerBinder ? { binderLease: ownerBinder } : {}),
-                ...(configPath ? { configPath } : {}),
-            });
+        sessionStartupComplete = true;
+        if (ownerChannel) {
             try {
                 await ownerChannel.start();
             }
@@ -743,18 +792,10 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 throw new Error(`[${name}] owner channel failed to start: `
                     + `${error?.message ?? String(error)}`);
             }
-            for (const event of pendingFleetSpawnNotices.splice(0)) {
-                try {
-                    await ownerChannel.notifyFleetSpawn?.(event);
-                }
-                catch (error) {
-                    deps.log(`[${name}] deferred spawned-agent owner notice failed: `
-                        + `${error?.message ?? String(error)}`);
-                }
-            }
         }
-        if (ownerChannel)
+        if (ownerChannel) {
             control.setOwnerChannel(ownerChannel);
+        }
         reloadLoopConfig = async () => {
             const nextRole = findRole(loadConfig(configPath), name);
             const definitions = nextRole.loops ?? [];
@@ -764,7 +805,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             if (generation === loopGeneration && (loopManager || !definitions.length))
                 return { changed: false, loops: definitions.length };
             if (!loopManager && definitions.length) {
-                loopManager = new ScheduledLoopManager(name, definitions, dir, arbiter, {
+                loopManager = deps.createLoopManager(name, definitions, dir, arbiter, {
                     now: deps.now,
                     setTimer: (callback, ms) => setTimeout(callback, ms),
                     clearTimer: timer => clearTimeout(timer),
@@ -780,10 +821,12 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             deps.log(`[${name}] scheduled loops reloaded (${definitions.length} definitions)`);
             return { changed: true, loops: definitions.length };
         };
-        control.setConfigReloader(reloadLoopConfig);
+        // Temporary agents are immutable launch snapshots: never re-resolve mutable Fleet YAML.
+        if (!temp)
+            control.setConfigReloader(reloadLoopConfig);
         if (role.loops?.length) {
             try {
-                loopManager = new ScheduledLoopManager(name, role.loops, dir, arbiter, {
+                loopManager = deps.createLoopManager(name, role.loops, dir, arbiter, {
                     now: deps.now,
                     setTimer: (callback, ms) => setTimeout(callback, ms),
                     clearTimer: timer => clearTimeout(timer),
@@ -793,6 +836,17 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 loopManager.start();
             }
             catch (error) {
+                if (temp) {
+                    monitor?.stop();
+                    if (monitorLoop)
+                        await monitorLoop;
+                    await control.close();
+                    ownerBinder?.release();
+                    await agentSession.close();
+                    unsubscribeRecovery?.();
+                    throw new Error(`[${name}] configured temporary loop manager failed to start: `
+                        + `${error?.message ?? String(error)}`);
+                }
                 deps.log(`[${name}] scheduled loop manager unavailable: ${error?.name ?? 'Error'}`);
             }
         }
@@ -801,16 +855,49 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     // The monitor loop lives exactly as long as the session: it starts once the
     // pane pid is known and is stopped when that pid dies (task dies with runner).
     monitorLoop ??= monitor?.run(pid);
+    recoveryController = new RoleRecoveryController({
+        role: name, identity: role.identity, stateDir: dir, now: deps.now, sleep: deps.sleep,
+        log: deps.log,
+        recoverAgent: async () => {
+            const evidence = await recoverAgentIdentity(arbiter, role.identity);
+            return evidence.ok ? { ok: true } : { ok: false, reason: evidence.reason };
+        },
+        recoverOwner: async (epoch) => {
+            if (!ownerChannel?.recover)
+                return { ok: true };
+            try {
+                await ownerChannel.recover(epoch);
+                return { ok: true };
+            }
+            catch (error) {
+                return { ok: false, reason: error instanceof Error
+                        ? `OWNER_${error.name.toUpperCase()}` : 'OWNER_UNKNOWN_ERROR' };
+            }
+        },
+    });
     const start = deps.now();
     let nextLoopReloadAt = deps.now() + 30_000;
     let nextIdentityPollAt = deps.now();
+    let nextDaemonProbeAt = deps.now();
     let lastReloadError = '';
     let identityObserved = false;
     let identityAbsentSince;
     let retirementReason;
+    let supervisorRecycleRequired = false;
     while (sessionHandle.isAlive()) {
         await deps.sleep(temp ? 500 : 2000);
         const now = deps.now();
+        if (now >= nextDaemonProbeAt) {
+            nextDaemonProbeAt = now + 2_000;
+            const observation = daemonObserver.observe(await deps.probeGeneration(resolvedMonitorDeps.env));
+            if (observation.kind === 'lost')
+                recoveryController.noteLoss(observation.reason);
+            if (observation.kind === 'changed' || observation.kind === 'available'
+                || (observation.kind === 'baseline' && sessionStartedWithoutDaemonBaseline)) {
+                sessionStartedWithoutDaemonBaseline = false;
+                void recoveryController.recover(observation.generation).catch(error => deps.log(`[${name}] daemon recovery controller failed: ${error?.name ?? 'Error'}`));
+            }
+        }
         if (temp && deps.shouldStop?.()) {
             retirementReason = requestedTempStopReason(dir) ?? 'supervisor-signal';
             deps.log(`[${name}] temporary supervisor retirement requested (${retirementReason})`);
@@ -861,6 +948,11 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         control?.setLoopManager(undefined);
         await loopManager.stop();
     }
+    // Let already-settled path operations publish their aggregate result before
+    // the shutdown fence invalidates the epoch. This never waits on I/O.
+    await Promise.resolve();
+    await Promise.resolve();
+    recoveryController?.cancel();
     control?.setConfigReloader(undefined);
     // Close the authenticated control route before releasing the binder lease;
     // otherwise the predecessor can unlink the replacement's new socket.
@@ -871,7 +963,12 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     }
     if (ownerChannel)
         await ownerChannel.close();
-    ownerBinder?.release();
+    if (ownerChannel?.binderReleaseSafe?.() === false) {
+        deps.log(`[${name}] owner binder retained because client quiescence was not proven at shutdown`);
+        supervisorRecycleRequired = true;
+    }
+    else
+        ownerBinder?.release();
     if (monitor) {
         monitor.stop();
         await monitorLoop;
@@ -895,7 +992,8 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         rotated = true;
         deps.log(`[${name}] ${why} -> rotated session-id; next start is FRESH`);
     };
-    if (exitRecord.detail.includes(ACP_CANCEL_DEADLINE_EXCEEDED))
+    if (exitRecord.detail.includes(ACP_CANCEL_DEADLINE_EXCEEDED)
+        || exitRecord.detail.includes(CODEX_APP_SERVER_CANCEL_DEADLINE_EXCEEDED))
         // This is a deliberate adapter reclamation, not evidence that resume state
         // is poisoned. Preserve the context even when the resumed generation hits
         // the same bound immediately; runSupervised still counts the fast exit and
@@ -920,6 +1018,8 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     }
     else
         deps.log(`[${name}] ${exitRecord.detail} (${elapsed.toFixed(0)}s) -> next start RESUMES context`);
+    if (supervisorRecycleRequired)
+        throw new SupervisorRecycleRequiredError();
     return {
         elapsedSecs: elapsed, exit: exitRecord, rotated, mode, modelRecovery,
         ...(retirementReason ? { retirementReason } : {}),
@@ -996,6 +1096,16 @@ export async function runSupervised(name, opts = {}, partialDeps = {}, attempt =
                 result = await attempt(name, { configPath: opts.configPath, allowResumeRotation: !ledger.resumeDiscarded }, deps);
             }
             catch (e) {
+                if (e instanceof SupervisorRecycleRequiredError) {
+                    writeRestartLedger(dir, {
+                        ...ledger,
+                        lastReason: SUPERVISOR_RECYCLE_REQUIRED,
+                        nextDelayMs: 0,
+                        updatedAt: stamp(),
+                    });
+                    deps.log(`[${name}] supervisor recycle required: ${SUPERVISOR_RECYCLE_REQUIRED}`);
+                    throw e;
+                }
                 // A session that could not even start is an immediate failure like any
                 // other; it must count, or an unstartable role loops forever.
                 result = {
@@ -1089,7 +1199,7 @@ function fastFailSecsFor(name, configPath) {
     }
 }
 /** Temp-agent entrypoint: run once, journal why it ended, then archive its evidence. */
-export async function runTemp(name, deps = {}) {
+export async function runTemp(name, deps = {}, attempt = runOnce) {
     const dir = agentDir(name, true);
     await markTempSupervisorActive(dir);
     let signal;
@@ -1100,7 +1210,7 @@ export async function runTemp(name, deps = {}) {
     let result;
     let failure;
     try {
-        result = await runOnce(name, { temp: true }, {
+        result = await attempt(name, { temp: true }, {
             ...deps,
             shouldStop: () => Boolean(signal) || (deps.shouldStop?.() ?? false),
         });
@@ -1114,6 +1224,7 @@ export async function runTemp(name, deps = {}) {
         const requested = requestedTempStopReason(dir);
         const reason = requested
             ?? result?.retirementReason
+            ?? (failure instanceof SupervisorRecycleRequiredError ? 'supervisor-recycle' : undefined)
             ?? (signal ? 'supervisor-signal' : failure ? 'startup-failure' : 'session-ended');
         // A service-manager stop can make the child connection close before the
         // runner reaches its normal loop. That is still a successful requested

package/dist/session/acp.d.ts

@@ -28,6 +28,8 @@ export declare function promptContentBlocks(text: string, origin?: PromptOrigin)
 export declare function runtimeSelector(options: acp.SessionConfigOption[] | null | undefined, category: string): RuntimeSelectorMetadata | undefined;
 export interface AcpSessionOptions {
     name: string;
+    /** Harness identity used only for honest optional capability reporting. */
+    harness?: string;
     argv: string[];
     cwd: string;
     env: Record<string, string>;
@@ -36,6 +38,11 @@ export interface AcpSessionOptions {
     permissions: CommonPermissions;
     /** Native permission-mode id to request via session/set_mode; undefined keeps the agent default. */
     modeId?: string;
+    /** Ordered explicit Brain choices that must be applied before readiness. */
+    configSelections?: Array<{
+        configId: string;
+        value: string;
+    }>;
     /** Adapter-resolved live permission policy; separate from ACP agent-specific session modes. */
     permissionMode?: NonNullable<SessionSnapshot['permissionMode']>;
     /** Adapter-authenticated request-metadata vocabulary; never inferred from ACP `_meta`. */
@@ -84,6 +91,7 @@ export declare function classifyStopReason(stopReason: string | undefined): Turn
 export declare class AcpSession implements AgentSession {
     private readonly options;
     readonly backend: "acp";
+    readonly capabilities: import("./types.js").AgentSessionCapabilities;
     readonly pid: number;
     private readonly child;
     private readonly events;
@@ -110,7 +118,7 @@ export declare class AcpSession implements AgentSession {
     private queueDepth;
     private exit;
     private steeringSupported;
-    private capabilities?;
+    private agentCapabilities?;
     private runtimeModel?;
     private reasoningEffort?;
     private controllerCount;

package/dist/session/acp.js

@@ -7,7 +7,7 @@ import * as acp from '@agentclientprotocol/sdk';
 import { normalizeSessionUpdate } from './conversation-normalizer.js';
 import { ConversationEventStore } from './conversation-store.js';
 import { SessionEvents } from './events.js';
-import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, classifyChildExit, turnResult, } from './types.js';
+import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, classifyChildExit, sessionBackendCapabilities, turnResult, } from './types.js';
 const CANCEL_SETTLE_GRACE_MS = 15_000;
 const CANCEL_TERMINATE_GRACE_MS = 5_000;
 /** A permission no human answered is eventually a decision nobody made. */
@@ -206,6 +206,7 @@ export function classifyStopReason(stopReason) {
 export class AcpSession {
     options;
     backend = 'acp';
+    capabilities;
     pid;
     child;
     events;
@@ -232,7 +233,7 @@ export class AcpSession {
     queueDepth = 0;
     exit = null;
     steeringSupported = false;
-    capabilities;
+    agentCapabilities;
     runtimeModel;
     reasoningEffort;
     controllerCount = 0;
@@ -265,6 +266,7 @@ export class AcpSession {
         this.child = child;
         this.connection = connection;
         this.pid = child.pid ?? -1;
+        this.capabilities = sessionBackendCapabilities('acp', options.harness);
         this.events = new SessionEvents(join(options.stateDir, '.session-events.jsonl'));
         this.conversation = new ConversationEventStore(join(options.stateDir, '.conversation'), {
             roleId: options.name, log: line => options.log(`[${options.name}] ${line}`),
@@ -994,7 +996,7 @@ export class AcpSession {
         for (const [permissionId, pending] of [...this.pendingPermissions])
             this.settlePendingAutomatically(permissionId, pending, 'cancelled', undefined, 'the session closed while this request was pending');
         this.releaseAllTools();
-        if (this.sessionId && this.capabilities?.sessionCapabilities?.close != null) {
+        if (this.sessionId && this.agentCapabilities?.sessionCapabilities?.close != null) {
             await this.connection.agent.request(acp.methods.agent.session.close, { sessionId: this.sessionId }).catch(() => undefined);
         }
         this.connection.close();
@@ -1020,23 +1022,25 @@ export class AcpSession {
         });
         if (initialized.protocolVersion !== acp.PROTOCOL_VERSION)
             throw new Error(`ACP protocol mismatch: agent selected ${initialized.protocolVersion}, client supports ${acp.PROTOCOL_VERSION}`);
-        this.capabilities = initialized.agentCapabilities;
+        this.agentCapabilities = initialized.agentCapabilities;
         const steering = initialized._meta?.steering;
         this.steeringSupported = steering !== null && typeof steering === 'object'
             && steering.supported === true;
         const persisted = this.options.mode === 'resume' && existsSync(this.sessionFile)
             ? readFileSync(this.sessionFile, 'utf8').trim()
             : '';
-        if (persisted && this.capabilities?.sessionCapabilities?.resume != null) {
+        let advertisedConfigOptions;
+        if (persisted && this.agentCapabilities?.sessionCapabilities?.resume != null) {
             const resumed = await this.connection.agent.request(acp.methods.agent.session.resume, {
                 sessionId: persisted,
                 cwd: this.options.cwd,
                 mcpServers: this.declaredMcpServers(),
             });
-            this.captureRuntimeMetadata(resumed.configOptions);
+            advertisedConfigOptions = resumed.configOptions;
+            this.captureRuntimeMetadata(advertisedConfigOptions);
             this.sessionId = persisted;
         }
-        else if (persisted && this.capabilities?.loadSession) {
+        else if (persisted && this.agentCapabilities?.loadSession) {
             // `session/load` replays prior history as ordinary updates before the
             // response; those records carry `agent_replay` provenance, never `agent`.
             this.replaying = true;
@@ -1046,7 +1050,8 @@ export class AcpSession {
                     cwd: this.options.cwd,
                     mcpServers: this.declaredMcpServers(),
                 });
-                this.captureRuntimeMetadata(loaded.configOptions);
+                advertisedConfigOptions = loaded.configOptions;
+                this.captureRuntimeMetadata(advertisedConfigOptions);
             }
             finally {
                 this.replaying = false;
@@ -1060,8 +1065,29 @@ export class AcpSession {
                 ...(this.options.sessionMeta ? { _meta: this.options.sessionMeta } : {}),
             });
             this.sessionId = created.sessionId;
-            this.captureRuntimeMetadata(created.configOptions);
+            advertisedConfigOptions = created.configOptions;
+            this.captureRuntimeMetadata(advertisedConfigOptions);
+        }
+        for (const selection of this.options.configSelections ?? []) {
+            if (!advertisedConfigOptions?.some(option => option.id === selection.configId))
+                throw new Error(`ACP agent did not advertise required session config option '${selection.configId}'`);
+            let configured;
+            try {
+                configured = await this.connection.agent.request(acp.methods.agent.session.setConfigOption, { sessionId: this.sessionId, configId: selection.configId, value: selection.value });
+            }
+            catch (error) {
+                throw new Error(`ACP agent refused required session config option '${selection.configId}' value '${selection.value}': `
+                    + (error instanceof Error ? error.message : String(error)));
+            }
+            advertisedConfigOptions = configured.configOptions;
+            this.captureRuntimeMetadata(advertisedConfigOptions);
+            const applied = advertisedConfigOptions.find(option => option.id === selection.configId);
+            if (applied?.currentValue !== selection.value)
+                throw new Error(`ACP agent did not apply required session config option '${selection.configId}' value '${selection.value}'`);
         }
+        // Do not persist a session until every required Brain choice is live. A
+        // failed startup closes the ACP session; persisting its id first would make
+        // a later resume repeatedly target that invalid session.
         writeFileSync(this.sessionFile, this.sessionId + '\n', { mode: 0o600 });
         // Deliver the configured permission mode whichever way the session came up
         // (new, resume or load) — the launch flag never reaches an ACP agent. A

package/dist/session/arbiter.d.ts

@@ -17,8 +17,9 @@ export type ScheduledAttempt = {
  */
 export declare class RoleTurnArbiter implements AgentSession {
     private readonly session;
-    readonly backend: "acp";
+    readonly backend: import("../config.js").SessionBackendId;
     readonly pid: number;
+    readonly capabilities: import("./types.js").AgentSessionCapabilities | undefined;
     private tail;
     private unsettled;
     private stopping;

package/dist/session/arbiter.js

@@ -25,6 +25,7 @@ export class RoleTurnArbiter {
     session;
     backend;
     pid;
+    capabilities;
     tail = Promise.resolve();
     unsettled = 0;
     stopping = false;
@@ -36,6 +37,7 @@ export class RoleTurnArbiter {
         this.session = session;
         this.backend = session.backend;
         this.pid = session.pid;
+        this.capabilities = session.capabilities;
     }
     /**
      * Waiters race the tail against their own generation's retirement, so a