@ours.network/fleet 1.0.5 → 1.1.0-nightly.10

package/dist/runner.js

@@ -5,16 +5,15 @@ import { parse } from 'yaml';
 import { agentDir, stateRoot } from './paths.js';
 import { loadConfig, findRole, isolationContextFor, resolveMonitorConfig, resolvePermissions, } from './config.js';
 import { getAdapter } from './harness/registry.js';
-import { Tmux } from './tmux.js';
 import { createMonitor, probeIdentityPresence, } from './monitor.js';
-import { realExec, shq } from './exec.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 { AcpSession } from './session/acp.js';
 import { controlRequest, RoleControlServer } from './session/control.js';
-import { TmuxSession } from './session/tmux.js';
 import { ACP_CANCEL_DEADLINE_EXCEEDED, classifyShellStatus } from './session/types.js';
 import { effectiveModelForRole, modelRecoveryHeld, reconcileModelRecovery, recordModelFailure, classifyFailureText, } from './model-recovery.js';
 import { rotateWorklog } from './worklog.js';
@@ -27,8 +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';
+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 = () => ({
-    tmux: new Tmux(),
     exec: realExec,
     cpuDelegated: () => cpuControllerDelegated(),
     isAlive: pid => { try {
@@ -42,9 +48,10 @@ 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),
-    startAcpSession: opts => AcpSession.start(opts),
+    startAgentSession: (adapter, options) => adapter.start(options),
     createControlServer: (stateDir, session, log) => new RoleControlServer(stateDir, session, log),
     acquireOwnerBinder: (stateDir, role, identity) => acquireOwnerBinderLease(stateDir, role, identity),
     reportOwnerStartupFailure: async (stateDir) => {
@@ -133,38 +140,10 @@ export function recordMonitorOwner(dir, owner) {
     catch { /* ownership diagnostics must never take the role down */ }
     return owner === 'fleet' && previous === 'native';
 }
-/**
- * Compose the tmux pane shell command: env prefix + argv + exit-status capture.
- * `paneArgv` defaults to `launch.argv`; when isolation is active the caller passes
- * the sandbox-wrapped argv (e.g. `bwrap … -- claude …`). The `env` prefix and the
- * `echo $? > exitfile` capture stay host-side, outside the sandbox, so the runner
- * still sees the real exit code.
- */
-export function buildPaneCommand(launch, roleEnv, exitStatusPath, paneArgv = launch.argv) {
-    const env = {
-        PATH: process.env.PATH ?? '', COLORTERM: 'truecolor', ...launch.env, ...(roleEnv ?? {}),
-    };
-    delete env[OBSOLETE_OURS_AUTOSTART_ENV];
-    // Interactive panes should advertise colour even when the supervisor itself
-    // was launched with NO_COLOR. A role may still deliberately opt back in to
-    // NO_COLOR (or replace COLORTERM) through its explicit env block.
-    const unsetNoColor = Object.prototype.hasOwnProperty.call(roleEnv ?? {}, 'NO_COLOR')
-        ? '' : '-u NO_COLOR ';
-    const envPfx = 'env -u OURS_AUTOSTART ' + unsetNoColor
-        + Object.entries(env).map(([k, v]) => `${k}=${shq(v)}`).join(' ');
-    const cmd = paneArgv.map(shq).join(' ');
-    // Write a structured record, not a bare number: the wait status alone cannot
-    // say whether the file is missing because the program never exited or because
-    // nothing ever wrote it. `printf` is POSIX; no shell branching is needed
-    // because classification happens in one place, in TypeScript.
-    const record = `'{"version":1,"backend":"tmux","status":'"$__ofs"'}'`;
-    return `${envPfx} ${cmd}; __ofs=$?; printf %s ${record} > ${shq(exitStatusPath)}`;
-}
 /** Adapt runner deps and the role's daemon-profile overrides for the monitor. */
 function monitorDeps(deps, roleEnv) {
     return {
         fetch: deps.fetch,
-        tmux: deps.tmux,
         isAlive: deps.isAlive,
         sleep: deps.sleep,
         now: deps.now,
@@ -484,16 +463,9 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     writeFileSync(bootedFile, `${new Date(deps.now()).toISOString()} ${mode}\n`);
     const runCwd = role.cwd && existsSync(role.cwd) ? role.cwd : dir;
     const prep = await adapter.prepareSession(role, { stateDir: dir, runCwd });
-    const sessionBackend = role.session ?? 'tmux';
-    let launch = sessionBackend === 'acp'
-        ? (() => {
-            if (!adapter.buildAcpLaunch)
-                throw new Error(`harness '${role.harness}' does not support the ACP session backend`);
-            return adapter.buildAcpLaunch(role, prep);
-        })()
-        : adapter.buildLaunch(role, mode, { sessionId }, prep);
-    // Isolation is additive: only roles that declare `isolation:` are wrapped. The
-    // env prefix + exit capture in buildPaneCommand stay host-side.
+    const sessionBackend = role.session ?? 'acp';
+    let launch = adapter.agentSession.prepareLaunch(role, prep);
+    // Isolation is additive: only roles that declare `isolation:` are wrapped.
     let wrappedArgv = launch.argv;
     if (role.isolation) {
         // Start with the same durable context that config validation and doctor judged,
@@ -530,7 +502,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     // user unit concurrently on boot; `ours-fleet up`/restart-all bulk-start) does not
     // hit the harness/API rate limit at once. Time-based via a shared launch gate, so
     // a lone start or a solo crash-restart waits zero. Applied right before the harness
-    // launch (tmux.newSession); the cheap monitor prime still runs immediately after.
+    // agent-session start; the cheap monitor prime still runs immediately after.
     if (staggerMs > 0) {
         const slot = await reserveLaunchSlot(stateRoot(), staggerMs, deps);
         const wait = slot - deps.now();
@@ -571,11 +543,14 @@ 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 });
     let pid;
-    let acpSession;
+    let agentSession;
     let control;
     let unsubscribeRecovery;
     let monitorLoop;
@@ -583,14 +558,14 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     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,
     ]));
-    if (sessionBackend === 'acp') {
+    {
         const perms = role.permissions ?? resolvePermissions(undefined, undefined);
         // Say once, at startup, that this role will decide permission requests by
         // itself. Without it the only trace of an auto-denied tool call is a turn
@@ -598,34 +573,16 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         if (perms.unattended === 'deny')
             deps.log(`[${name}] permission policy: unattended=deny — with no console attached, ` +
                 `permission requests are automatically denied once each (reject_once) and the turn continues`);
-        acpSession = await deps.startAcpSession({
-            name,
-            argv: wrappedArgv,
-            cwd: runCwd,
-            env: harnessChildEnv(role, launch.env, dir),
-            stateDir: dir,
-            mode,
-            permissions: perms,
-            modeId: adapter.acpPermissionModeId?.(role),
-            // The role's declared MCP servers, and the bundled agent's `_meta`
-            // vocabulary for the options it takes no flag for. Both come from the
-            // ADAPTER and from `prep`: the ACP launch cannot carry `prep.argv`, so this
-            // is the route by which harness_options that used to be silently dropped
-            // for an ACP role actually reach the session.
-            mcpServers: adapter.acpMcpServers?.(role),
-            sessionMeta: adapter.acpSessionMeta?.(role, prep),
-            permissionMode: effectivePermissionMode(role),
-            // Provenance travels with the exact ACP launch. Keeping it out of a
-            // role-only adapter hook prevents a PATH fallback or resolver skew from
-            // claiming metadata trust for an argv it did not authenticate.
-            permissionMetadataSource: launch.permissionMetadataSource,
-            scrubObsoleteOursAutostart: true,
-            log: deps.log,
+        agentSession = await deps.startAgentSession(adapter.agentSession, {
+            role, prep,
+            launch: { ...launch, argv: wrappedArgv, env: harnessChildEnv(role, launch.env, dir) },
+            cwd: runCwd, stateDir: dir, mode, permissions: perms,
+            permissionMode: effectivePermissionMode(role), log: deps.log,
         });
-        pid = acpSession.pid;
-        arbiter = new RoleTurnArbiter(acpSession);
+        pid = agentSession.pid;
+        arbiter = new RoleTurnArbiter(agentSession);
         sessionHandle = arbiter;
-        unsubscribeRecovery = acpSession.subscribe(event => {
+        unsubscribeRecovery = agentSession.subscribe(event => {
             if (event.kind !== 'error' || !event.text)
                 return;
             const evidence = classifyFailureText(event.text, 'acp', new Date(deps.now()).toISOString());
@@ -647,7 +604,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                             + `${notifyError?.message ?? String(notifyError)}`);
                     }
                 }
-                await acpSession.close();
+                await agentSession.close();
                 unsubscribeRecovery?.();
                 throw new Error(`[${name}] owner channel failed to start: `
                     + `${error?.message ?? String(error)}`);
@@ -659,25 +616,23 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         }
         catch (error) {
             ownerBinder?.release();
-            await acpSession.close();
+            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) {
+            // 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}] spawned-agent owner notice failed: `
+                    deps.log(`[${name}] Agent lifecycle notice delivery failed: `
                         + `${error?.message ?? String(error)}`);
                 }
             }
-            else
-                pendingFleetSpawnNotices.push(event);
             return event;
         });
         resolvedMonitorDeps.delivery = {
@@ -740,7 +695,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         const started = await starting;
         // A temporary role's first turn can be the active turn when an ours wake
         // needs immediate attention. A typed console/monitor cancellation ends
-        // only that turn: the already-live ACP session and any queued wake remain
+        // only that turn: the already-live agent session and any queued wake remain
         // valid. Keep every unproven cancellation, refusal, shutdown, and genuine
         // failure terminal so a role that never accepted its briefing is not
         // silently reported as healthy.
@@ -749,7 +704,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             monitor?.stop();
             await control.close();
             ownerBinder?.release();
-            await acpSession.close();
+            await agentSession.close();
             unsubscribeRecovery?.();
             if (modelRecovery) {
                 if (monitorLoop)
@@ -795,23 +750,19 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 await ownerChannel.close().catch(() => undefined);
                 await control.close();
                 ownerBinder?.release();
-                await acpSession.close();
+                await agentSession.close();
                 unsubscribeRecovery?.();
                 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);
+            control.setFleetAuditor({
+                begin: (requestId, argv) => ownerChannel.beginFleetCommandAudit(requestId, argv),
+                finish: input => ownerChannel.finishFleetCommandAudit(input),
+            });
+        }
         reloadLoopConfig = async () => {
             const nextRole = findRole(loadConfig(configPath), name);
             const definitions = nextRole.loops ?? [];
@@ -854,34 +805,53 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             }
         }
     }
-    else {
-        await deps.tmux.kill(name);
-        await deps.tmux.newSession(name, runCwd, buildPaneCommand(launch, role.env, exitFile, wrappedArgv));
-        let panePid = null;
-        for (let i = 0; i < 40 && panePid === null; i++) {
-            panePid = await deps.tmux.panePid(name);
-            if (panePid === null)
-                await deps.sleep(250);
-        }
-        if (panePid === null)
-            throw new Error(`[${name}] could not resolve tmux pane pid`);
-        pid = panePid;
-        sessionHandle = new TmuxSession(name, pid, deps.tmux, deps.isAlive);
-    }
     deps.log(`[${name}] up; pid=${pid} cwd=${runCwd} harness=${role.harness} session=${sessionBackend} mode=${mode}`);
     // 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})`);
@@ -899,7 +869,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             else if (presence.state === 'absent' && identityObserved) {
                 identityAbsentSince ??= now;
                 // Require a continuous, time-bounded run of authoritative absence.
-                // The first positive observation is the readiness gate: cold tmux
+                // The first positive observation is the readiness gate: cold harness
                 // starts may spend minutes loading the harness and briefing before the
                 // agent creates/binds its identity, and absence before then is not a
                 // close event. After readiness, debounce a real disappearance.
@@ -932,6 +902,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.
@@ -942,25 +917,25 @@ 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;
     }
     unsubscribeRecovery?.();
-    if (acpSession && !sessionClosed)
-        await acpSession.close();
+    if (agentSession && !sessionClosed)
+        await agentSession.close();
     const elapsed = (deps.now() - start) / 1000;
     // Establish what actually happened before deciding anything. Absence of a
     // record is `unknown` — except when the console itself is gone, which is a
     // different event with a different consequence.
-    const exitRecord = acpSession
-        ? acpSession.exitResult()
-            ?? { version: 1, class: 'unknown', detail: 'the ACP agent stopped without reporting an exit' }
-        : readExitRecord(exitFile)
-            ?? (await deps.tmux.has(name)
-                ? { version: 1, class: 'unknown', detail: 'the pane process ended without writing an exit record' }
-                : { version: 1, class: 'session-destroyed', detail: `the tmux session '${name}' no longer exists` });
+    const exitRecord = agentSession.exitResult()
+        ?? { version: 1, class: 'unknown', detail: 'the agent session stopped without reporting an exit' };
     writeFileSync(exitFile, JSON.stringify({
         ...exitRecord, at: new Date(deps.now()).toISOString(), elapsedSecs: Number(elapsed.toFixed(1)),
     }) + '\n');
@@ -996,6 +971,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 } : {}),
@@ -1072,6 +1049,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 = {
@@ -1165,7 +1152,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;
@@ -1176,7 +1163,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),
         });
