@scotthuang/agent-knock-knock 0.13.2 → 0.13.4

package/dist/src/native-thread-lifecycle-cli-adapter.js

@@ -12,6 +12,8 @@ import { isSessionSendBlockingStatus, turnIdForConversation } from "./protocol.j
 import { listManagedSessions, loadNativeThreadTransition } from "./session-store.js";
 import { isExactClaudeNativeInspectionIdleComposer, NativeInspectionSubmissionError } from "./terminal-agent-bridge.js";
 import { terminalControlAliasMatches, selectRootTerminalProcesses, withCodexCompanionFences } from "./terminal-authority-policy.js";
+import { decideModelControlAvailability } from "./terminal-model-control-availability.js";
+import { CODEX_MODEL_CONTROL_AGENT_VERSION, isTerminalModelControlPlanForAgent, isTerminalModelReasoningEffort, terminalModelControlPlanConforms, terminalModelControlProfileForPlan, terminalUserExplicitModelControlBindingToken } from "./terminal-model-control.js";
 import { nonBlankString } from "./value-guards.js";
 export const CODEX_FOREGROUND_IDENTIFICATION_TTL_MS = 30_000;
 export const CODEX_FOREGROUND_IDENTIFICATION_SCROLLBACK_LINES = 240;
@@ -26,6 +28,9 @@ export function createNativeThreadLifecycleCliAdapter(ports) {
         agentAdapter: (options, agent) => app.agentAdapter(options, agent),
         runList: (options) => app.runList(options),
         runInspect: (options) => app.runInspect(options),
+        runModelOptions: (options) => app.runModelOptions(options),
+        runSetModel: (options) => app.runSetModel(options),
+        runRepairModelControl: (options) => app.runRepairModelControl(options),
         runIdentifyForeground: (options) => app.runIdentifyForeground(options),
         identifyCodexForegroundWhileLocked: (input) => app.identifyCodexForegroundWhileLocked(input),
         assertSameInspectionTerminal: (expected, actual, stage) => app.assertSameInspectionTerminal(expected, actual, stage),
@@ -216,6 +221,50 @@ class NativeThreadLifecycleCliApplication {
             bindingToken: bindingTokens[0], bindingTokens
         });
     }
