@scotthuang/agent-knock-knock 0.13.3 → 0.13.4

package/dist/src/terminal-model-control.js

@@ -1,5 +1,10 @@
 import { createHash } from "node:crypto";
+import { CODEX_MODEL_CONTROL_AGENT_VERSION, isTerminalModelControlPlanForAgent, planTerminalModelControlProfile, probeTerminalModelControlProfile, terminalModelControlProfileForPlan } from "./terminal-model-control-profile.js";
+import { canonicalModelControlSubject } from "./terminal-model-control-subject.js";
+import { decideTerminalModelControlFailure, reduceTerminalModelControlTransactionPhase } from "./terminal-model-control-transaction.js";
 import { terminalPhysicalBindingToken } from "./terminal-control-ref.js";
+export { CLAUDE_MODEL_CONTROL_AGENT_VERSION, CODEX_MODEL_CONTROL_AGENT_VERSION, TERMINAL_MODEL_CONTROL_PROFILE_IDS, isTerminalModelControlPlanForAgent, terminalModelControlPlanConforms, terminalModelControlProfileFor, terminalModelControlProfileForPlan, terminalModelControlProfiles, terminalModelControlSlashCompletionRows } from "./terminal-model-control-profile.js";
+export { canonicalModelControlSubject } from "./terminal-model-control-subject.js";
 /** Caller-visible reasoning values. Native labels and menu positions stay private. */
 export const TERMINAL_MODEL_REASONING_EFFORTS = [
     "low",
@@ -15,25 +20,36 @@ export const TERMINAL_MODEL_REASONING_EFFORTS = [
  * as Send or native-lifecycle authority even though all bind the same pane.
  */
 export function terminalUserExplicitModelControlBindingToken(value) {
+    const subject = requiredModelControlSubject({
+        ...value,
+        agent: "codex"
+    });
     const physicalTerminalToken = terminalPhysicalBindingToken({
-        terminalId: value.terminalId,
-        terminalControl: value.terminalControl,
+        terminalId: subject.terminalId,
+        terminalControl: subject.terminalControl,
         agent: "codex",
-        pid: value.pid,
-        workspace: value.workspace,
-        processUuid: value.processUuid,
-        processBirth: value.processBirth
+        pid: subject.pid,
+        workspace: subject.workspace,
+        processUuid: subject.processUuid,
+        processBirth: subject.processBirth
     });
     return createHash("sha256")
         .update(JSON.stringify({
         version: 1,
         authority: "terminal_user_explicit_model_control",
         physical_terminal_token: physicalTerminalToken,
-        agent_version: value.agentVersion,
-        behavior_profile: value.behaviorProfile
+        agent_version: subject.agentVersion,
+        behavior_profile: subject.behaviorProfile
     }))
         .digest("hex");
 }
+function requiredModelControlSubject(input) {
+    const subject = canonicalModelControlSubject(input);
+    if (!subject) {
+        throw new Error("model-control authority requires one canonical supported terminal subject");
+    }
+    return subject;
+}
 /**
  * Snapshot authority for adopting and cleaning one exact native `/model`
  * residual. The residual kind and normalized surface digest prevent a token
@@ -162,63 +178,10 @@ export function isTerminalModelReasoningEffort(value) {
         TERMINAL_MODEL_REASONING_EFFORTS.includes(value);
 }
 export function probeTerminalModelControl(agent, agentVersion) {
-    if (!agentVersion) {
-        return {
-            status: "unknown",
-            modelSelection: false,
-            reasoningEffortSelection: false,
-            reason: `the running ${agent === "codex" ? "Codex" : "Claude Code"} version could not be verified`
-        };
-    }
-    if (agent === "codex" && agentVersion === "0.154.0") {
-        return {
-            status: "supported",
-            agentVersion,
-            behaviorProfile: "codex-model-control-0.154.0",
-            scope: "current_and_new_sessions",
-            modelSelection: true,
-            reasoningEffortSelection: true,
-            reason: "Codex 0.154.0 /model control changes the current session and persisted defaults"
-        };
-    }
-    if (agent === "claude" && agentVersion === "2.1.266") {
-        return {
-            status: "supported",
-            agentVersion,
-            behaviorProfile: "claude-model-control-2.1.266",
-            scope: "current_session",
-            modelSelection: true,
-            reasoningEffortSelection: true,
-            reason: "Claude Code 2.1.266 /model supports the explicit session-only selection path"
-        };
-    }
-    return {
-        status: "unsupported",
-        agentVersion,
-        modelSelection: false,
-        reasoningEffortSelection: false,
-        reason: `${agent === "codex" ? "Codex" : "Claude Code"} ${agentVersion} has no verified model-control profile`
-    };
+    return probeTerminalModelControlProfile(agent, agentVersion);
 }
 export function planTerminalModelControl(capabilities) {
-    if (capabilities.status !== "supported" ||
-        capabilities.modelSelection !== true ||
-        capabilities.reasoningEffortSelection !== true ||
-        !capabilities.behaviorProfile ||
-        !capabilities.scope) {
-        throw new Error(capabilities.reason);
-    }
-    if (capabilities.behaviorProfile !== "codex-model-control-0.154.0" &&
-        capabilities.behaviorProfile !== "claude-model-control-2.1.266") {
-        throw new Error("refusing an unprofiled terminal model-control plan");
-    }
-    return {
-        behaviorProfile: capabilities.behaviorProfile,
-        command: "/model",
-        scope: capabilities.scope,
-        requiresIdle: true,
-        requiresExactEmptyComposer: true
-    };
+    return planTerminalModelControlProfile(capabilities);
 }
 /**
  * Observe only complete, current model-control modal frames. Historical or
@@ -226,7 +189,7 @@ export function planTerminalModelControl(capabilities) {
  */
 export function observeTerminalModelControl(plan, screen) {
     const normalized = stripAnsi(screen).replace(/\r\n?/gu, "\n");
-    return plan.behaviorProfile === "codex-model-control-0.154.0"
+    return isTerminalModelControlPlanForAgent(plan, "codex")
         ? observeCodexModelControl(normalized)
         : observeClaudeModelControl(normalized);
 }
@@ -302,44 +265,167 @@ export function claudeModelControlEffortKey(direction) {
     return [direction === "lower" ? "Left" : "Right"];
 }
 export function claudeModelControlCommitKeys(plan) {
-    if (plan.behaviorProfile !== "claude-model-control-2.1.266" ||
+    if (!isTerminalModelControlPlanForAgent(plan, "claude") ||
         plan.scope !== "current_session") {
         throw new Error("Claude model control cannot commit outside session-only scope");
     }
     return ["s"];
 }
+function isExactTerminalModelControlObservation(observation) {
+    return observation.state !== "none" && observation.state !== "ambiguous";
+}
+/** Pure capture classifier. It never authorizes input by itself. */
+export function classifyTerminalModelControlSurface(plan, capture) {
+    const observation = observeTerminalModelControl(plan, capture.screen);
+    // Approval and a positively identified non-model input owner remain hard
+    // safety boundaries even when stale transcript text resembles a picker.
+    const hardBlock = modelControlHardBlock(capture);
+    if (hardBlock)
+        return hardBlock;
+    // Exact profile-owned surfaces outrank generic lifecycle activity. Codex and
+    // Claude can report working/waiting while their native picker owns input.
+    if (isExactTerminalModelControlObservation(observation)) {
+        return {
+            state: "picker",
+            pickerKind: modelControlPickerKind(observation),
+            observation
+        };
+    }
+    // Only a complete picker owns the lifecycle override. Composer proofs do
+    // not supersede genuine working/approval lifecycle state.
+    const activityBlock = modelControlActivityBlock(capture);
+    if (activityBlock)
+        return activityBlock;
+    return classifyModelControlComposerSurface(capture, observation);
+}
+function modelControlHardBlock(capture) {
+    if (capture.approvalBlocked) {
+        return { state: "blocked", owner: "approval" };
+    }
+    return capture.inputBlocked === true
+        ? { state: "blocked", owner: "input" }
+        : undefined;
+}
+function modelControlActivityBlock(capture) {
+    return capture.activityState === "working" ||
+        capture.activityState === "awaiting_approval"
+        ? { state: "blocked", owner: "agent" }
+        : undefined;
+}
+function modelControlPickerKind(observation) {
+    if (observation.state === "codex_reasoning_picker" ||
+        observation.state === "codex_advanced_reasoning_picker") {
+        return "effort";
+    }
+    return observation.state === "codex_plan_scope_picker" ? "scope" : "model";
+}
+function classifyModelControlComposerSurface(capture, observation) {
+    const contradictoryComposerProof = capture.exactEmptyComposer && capture.exactCommandComposer ||
+        capture.exactCommandReady && capture.exactBareCommand === true ||
+        (capture.exactCommandReady || capture.exactBareCommand === true) &&
+            !capture.exactCommandComposer;
+    if (contradictoryComposerProof) {
+        return {
+            state: "unknown",
+            reason: "model-control Composer proofs conflict"
+        };
+    }
+    if (capture.exactCommandComposer &&
+        capture.exactCommandReady) {
+        return {
+            state: "command_popup",
+            ...(capture.exactCommandFingerprint
+                ? { fingerprint: capture.exactCommandFingerprint }
+                : {})
+        };
+    }
+    if (capture.exactCommandComposer &&
+        capture.exactBareCommand === true) {
+        return {
+            state: "bare_command",
+            ...(capture.exactCommandFingerprint
+                ? { fingerprint: capture.exactCommandFingerprint }
+                : {})
+        };
+    }
+    if (capture.exactCommandComposer) {
+        return {
+            state: "command_draft",
+            ...(capture.exactCommandFingerprint
+                ? { fingerprint: capture.exactCommandFingerprint }
+                : {})
+        };
+    }
+    if (capture.exactEmptyComposer && capture.activityState === "idle") {
+        return { state: "idle_empty" };
+    }
+    return {
+        state: "unknown",
+        reason: observation.state === "ambiguous"
+            ? observation.reason
+            : "no exact current model-control surface is proven"
+    };
+}
 const MODEL_CONTROL_SETTLE_TIMEOUT_MS = 5_000;
 const MODEL_CONTROL_POLL_MS = 40;
+function advanceTerminalModelControlTransaction(transaction, event) {
+    transaction.phase = reduceTerminalModelControlTransactionPhase(transaction.phase, event);
+}
+/** Track every nested native write even when its transport receipt rejects. */
+function beginTerminalModelControlTransaction(input) {
+    const transaction = { phase: "no_input" };
+    return {
+        ...input,
+        transaction,
+        ports: {
+            ...input.ports,
+            sendText: async (terminalControl, text) => {
+                advanceTerminalModelControlTransaction(transaction, "reversible_input_attempted");
+                await input.ports.sendText(terminalControl, text);
+            },
+            sendKeys: async (terminalControl, keys) => {
+                advanceTerminalModelControlTransaction(transaction, "reversible_input_attempted");
+                await input.ports.sendKeys(terminalControl, keys);
+            }
+        }
+    };
+}
+function terminalModelControlInputAttempted(transaction) {
+    return transaction.phase === "reversible_input" ||
+        transaction.phase === "commit_attempted";
+}
+async function settleTerminalModelControlFailure(input, terminalControl) {
+    const pending = decideTerminalModelControlFailure(input.transaction.phase, "not_attempted");
+    if (!pending.unwind)
+        return { decision: pending };
+    const cleanupError = await tryUnwindModelControl(input, terminalControl);
+    return {
+        decision: decideTerminalModelControlFailure(input.transaction.phase, cleanupError ? "failed" : "proven"),
+        ...(cleanupError ? { cleanupError } : {})
+    };
+}
 function modelControlCaptureBlocked(capture) {
     return capture.approvalBlocked || capture.inputBlocked === true;
 }
-function modelCommandReadyForEnter(plan, capture) {
-    return capture.exactCommandReady ||
-        plan.behaviorProfile === "codex-model-control-0.154.0" &&
-            capture.exactBareCommand === true;
-}
 function residualFromCapture(plan, capture) {
-    if (plan.behaviorProfile !== "codex-model-control-0.154.0") {
+    const profile = terminalModelControlProfileForPlan(plan);
+    if (!profile?.supportsResidualRepair) {
         return {
             state: "unsafe",
-            reason: "model-control residual repair is profiled only for Codex 0.154.0",
+            reason: "model-control residual repair is profiled only for Codex " +
+                CODEX_MODEL_CONTROL_AGENT_VERSION,
             terminalControl: capture.terminalControl
         };
     }
-    const modelObservation = observeTerminalModelControl(plan, capture.screen);
-    const exactModelSurface = modelObservation.state !== "none" &&
-        modelObservation.state !== "ambiguous";
-    if (capture.approvalBlocked ||
-        capture.inputBlocked === true && !exactModelSurface ||
-        (capture.activityState === "working" ||
-            capture.activityState === "awaiting_approval") && !exactModelSurface) {
+    const surface = classifyTerminalModelControlSurface(plan, capture);
+    if (surface.state === "blocked") {
         return {
             state: "unsafe",
             reason: "another prompt or active agent state owns terminal input",
             terminalControl: capture.terminalControl
         };
     }
-    if (exactModelSurface) {
+    if (surface.state === "picker") {
         return {
             state: "recoverable",
             kind: "model_surface",
@@ -348,25 +434,31 @@ function residualFromCapture(plan, capture) {
                 version: 1,
                 behavior_profile: plan.behaviorProfile,
                 kind: "model_surface",
-                surface_state: modelObservation.state,
-                surface_fingerprint: modelObservation.fingerprint
+                surface_state: surface.observation.state,
+                surface_fingerprint: surface.observation.fingerprint
             }))
                 .digest("hex"),
             terminalControl: capture.terminalControl
         };
     }
-    if (!capture.exactCommandComposer ||
-        !capture.exactCommandFingerprint ||
-        (!capture.exactCommandReady && capture.exactBareCommand !== true)) {
+    if (surface.state !== "command_popup" &&
+        surface.state !== "bare_command") {
         return {
             state: "absent",
-            reason: capture.exactEmptyComposer
+            reason: surface.state === "idle_empty"
                 ? "the Composer is already empty"
                 : "the current Composer is not one exact profiled /model residual",
             terminalControl: capture.terminalControl
         };
     }
-    const kind = capture.exactCommandReady
+    if (!surface.fingerprint) {
+        return {
+            state: "absent",
+            reason: "the current Composer is not one exact profiled /model residual",
+            terminalControl: capture.terminalControl
+        };
+    }
+    const kind = surface.state === "command_popup"
         ? "profiled_command_popup"
         : "bare_command";
     return {
@@ -377,7 +469,7 @@ function residualFromCapture(plan, capture) {
             version: 1,
             behavior_profile: plan.behaviorProfile,
             kind,
-            exact_command_fingerprint: capture.exactCommandFingerprint
+            exact_command_fingerprint: surface.fingerprint
         }))
             .digest("hex"),
         terminalControl: capture.terminalControl
@@ -425,21 +517,15 @@ export async function repairTerminalModelControlResidual(input) {
     if (observed.fingerprint !== input.expectedResidualFingerprint) {
         throw new Error("the exact /model residual changed after authorization; refresh AKK list");
     }
-    let terminalInputAttempted = false;
-    const ports = {
-        ...input.ports,
-        sendKeys: async (terminalControl, keys) => {
-            terminalInputAttempted = true;
-            await input.ports.sendKeys(terminalControl, keys);
-        }
-    };
+    const operation = beginTerminalModelControlTransaction(input);
     try {
-        const cleared = await unwindModelControl({ plan: input.plan, ports }, observed.terminalControl);
-        if (modelControlCaptureBlocked(cleared) ||
-            cleared.activityState !== "idle" ||
-            !cleared.exactEmptyComposer) {
+        const cleared = await unwindModelControl(operation, observed.terminalControl);
+        if (classifyTerminalModelControlSurface(input.plan, cleared).state !==
+            "idle_empty") {
             throw new Error("cleanup did not prove an exact idle empty Composer");
         }
+        const terminalInputAttempted = terminalModelControlInputAttempted(operation.transaction);
+        advanceTerminalModelControlTransaction(operation.transaction, "postcondition_proven");
         return {
             outcome: "repaired",
             terminalControl: cleared.terminalControl,
@@ -449,14 +535,15 @@ export async function repairTerminalModelControlResidual(input) {
         };
     }
     catch (error) {
-        if (!terminalInputAttempted)
+        const decision = decideTerminalModelControlFailure(operation.transaction.phase, "failed");
+        if (decision.outcome === "throw")
             throw error;
         return {
             outcome: "uncertain",
             terminalControl: observed.terminalControl,
             terminalInputAttempted: true,
             composerPostcondition: "unproven",
-            doNotRetry: true,
+            doNotRetry: decision.doNotRetry,
             reason: error instanceof Error ? error.message : String(error)
         };
     }
@@ -466,14 +553,15 @@ export async function repairTerminalModelControlResidual(input) {
  * adapter-owned `/model` surface and always returns through exact Escape paths.
  */
 export async function discoverTerminalModelOptions(input) {
-    const codexNativeCatalog = input.agent === "codex"
-        ? await input.ports.loadCodexCatalog?.()
+    const operation = beginTerminalModelControlTransaction(input);
+    const codexNativeCatalog = operation.agent === "codex"
+        ? await operation.ports.loadCodexCatalog?.()
         : undefined;
-    if (input.agent === "codex" && !codexNativeCatalog) {
+    if (operation.agent === "codex" && !codexNativeCatalog) {
         throw new Error("Codex model discovery requires the exact running executable's validated model catalog");
     }
-    let control = input.terminalControl;
-    const opened = await openModelPicker(input, control);
+    let control = operation.terminalControl;
+    const opened = await openModelPicker(operation, control);
     control = opened.capture.terminalControl;
     const picker = opened.observation;
     try {
@@ -499,7 +587,7 @@ export async function discoverTerminalModelOptions(input) {
                         }]
                     : [];
             });
-            const dismissed = await exactDismiss(input, control, picker);
+            const dismissed = await exactDismiss(operation, control, picker);
             control = dismissed.terminalControl;
             // An adopted profiled slash popup temporarily replaces the ordinary
             // footer. Once the read-only picker is dismissed, the exact idle footer
@@ -518,7 +606,7 @@ export async function discoverTerminalModelOptions(input) {
             let livePicker = picker;
             models = [];
             for (const row of picker.rows) {
-                const inspected = await inspectClaudeModelEfforts(input, control, livePicker, row.id);
+                const inspected = await inspectClaudeModelEfforts(operation, control, livePicker, row.id);
                 control = inspected.capture.terminalControl;
                 livePicker = inspected.observation;
                 if (inspected.reasoningEfforts.length > 0) {
@@ -529,7 +617,7 @@ export async function discoverTerminalModelOptions(input) {
                     });
                 }
             }
-            control = (await exactDismiss(input, control, livePicker)).terminalControl;
+            control = (await exactDismiss(operation, control, livePicker)).terminalControl;
         }
         if (models.length === 0) {
             throw new Error("the live native model picker had no verified model choices");
@@ -539,23 +627,25 @@ export async function discoverTerminalModelOptions(input) {
             reasoningEffort: currentEffort
         };
         const fingerprintInput = {
-            agent: input.agent,
-            agentVersion: input.agentVersion,
-            behaviorProfile: input.plan.behaviorProfile,
-            scope: input.plan.scope,
+            agent: operation.agent,
+            agentVersion: operation.agentVersion,
+            behaviorProfile: operation.plan.behaviorProfile,
+            scope: operation.plan.scope,
             current,
             models
         };
-        return {
+        const result = {
             terminalControl: control,
             catalog: {
                 ...fingerprintInput,
                 catalogFingerprint: terminalModelCatalogFingerprint(fingerprintInput)
             }
         };
+        advanceTerminalModelControlTransaction(operation.transaction, "postcondition_proven");
+        return result;
     }
     catch (error) {
-        const cleanupError = await tryUnwindModelControl(input, control);
+        const { cleanupError } = await settleTerminalModelControlFailure(operation, control);
         const detail = error instanceof Error ? error.message : String(error);
         if (cleanupError) {
             throw new Error(`${detail}; exact native model-control cleanup failed: ${cleanupError}`);
@@ -594,22 +684,22 @@ export async function switchTerminalModel(input) {
             doNotRetry: false
         };
     }
-    let irreversible = false;
+    const operation = beginTerminalModelControlTransaction(input);
     let control = discovery.terminalControl;
     let codexPersistenceBaseline;
     let codexPersistenceScreen;
     try {
-        const opened = await openModelPicker(input, control);
+        const opened = await openModelPicker(operation, control);
         control = opened.capture.terminalControl;
         const picker = opened.observation;
         if (picker.state === "codex_model_picker") {
             codexPersistenceBaseline = opened.idleCapture.screen;
-            const committed = await applyCodexModelSelection(input, control, picker, input.request, () => { irreversible = true; });
+            const committed = await applyCodexModelSelection(operation, control, picker, input.request, () => advanceTerminalModelControlTransaction(operation.transaction, "commit_attempted"));
             control = committed.capture.terminalControl;
             codexPersistenceScreen = committed.capture.screen;
         }
         else if (picker.state === "claude_model_picker") {
-            const selected = await transitionModelControl(input, control, picker, modelControlSelectModelKeys(picker, input.request.model), ["claude_model_picker"]);
+            const selected = await transitionModelControl(operation, control, picker, modelControlSelectModelKeys(picker, input.request.model), ["claude_model_picker"]);
             control = selected.capture.terminalControl;
             if (selected.observation.state !== "claude_model_picker") {
                 throw new Error("Claude model selection did not remain in its picker");
@@ -629,7 +719,7 @@ export async function switchTerminalModel(input) {
                     throw new Error("the requested effort is absent from Claude's live effort ring");
                 }
                 seen.add(displayed);
-                const next = await transitionModelControl(input, control, effortPicker, claudeModelControlEffortKey("higher"), ["claude_model_picker"]);
+                const next = await transitionModelControl(operation, control, effortPicker, claudeModelControlEffortKey("higher"), ["claude_model_picker"]);
                 control = next.capture.terminalControl;
                 if (next.observation.state !== "claude_model_picker") {
                     throw new Error("Claude effort adjustment left the model picker");
@@ -645,9 +735,9 @@ export async function switchTerminalModel(input) {
             if (selectedClaudeModelId(effortPicker) !== input.request.model) {
                 throw new Error("Claude changed the highlighted model before session-only commit");
             }
-            irreversible = true;
-            await exactDispatchKeys(input, control, effortPicker, claudeModelControlCommitKeys(input.plan));
-            const closed = await waitForObservation(input, control, ["none"], {
+            advanceTerminalModelControlTransaction(operation.transaction, "commit_attempted");
+            await exactDispatchKeys(operation, control, effortPicker, claudeModelControlCommitKeys(input.plan));
+            const closed = await waitForObservation(operation, control, ["none"], {
                 allowImmediateNone: true
             });
             control = closed.capture.terminalControl;
@@ -656,7 +746,7 @@ export async function switchTerminalModel(input) {
             throw new Error("the native model picker changed before selection");
         }
         let persistence = input.agent === "codex"
-            ? await waitForCodexPersistencePostcondition(input, control, codexPersistenceBaseline ?? "", input.request, codexPersistenceScreen)
+            ? await waitForCodexPersistencePostcondition(operation, control, codexPersistenceBaseline ?? "", input.request, codexPersistenceScreen)
             : { proven: true };
         let post = await discoverTerminalModelOptions({
             ...input, terminalControl: control
@@ -670,14 +760,14 @@ export async function switchTerminalModel(input) {
             effective.model === input.request.model &&
             effective.reasoningEffort === discovery.catalog.current.reasoningEffort &&
             effective.reasoningEffort !== requestedEffort) {
-            const reopened = await openModelPicker(input, control);
+            const reopened = await openModelPicker(operation, control);
             if (reopened.observation.state !== "codex_model_picker") {
                 throw new Error("Codex Plan-mode reconciliation did not open its model picker");
             }
             const secondBaseline = reopened.idleCapture.screen;
-            const reconciled = await applyCodexModelSelection(input, reopened.capture.terminalControl, reopened.observation, input.request, () => { irreversible = true; });
+            const reconciled = await applyCodexModelSelection(operation, reopened.capture.terminalControl, reopened.observation, input.request, () => advanceTerminalModelControlTransaction(operation.transaction, "commit_attempted"));
             control = reconciled.capture.terminalControl;
-            persistence = await waitForCodexPersistencePostcondition(input, control, secondBaseline, input.request, reconciled.capture.screen);
+            persistence = await waitForCodexPersistencePostcondition(operation, control, secondBaseline, input.request, reconciled.capture.screen);
             post = await discoverTerminalModelOptions({
                 ...input, terminalControl: control
             });
@@ -717,6 +807,7 @@ export async function switchTerminalModel(input) {
                     : { reasoningEffort: requestedEffort })
             }
             : undefined;
+        advanceTerminalModelControlTransaction(operation.transaction, "postcondition_proven");
         return {
             terminalControl: control,
             outcome: "changed",
@@ -729,8 +820,8 @@ export async function switchTerminalModel(input) {
         };
     }
     catch (error) {
-        const cleanupError = await tryUnwindModelControl(input, control);
-        if (!irreversible && !cleanupError)
+        const { decision, cleanupError } = await settleTerminalModelControlFailure(operation, control);
+        if (decision.outcome === "throw")
             throw error;
         const detail = error instanceof Error ? error.message : String(error);
         return {
@@ -739,14 +830,14 @@ export async function switchTerminalModel(input) {
             scope: input.plan.scope,
             defaultsChanged: null,
             requested: input.request,
-            doNotRetry: true,
+            doNotRetry: decision.doNotRetry,
             reason: cleanupError
                 ? `${detail}; exact native model-control cleanup failed: ${cleanupError}`
                 : detail
         };
     }
 }
-async function applyCodexModelSelection(input, terminalControl, picker, request, beforeIrreversible) {
+async function applyCodexModelSelection(input, terminalControl, picker, request, beforeCommitAttempt) {
     const target = picker.rows.find((row) => row.id === request.model);
     if (!target) {
         throw new Error("the requested Codex model left the current native picker");
@@ -761,7 +852,7 @@ async function applyCodexModelSelection(input, terminalControl, picker, request,
     }
     // A remotely refreshed model can become single-effort after discovery; in
     // that case Enter may commit immediately instead of opening a submenu.
-    beforeIrreversible();
+    beforeCommitAttempt();
     const reasoning = await transitionModelControl(input, moved.capture.terminalControl, moved.observation, ["C-m"], ["codex_reasoning_picker"]);
     if (reasoning.observation.state !== "codex_reasoning_picker" ||
         reasoning.observation.model !== request.model) {
@@ -772,7 +863,7 @@ async function applyCodexModelSelection(input, terminalControl, picker, request,
     const advanced = request.reasoningEffort === "max" ||
         request.reasoningEffort === "ultra";
     if (!advanced)
-        beforeIrreversible();
+        beforeCommitAttempt();
     let selected = await transitionModelControl(input, reasoning.capture.terminalControl, selection, keys, advanced
         ? ["codex_advanced_reasoning_picker"]
         : ["none", "codex_plan_scope_picker"], advanced ? {} : { allowImmediateNone: true });
@@ -782,24 +873,25 @@ async function applyCodexModelSelection(input, terminalControl, picker, request,
         }
         selection = selected.observation;
         keys = codexModelControlSelectEffortKeys(selection, request.reasoningEffort);
-        beforeIrreversible();
+        beforeCommitAttempt();
         selected = await transitionModelControl(input, selected.capture.terminalControl, selection, keys, ["none", "codex_plan_scope_picker"], { allowImmediateNone: true });
     }
     if (selected.observation.state !== "codex_plan_scope_picker") {
         return selected;
     }
-    beforeIrreversible();
+    beforeCommitAttempt();
     return transitionModelControl(input, selected.capture.terminalControl, selected.observation, codexModelControlAllModesKeys(selected.observation), ["none"], { allowImmediateNone: true });
 }
 async function openModelPicker(input, terminalControl) {
     let cleanupControl = terminalControl;
-    let terminalInputAttempted = false;
     try {
         let idleCapture;
         let revalidatedCommand;
         if (input.initialResidual) {
-            if (input.plan.behaviorProfile !== "codex-model-control-0.154.0") {
-                throw new Error("native model-control continuation is profiled only for Codex 0.154.0");
+            const profile = terminalModelControlProfileForPlan(input.plan);
+            if (!profile?.supportsResidualContinuation) {
+                throw new Error("native model-control continuation is profiled only for Codex " +
+                    CODEX_MODEL_CONTROL_AGENT_VERSION);
             }
             const observed = await inspectTerminalModelControlResidual({
                 plan: input.plan,
@@ -828,21 +920,18 @@ async function openModelPicker(input, terminalControl) {
         else {
             const before = await input.ports.capture({ terminalControl });
             cleanupControl = before.terminalControl;
-            if (before.activityState !== "idle" ||
-                modelControlCaptureBlocked(before) ||
-                !before.exactEmptyComposer) {
+            if (classifyTerminalModelControlSurface(input.plan, before).state !==
+                "idle_empty") {
                 throw new Error("model control requires an exact verified idle pane with an empty composer and no blocking interaction");
             }
             await input.ports.beforeInput();
             const finalEmpty = await input.ports.capture({
                 terminalControl: before.terminalControl
             });
-            if (finalEmpty.activityState !== "idle" ||
-                modelControlCaptureBlocked(finalEmpty) ||
-                !finalEmpty.exactEmptyComposer) {
+            if (classifyTerminalModelControlSurface(input.plan, finalEmpty).state !==
+                "idle_empty") {
                 throw new Error("the exact idle composer changed before /model input");
             }
-            terminalInputAttempted = true;
             await input.ports.sendText(finalEmpty.terminalControl, input.plan.command);
             let commandCapture;
             const startedAt = Date.now();
@@ -851,9 +940,10 @@ async function openModelPicker(input, terminalControl) {
                     terminalControl: before.terminalControl,
                     expectedComposer: input.plan.command
                 });
-                if (!modelControlCaptureBlocked(captured) &&
-                    captured.activityState !== "working" &&
-                    modelCommandReadyForEnter(input.plan, captured)) {
+                const surface = classifyTerminalModelControlSurface(input.plan, captured);
+                if (surface.state === "command_popup" ||
+                    isTerminalModelControlPlanForAgent(input.plan, "codex") &&
+                        surface.state === "bare_command") {
                     commandCapture = captured;
                     break;
                 }
@@ -867,15 +957,15 @@ async function openModelPicker(input, terminalControl) {
                 terminalControl: commandCapture.terminalControl,
                 expectedComposer: input.plan.command
             });
-            if (modelControlCaptureBlocked(revalidatedCommand) ||
-                revalidatedCommand.activityState === "working" ||
-                !modelCommandReadyForEnter(input.plan, revalidatedCommand)) {
+            const revalidatedSurface = classifyTerminalModelControlSurface(input.plan, revalidatedCommand);
+            if (revalidatedSurface.state !== "command_popup" &&
+                !(isTerminalModelControlPlanForAgent(input.plan, "codex") &&
+                    revalidatedSurface.state === "bare_command")) {
                 throw new Error("the exact /model composer changed before Enter");
             }
             idleCapture = finalEmpty;
         }
         cleanupControl = revalidatedCommand.terminalControl;
-        terminalInputAttempted = true;
         await input.ports.sendKeys(revalidatedCommand.terminalControl, ["C-m"]);
         let opened = await waitForObservation(input, revalidatedCommand.terminalControl, ["codex_entry_model_picker", "codex_model_picker", "claude_model_picker"]);
         if (opened.observation.state === "codex_entry_model_picker") {
@@ -902,9 +992,7 @@ async function openModelPicker(input, terminalControl) {
         return { ...opened, idleCapture };
     }
     catch (error) {
-        if (!terminalInputAttempted)
-            throw error;
-        const cleanupError = await tryUnwindModelControl(input, cleanupControl);
+        const { cleanupError } = await settleTerminalModelControlFailure(input, cleanupControl);
         if (!cleanupError)
             throw error;
         const detail = error instanceof Error ? error.message : String(error);
@@ -928,32 +1016,34 @@ async function unwindModelControl(input, terminalControl) {
             expectedComposer: input.plan.command
         });
         control = captured.terminalControl;
-        if (modelControlCaptureBlocked(captured) ||
-            captured.activityState === "working") {
+        const surface = classifyTerminalModelControlSurface(input.plan, captured);
+        if (surface.state === "blocked") {
             throw new Error("the terminal became busy or blocked during cleanup");
         }
-        if (captured.exactEmptyComposer && captured.activityState === "idle") {
+        if (surface.state === "idle_empty") {
             return captured;
         }
-        if (captured.exactCommandComposer) {
+        if (surface.state === "command_popup" ||
+            surface.state === "bare_command" ||
+            surface.state === "command_draft") {
             await input.ports.beforeInput();
             const finalCommand = await input.ports.capture({
                 terminalControl: control,
                 expectedComposer: input.plan.command
             });
-            if (modelControlCaptureBlocked(finalCommand) ||
-                finalCommand.activityState === "working" ||
-                !finalCommand.exactCommandComposer) {
+            const finalCommandSurface = classifyTerminalModelControlSurface(input.plan, finalCommand);
+            if (finalCommandSurface.state !== "command_popup" &&
+                finalCommandSurface.state !== "bare_command" &&
+                finalCommandSurface.state !== "command_draft") {
                 throw new Error("the exact /model composer changed during cleanup");
             }
             control = finalCommand.terminalControl;
-            if (finalCommand.exactCommandReady ||
-                input.plan.behaviorProfile === "claude-model-control-2.1.266" ||
-                finalCommand.exactBareCommand !== true) {
+            if (finalCommandSurface.state !== "bare_command" ||
+                isTerminalModelControlPlanForAgent(input.plan, "claude")) {
                 await input.ports.sendKeys(control, ["Escape"]);
                 const afterEscape = await waitForModelCommandCleanupState(input, control);
                 control = afterEscape.terminalControl;
-                if (afterEscape.exactEmptyComposer)
+                if (classifyTerminalModelControlSurface(input.plan, afterEscape).state === "idle_empty")
                     return afterEscape;
             }
             await input.ports.beforeInput();
@@ -961,10 +1051,7 @@ async function unwindModelControl(input, terminalControl) {
                 terminalControl: control,
                 expectedComposer: input.plan.command
             });
-            if (modelControlCaptureBlocked(finalBareCommand) ||
-                finalBareCommand.activityState === "working" ||
-                !finalBareCommand.exactCommandComposer ||
-                finalBareCommand.exactCommandReady) {
+            if (classifyTerminalModelControlSurface(input.plan, finalBareCommand).state !== "bare_command") {
                 throw new Error(`the exact bare ${input.plan.behaviorProfile.startsWith("codex-")
                     ? "Codex"
                     : "Claude"} /model composer changed during cleanup`);
@@ -977,10 +1064,10 @@ async function unwindModelControl(input, terminalControl) {
             control = cleared.capture.terminalControl;
             continue;
         }
-        const observation = observeTerminalModelControl(input.plan, captured.screen);
-        if (observation.state === "none" || observation.state === "ambiguous") {
+        if (surface.state !== "picker") {
             throw new Error("no exact current model-control frame was available for Escape");
         }
+        const observation = surface.observation;
         control = await exactDispatchKeys(input, control, observation, ["Escape"]);
         const next = await waitForObservation(input, control, [
             "none",
@@ -1007,17 +1094,13 @@ async function waitForModelCommandCleanupState(input, terminalControl) {
             terminalControl,
             expectedComposer: input.plan.command
         });
-        const exactState = captured.exactEmptyComposer ||
-            captured.exactCommandComposer && !captured.exactCommandReady &&
-                (input.plan.behaviorProfile === "claude-model-control-2.1.266" ||
-                    captured.exactBareCommand === true);
-        if (!modelControlCaptureBlocked(captured) &&
-            captured.activityState !== "working" && exactState) {
-            const semanticState = captured.exactEmptyComposer
+        const surface = classifyTerminalModelControlSurface(input.plan, captured);
+        if (surface.state === "idle_empty" || surface.state === "bare_command") {
+            const semanticState = surface.state === "idle_empty"
                 ? "empty"
-                : captured.exactCommandFingerprint
-                    ? `bare:${captured.exactCommandFingerprint}`
-                    : input.plan.behaviorProfile === "claude-model-control-2.1.266"
+                : surface.fingerprint
+                    ? `bare:${surface.fingerprint}`
+                    : isTerminalModelControlPlanForAgent(input.plan, "claude")
                         ? "bare:claude-profiled-composer"
                         : undefined;
             if (!semanticState) {
@@ -1073,9 +1156,11 @@ async function exactDispatchKeys(input, terminalControl, observation, keys) {
     }
     await input.ports.beforeInput();
     const captured = await input.ports.capture({ terminalControl });
-    const current = observeTerminalModelControl(input.plan, captured.screen);
-    if (modelControlCaptureBlocked(captured) ||
-        captured.activityState === "working" ||
+    const surface = classifyTerminalModelControlSurface(input.plan, captured);
+    const current = surface.state === "picker"
+        ? surface.observation
+        : undefined;
+    if (!current ||
         current.state !== observation.state ||
         current.fingerprint !== observation.fingerprint) {
         throw new Error("the native model-control frame changed before key dispatch");
@@ -1089,14 +1174,18 @@ async function waitForObservation(input, terminalControl, expectedStates, option
     let stableCaptures = 0;
     while (Date.now() - startedAt <= MODEL_CONTROL_SETTLE_TIMEOUT_MS) {
         const captured = await input.ports.capture({ terminalControl });
-        if (modelControlCaptureBlocked(captured) ||
-            captured.activityState === "working") {
+        const surface = classifyTerminalModelControlSurface(input.plan, captured);
+        if (surface.state === "blocked") {
             throw new Error("the terminal became busy or blocked during model control");
         }
-        const observation = observeTerminalModelControl(input.plan, captured.screen);
-        const expectedNone = observation.state === "none" && (options.allowImmediateNone === true && captured.exactEmptyComposer ||
+        const observation = surface.state === "picker"
+            ? surface.observation
+            : observeTerminalModelControl(input.plan, captured.screen);
+        const expectedNone = observation.state === "none" && (options.allowImmediateNone === true && surface.state === "idle_empty" ||
             options.allowExactCommandComposer === true &&
-                captured.exactCommandComposer);
+                (surface.state === "command_popup" ||
+                    surface.state === "bare_command" ||
+                    surface.state === "command_draft"));
         const expected = observation.fingerprint !== options.excludeFingerprint &&
             expectedStates.includes(observation.state) &&
             (observation.state !== "none" || expectedNone);
@@ -1125,11 +1214,13 @@ async function exactDismiss(input, terminalControl, observation) {
         allowExactCommandComposer: true,
         excludeFingerprint: observation.fingerprint
     });
-    if (closed.capture.exactEmptyComposer &&
-        closed.capture.activityState === "idle") {
+    const closedSurface = classifyTerminalModelControlSurface(input.plan, closed.capture);
+    if (closedSurface.state === "idle_empty") {
         return closed.capture;
     }
-    if (closed.capture.exactCommandComposer) {
+    if (closedSurface.state === "command_popup" ||
+        closedSurface.state === "bare_command" ||
+        closedSurface.state === "command_draft") {
         return unwindModelControl(input, closed.capture.terminalControl);
     }
     throw new Error("native model-control dismissal did not return to exact idle");