@scotthuang/agent-knock-knock 0.11.5 → 0.11.7

package/dist/src/terminal-agent-bridge.js

@@ -1,9 +1,11 @@
 import { createHash } from "node:crypto";
 import { formatTerminalConversationId, parseTerminalConversationId, terminalControlCapabilitiesForAdapter } from "./terminal-agent-adapter.js";
-import { enrichActiveProcessesWithTerminalControl, TerminalControlInputNotSentError, terminalRefFromPane } from "./terminal-control-provider.js";
-// Codex 0.146.x keeps Enter in paste/newline mode for 120ms after burst input.
-// Cross that boundary rather than landing on it, and also require observable
-// composer stability instead of treating this delay alone as acceptance.
+import { enrichActiveProcessesWithTerminalControl, TerminalControlInputNotSentError } from "./terminal-control-provider.js";
+import { hasCanonicalTerminalEndpoint, sameTerminalControlIncarnation, terminalEndpointFromControlRef, terminalEndpointIdentityKey } from "./terminal-control-ref.js";
+// Verified Codex profiles through 0.147.0 keep Enter in paste/newline mode for
+// 120ms after burst input. Cross that boundary rather than landing on it, and
+// also require observable composer stability instead of treating this delay
+// alone as acceptance.
 const CODEX_PASTE_ENTER_SETTLE_MS = 121;
 const CODEX_MULTILINE_SETTLE_POLL_MS = 30;
 const CODEX_MULTILINE_SETTLE_TIMEOUT_MS = 2_000;
@@ -11,12 +13,20 @@ const CODEX_MULTILINE_STABLE_CAPTURES = 2;
 const CODEX_MULTILINE_SETTLE_SCROLLBACK_LINES = 240;
 const CODEX_COMPOSER_MARKER = /^[›»](?:\s|$)/u;
 const CODEX_COMPOSER_FOOTER = /^(?:gpt-[\w.-]+(?:\s|$)|[-\w.]+ default ·)/u;
-// Codex 0.146.0 and 0.146.1 render the same verified slash-completion row.
-// Keep it closed per behavior profile so changed text cannot silently become
-// a newly authorized native command surface.
+// Keep every exact slash-completion shape closed per behavior profile so a
+// version adding another matching command cannot silently become an authorized
+// native command surface.
 const CODEX_NATIVE_STATUS_POPUP_BY_PROFILE = {
-    "codex-tui-0.146.0": "  /status  show current session configuration and token usage",
-    "codex-tui-0.146.1": "  /status  show current session configuration and token usage"
+    "codex-tui-0.146.0": [
+        "  /status  show current session configuration and token usage"
+    ],
+    "codex-tui-0.146.1": [
+        "  /status  show current session configuration and token usage"
+    ],
+    "codex-tui-0.147.0": [
+        "  /status      show current session configuration and token usage",
+        "  /statusline  configure which items appear in the status line"
+    ]
 };
 const CLAUDE_NATIVE_STATUS_POPUP_BY_PROFILE = {
     "claude-code-2.1.218-native-status": [
@@ -24,6 +34,12 @@ const CLAUDE_NATIVE_STATUS_POPUP_BY_PROFILE = {
         "/statusline Set up Claude Code's status line UI",
         "/ide Manage IDE integrations and show status",
         "/usage Show session cost, plan usage, and activity stats"
+    ],
+    "claude-code-2.1.226-native-status": [
+        "/status Show Claude Code status including version, model, account, API connectivity, and tool statuses",
+        "/statusline Set up Claude Code's status line UI",
+        "/ide Manage IDE integrations and show status",
+        "/usage Show session cost, plan usage, and activity stats"
     ]
 };
 const CODEX_LARGE_PASTE_CHAR_THRESHOLD = 1_000;
@@ -109,34 +125,57 @@ export class TerminalAgentBridge {
             throw new Error(`process ${process.pid} is not terminal-controlled`);
         }
         this.registry.require(process.agent);
+        const terminal = this.terminalProvider.endpoint(process.terminalControl);
         return formatTerminalConversationId({
             agent: process.agent,
-            target: process.terminalControl.target,
+            target: terminal.route.label,
             pid: process.pid
         });
     }