+    /**
+     * Model control on Codex is an explicit physical-pane operation. A freshly
+     * started TUI may legitimately have no rollout-backed Session yet. Keep the
+     * physical token separate from native lifecycle binding while retaining the
+     * resolver's fail-closed behavior for genuinely ambiguous live rollouts.
+     */
+    async modelControlSnapshot(options, terminal) {
+        if (terminal.agent !== "codex") {
+            return this.currentSnapshot(options, terminal);
+        }
+        const snapshot = await this.currentSnapshot(options, terminal);
+        const nativeThreadId = snapshot.identity?.sessionId ??
+            snapshot.session?.binding?.native_thread_id;
+        if (isExactNativeThreadId(nativeThreadId) ||
+            snapshot.identity || snapshot.session) {
+            return snapshot;
+        }
+        const adapter = this.agentAdapter(options, terminal.agent);
+        const { capability, plan, profile } = modelControlProfileObservation(adapter, snapshot.version);
+        if (!plan || profile?.agent !== "codex" ||
+            !profile.supportsZeroRolloutPhysicalAuthority) {
+            throw new Error(capability?.reason ?? "Codex has no verified physical model-control profile");
+        }
+        const bindingToken = this.physicalModelControlBindingToken(terminal, snapshot.version, plan.behaviorProfile);
+        return Object.freeze({
+            ...snapshot,
+            bindingToken,
+            bindingTokens: Object.freeze([bindingToken])
+        });
+    }
+    physicalModelControlBindingToken(terminal, agentVersion, behaviorProfile) {
+        const version = required(nonBlankString(agentVersion), "Codex physical model control requires an exact running version");
+        const incarnation = this.ports.identity.physicalProcessIncarnation(terminal.pid);
+        return terminalUserExplicitModelControlBindingToken({
+            terminalId: terminal.conversationId,
+            terminalControl: terminal.terminalControl,
+            pid: terminal.pid,
+            workspace: terminal.terminalControl.currentPath ?? this.ports.output.cwd(),
+            processUuid: incarnation.processUuid,
+            processBirth: incarnation.processBirth,
+            agentVersion: version,
+            behaviorProfile
+        });
+    }
     async runList(options) {
         const terminal = await this.resolveLifecycleTerminal(options);
         const snapshot = await this.currentSnapshot(options, terminal);
@@ -537,7 +586,7 @@ class NativeThreadLifecycleCliApplication {
         const terminal = await bridge.resolveStoredTerminal("codex", input.terminal.pid, input.terminal.terminalControl, physicalRuntime);
         this.assertSameInspectionTerminal(input.terminal, terminal, "while waiting for foreground-identification control");
         const realCwd = this.realForegroundWorkspace(terminal);
-        const processIncarnation = this.ports.identity.processIncarnation(terminal.pid);
+        const processIncarnation = this.ports.identity.physicalProcessIncarnation(terminal.pid);
         this.assertForegroundPhysicalToken({
             terminal,
             processIncarnation,
@@ -659,7 +708,7 @@ class NativeThreadLifecycleCliApplication {
         if (this.realForegroundWorkspace(input.terminal) !== boundary.realCwd) {
             throw new Error(`terminal real cwd changed ${input.stage}; refresh AKK list`);
         }
-        const processIncarnation = this.ports.identity.processIncarnation(input.terminal.pid);
+        const processIncarnation = this.ports.identity.physicalProcessIncarnation(input.terminal.pid);
         if (processIncarnation.processUuid !== boundary.processUuid ||
             processIncarnation.processBirth !== boundary.processBirth) {
             throw new Error(`Codex process incarnation changed ${input.stage}; refresh AKK list`);
@@ -735,6 +784,567 @@ class NativeThreadLifecycleCliApplication {
                 "native-thread transition");
         }
     }
+    validateModelOptions(options) {
+        if (options.command !== undefined || options.message !== undefined ||
+            options.model !== undefined || options.reasoningEffort !== undefined ||
+            options.expectedCatalogFingerprint !== undefined) {
+            throw new Error("model-options accepts only an exact terminal and current binding authority");
+        }
+        return required(nonBlankString(options.expectedBindingToken), "--expected-binding-token is required");
+    }
+    validateSetModel(options) {
+        if (options.command !== undefined || options.message !== undefined ||
+            options.scope !== undefined || options.keys !== undefined ||
+            options.index !== undefined) {
+            throw new Error("set-model accepts no command, key, menu index, or caller-selected scope");
+        }
+        const expectedBindingToken = required(nonBlankString(options.expectedBindingToken), "--expected-binding-token is required");
+        const expectedCatalogFingerprint = required(nonBlankString(options.expectedCatalogFingerprint), "--expected-catalog-fingerprint is required");
+        if (!/^[0-9a-f]{64}$/u.test(expectedCatalogFingerprint)) {
+            throw new Error("--expected-catalog-fingerprint must be the exact sha256 from model-options");
+        }
+        const model = required(nonBlankString(options.model), "--model is required");
+        const reasoningEffort = options.reasoningEffort;
+        if (!isTerminalModelReasoningEffort(reasoningEffort)) {
+            throw new Error("--reasoning-effort must be one exact semantic value advertised by model-options");
+        }
+        return {
+            expectedBindingToken,
+            expectedCatalogFingerprint,
+            request: { model, reasoningEffort }
+        };
+    }
+    validateRepairModelControl(options) {
+        if (options.command !== undefined ||
+            options.message !== undefined ||
+            options.model !== undefined ||
+            options.reasoningEffort !== undefined ||
+            options.expectedCatalogFingerprint !== undefined ||
+            options.scope !== undefined ||
+            options.keys !== undefined ||
+            options.index !== undefined) {
+            throw new Error("repair-model-control accepts only an exact terminal and current private repair authority");
+        }
+        return required(nonBlankString(options.expectedBindingToken), "--expected-binding-token is required");
+    }
+    async runModelOptions(options) {
+        const expectedBindingToken = this.validateModelOptions(options);
+        const context = await this.withPreparedModelControl(options, expectedBindingToken, async (prepared) => {
+            const result = await prepared.bridge.modelOptions(prepared.terminal.agent, prepared.terminal.terminalControl, prepared.agentVersion, prepared.plan, {
+                runtime: prepared.runtime,
+                beforeInput: () => prepared.initialResidual
+                    ? this.assertFreshModelControlResidualBoundary(prepared)
+                    : this.assertFreshModelControlBoundary(prepared),
+                loadCodexCatalog: prepared.loadCodexCatalog,
+                initialResidual: prepared.initialResidual
+            });
+            if (prepared.initialResidual) {
+                await this.assertFreshModelControlBoundary({
+                    ...prepared,
+                    expectedBindingToken: prepared.ordinaryBindingToken,
+                    initialResidual: undefined
+                });
+            }
+            return { prepared, catalog: result.catalog };
+        }, { allowResidualEntry: true });
+        this.ports.output.print(this.modelOptionsResult(context.prepared, context.catalog));
+    }
+    async runSetModel(options) {
+        const validated = this.validateSetModel(options);
+        const output = await this.withPreparedModelControl(options, validated.expectedBindingToken, async (prepared) => {
+            const result = await prepared.bridge.setModel(prepared.terminal.agent, prepared.terminal.terminalControl, prepared.agentVersion, prepared.plan, validated.expectedCatalogFingerprint, validated.request, {
+                runtime: prepared.runtime,
+                beforeInput: () => this.assertFreshModelControlBoundary(prepared),
+                loadCodexCatalog: prepared.loadCodexCatalog
+            });
+            return { prepared, result };
+        });
+        const { result, prepared } = output;
+        this.ports.output.print({
+            terminal_id: prepared.terminal.conversationId,
+            agent: prepared.terminal.agent,
+            agent_version: prepared.agentVersion,
+            behavior_profile: prepared.plan.behaviorProfile,
+            outcome: result.outcome,
+            requested: modelValueOutput(result.requested),
+            ...(result.effective
+                ? { effective: modelValueOutput(result.effective) }
+                : {}),
+            ...(result.newSessionDefaults
+                ? { new_session_defaults: modelValueOutput(result.newSessionDefaults) }
+                : {}),
+            scope: result.scope,
+            defaults_changed: result.defaultsChanged,
+            do_not_retry: result.doNotRetry,
+            ...(result.reason ? { reason: result.reason } : {})
+        });
+    }
+    async runRepairModelControl(options) {
+        const expectedBindingToken = this.validateRepairModelControl(options);
+        const output = await this.withPreparedModelControlRepair(options, expectedBindingToken, async (prepared) => {
+            const result = await prepared.bridge.repairModelControlResidual(prepared.terminal.agent, prepared.terminal.terminalControl, prepared.agentVersion, prepared.plan, prepared.residual.fingerprint, {
+                runtime: prepared.runtime,
+                beforeInput: () => this.assertFreshModelControlResidualBoundary(prepared)
+            });
+            return { prepared, result };
+        });
+        this.ports.output.print({
+            terminal_id: output.prepared.terminal.conversationId,
+            agent: output.prepared.terminal.agent,
+            agent_version: output.prepared.agentVersion,
+            behavior_profile: output.prepared.plan.behaviorProfile,
+            outcome: output.result.outcome,
+            terminal_input_attempted: output.result.terminalInputAttempted,
+            composer_postcondition: output.result.composerPostcondition,
+            do_not_retry: output.result.doNotRetry,
+            ...(output.result.reason ? { reason: output.result.reason } : {}),
+            ...(output.result.outcome === "repaired"
+                ? { next: "refresh_list_then_model_options" }
+                : {})
+        });
+    }
+    async withPreparedModelControlRepair(options, expectedBindingToken, operation) {
+        const storeDir = this.ports.state.storeDir(options);
+        if (this.ports.state.inspectStore(storeDir).writable !== true) {
+            throw new Error("model-control repair requires a compatible AKK Store for current-snapshot authority");
+        }
+        const initiallyResolved = await this.resolveLifecycleTerminal(options);
+        const release = this.ports.state.acquireTerminal(storeDir, initiallyResolved.terminalControl, { timeoutMs: 30_000 });
+        try {
+            const runtimeFacade = this.ports.runtime.forOptions(options);
+            const bridge = runtimeFacade.createBridge();
+            const terminal = await bridge.resolveStoredTerminal(initiallyResolved.agent, initiallyResolved.pid, initiallyResolved.terminalControl, { pid: initiallyResolved.pid });
+            this.assertSameInspectionTerminal(initiallyResolved, terminal, "while waiting for model-control repair ownership");
+            if (terminal.agent !== "codex") {
+                throw new Error("model-control residual repair currently supports only Codex " +
+                    CODEX_MODEL_CONTROL_AGENT_VERSION);
+            }
+            const snapshot = await this.modelControlSnapshot(options, terminal);
+            const agentVersion = required(nonBlankString(snapshot.version), "model-control repair requires an exact running agent version");
+            const adapter = runtimeFacade.createAgentRegistry().require(terminal.agent);
+            const { capability, plan, profile } = modelControlProfileObservation(adapter, agentVersion);
+            if (!plan || profile?.agent !== "codex" ||
+                !profile.supportsResidualRepair) {
+                throw new Error(capability?.reason ??
+                    "the running Codex version has no verified model-control repair profile");
+            }
+            await this.assertModelControlExclusive({ options, terminal, snapshot });
+            const runtime = this.inspectionRuntime(terminal, snapshot);
+            const status = await this.assertModelControlRepairReady({
+                options,
+                terminal,
+                snapshot,
+                bridge,
+                runtime
+            });
+            const residual = await bridge.inspectModelControlResidual(terminal.agent, terminal.terminalControl, agentVersion, plan, { runtime, beforeInput: () => undefined });
+            if (residual.state !== "recoverable") {
+                throw new Error(residual.reason);
+            }
+            const availability = this.modelControlAvailability({
+                options,
+                terminal,
+                snapshot,
+                agentVersion,
+                plan,
+                status,
+                surface: {
+                    kind: "residual",
+                    residualKind: residual.kind,
+                    residualFingerprint: residual.fingerprint,
+                    activityState: status.activity_state
+                }
+            });
+            const repairBindingToken = availability.availability === "residual_continuation"
+                ? availability.repairBindingToken
+                : availability.availability === "repair_only"
+                    ? availability.expectedBindingToken
+                    : undefined;
+            if (repairBindingToken !== expectedBindingToken) {
+                throw new Error("the exact model-control residual changed after it was listed; refresh AKK list");
+            }
+            return await operation({
+                options,
+                terminal,
+                snapshot,
+                bridge,
+                runtime,
+                adapter,
+                agentVersion,
+                plan,
+                expectedBindingToken,
+                residual
+            });
+        }
+        finally {
+            release();
+        }
+    }
+    async assertFreshModelControlResidualBoundary(context) {
+        const terminal = await this.resolveModelControlBoundaryTerminal(context);
+        this.assertSameInspectionTerminal(context.terminal, terminal, "immediately before model-control repair input");
+        const snapshot = await this.modelControlSnapshot(context.options, terminal);
+        if (snapshot.version !== context.agentVersion) {
+            throw new Error("terminal binding or coding-agent version changed during model-control repair");
+        }
+        const expectedNativeThreadId = context.snapshot.identity?.sessionId ??
+            context.snapshot.session?.binding?.native_thread_id;
+        const actualNativeThreadId = snapshot.identity?.sessionId ??
+            snapshot.session?.binding?.native_thread_id;
+        if (expectedNativeThreadId !== actualNativeThreadId) {
+            throw new Error("the current native Session changed during model-control repair");
+        }
+        const { plan } = modelControlProfileObservation(context.adapter, snapshot.version);
+        if (!plan || JSON.stringify(plan) !== JSON.stringify(context.plan)) {
+            throw new Error("the exact model-control repair profile changed during the operation");
+        }
+        await this.assertModelControlExclusive({
+            options: context.options,
+            terminal,
+            snapshot
+        });
+        await this.assertModelControlRepairReady({
+            options: context.options,
+            terminal,
+            snapshot,
+            bridge: context.bridge,
+            runtime: context.runtime
+        });
+    }
+    async assertModelControlRepairReady(input) {
+        const status = await input.bridge.status(input.terminal.agent, input.terminal.terminalControl, { runtime: input.runtime });
+        if (status.reachable !== true ||
+            status.approval_state.scanned !== true ||
+            status.approval_state.blocked === true ||
+            status.interaction_state !== undefined) {
+            throw new Error("model-control repair requires a reachable prompt with no approval or questionnaire");
+        }
+        const storeDir = this.ports.state.storeDir(input.options);
+        const blocker = this.ports.state.terminalBlockingTurns(storeDir, input.terminal.terminalControl)[0];
+        if (blocker) {
+            throw new Error(`terminal ${input.terminal.terminalControl.target} still has unresolved Turn ` +
+                `${turnIdForConversation(blocker)} (${blocker.status})`);
+        }
+        if (input.snapshot.session &&
+            this.ports.state.hasUnresolvedTransition(storeDir, input.snapshot.session)) {
+            throw new Error(`managed Session ${input.snapshot.session.session_id} has an unresolved native-thread transition`);
+        }
+        if (this.ports.state.dispatchOwnership(input.terminal.terminalControl).state !==
+            "none") {
+            throw new Error("the terminal has unresolved dispatch ownership during model-control repair");
+        }
+        if (this.ports.state.orphanedForRecovery(input.terminal.terminalControl)) {
+            throw new Error("the terminal has unresolved input ownership during model-control repair");
+        }
+        return status;
+    }
+    modelControlAvailability(input) {
+        const nativeThreadId = input.snapshot.identity?.sessionId ??
+            input.snapshot.session?.binding?.native_thread_id;
+        const zeroRolloutVerified = input.terminal.agent === "codex" &&
+            !input.snapshot.identity && !input.snapshot.session;
+        const incarnation = this.ports.identity.physicalProcessIncarnation(input.terminal.pid);
+        const storeDir = this.ports.state.storeDir(input.options);
+        return decideModelControlAvailability({
+            exactTerminalRow: true,
+            terminalId: input.terminal.conversationId,
+            processState: "active",
+            terminalControl: input.terminal.terminalControl,
+            agent: input.terminal.agent,
+            pid: input.terminal.pid,
+            processUuid: incarnation.processUuid,
+            processBirth: incarnation.processBirth,
+            agentVersion: input.agentVersion,
+            behaviorProfile: input.plan.behaviorProfile,
+            nativeAuthority: isExactNativeThreadId(nativeThreadId)
+                ? {
+                    kind: "exact_session",
+                    ordinaryBindingToken: input.snapshot.bindingToken
+                }
+                : zeroRolloutVerified
+                    ? { kind: "verified_zero_rollout" }
+                    : { kind: "unavailable" },
+            modelControlSupported: true,
+            approvalScanned: input.status.approval_state.scanned === true,
+            approvalBlocked: input.status.approval_state.blocked === true,
+            terminalHasInteraction: input.status.interaction_state !== undefined,
+            terminalHasBlockingTurn: this.ports.state.terminalBlockingTurns(storeDir, input.terminal.terminalControl).length > 0,
+            hasOrphanedDispatch: this.ports.state.dispatchOwnership(input.terminal.terminalControl)
+                .state !== "none" ||
+                this.ports.state.orphanedForRecovery(input.terminal.terminalControl) !== undefined,
+            surface: input.surface
+        });
+    }
+    async withPreparedModelControl(options, expectedBindingToken, operation, behavior = {}) {
+        const storeDir = this.ports.state.storeDir(options);
+        if (this.ports.state.inspectStore(storeDir).writable !== true) {
+            throw new Error("terminal model control requires a compatible AKK Store for current-snapshot authority");
+        }
+        const initiallyResolved = await this.resolveLifecycleTerminal(options);
+        const release = this.ports.state.acquireTerminal(storeDir, initiallyResolved.terminalControl, { timeoutMs: 30_000 });
+        try {
+            const runtimeFacade = this.ports.runtime.forOptions(options);
+            const bridge = runtimeFacade.createBridge();
+            const terminal = await bridge.resolveStoredTerminal(initiallyResolved.agent, initiallyResolved.pid, initiallyResolved.terminalControl, { pid: initiallyResolved.pid });
+            this.assertSameInspectionTerminal(initiallyResolved, terminal, "while waiting for model-control ownership");
+            const snapshot = await this.modelControlSnapshot(options, terminal);
+            const ordinaryBindingToken = required(nonBlankString(snapshot.bindingToken), "terminal model control requires current ordinary binding authority");
+            const hasOrdinaryAuthority = snapshot.bindingTokens.includes(expectedBindingToken);
+            if (!hasOrdinaryAuthority && !behavior.allowResidualEntry) {
+                throw new Error("terminal binding changed after it was listed; refresh AKK list and retry");
+            }
+            const agentVersion = required(nonBlankString(snapshot.version), "model control requires an exact running agent version");
+            const adapter = runtimeFacade.createAgentRegistry().require(terminal.agent);
+            const { capability, plan } = modelControlProfileObservation(adapter, agentVersion);
+            if (capability?.status !== "supported" ||
+                capability.modelSelection !== true ||
+                capability.reasoningEffortSelection !== true) {
+                throw new Error(capability?.reason ??
+                    `${adapter.displayName} has no verified model-control profile`);
+            }
+            if (!plan) {
+                throw new Error("the agent adapter did not produce a model-control plan");
+            }
+            await this.assertModelControlExclusive({ options, terminal, snapshot });
+            let initialResidual;
+            let runtime;
+            if (hasOrdinaryAuthority) {
+                const ready = await this.observeInitialInspectionReady(options, terminal, snapshot, bridge);
+                runtime = ready.runtime;
+                if (ready.status.approval_state.scanned !== true ||
+                    ready.status.approval_state.blocked === true ||
+                    ready.status.interaction_state !== undefined) {
+                    throw new Error("model control requires a freshly scanned terminal with no approval or questionnaire");
+                }
+                const availability = this.modelControlAvailability({
+                    options,
+                    terminal,
+                    snapshot,
+                    agentVersion,
+                    plan,
+                    status: ready.status,
+                    surface: {
+                        kind: "idle_empty",
+                        screenState: ready.status.screen_state
+                    }
+                });
+                if (availability.availability !== "open_from_empty" ||
+                    availability.expectedBindingToken !== ordinaryBindingToken) {
+                    throw new Error("model control requires an exact verified idle pane with an empty composer and no blocking interaction");
+                }
+            }
+            else {
+                if (terminal.agent !== "codex" ||
+                    terminalModelControlProfileForPlan(plan)
+                        ?.supportsResidualContinuation !== true) {
+                    throw new Error("terminal binding changed after it was listed; refresh AKK list and retry");
+                }
+                runtime = this.inspectionRuntime(terminal, snapshot);
+                const status = await this.assertModelControlRepairReady({
+                    options,
+                    terminal,
+                    snapshot,
+                    bridge,
+                    runtime
+                });
+                const observed = await bridge.inspectModelControlResidual(terminal.agent, terminal.terminalControl, agentVersion, plan, { runtime, beforeInput: () => undefined });
+                if (observed.state !== "recoverable") {
+                    throw new Error(observed.reason);
+                }
+                const availability = this.modelControlAvailability({
+                    options,
+                    terminal,
+                    snapshot,
+                    agentVersion,
+                    plan,
+                    status,
+                    surface: {
+                        kind: "residual",
+                        residualKind: observed.kind,
+                        residualFingerprint: observed.fingerprint,
+                        activityState: status.activity_state
+                    }
+                });
+                if (availability.availability !== "residual_continuation" ||
+                    availability.expectedBindingToken !== expectedBindingToken) {
+                    throw new Error("the exact model-control residual changed after it was listed; refresh AKK list");
+                }
+                initialResidual = observed;
+            }
+            return await operation({
+                options,
+                terminal,
+                snapshot,
+                bridge,
+                runtime,
+                adapter,
+                agentVersion,
+                plan,
+                expectedBindingToken,
+                ordinaryBindingToken,
+                initialResidual,
+                ...(terminal.agent === "codex" &&
+                    isTerminalModelControlPlanForAgent(plan, "codex")
+                    ? {
+                        loadCodexCatalog: async () => runtimeFacade.codexModelCatalogForRunningProcess(terminal.pid, CODEX_MODEL_CONTROL_AGENT_VERSION, terminal.terminalControl.currentPath)
+                    }
+                    : {})
+            });
+        }
+        finally {
+            release();
+        }
+    }
+    async assertFreshModelControlBoundary(context) {
+        const terminal = await this.resolveModelControlBoundaryTerminal(context);
+        this.assertSameInspectionTerminal(context.terminal, terminal, "immediately before model-control input");
+        const snapshot = await this.modelControlSnapshot(context.options, terminal);
+        if (!snapshot.bindingTokens.includes(context.expectedBindingToken) ||
+            snapshot.version !== context.agentVersion) {
+            throw new Error("terminal binding or coding-agent version changed during model control; refresh AKK list");
+        }
+        const expectedNativeThreadId = context.snapshot.identity?.sessionId ??
+            context.snapshot.session?.binding?.native_thread_id;
+        const actualNativeThreadId = snapshot.identity?.sessionId ??
+            snapshot.session?.binding?.native_thread_id;
+        if (expectedNativeThreadId !== actualNativeThreadId) {
+            throw new Error("the current native Session changed during model control; inspect the pane before retrying");
+        }
+        const { plan } = modelControlProfileObservation(context.adapter, snapshot.version);
+        if (!plan || JSON.stringify(plan) !== JSON.stringify(context.plan)) {
+            throw new Error("the exact model-control profile changed during the operation");
+        }
+        await this.assertModelControlExclusive({
+            options: context.options,
+            terminal,
+            snapshot
+        });
+        this.assertInspectionReady({
+            options: context.options,
+            terminal,
+            session: snapshot.session
+        });
+        this.assertModelControlAgentIdentity({
+            options: context.options,
+            terminal,
+            snapshot
+        });
+    }
+    async resolveModelControlBoundaryTerminal(context) {
+        try {
+            return await context.bridge.resolveStoredTerminal(context.terminal.agent, context.terminal.pid, context.terminal.terminalControl, context.runtime);
+        }
+        catch (idleError) {
+            if (context.terminal.agent !== "claude" ||
+                !terminalModelControlPlanConforms({
+                    agent: context.terminal.agent,
+                    agentVersion: context.agentVersion,
+                    plan: context.plan
+                }) ||
+                context.runtime.requireExactClaudeAgentRow !== true ||
+                context.runtime.exactClaudeAgentState !== "idle") {
+                throw idleError;
+            }
+            try {
+                return await context.bridge.resolveStoredTerminal(context.terminal.agent, context.terminal.pid, context.terminal.terminalControl, { ...context.runtime, exactClaudeAgentState: "status_dialog" });
+            }
+            catch {
+                // All immutable process, native Session, cwd, and terminal fences are
+                // identical in both attempts. Only the exact Claude agents UI state
+                // differs, and the bridge must still prove a fresh profiled model
+                // surface after this read-only boundary before any key is dispatched.
+                throw idleError;
+            }
+        }
+    }
+    assertModelControlAgentIdentity(input) {
+        if (input.terminal.agent !== "claude")
+            return;
+        try {
+            this.assertInspectionAgentIdentity({
+                ...input,
+                stage: "during model control",
+                expectedClaudeState: "idle"
+            });
+        }
+        catch (idleError) {
+            try {
+                this.assertInspectionAgentIdentity({
+                    ...input,
+                    stage: "during model control",
+                    expectedClaudeState: "status_dialog"
+                });
+            }
+            catch {
+                throw idleError;
+            }
+        }
+    }
+    async assertModelControlExclusive(input) {
+        if (input.terminal.agent === "codex") {
+            const nativeThreadId = input.snapshot.identity?.sessionId ??
+                input.snapshot.session?.binding?.native_thread_id;
+            if (!nativeThreadId && !input.snapshot.identity && !input.snapshot.session) {
+                // A fresh, verified-empty Codex process has no durable native Session
+                // to own yet. The physical pane/process/cwd fence remains exact.
+                this.assertForegroundHasNoLifecycleTransition(input.options, input.terminal);
+                return;
+            }
+            if (!isExactNativeThreadId(nativeThreadId)) {
+                throw new Error("Codex model control requires either a fresh zero-rollout pane or one exact current native Session identity");
+            }
+            await this.assertExclusive({
+                options: input.options,
+                agent: input.terminal.agent,
+                currentPid: input.terminal.pid,
+                nativeThreadId,
+                storeDir: this.ports.state.storeDir(input.options),
+                terminalControl: input.terminal.terminalControl,
+                excludedManagedSessionId: input.snapshot.session?.session_id
+            });
+            return;
+        }
+        const nativeThreadId = input.snapshot.identity?.sessionId ??
+            input.snapshot.session?.binding?.native_thread_id;
+        if (!isExactNativeThreadId(nativeThreadId)) {
+            throw new Error("model control requires one exact current native Session identity");
+        }
+        await this.assertExclusive({
+            options: input.options,
+            agent: input.terminal.agent,
+            currentPid: input.terminal.pid,
+            nativeThreadId,
+            storeDir: this.ports.state.storeDir(input.options),
+            terminalControl: input.terminal.terminalControl,
+            excludedManagedSessionId: input.snapshot.session?.session_id
+        });
+    }
+    modelOptionsResult(context, catalog) {
+        return {
+            terminal_id: context.terminal.conversationId,
+            agent: context.terminal.agent,
+            agent_version: context.agentVersion,
+            behavior_profile: catalog.behaviorProfile,
+            scope: catalog.scope,
+            current: modelValueOutput(catalog.current),
+            models: catalog.models.map((model) => ({
+                id: model.id,
+                label: model.label,
+                reasoning_efforts: [...model.reasoningEfforts]
+            })),
+            catalog_fingerprint: catalog.catalogFingerprint,
+            available_actions: {
+                set_model: {
+                    tool: "agent_knock_knock_set_model",
+                    arguments: {
+                        terminal_id: context.terminal.conversationId,
+                        expected_binding_token: context.ordinaryBindingToken,
+                        expected_catalog_fingerprint: catalog.catalogFingerprint
+                    }
+                }
+            }
+        };
+    }
     validateInspectionOptions(options) {
         const inspection = required(nonBlankString(options.inspection), "--inspection is required");
         if (inspection !== "status") {
@@ -806,6 +1416,9 @@ class NativeThreadLifecycleCliApplication {
         };
     }
     async assertInitialInspectionReady(options, terminal, snapshot, bridge) {
+        return (await this.observeInitialInspectionReady(options, terminal, snapshot, bridge)).runtime;
+    }
+    async observeInitialInspectionReady(options, terminal, snapshot, bridge) {
         this.assertInspectionAgentIdentity({
             options, terminal, snapshot, stage: "before native status inspection"
         });
@@ -816,7 +1429,7 @@ class NativeThreadLifecycleCliApplication {
             options, terminal, terminalStatus: status, session: snapshot.session
         });
         await this.assertInspectionComposerReady({ options, terminal });
-        return runtime;
+        return { runtime, status };
     }
     async submitInspection(context) {
         try {
@@ -1020,6 +1633,14 @@ class NativeThreadLifecycleCliApplication {
         });
     }
 }
+function modelValueOutput(value) {
+    return {
+        model: value.model,
+        ...(value.reasoningEffort
+            ? { reasoning_effort: value.reasoningEffort }
+            : {})
+    };
+}
 function bareNativeInspectionScreenDigest(fingerprint) {
     return /^sha256:([0-9a-f]{64})$/u.exec(fingerprint)?.[1];
 }
@@ -1093,6 +1714,17 @@ function nativeInspectionComposerEmpty(agent, screen) {
         ? codexComposerEmpty(screen)
         : isExactClaudeNativeInspectionIdleComposer(String(screen ?? ""));
 }
+function modelControlProfileObservation(adapter, agentVersion) {
+    const capability = adapter.probeModelControl?.(agentVersion);
+    const plan = capability?.status === "supported"
+        ? adapter.planModelControl?.(capability)
+        : undefined;
+    return {
+        capability,
+        plan,
+        profile: plan ? terminalModelControlProfileForPlan(plan) : undefined
+    };
+}
 function required(value, message) {
     if (value === undefined || value === "")
         throw new Error(message);