@ours.network/fleet 1.1.0-nightly.2 → 1.1.0-nightly.20

package/dist/rooms-tasks/terminal.js

@@ -2,10 +2,11 @@ import { join } from 'node:path';
 import { withFileLock } from '../atomic-file.js';
 import { stateRoot } from '../paths.js';
 import { deleteManagedRoom } from './close.js';
-import { beginTaskTerminalIntent, finishTaskTerminalIntent, getTask, setTaskTerminalIntentError, } from './task-state.js';
+import { assertNoPendingDeletion, beginTaskTerminalIntent, finishTaskTerminalIntent, getTask, setTaskTerminalIntentError, } from './task-state.js';
 import { getRoomRecord } from './room-state.js';
-const TASK_OPERATION_LOCK_STALE_MS = 10 * 60_000;
-function taskOperationLockPath(taskId) {
+export const TASK_OPERATION_LOCK_STALE_MS = 10 * 60_000;
+/** Common per-task operation lock serializing terminal, deletion, and recovery acceptance. */
+export function taskOperationLockPath(taskId) {
     return join(stateRoot(), 'locks', 'task-terminal', encodeURIComponent(taskId));
 }
 function errorText(error) {
@@ -24,6 +25,9 @@ export function acceptTaskTerminalIntent(input) {
 export function settleTaskTerminalIntent(input) {
     return withFileLock(taskOperationLockPath(input.taskId), async () => {
         const current = getTask(input.taskId);
+        // Deletion supersedes a pending terminal intent: fail boundedly before any
+        // room side effect so the deletion worker owns all remaining cleanup.
+        assertNoPendingDeletion(current);
         const intent = current.terminal_intent;
         if (!intent)
             throw new Error(`task ${input.taskId} has no accepted terminal intent`);

package/dist/rooms-tasks/types.d.ts

@@ -5,6 +5,7 @@
  * membership, and archive. Messenger Server owns owner presentation.
  * Fleet stores only IDs, CIDs, orchestration state, and saga cursors.
  */
+import type { AgentLaunchConfiguration } from '../lifecycle-summary.js';
 export type TaskState = 'backlog' | 'provisioning' | 'active' | 'review' | 'done' | 'cancelled' | 'failed';
 export declare const TASK_TERMINAL_STATES: readonly TaskState[];
 export declare const TASK_CANCELLABLE_STATES: readonly TaskState[];
@@ -44,6 +45,47 @@ export interface TaskTerminalIntent {
     first_failure?: string;
     first_recovery_hint?: string;
 }
+/** Origin evidence for an accepted deletion; retained until the record is unlinked. */
+export type TaskDeletionActor = {
+    kind: 'local_control';
+    surface: 'cli' | 'web';
+} | {
+    kind: 'authenticated_owner';
+    surface: 'messenger';
+    cid: string;
+};
+export type TaskDeletionMemberPhase = 'pending' | 'stop_requested' | 'liveness_absent' | 'archive_secured' | 'identity_absent';
+/**
+ * Durable retirement cursor for a managed member when no room orchestration
+ * record exists to carry the equivalent seat cursor.
+ */
+export interface TaskDeletionMemberCursor {
+    name: string;
+    identity_cid: string;
+    phase: TaskDeletionMemberPhase;
+    launch_id?: string;
+    archive_path?: string;
+    updated_at: string;
+}
+/**
+ * First-wins durable deletion intent. There is no settled status: settlement
+ * ends by unlinking the task record, so physical absence is the completion
+ * evidence. While pending, the task is hidden from normal operation and every
+ * lifecycle mutation or room publication is rejected.
+ */
+export interface TaskDeletionIntent {
+    status: 'pending';
+    accepted_at: string;
+    actor: TaskDeletionActor;
+    room_id?: string;
+    /** Snapshot of managed members at acceptance; the missing-room retirement evidence. */
+    members: TaskDeletionMemberCursor[];
+    error?: string;
+    error_at?: string;
+    recovery_hint?: string;
+    first_failure?: string;
+    first_recovery_hint?: string;
+}
 export interface TaskRecord {
     task_id: string;
     /** Stable organizational list identifier. Missing legacy values mean `default`. */
@@ -56,6 +98,14 @@ export interface TaskRecord {
     state: TaskState;
     blocked?: TaskBlocked;
     template?: TaskTemplateRef;
+    execution_plan?: {
+        schema_version: 1;
+        snapshot: TemplateSnapshot;
+        room_policy?: RoomLaunchPolicy;
+        overrides: Record<string, unknown>;
+        overrides_hash: string;
+        plan_hash: string;
+    };
     no_room?: boolean;
     room_id?: string;
     room_identity_cid?: string;
@@ -67,6 +117,7 @@ export interface TaskRecord {
     ended_at?: string;
     outcome?: TaskOutcome;
     terminal_intent?: TaskTerminalIntent;
+    deletion?: TaskDeletionIntent;
 }
 export interface TaskListRecord {
     list_id: string;
@@ -100,6 +151,16 @@ export interface RoomMemberLaunchState {
     /** Expected authenticated proxy caller while adopting a post-spawn crash. */
     caller_role?: string;
     mission_sha256?: string;
+    /** Redacted, deterministic effective Agent launch definition retained for retry inspection. */
+    agent_definition?: Record<string, unknown>;
+    agent_fingerprint?: string;
+    agent_template?: string;
+    agent_template_hash?: string;
+    /**
+     * Operator-facing launch configuration captured from the exact resolved
+     * launch state; the single source for later Task/Room lifecycle reports.
+     */
+    presentation?: AgentLaunchConfiguration;
     launch_id?: string;
     updated_at: string;
     error?: string;
@@ -172,6 +233,8 @@ export interface RoomOrchestrationRecord {
     goal?: string;
     task_id?: string;
     template_snapshot?: TemplateSnapshot;
+    /** Resolved once at launch; legacy absence means non-anonymous. */
+    room_policy?: RoomLaunchPolicy;
     saga: SagaCursor;
     provisioning_detail?: ProvisioningDetail;
     owner_seat_cid?: string;
@@ -189,35 +252,48 @@ export interface TemplateMemberSlot {
     slot: string;
     role: string;
     count: number;
-    role_ref: string;
-    overrides?: TemplateRoleOverrides;
-}
-export interface TemplateRoleOverrides {
-    harness?: string;
-    model?: string;
-    model_chain?: string[];
-    permissions?: Record<string, unknown>;
-    isolation?: Record<string, unknown>;
-    cwd?: string;
-    env?: Record<string, string>;
-    persona?: string;
-    mission?: string;
+    /** Stable reference to an inert Agent Template, never a persistent Agent. */
+    agent_template: string;
 }
 export interface TemplateRoomConfig {
     quiet_membership?: boolean;
     anonymous?: boolean;
 }
+export interface RoomLaunchPolicy {
+    anonymous: boolean;
+}
+export declare const LEGACY_ROOM_LAUNCH_POLICY: Readonly<RoomLaunchPolicy>;
+/** Validate durable policy before it can influence room creation or recovery. */
+export declare function storedRoomLaunchPolicy(value: RoomLaunchPolicy | undefined): RoomLaunchPolicy;
 export interface TemplateDefinition {
     name: string;
     version: number;
     description: string;
-    builtin?: boolean;
+    /** Authoring provenance only; excluded from snapshots and semantic hashes. */
+    sourceFile?: string;
     room?: TemplateRoomConfig;
     contract?: string;
     members: TemplateMemberSlot[];
 }
-export interface TemplateSnapshot extends TemplateDefinition {
+export interface TemplateSnapshotMember extends TemplateMemberSlot {
+    /** Secret-safe public projection; launch material lives in the sealed snapshot. */
+    agent_projection?: Record<string, unknown>;
+    agent_template_hash?: string;
+    /** Private sealed-snapshot lookup key; harmless provenance, not an identity. */
+    launch_definition_id?: string;
+    role_preset?: {
+        id: string;
+        hash: string;
+    };
+    brain_preset?: {
+        id: string;
+        hash: string;
+    };
+}
+export interface TemplateSnapshot extends Omit<TemplateDefinition, 'members'> {
+    members: TemplateSnapshotMember[];
     content_hash: string;
+    launch_snapshot_hash?: string;
 }
 export interface RoomsOwnerConfig {
     provider: string;
@@ -252,5 +328,6 @@ export declare const ROOMS_COWORK_KEYS: readonly ["config"];
 export declare const ROOMS_DEFAULTS_KEYS: readonly ["template", "attach_owner", "close_when_task_done"];
 export declare const TASKS_KEYS: readonly ["default_room_template", "create_mode", "close_room_on_done", "retain_completed_for"];
 export declare const TEMPLATE_KEYS: readonly ["version", "description", "room", "contract", "members", "override_builtin"];
-export declare const TEMPLATE_MEMBER_KEYS: readonly ["slot", "role", "count", "role_ref", "overrides"];
-export declare const TEMPLATE_OVERRIDE_KEYS: readonly ["harness", "model", "model_chain", "permissions", "isolation", "cwd", "env", "persona", "mission"];
+export declare const TEMPLATE_ROOM_KEYS: readonly ["quiet_membership", "anonymous"];
+/** `agent` is accepted only so validation can emit its actionable migration error. */
+export declare const TEMPLATE_MEMBER_KEYS: readonly ["slot", "role", "count", "agent_template", "agent"];

package/dist/rooms-tasks/types.js

@@ -7,6 +7,17 @@
  */
 export const TASK_TERMINAL_STATES = ['done', 'cancelled', 'failed'];
 export const TASK_CANCELLABLE_STATES = ['backlog', 'provisioning', 'active', 'review'];
+export const LEGACY_ROOM_LAUNCH_POLICY = Object.freeze({
+    anonymous: false,
+});
+/** Validate durable policy before it can influence room creation or recovery. */
+export function storedRoomLaunchPolicy(value) {
+    if (value === undefined)
+        return { ...LEGACY_ROOM_LAUNCH_POLICY };
+    if (typeof value.anonymous !== 'boolean')
+        throw new Error('invalid durable Room launch policy; anonymous must be a boolean');
+    return { ...value };
+}
 // ── Validation keys ─────────────────────────────────────────────────────
 export const ROOMS_KEYS = ['cowork', 'owner', 'defaults'];
 export const ROOMS_OWNER_KEYS = ['provider', 'public_invite', 'public_invite_file', 'expected_cid', 'role'];
@@ -14,7 +25,6 @@ export const ROOMS_COWORK_KEYS = ['config'];
 export const ROOMS_DEFAULTS_KEYS = ['template', 'attach_owner', 'close_when_task_done'];
 export const TASKS_KEYS = ['default_room_template', 'create_mode', 'close_room_on_done', 'retain_completed_for'];
 export const TEMPLATE_KEYS = ['version', 'description', 'room', 'contract', 'members', 'override_builtin'];
-export const TEMPLATE_MEMBER_KEYS = ['slot', 'role', 'count', 'role_ref', 'overrides'];
-export const TEMPLATE_OVERRIDE_KEYS = [
-    'harness', 'model', 'model_chain', 'permissions', 'isolation', 'cwd', 'env', 'persona', 'mission',
-];
+export const TEMPLATE_ROOM_KEYS = ['quiet_membership', 'anonymous'];
+/** `agent` is accepted only so validation can emit its actionable migration error. */
+export const TEMPLATE_MEMBER_KEYS = ['slot', 'role', 'count', 'agent_template', 'agent'];

package/dist/runner.d.ts

@@ -1,5 +1,6 @@
 import { type ResolvedRole } from './config.js';
 import { type MonitorHandle, type MonitorOpts, type FetchLike } from './monitor.js';
+import { type DaemonGenerationProbe } from './daemon-recovery.js';
 import { type Exec } from './exec.js';
 import { RoleControlServer } from './session/control.js';
 import type { AgentSession, ExitRecord, TurnResult } from './session/types.js';
@@ -15,6 +16,7 @@ export interface RunnerDeps {
     log(line: string): void;
     /** HTTP transport for the monitor's daemon long-poll (injectable for tests). */
     fetch: FetchLike;
+    probeGeneration(env: NodeJS.ProcessEnv): Promise<DaemonGenerationProbe>;
     /** Construct the supervisor mail monitor (injectable so tests stub it out). */
     createMonitor(opts: MonitorOpts): MonitorHandle;
     /** Construct trusted owner ingress (injectable for lifecycle tests). */
@@ -23,7 +25,7 @@ export interface RunnerDeps {
     /** Neutral construction seam for deterministic runner lifecycle tests. */
     startAgentSession(adapter: AgentSessionAdapter, options: AgentSessionStartOptions): Promise<AgentSession>;
     /** Construct the authenticated role control route (injectable where sockets are unavailable). */
-    createControlServer(stateDir: string, session: AgentSession, log: (line: string) => void): Pick<RoleControlServer, 'start' | 'close' | 'setFleetSpawner' | 'setOwnerChannel' | 'setConfigReloader' | 'setLoopManager'>;
+    createControlServer(stateDir: string, session: AgentSession, log: (line: string) => void): Pick<RoleControlServer, 'start' | 'close' | 'setFleetSpawner' | 'setFleetAuditor' | 'setOwnerChannel' | 'setConfigReloader' | 'setLoopManager'>;
     /** Acquire the cross-process owner-channel binder lease before replacing the control socket. */
     acquireOwnerBinder(stateDir: string, role: string, identity: string): Promise<OwnerBinderLease>;
     /** Ask the still-authenticated predecessor to emit the fixed recovery notice. */
@@ -31,6 +33,11 @@ export interface RunnerDeps {
     /** Lets a test (or a shutdown path) end the supervised restart loop. */
     shouldStop?(): boolean;
 }
+export declare const SUPERVISOR_RECYCLE_REQUIRED = "OWNER_CHANNEL_SUPERVISOR_RECYCLE_REQUIRED";
+export declare class SupervisorRecycleRequiredError extends Error {
+    readonly code = "OWNER_CHANNEL_SUPERVISOR_RECYCLE_REQUIRED";
+    constructor();
+}
 /** Environment injected only into the managed harness process. */
 export declare function managedFleetProxyEnv(role: ResolvedRole, stateDir: string): Record<string, string>;
 /**
@@ -176,4 +183,4 @@ export declare function runSupervised(name: string, opts?: {
     allowResumeRotation?: boolean;
 }, d: Partial<RunnerDeps>) => Promise<AttemptResult>): Promise<RestartLedger>;
 /** Temp-agent entrypoint: run once, journal why it ended, then archive its evidence. */
-export declare function runTemp(name: string, deps?: Partial<RunnerDeps>): Promise<void>;
+export declare function runTemp(name: string, deps?: Partial<RunnerDeps>, attempt?: typeof runOnce): Promise<void>;

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,14 @@ 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 = () => ({
     exec: realExec,
     cpuDelegated: () => cpuControllerDelegated(),
@@ -38,6 +48,7 @@ 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),
@@ -453,6 +464,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 +544,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 +555,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 +586,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);
         });
@@ -606,23 +621,22 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             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 +647,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 +655,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,20 +716,20 @@ 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;
+        sessionStartupComplete = true;
         if (role.owner_channel) {
             ownerChannel = deps.createOwnerChannel({
                 role: name,
@@ -743,18 +757,14 @@ 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);
+            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 ?? [];
@@ -801,16 +811,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 +904,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 +919,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 +948,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 +974,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 +1052,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 +1155,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 +1166,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 +1180,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;