+    /**
+     * Resolve a persisted control reference by stable endpoint identity. This is
+     * the managed-Session path: its route-shaped v2 terminal id is only a
+     * compatibility alias and may be stale after an explicit provider refresh.
+     */
+    async resolveStoredTerminal(agent, pid, terminalControl, runtime = { pid }) {
+        const adapter = this.registry.require(agent);
+        const freshControl = await this.verifyTerminalIdentity(agent, terminalControl, { ...runtime, pid });
+        return {
+            conversationId: this.terminalConversationId({
+                agent,
+                pid,
+                terminalControl: freshControl
+            }),
+            agent,
+            pid,
+            legacy: false,
+            adapter,
+            terminalControl: freshControl
+        };
+    }
     async resolveConversationId(conversationId) {
         const parsed = parseTerminalConversationId(conversationId);
         if (!parsed) {
             return undefined;
         }
         const adapter = this.registry.require(parsed.agent);
-        const panes = await this.terminalProvider.listPanes();
-        const candidates = panes.filter((candidate) => candidate.kind === parsed.kind && candidate.target === parsed.target);
+        const terminals = await this.terminalProvider.listTerminals();
+        const candidates = terminals.filter((candidate) => candidate.identity.providerKind === parsed.kind &&
+            candidate.route.label === parsed.target);
         const verified = this.verifyIdentity
-            ? (await Promise.all(candidates.map(async (pane) => {
-                const terminalControl = terminalRefFromPane(pane, terminalControlCapabilitiesForAdapter(adapter));
+            ? (await Promise.all(candidates.map(async (terminal) => {
+                const terminalControl = this.terminalProvider.toControlRef(terminal, terminalControlCapabilitiesForAdapter(adapter));
                 try {
                     const verifiedTerminalControl = await this.verifyTerminalIdentity(adapter.agent, terminalControl, { pid: parsed.pid });
-                    return { pane, terminalControl: verifiedTerminalControl };
+                    return { terminal, terminalControl: verifiedTerminalControl };
                 }
                 catch {
                     return undefined;
                 }
             }))).filter((candidate) => candidate !== undefined)
-            : candidates.slice(0, 1).map((pane) => ({
-                pane,
-                terminalControl: terminalRefFromPane(pane, terminalControlCapabilitiesForAdapter(adapter))
+            : candidates.slice(0, 1).map((terminal) => ({
+                terminal,
+                terminalControl: this.terminalProvider.toControlRef(terminal, terminalControlCapabilitiesForAdapter(adapter))
             }));
         if (verified.length === 0) {
             throw new Error(`terminal-controlled session ${parsed.conversationId} is no longer available`);
@@ -188,14 +227,34 @@ export class TerminalAgentBridge {
     }
     async send(agent, terminalControl, text, options = {}) {
         const adapter = this.registry.require(agent);
-        if (!terminalControl.capabilities.includes("send_keys")) {
-            throw new TerminalInputNotStartedError(`${adapter.displayName} terminal input is not supported`);
+        const multiline = /[\r\n]/u.test(text.trimEnd());
+        try {
+            assertTerminalMutationCapabilities({
+                provider: this.terminalProvider,
+                terminal: this.terminalProvider.endpoint(terminalControl),
+                semantic: [
+                    "send_keys",
+                    ...(adapter.agent === "codex" && multiline
+                        ? ["screen_status"]
+                        : [])
+                ],
+                transport: [
+                    "stable_resource_resolution",
+                    "text_delivery",
+                    "key_delivery",
+                    ...(adapter.agent === "codex" && multiline
+                        ? ["screen_capture"]
+                        : [])
+                ]
+            });
+        }
+        catch (error) {
+            throw new TerminalInputNotStartedError(error instanceof Error ? error.message : String(error), { cause: error });
         }
         const normalized = text.trimEnd();
         if (!normalized) {
             throw new TerminalInputNotStartedError("terminal message is empty");
         }
-        const multiline = /[\r\n]/u.test(normalized);
         let verifiedForText;
         try {
             verifiedForText = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
@@ -204,9 +263,10 @@ export class TerminalAgentBridge {
             throw new TerminalInputNotStartedError(error instanceof Error ? error.message : String(error), { cause: error });
         }
         try {
-            await this.terminalProvider.sendText(verifiedForText.target, normalized, {
-                socketPath: verifiedForText.socketPath
-            });
+            if (!verifiedForText.capabilities.includes("send_keys")) {
+                throw new TerminalControlInputNotSentError(`${adapter.displayName} terminal input capability changed before injection`);
+            }
+            await this.terminalProvider.sendText(this.terminalProvider.endpoint(verifiedForText), normalized);
         }
         catch (error) {
             if (error instanceof TerminalControlInputNotSentError) {
@@ -223,8 +283,9 @@ export class TerminalAgentBridge {
             multiline
         });
         // Text and Enter are separate tmux operations. Revalidate between them and
-        // never submit after identity or composer drift. The legacy single-line
-        // path retains its best-effort pre-submit cleanup behavior.
+        // never submit after identity or composer drift. A failed revalidation
+        // leaves the injected draft untouched because cleanup is also terminal
+        // input and cannot safely use a stale route.
         let verifiedForEnter;
         if (adapter.agent === "codex" && multiline) {
             verifiedForEnter = await this.settleCodexMultilineComposer(adapter, terminalControl, normalized, options.runtime);
@@ -234,20 +295,10 @@ export class TerminalAgentBridge {
                 verifiedForEnter = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
             }
             catch (error) {
-                try {
-                    await this.terminalProvider.sendKeys(verifiedForText.target, ["C-u"], {
-                        socketPath: verifiedForText.socketPath
-                    });
-                }
-                catch {
-                    // Best effort only: preserving the identity failure is more important than cleanup.
-                }
                 throw error;
             }
         }
-        await this.terminalProvider.sendKeys(verifiedForEnter.target, ["C-m"], {
-            socketPath: verifiedForEnter.socketPath
-        });
+        await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(verifiedForEnter), ["C-m"]);
         await options.onTransportStage?.({
             stage: "enter_dispatched",
             agent: adapter.agent,
@@ -272,6 +323,17 @@ export class TerminalAgentBridge {
         const adapter = this.registry.require(agent);
         try {
             assertClosedStatusInspectionPlan(adapter, terminalControl, plan);
+            assertTerminalMutationCapabilities({
+                provider: this.terminalProvider,
+                terminal: this.terminalProvider.endpoint(terminalControl),
+                semantic: ["send_keys", "screen_status"],
+                transport: [
+                    "stable_resource_resolution",
+                    "screen_capture",
+                    "text_delivery",
+                    "key_delivery"
+                ]
+            });
         }
         catch (error) {
             throw nativeInspectionSubmissionError("not_started", error);
@@ -284,7 +346,10 @@ export class TerminalAgentBridge {
             throw nativeInspectionSubmissionError("not_started", error);
         }
         try {
-            await this.terminalProvider.sendText(verifiedForText.target, plan.command, { socketPath: verifiedForText.socketPath });
+            if (!verifiedForText.capabilities.includes("send_keys")) {
+                throw new TerminalControlInputNotSentError(`${adapter.displayName} native inspection input capability changed`);
+            }
+            await this.terminalProvider.sendText(this.terminalProvider.endpoint(verifiedForText), plan.command);
         }
         catch (error) {
             if (error instanceof TerminalControlInputNotSentError) {
@@ -312,7 +377,7 @@ export class TerminalAgentBridge {
         try {
             // Exactly one Enter attempt. Any error is submission-uncertain and must
             // never trigger a fallback executable or a blind second Enter.
-            await this.terminalProvider.sendKeys(settled.terminalControl.target, ["C-m"], { socketPath: settled.terminalControl.socketPath });
+            await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(settled.terminalControl), ["C-m"]);
         }
         catch (error) {
             throw nativeInspectionSubmissionError("enter_uncertain", error);
@@ -415,7 +480,7 @@ export class TerminalAgentBridge {
             });
             verified = await observeExactPanel(verified);
             try {
-                await this.terminalProvider.sendKeys(verified.target, plan.expectedResult.dismissal.keys, { socketPath: verified.socketPath });
+                await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(verified), plan.expectedResult.dismissal.keys);
             }
             catch (error) {
                 throw new NativeInspectionDismissalError("native status modal dismissal outcome is uncertain; do not retry automatically", { cause: error });
@@ -437,11 +502,12 @@ export class TerminalAgentBridge {
     }
     async settleNativeInspectionComposer(adapter, terminalControl, plan, runtime) {
         const startedAt = performance.now();
+        const settleTimeoutMs = plan.composer.maximumSettleMs;
         let stableDigest;
         let stableKind;
         let stableSince;
         let stableCaptures = 0;
-        while (performance.now() - startedAt <= CODEX_MULTILINE_SETTLE_TIMEOUT_MS) {
+        while (performance.now() - startedAt <= settleTimeoutMs) {
             const captured = await this.captureInspection(adapter, terminalControl, {
                 runtime,
                 scrollbackLines: CODEX_MULTILINE_SETTLE_SCROLLBACK_LINES
@@ -479,7 +545,7 @@ export class TerminalAgentBridge {
                 stableCaptures = 0;
             }
             const elapsed = performance.now() - startedAt;
-            const remaining = CODEX_MULTILINE_SETTLE_TIMEOUT_MS - elapsed;
+            const remaining = settleTimeoutMs - elapsed;
             if (remaining <= 0) {
                 break;
             }
@@ -626,13 +692,14 @@ export class TerminalAgentBridge {
      */
     async clearInputLine(agent, terminalControl, options = {}) {
         const adapter = this.registry.require(agent);
-        if (!terminalControl.capabilities.includes("send_keys")) {
-            throw new Error(`${adapter.displayName} terminal input is not supported`);
-        }
-        const verified = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
-        await this.terminalProvider.sendKeys(verified.target, ["C-u"], {
-            socketPath: verified.socketPath
+        assertTerminalMutationCapabilities({
+            provider: this.terminalProvider,
+            terminal: this.terminalProvider.endpoint(terminalControl),
+            semantic: ["send_keys"],
+            transport: ["stable_resource_resolution", "key_delivery"]
         });
+        const verified = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
+        await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(verified), ["C-u"]);
     }
     async cancel(agent, terminalControl, options = {}) {
         const adapter = this.registry.require(agent);
@@ -657,10 +724,14 @@ export class TerminalAgentBridge {
                 reason: `${adapter.displayName} terminal cancellation is not supported`
             };
         }
-        const verifiedForCancel = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
-        await this.terminalProvider.sendKeys(verifiedForCancel.target, adapter.cancelKeys, {
-            socketPath: verifiedForCancel.socketPath
+        assertTerminalMutationCapabilities({
+            provider: this.terminalProvider,
+            terminal: this.terminalProvider.endpoint(terminalControl),
+            semantic: ["terminal_cancel", "send_keys"],
+            transport: ["stable_resource_resolution", "key_delivery"]
         });
+        const verifiedForCancel = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
+        await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(verifiedForCancel), adapter.cancelKeys);
         return {
             cancelRequested: true,
             key: adapter.cancelKeys.length === 1 ? adapter.cancelKeys[0] : undefined,
@@ -677,6 +748,16 @@ export class TerminalAgentBridge {
                 reason: `${adapter.displayName} terminal approval is not supported`
             };
         }
+        assertTerminalMutationCapabilities({
+            provider: this.terminalProvider,
+            terminal: this.terminalProvider.endpoint(terminalControl),
+            semantic: ["screen_status", "terminal_approval", "send_keys"],
+            transport: [
+                "stable_resource_resolution",
+                "screen_capture",
+                "key_delivery"
+            ]
+        });
         const captured = await this.captureInspection(adapter, terminalControl, options);
         const { inspection } = captured;
         const activeTerminalControl = captured.terminalControl;
@@ -719,10 +800,24 @@ export class TerminalAgentBridge {
                 screenExcerpt: inspection.screenExcerpt
             };
         }
-        const fingerprint = terminalApprovalFingerprint(adapter.agent, activeTerminalControl, inspection, {
+        const canonicalFingerprint = terminalApprovalFingerprint(adapter.agent, activeTerminalControl, inspection, {
             screen: captured.screen,
             runtime: options.runtime
         });
+        const legacyFingerprint = hasCanonicalTerminalEndpoint(terminalControl)
+            ? undefined
+            : terminalApprovalFingerprint(adapter.agent, terminalControl, inspection, {
+                screen: captured.screen,
+                runtime: options.runtime
+            });
+        const useLegacyFingerprint = Boolean(options.expectedFingerprint &&
+            options.expectedFingerprint === legacyFingerprint);
+        const fingerprintControl = useLegacyFingerprint
+            ? terminalControl
+            : activeTerminalControl;
+        const fingerprint = useLegacyFingerprint
+            ? legacyFingerprint
+            : canonicalFingerprint;
         if (adapter.agent === "claude" &&
             decisionMode === "keys" &&
             !options.expectedFingerprint) {
@@ -809,7 +904,7 @@ export class TerminalAgentBridge {
             };
         }
         const recapturedDecisionMode = recapturedInspection.approval.action.mode ?? "keys";
-        const recapturedFingerprint = terminalApprovalFingerprint(adapter.agent, recaptured.terminalControl, recapturedInspection, {
+        const recapturedFingerprint = terminalApprovalFingerprint(adapter.agent, fingerprintControl, recapturedInspection, {
             screen: recaptured.screen,
             runtime: options.runtime
         });
@@ -892,7 +987,7 @@ export class TerminalAgentBridge {
                 };
             }
             const afterReservationMode = afterReservationInspection.approval.action.mode ?? "keys";
-            const afterReservationFingerprint = terminalApprovalFingerprint(adapter.agent, afterReservation.terminalControl, afterReservationInspection, {
+            const afterReservationFingerprint = terminalApprovalFingerprint(adapter.agent, fingerprintControl, afterReservationInspection, {
                 screen: afterReservation.screen,
                 runtime: options.runtime
             });
@@ -934,7 +1029,7 @@ export class TerminalAgentBridge {
         if (!sameTerminalControlIdentity(dispatchTerminalControl, verifiedImmediatelyBeforeSend)) {
             throw new Error("terminal control identity changed after the final approval capture");
         }
-        await this.terminalProvider.sendKeys(verifiedImmediatelyBeforeSend.target, dispatchApproval.action.keys, { socketPath: verifiedImmediatelyBeforeSend.socketPath });
+        await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(verifiedImmediatelyBeforeSend), dispatchApproval.action.keys);
         return {
             approved: true,
             blocked: false,
@@ -1007,10 +1102,7 @@ export class TerminalAgentBridge {
     }
     async captureInspection(adapter, terminalControl, options = {}) {
         const verifiedTerminalControl = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
-        const screen = await this.terminalProvider.capture(verifiedTerminalControl.target, {
-            scrollbackLines: options.scrollbackLines ?? 120,
-            socketPath: verifiedTerminalControl.socketPath
-        });
+        const screen = await this.terminalProvider.capture(this.terminalProvider.endpoint(verifiedTerminalControl), { scrollbackLines: options.scrollbackLines ?? 120 });
         return {
             terminalControl: verifiedTerminalControl,
             screen,
@@ -1025,21 +1117,46 @@ export class TerminalAgentBridge {
         };
     }
     async verifyTerminalIdentity(agent, terminalControl, runtime) {
-        if (!this.verifyIdentity) {
-            return terminalControl;
+        let verifiedControl = terminalControl;
+        if (this.verifyIdentity) {
+            if (!Number.isInteger(runtime?.pid) || Number(runtime?.pid) <= 0) {
+                throw new Error(`refusing terminal access for ${agent}:${terminalControl.target} without an exact agent pid; reattach this legacy tmux session before controlling it`);
+            }
+            const result = await this.verifyIdentity({
+                agent,
+                pid: Number(runtime?.pid),
+                terminalControl,
+                runtime
+            });
+            verifiedControl = result?.terminalControl ?? terminalControl;
+            if (!sameTerminalControlIncarnation(terminalControl, verifiedControl)) {
+                throw new Error("terminal control identity changed during identity verification");
+            }
         }
-        if (!Number.isInteger(runtime?.pid) || Number(runtime?.pid) <= 0) {
-            throw new Error(`refusing terminal access for ${agent}:${terminalControl.target} without an exact agent pid; reattach this legacy tmux session before controlling it`);
+        const verifiedEndpoint = this.terminalProvider.endpoint(verifiedControl);
+        const resolvedEndpoint = await this.terminalProvider.resolve(verifiedEndpoint);
+        if (hasCanonicalTerminalEndpoint(verifiedControl) &&
+            !sameTerminalControlIncarnation(verifiedEndpoint, resolvedEndpoint)) {
+            throw new Error("terminal stable resource or process anchor changed during fresh resolution");
         }
-        const result = await this.verifyIdentity({
-            agent,
-            pid: Number(runtime?.pid),
-            terminalControl,
-            runtime
-        });
-        return result?.terminalControl ?? terminalControl;
+        return this.terminalProvider.toControlRef(resolvedEndpoint, verifiedControl.capabilities);
     }
 }
+function assertTerminalMutationCapabilities({ provider, terminal, semantic, transport }) {
+    const missingSemantic = semantic.filter((capability) => !provider.supportedCapabilities.includes(capability) ||
+        !terminal.capabilities.includes(capability));
+    const missingTransport = transport.filter((capability) => !provider.providerCapabilities.includes(capability));
+    if (missingSemantic.length === 0 && missingTransport.length === 0) {
+        return;
+    }
+    const missing = [
+        ...missingSemantic.map((value) => `terminal:${value}`),
+        ...missingTransport.map((value) => `provider:${value}`)
+    ];
+    throw new TerminalControlInputNotSentError(`terminal action capability preflight failed for ` +
+        `${terminal.identity.providerKind}:${terminal.route.label}: ` +
+        missing.join(", "));
+}
 function nativeInspectionSubmissionError(stage, error) {
     if (error instanceof NativeInspectionSubmissionError) {
         const stageRank = {
@@ -1063,19 +1180,26 @@ function assertClosedStatusInspectionPlan(adapter, terminalControl, plan) {
     if (!terminalControl.capabilities.includes("screen_status")) {
         throw new Error(`${adapter.displayName} terminal screen inspection is not supported`);
     }
-    const codexProfile = adapter.agent === "codex" && [
-        "codex-tui-0.146.0",
-        "codex-tui-0.146.1"
-    ].includes(plan.behaviorProfile);
+    const codexProfile = adapter.agent === "codex" &&
+        CODEX_NATIVE_STATUS_POPUP_BY_PROFILE[plan.behaviorProfile] !== undefined;
     const claudeProfile = adapter.agent === "claude" &&
-        plan.behaviorProfile === "claude-code-2.1.218-native-status";
+        CLAUDE_NATIVE_STATUS_POPUP_BY_PROFILE[plan.behaviorProfile] !== undefined;
+    const expectedSettle = codexProfile
+        ? { minimumStableMs: CODEX_PASTE_ENTER_SETTLE_MS, maximumSettleMs: 2_000 }
+        : plan.behaviorProfile === "claude-code-2.1.218-native-status"
+            ? { minimumStableMs: 80, maximumSettleMs: 2_000 }
+            : plan.behaviorProfile === "claude-code-2.1.226-native-status"
+                ? { minimumStableMs: 80, maximumSettleMs: 5_000 }
+                : undefined;
     const exactPresentation = codexProfile
         ? plan.expectedResult.presentation === "inline" &&
             plan.expectedResult.dismissal === undefined &&
-            plan.composer.minimumStableMs >= CODEX_PASTE_ENTER_SETTLE_MS
+            plan.composer.minimumStableMs === expectedSettle?.minimumStableMs &&
+            plan.composer.maximumSettleMs === expectedSettle.maximumSettleMs
         : claudeProfile
             ? plan.expectedResult.presentation === "modal" &&
-                plan.composer.minimumStableMs >= 80 &&
+                plan.composer.minimumStableMs === expectedSettle?.minimumStableMs &&
+                plan.composer.maximumSettleMs === expectedSettle.maximumSettleMs &&
                 plan.expectedResult.dismissal?.expected === "idle_empty_composer" &&
                 JSON.stringify(plan.expectedResult.dismissal.keys) ===
                     JSON.stringify(["Escape"])
@@ -1087,6 +1211,8 @@ function assertClosedStatusInspectionPlan(adapter, terminalControl, plan) {
         plan.composer.kind !== "exact" ||
         !Number.isFinite(plan.composer.minimumStableMs) ||
         plan.composer.minimumStableMs < 0 ||
+        !Number.isFinite(plan.composer.maximumSettleMs) ||
+        plan.composer.maximumSettleMs < plan.composer.minimumStableMs ||
         plan.expectedResult.kind !== "native_status" ||
         !exactPresentation) {
         throw new Error("refusing a non-closed or unverified native inspection plan");
@@ -1146,9 +1272,8 @@ function exactCodexNativeInspectionComposerCapture(screen, plan) {
     if (popupRows.length === 0) {
         kind = "exact_slash_composer";
     }
-    else if (popupRows.length === 1 &&
-        popupRows[0].trimEnd() ===
-            CODEX_NATIVE_STATUS_POPUP_BY_PROFILE[plan.behaviorProfile]) {
+    else if (JSON.stringify(popupRows.map((line) => line.trimEnd())) ===
+        JSON.stringify(CODEX_NATIVE_STATUS_POPUP_BY_PROFILE[plan.behaviorProfile])) {
         kind = "exact_slash_popup";
     }
     else {
@@ -1189,7 +1314,7 @@ function exactClaudeNativeInspectionComposerCapture(screen, plan) {
                 return undefined;
             }
         }
-        if (JSON.stringify(suggestions) !== JSON.stringify(CLAUDE_NATIVE_STATUS_POPUP_BY_PROFILE[plan.behaviorProfile])) {
+        if (!closedClaudeNativeStatusSuggestionsMatch(suggestions, CLAUDE_NATIVE_STATUS_POPUP_BY_PROFILE[plan.behaviorProfile])) {
             return undefined;
         }
         kind = "exact_slash_popup";
@@ -1202,7 +1327,33 @@ function exactClaudeNativeInspectionComposerCapture(screen, plan) {
     };
 }
 /**
- * Prove the exact idle input frame from the verified Claude Code 2.1.218
+ * Claude truncates a suggestion row with a Unicode ellipsis at narrow pane
+ * widths. Keep authorization closed by accepting only an exact ordered row or
+ * an explicit ellipsis whose preceding text is an exact, non-trivial prefix of
+ * that same profiled row. A caller still cannot introduce, omit, or reorder a
+ * slash command.
+ */
+function closedClaudeNativeStatusSuggestionsMatch(observed, expected) {
+    if (!expected || observed.length !== expected.length) {
+        return false;
+    }
+    return observed.every((row, index) => {
+        const exact = expected[index];
+        if (row === exact) {
+            return true;
+        }
+        if (!row.endsWith("…")) {
+            return false;
+        }
+        const prefix = row.slice(0, -1);
+        const commandEnd = exact.indexOf(" ");
+        return (commandEnd > 0 &&
+            prefix.length >= commandEnd + 12 &&
+            exact.startsWith(prefix));
+    });
+}
+/**
+ * Prove the exact idle input frame from a verified Claude Code native-status
  * profile. A loose or historical `❯` prompt is not enough to authorize even
  * the initial literal `/status` injection.
  */
@@ -1383,13 +1534,7 @@ async function terminalSettleDelay(milliseconds) {
     await new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 function sameTerminalControlIdentity(left, right) {
-    return left.kind === right.kind &&
-        left.target === right.target &&
-        left.socketPath === right.socketPath &&
-        left.session === right.session &&
-        left.window === right.window &&
-        left.pane === right.pane &&
-        left.panePid === right.panePid;
+    return sameTerminalControlIncarnation(left, right);
 }
 export function terminalApprovalFingerprint(agent, terminalControl, inspection, options = {}) {
     if (!inspection.approval.approvable) {
@@ -1399,18 +1544,28 @@ export function terminalApprovalFingerprint(agent, terminalControl, inspection,
     const rawScreenDigest = decisionMode === "keys" && options.screen !== undefined
         ? createHash("sha256").update(options.screen).digest("hex")
         : undefined;
-    return createHash("sha256")
-        .update(JSON.stringify({
-        agent,
-        provider: "tmux",
-        terminal: {
+    const terminal = terminalEndpointFromControlRef(terminalControl);
+    // A pending v0.11.x approval may outlive an upgrade. Preserve its exact
+    // fingerprint until the persisted control record has canonical endpoint
+    // evidence; new records bind the fingerprint to stable endpoint identity.
+    const terminalFingerprint = hasCanonicalTerminalEndpoint(terminalControl)
+        ? {
+            identity: terminalEndpointIdentityKey(terminal),
+            process_anchor_pid: terminal.processAnchorPid
+        }
+        : {
             target: terminalControl.target,
             socket_path: terminalControl.socketPath,
             session: terminalControl.session,
             window: terminalControl.window,
             pane: terminalControl.pane,
             pane_pid: terminalControl.panePid
-        },
+        };
+    return createHash("sha256")
+        .update(JSON.stringify({
+        agent,
+        provider: terminal.identity.providerKind,
+        terminal: terminalFingerprint,
         runtime: {
             pid: options.runtime?.pid,
             session_id: options.runtime?.sessionId,