@@ -1190,6 +1177,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/sensitive-config.d.ts

@@ -0,0 +1,2 @@
+/** Shared recursive configuration redaction boundary for operator-facing models. */
+export declare function isSensitiveConfigKey(key: string): boolean;

package/dist/sensitive-config.js

@@ -0,0 +1,4 @@
+/** Shared recursive configuration redaction boundary for operator-facing models. */
+export function isSensitiveConfigKey(key) {
+    return /(?:secret|token|password|credential|private[_-]?key|auth|invite|api[_-]?key)/i.test(key);
+}

package/dist/session/acp.d.ts

@@ -3,7 +3,7 @@ import type { CommonPermissions } from '../config.js';
 import type { AcpMcpServer } from '../harness/types.js';
 import { ConversationEventStore } from './conversation-store.js';
 import type { ConversationSnapshot, PromptOrigin, PromptReceipt, SubmitPromptCommand } from './conversation-types.js';
-import type { ConversationHandlePage, ExitRecord, InterruptOutcome, QueuedPrompt, SessionEvent, RuntimeSelectorMetadata, SessionHandle, SessionSnapshot, SubmitPromptOptions, TurnCancellationSource, TurnOutcome, TurnResult } from './types.js';
+import type { ConversationHandlePage, ExitRecord, InterruptOutcome, QueuedPrompt, SessionEvent, AgentSession, RuntimeSelectorMetadata, SessionSnapshot, SubmitPromptOptions, TurnCancellationSource, TurnOutcome, TurnResult } from './types.js';
 /** Bound safe-boundary waiting without turning a hung tool into cancellation. */
 export declare const AFTER_TOOL_BOUNDARY_TIMEOUT_MS = 120000;
 /**
@@ -36,6 +36,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`. */
@@ -81,7 +86,7 @@ export declare function classifyStopReason(stopReason: string | undefined): Turn
  * Persistent ACP v1 client. It is the sole owner of the agent's stdio; all
  * human/automation attachment happens through the fleet role-control protocol.
  */
-export declare class AcpSession implements SessionHandle {
+export declare class AcpSession implements AgentSession {
     private readonly options;
     readonly backend: "acp";
     readonly pid: number;

package/dist/session/acp.js

@@ -281,8 +281,7 @@ export class AcpSession {
                 clearTimeout(this.cancelForceKill);
             this.cancelForceKill = undefined;
             this.releaseSteeringOccupancy('adapter exited');
-            // Record the child's real exit code/signal. The tmux path can only see a
-            // shell's `$?`; here the truth is available, so keep it.
+            // Record the child's real exit code/signal while the truth is available.
             const classified = classifyChildExit(code, signal);
             this.exit = this.cancelRecoveryReason
                 ? { ...classified, detail: `${this.cancelRecoveryReason}; ${classified.detail}` }
@@ -1028,13 +1027,15 @@ export class AcpSession {
         const persisted = this.options.mode === 'resume' && existsSync(this.sessionFile)
             ? readFileSync(this.sessionFile, 'utf8').trim()
             : '';
+        let advertisedConfigOptions;
         if (persisted && this.capabilities?.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) {
@@ -1047,7 +1048,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;
@@ -1061,8 +1063,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
@@ -1476,7 +1499,7 @@ export class AcpSession {
             ...(normalized.adapterMeta ? { adapterMeta: normalized.adapterMeta } : {}),
         });
     }
-    // ── conversation ledger access (SessionHandle) ─────────────────────────────
+    // ── conversation ledger access (AgentSession) ─────────────────────────────
     conversationPage(request = {}) {
         const floor = Number(this.conversationStartCursor ?? 0);
         const requested = Number(request.after ?? 0);

package/dist/session/activity.d.ts

@@ -18,9 +18,8 @@ export interface ObservedActivity {
     lastUpdateAt?: string;
 }
 /**
- * Classify agent-side activity. `unobservable` is NOT `quiet`: a backend that
- * cannot see the agent (tmux) has no evidence, and no evidence must never be
- * reported as "doing nothing".
+ * Classify agent-side activity. `unobservable` is NOT `quiet`: absent evidence
+ * must never be reported as "doing nothing".
  */
 export declare function classifyActivity(activity: SessionActivity | undefined, now?: number): ObservedActivity;
 /**

package/dist/session/activity.js

@@ -11,9 +11,8 @@
  */
 export const ACTIVITY_WINDOW_MS = 60_000;
 /**
- * Classify agent-side activity. `unobservable` is NOT `quiet`: a backend that
- * cannot see the agent (tmux) has no evidence, and no evidence must never be
- * reported as "doing nothing".
+ * Classify agent-side activity. `unobservable` is NOT `quiet`: absent evidence
+ * must never be reported as "doing nothing".
  */
 export function classifyActivity(activity, now = Date.now()) {
     if (!activity)

package/dist/session/arbiter.d.ts

@@ -1,4 +1,4 @@
-import type { ConversationHandlePage, ExitRecord, InterruptOutcome, PromptOrigin, QueuedPrompt, SessionEvent, SessionHandle, SessionSnapshot, SubmitPromptOptions, TurnCancellationSource, TurnResult } from './types.js';
+import type { ConversationHandlePage, ExitRecord, InterruptOutcome, PromptOrigin, QueuedPrompt, SessionEvent, AgentSession, SessionSnapshot, SubmitPromptOptions, TurnCancellationSource, TurnResult } from './types.js';
 import type { ConversationEventV1, ConversationSnapshot, PromptReceipt, SubmitPromptCommand } from './conversation-types.js';
 export type ScheduledAttempt = {
     state: 'started';
@@ -15,9 +15,9 @@ export type ScheduledAttempt = {
  * producers retain ACP queue semantics while making their unsettled claim
  * visible before another producer can inspect idle state.
  */
-export declare class RoleTurnArbiter implements SessionHandle {
+export declare class RoleTurnArbiter implements AgentSession {
     private readonly session;
-    readonly backend: import("../config.js").SessionBackendId;
+    readonly backend: "acp";
     readonly pid: number;
     private tail;
     private unsettled;
@@ -26,7 +26,7 @@ export declare class RoleTurnArbiter implements SessionHandle {
     private generation;
     /** Resolves the instant the CURRENT generation is retired. */
     private retirement;
-    constructor(session: SessionHandle);
+    constructor(session: AgentSession);
     /**
      * Waiters race the tail against their own generation's retirement, so a
      * single operation that never settles cannot own the boundary forever. A