@scotthuang/agent-knock-knock 0.12.2 → 0.12.4

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

@@ -28,6 +28,16 @@ const CODEX_NATIVE_STATUS_POPUP_BY_PROFILE = {
         "  /statusline  configure which items appear in the status line"
     ]
 };
+// Codex's verified `/status` profiles are exercised against its canonical
+// 80-column status surface. Narrower layouts can truncate the 36-character
+// Session UUID after a dynamically sized label column. Exact provider geometry
+// is required before input; ANSI visible-buffer width is only a conservative
+// fallback diagnostic and never upgrades unknown geometry to safe.
+const CODEX_NATIVE_STATUS_MIN_VIEWPORT_BY_PROFILE = {
+    "codex-tui-0.146.0": 80,
+    "codex-tui-0.146.1": 80,
+    "codex-tui-0.147.0": 80
+};
 const CLAUDE_NATIVE_STATUS_POPUP_BY_PROFILE = {
     "claude-code-2.1.218-native-status": [
         "/status Show Claude Code status including version, model, account, API connectivity, and tool statuses",
@@ -67,6 +77,16 @@ export class NativeInspectionSubmissionError extends Error {
         this.stage = stage;
         this.name = "NativeInspectionSubmissionError";
         this.doNotRetry = stage !== "not_started";
+        this.diagnostic = options.diagnostic;
+    }
+    diagnostic;
+}
+class NativeInspectionDiagnosticError extends Error {
+    diagnostic;
+    constructor(diagnostic, message, options = {}) {
+        super(message, options);
+        this.diagnostic = diagnostic;
+        this.name = "NativeInspectionDiagnosticError";
     }
 }
 /** A verified modal could not be dismissed across one exact key attempt. */
@@ -376,6 +396,49 @@ export class TerminalAgentBridge {
      * draft untouched instead of issuing the legacy best-effort C-u cleanup.
      */
     async submitNativeInspection(agent, terminalControl, plan, options = {}) {
+        return this.submitClosedNativeInspection(agent, terminalControl, plan, options, { requireCodexReadyComposer: agent === "codex" });
+    }
+    /**
+     * Submit Codex's closed, version-profiled `/status` probe.
+     *
+     * Unlike the generic native-inspection entry point, callers provide only
+     * the detected Codex version, never a command or plan. The bridge proves an
+     * exact empty (or fully dim replace-on-type) ANSI composer before injecting
+     * text, then crosses Codex's paste suppression window under the same exact
+     * composer and terminal-identity fences used by native inspection.
+     */
+    async submitCodexStatusProbe(terminalControl, agentVersion, options = {}) {
+        const adapter = this.registry.require("codex");
+        let plan;
+        try {
+            const capability = adapter.probeNativeInspection?.(agentVersion);
+            if (capability?.status !== "supported" ||
+                capability.statusInspection !== true) {
+                throw new NativeInspectionDiagnosticError("unsupported_profile", capability?.reason ??
+                    `Codex ${agentVersion} has no closed /status behavior profile`);
+            }
+            const planned = adapter.planNativeInspection?.({ kind: "status" }, capability);
+            if (!planned) {
+                throw new NativeInspectionDiagnosticError("unsupported_profile", `Codex ${agentVersion} did not produce a closed /status plan`);
+            }
+            plan = planned;
+        }
+        catch (error) {
+            throw nativeInspectionSubmissionError("not_started", error, "unsupported_profile");
+        }
+        const result = await this.submitClosedNativeInspection("codex", terminalControl, plan, options, { requireCodexReadyComposer: true });
+        if (!result.preTextScreenDigest) {
+            throw new Error("Codex /status pre-text composer evidence is missing");
+        }
+        return {
+            ...result,
+            agent: "codex",
+            preTextScreenDigest: result.preTextScreenDigest,
+            observationBaselineDigest: bareDigestFromNativeInspectionScreenFingerprint(result.preEnterScreenDigest),
+            observationScrollbackLines: CODEX_MULTILINE_SETTLE_SCROLLBACK_LINES
+        };
+    }
+    async submitClosedNativeInspection(agent, terminalControl, plan, options, safety = {}) {
         const adapter = this.registry.require(agent);
         try {
             assertClosedStatusInspectionPlan(adapter, terminalControl, plan);
@@ -387,19 +450,33 @@ export class TerminalAgentBridge {
                     "stable_resource_resolution",
                     "screen_capture",
                     "text_delivery",
-                    "key_delivery"
+                    "key_delivery",
+                    ...(safety.requireCodexReadyComposer
+                        ? ["ansi_capture"]
+                        : [])
                 ]
             });
         }
         catch (error) {
-            throw nativeInspectionSubmissionError("not_started", error);
+            throw nativeInspectionSubmissionError("not_started", error, "capability_unavailable");
         }
         let verifiedForText;
         try {
             verifiedForText = await this.verifyTerminalIdentity(adapter.agent, terminalControl, options.runtime);
         }
         catch (error) {
-            throw nativeInspectionSubmissionError("not_started", error);
+            throw nativeInspectionSubmissionError("not_started", error, "identity_unverified");
+        }
+        let preTextScreenDigest;
+        if (safety.requireCodexReadyComposer) {
+            try {
+                const ready = await this.captureCodexReadyComposer(adapter, verifiedForText, plan, options.runtime);
+                verifiedForText = ready.terminalControl;
+                preTextScreenDigest = ready.screenDigest;
+            }
+            catch (error) {
+                throw nativeInspectionSubmissionError("not_started", error, "composer_not_ready");
+            }
         }
         try {
             if (!verifiedForText.capabilities.includes("send_keys")) {
@@ -409,11 +486,11 @@ export class TerminalAgentBridge {
         }
         catch (error) {
             if (error instanceof TerminalControlInputNotSentError) {
-                throw nativeInspectionSubmissionError("not_started", error);
+                throw nativeInspectionSubmissionError("not_started", error, "text_delivery_unproven");
             }
             // The transport cannot prove whether an untyped failure happened before
             // or after tmux accepted the literal input. Fail closed as injected.
-            throw nativeInspectionSubmissionError("text_injected", error);
+            throw nativeInspectionSubmissionError("text_injected", error, "text_delivery_unproven");
         }
         let settled;
         try {
@@ -425,10 +502,20 @@ export class TerminalAgentBridge {
                 preEnterScreenDigest: settled.screenDigest,
                 materialization: settled.materialization
             });
+            if (safety.requireCodexReadyComposer) {
+                settled = {
+                    ...settled,
+                    terminalControl: await this.assertFinalCodexStatusViewport(settled.terminalControl, plan, options.runtime)
+                };
+            }
+            // Viewport inspection may await provider I/O and the PTY may receive
+            // human input while that proof is in flight. Keep the exact composer
+            // capture as the final substantive asynchronous evidence before the
+            // single Enter attempt.
             settled = await this.revalidateNativeInspectionComposer(adapter, settled.terminalControl, plan, settled.materialization, options.runtime);
         }
         catch (error) {
-            throw nativeInspectionSubmissionError("text_injected", error);
+            throw nativeInspectionSubmissionError("text_injected", error, "composer_not_exact");
         }
         try {
             // Exactly one Enter attempt. Any error is submission-uncertain and must
@@ -436,7 +523,7 @@ export class TerminalAgentBridge {
             await this.terminalProvider.sendKeys(this.terminalProvider.endpoint(settled.terminalControl), ["C-m"]);
         }
         catch (error) {
-            throw nativeInspectionSubmissionError("enter_uncertain", error);
+            throw nativeInspectionSubmissionError("enter_uncertain", error, "enter_uncertain");
         }
         return {
             stage: "enter_dispatched",
@@ -447,7 +534,8 @@ export class TerminalAgentBridge {
             preEnterScreenDigest: settled.screenDigest,
             preEnterEvidenceInventory: settled.evidenceInventory,
             materialization: settled.materialization,
-            enterCount: 1
+            enterCount: 1,
+            ...(preTextScreenDigest ? { preTextScreenDigest } : {})
         };
     }
     async observeNativeInspection(agent, terminalControl, request, options = {}) {
@@ -556,6 +644,121 @@ export class TerminalAgentBridge {
             throw new NativeInspectionDismissalError(error instanceof Error ? error.message : String(error), { cause: error });
         }
     }
+    async captureCodexReadyComposer(adapter, terminalControl, plan, runtime) {
+        if (adapter.agent !== "codex") {
+            throw new NativeInspectionDiagnosticError("unsupported_profile", "the closed Codex /status probe requires the Codex adapter");
+        }
+        const minimumViewport = CODEX_NATIVE_STATUS_MIN_VIEWPORT_BY_PROFILE[plan.behaviorProfile];
+        if (minimumViewport === undefined) {
+            throw new NativeInspectionDiagnosticError("unsupported_profile", `Codex ${plan.behaviorProfile} has no exact /status viewport profile`);
+        }
+        const captureReady = async (control) => {
+            const verified = await this.verifyTerminalIdentity(adapter.agent, control, runtime);
+            const endpoint = this.terminalProvider.endpoint(verified);
+            const viewportInspector = this.terminalProvider.inspectViewport;
+            let exactViewport;
+            let viewportUnavailableReason = "terminal provider has no exact viewport inspector";
+            if (viewportInspector) {
+                let viewport;
+                try {
+                    viewport = await viewportInspector.call(this.terminalProvider, endpoint);
+                }
+                catch (error) {
+                    throw new NativeInspectionDiagnosticError("viewport_unavailable", `Codex /status viewport inspection failed before terminal input: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                }
+                if (viewport) {
+                    if (!Number.isSafeInteger(viewport.columns) ||
+                        viewport.columns <= 0 ||
+                        !Number.isSafeInteger(viewport.rows) ||
+                        viewport.rows <= 0) {
+                        throw new NativeInspectionDiagnosticError("viewport_unavailable", "Codex /status viewport inspector returned invalid geometry");
+                    }
+                    exactViewport = viewport.columns;
+                }
+                else {
+                    viewportUnavailableReason =
+                        "terminal provider could not prove exact viewport geometry";
+                }
+            }
+            const styledScreen = await this.terminalProvider.capture(endpoint, { scrollbackLines: 40, preserveEscapes: true });
+            const plainScreen = stripTerminalEscapeSequences(styledScreen);
+            const inspection = adapter.inspectScreen({ screen: plainScreen, runtime });
+            assertNativeInspectionComposerSafe(inspection, adapter.displayName);
+            const composer = exactCodexReadyStyledComposerCapture(styledScreen);
+            if (!composer) {
+                throw new NativeInspectionDiagnosticError("composer_not_ready", "Codex composer contains non-placeholder input or is not at the exact idle prompt");
+            }
+            const inferredViewport = inferCodexVisibleViewportColumns(styledScreen);
+            const observedViewport = exactViewport ?? inferredViewport;
+            if ((observedViewport !== undefined && observedViewport < minimumViewport) ||
+                hasTruncatedCodexStatusSessionLine(plainScreen)) {
+                throw new NativeInspectionDiagnosticError("viewport_too_narrow", `Codex /status requires a proven viewport of at least ` +
+                    `${minimumViewport} columns to preserve the complete Session UUID` +
+                    `${observedViewport === undefined
+                        ? ""
+                        : `; observed ${observedViewport}`}; widen or zoom the pane before retrying`);
+            }
+            if (exactViewport === undefined) {
+                throw new NativeInspectionDiagnosticError("viewport_unavailable", `Codex /status requires exact terminal viewport geometry before input; ` +
+                    viewportUnavailableReason +
+                    `${inferredViewport === undefined
+                        ? ""
+                        : ` (ANSI fallback estimated ${inferredViewport} columns)`}`);
+            }
+            const reverified = await this.verifyTerminalIdentity(adapter.agent, verified, runtime);
+            if (!sameTerminalControlIdentity(verified, reverified)) {
+                throw new NativeInspectionDiagnosticError("identity_unverified", "terminal control identity changed after the Codex pre-text composer capture");
+            }
+            return {
+                terminalControl: reverified,
+                screenDigest: nativeInspectionScreenFingerprint(styledScreen),
+                composerDigest: composer.digest
+            };
+        };
+        const first = await captureReady(terminalControl);
+        const second = await captureReady(first.terminalControl);
+        if (second.composerDigest !== first.composerDigest) {
+            throw new NativeInspectionDiagnosticError("composer_not_ready", "Codex empty composer changed across its stable pre-text captures");
+        }
+        return {
+            terminalControl: second.terminalControl,
+            screenDigest: second.screenDigest
+        };
+    }
+    async assertFinalCodexStatusViewport(terminalControl, plan, runtime) {
+        const minimumViewport = CODEX_NATIVE_STATUS_MIN_VIEWPORT_BY_PROFILE[plan.behaviorProfile];
+        if (minimumViewport === undefined) {
+            throw new NativeInspectionDiagnosticError("unsupported_profile", `Codex ${plan.behaviorProfile} has no exact /status viewport profile`);
+        }
+        const verified = await this.verifyTerminalIdentity("codex", terminalControl, runtime);
+        const viewportInspector = this.terminalProvider.inspectViewport;
+        if (!viewportInspector) {
+            throw new NativeInspectionDiagnosticError("viewport_unavailable", "Codex /status requires exact terminal viewport geometry immediately before Enter");
+        }
+        let viewport;
+        try {
+            viewport = await viewportInspector.call(this.terminalProvider, this.terminalProvider.endpoint(verified));
+        }
+        catch (error) {
+            throw new NativeInspectionDiagnosticError("viewport_unavailable", `Codex /status viewport inspection failed immediately before Enter: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        if (!viewport ||
+            !Number.isSafeInteger(viewport.columns) ||
+            viewport.columns <= 0 ||
+            !Number.isSafeInteger(viewport.rows) ||
+            viewport.rows <= 0) {
+            throw new NativeInspectionDiagnosticError("viewport_unavailable", "Codex /status exact terminal viewport became unavailable immediately before Enter");
+        }
+        if (viewport.columns < minimumViewport) {
+            throw new NativeInspectionDiagnosticError("viewport_too_narrow", `Codex /status viewport narrowed to ${viewport.columns} columns before Enter; ` +
+                `at least ${minimumViewport} are required to preserve the complete Session UUID`);
+        }
+        const reverified = await this.verifyTerminalIdentity("codex", verified, runtime);
+        if (!sameTerminalControlIdentity(verified, reverified)) {
+            throw new NativeInspectionDiagnosticError("identity_unverified", "terminal control identity changed after the final Codex viewport proof");
+        }
+        return reverified;
+    }
     async settleNativeInspectionComposer(adapter, terminalControl, plan, runtime) {
         const startedAt = this.nowMs();
         const settleTimeoutMs = plan.composer.maximumSettleMs;
@@ -563,6 +766,7 @@ export class TerminalAgentBridge {
         let stableKind;
         let stableSince;
         let stableCaptures = 0;
+        let lastMismatchDiagnostic = "composer_not_exact";
         while (this.nowMs() - startedAt <= settleTimeoutMs) {
             const captured = await this.captureInspection(adapter, terminalControl, {
                 runtime,
@@ -595,6 +799,9 @@ export class TerminalAgentBridge {
                 }
             }
             else {
+                lastMismatchDiagnostic = adapter.agent === "codex"
+                    ? codexNativeInspectionComposerMismatchDiagnostic(captured.screen, plan)
+                    : "composer_not_exact";
                 stableDigest = undefined;
                 stableKind = undefined;
                 stableSince = undefined;
@@ -607,7 +814,9 @@ export class TerminalAgentBridge {
             }
             await this.sleep(Math.min(CODEX_MULTILINE_SETTLE_POLL_MS, remaining));
         }
-        throw new Error(`${adapter.displayName} /status composer did not become exact, idle, and stable before the bounded submit deadline`);
+        throw new NativeInspectionDiagnosticError(lastMismatchDiagnostic, lastMismatchDiagnostic === "composer_viewport_truncated"
+            ? `${adapter.displayName} /status slash popup was truncated by the viewport; widen or zoom the pane before retrying manually`
+            : `${adapter.displayName} /status composer did not become exact, idle, and stable before the bounded submit deadline`);
     }
     async revalidateNativeInspectionComposer(adapter, terminalControl, plan, expected, runtime) {
         const captured = await this.captureInspection(adapter, terminalControl, {
@@ -619,7 +828,7 @@ export class TerminalAgentBridge {
         if (!materialized ||
             materialized.digest !== expected.digest ||
             materialized.kind !== expected.kind) {
-            throw new Error(`${adapter.displayName} /status composer changed after its stable pre-submit capture`);
+            throw new NativeInspectionDiagnosticError("composer_drift", `${adapter.displayName} /status composer changed after its stable pre-submit capture`);
         }
         const baseline = adapter.observeNativeInspection?.({
             operation: plan.operation,
@@ -628,12 +837,12 @@ export class TerminalAgentBridge {
         if (!baseline ||
             baseline.status === "ambiguous" ||
             !Array.isArray(baseline.evidenceInventory)) {
-            throw new Error(baseline?.reason ??
+            throw new NativeInspectionDiagnosticError("evidence_unproven", baseline?.reason ??
                 `${adapter.displayName} /status pre-Enter evidence inventory was not proven`);
         }
         const verifiedImmediatelyBeforeEnter = await this.verifyTerminalIdentity(adapter.agent, captured.terminalControl, runtime);
         if (!sameTerminalControlIdentity(captured.terminalControl, verifiedImmediatelyBeforeEnter)) {
-            throw new Error(`terminal control identity changed after the final ${adapter.displayName} /status composer capture`);
+            throw new NativeInspectionDiagnosticError("identity_unverified", `terminal control identity changed after the final ${adapter.displayName} /status composer capture`);
         }
         return {
             terminalControl: verifiedImmediatelyBeforeEnter,
@@ -1213,7 +1422,12 @@ function assertTerminalMutationCapabilities({ provider, terminal, semantic, tran
         `${terminal.identity.providerKind}:${terminal.route.label}: ` +
         missing.join(", "));
 }
-function nativeInspectionSubmissionError(stage, error) {
+function nativeInspectionSubmissionError(stage, error, fallbackDiagnostic) {
+    const diagnostic = error instanceof NativeInspectionSubmissionError
+        ? error.diagnostic
+        : error instanceof NativeInspectionDiagnosticError
+            ? error.diagnostic
+            : fallbackDiagnostic;
     if (error instanceof NativeInspectionSubmissionError) {
         const stageRank = {
             not_started: 0,
@@ -1224,10 +1438,11 @@ function nativeInspectionSubmissionError(stage, error) {
             return error;
         }
         return new NativeInspectionSubmissionError(stage, error.message, {
-            cause: error
+            cause: error,
+            diagnostic
         });
     }
-    return new NativeInspectionSubmissionError(stage, error instanceof Error ? error.message : String(error), { cause: error });
+    return new NativeInspectionSubmissionError(stage, error instanceof Error ? error.message : String(error), { cause: error, diagnostic });
 }
 function assertClosedStatusInspectionPlan(adapter, terminalControl, plan) {
     if (!terminalControl.capabilities.includes("send_keys")) {
@@ -1286,7 +1501,7 @@ function assertNativeInspectionComposerSafe(inspection, displayName = "terminal
     if (inspection.approval.blocked ||
         inspection.activity.state === "awaiting_approval" ||
         inspection.activity.state === "working") {
-        throw new Error(`${displayName} became busy or blocked while its /status composer was settling`);
+        throw new NativeInspectionDiagnosticError("composer_not_ready", `${displayName} became busy or blocked while its /status composer was settling`);
     }
     // Codex's generic activity parser deliberately reports a non-empty slash
     // composer as unknown. At this stage the caller has already proved an idle,
@@ -1341,7 +1556,7 @@ function exactCodexNativeInspectionComposerCapture(screen, plan) {
     };
 }
 function exactClaudeNativeInspectionComposerCapture(screen, plan) {
-    const frame = exactClaudeNativeInspectionComposerFrame(screen);
+    const frame = exactClaudeComposerFrame(screen);
     if (!frame) {
         return undefined;
     }
@@ -1409,12 +1624,12 @@ function closedClaudeNativeStatusSuggestionsMatch(observed, expected) {
     });
 }
 /**
- * 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.
+ * Prove Claude Code's exact current idle input frame. This is shared by every
+ * automated-input path: a loose or historical `❯` prompt is not authority to
+ * inject text into the terminal.
  */
-export function isExactClaudeNativeInspectionIdleComposer(screen) {
-    const frame = exactClaudeNativeInspectionComposerFrame(screen);
+export function isExactClaudeIdleComposer(screen) {
+    const frame = exactClaudeComposerFrame(screen);
     if (!frame) {
         return false;
     }
@@ -1423,7 +1638,14 @@ export function isExactClaudeNativeInspectionIdleComposer(screen) {
         (frame.trailing.length === 0 ||
             claudeNativeInspectionTrailingIsFooter(frame.trailing)));
 }
-function exactClaudeNativeInspectionComposerFrame(screen) {
+/**
+ * Compatibility export retained for callers that adopted the native-status
+ * name before the same exact-frame proof was reused by lifecycle handoff.
+ */
+export function isExactClaudeNativeInspectionIdleComposer(screen) {
+    return isExactClaudeIdleComposer(screen);
+}
+function exactClaudeComposerFrame(screen) {
     const lines = screen.replace(/\r\n?/gu, "\n").replace(/\u00a0/gu, " ")
         .split("\n");
     const dividerIndexes = lines
@@ -1451,6 +1673,162 @@ function claudeNativeInspectionTrailingIsFooter(lines) {
 function nativeInspectionScreenFingerprint(screen) {
     return `sha256:${createHash("sha256").update(screen).digest("hex")}`;
 }
+function bareDigestFromNativeInspectionScreenFingerprint(fingerprint) {
+    const match = /^sha256:([0-9a-f]{64})$/u.exec(fingerprint);
+    if (!match) {
+        throw new Error("native inspection screen fingerprint is malformed");
+    }
+    return match[1];
+}
+function stripTerminalEscapeSequences(value) {
+    return value.replace(/\x1B(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\))/gu, "");
+}
+function exactCodexReadyStyledComposerCapture(screen) {
+    const lines = screen.replace(/\r\n?/gu, "\n").split("\n");
+    while (lines.length > 0 &&
+        stripTerminalEscapeSequences(lines.at(-1) ?? "").trim().length === 0) {
+        lines.pop();
+    }
+    const composerLine = [...lines.slice(-12)].reverse().find((line) => CODEX_COMPOSER_MARKER.test(stripTerminalEscapeSequences(line).trimEnd()));
+    if (composerLine === undefined) {
+        return undefined;
+    }
+    let dim = false;
+    const visible = [];
+    for (let index = 0; index < composerLine.length;) {
+        if (composerLine[index] === "\x1b") {
+            const escape = /^(?:\x1B\[([0-9;]*)m|\x1B\][^\x07]*(?:\x07|\x1B\\))/u
+                .exec(composerLine.slice(index));
+            if (escape) {
+                if (escape[1] !== undefined) {
+                    const codes = escape[1] === ""
+                        ? [0]
+                        : escape[1].split(";").map((value) => Number(value));
+                    for (let codeIndex = 0; codeIndex < codes.length; codeIndex += 1) {
+                        const code = codes[codeIndex];
+                        if ([38, 48, 58].includes(code) &&
+                            codes[codeIndex + 1] === 2) {
+                            codeIndex += 4;
+                            continue;
+                        }
+                        if ([38, 48, 58].includes(code) &&
+                            codes[codeIndex + 1] === 5) {
+                            codeIndex += 2;
+                            continue;
+                        }
+                        if (code === 0 || code === 22) {
+                            dim = false;
+                        }
+                        else if (code === 2) {
+                            dim = true;
+                        }
+                    }
+                }
+                index += escape[0].length;
+                continue;
+            }
+        }
+        const codePoint = composerLine.codePointAt(index);
+        if (codePoint === undefined) {
+            break;
+        }
+        const character = String.fromCodePoint(codePoint);
+        visible.push({ character, dim });
+        index += character.length;
+    }
+    const promptIndex = visible.findIndex(({ character }) => character === "›" || character === "»");
+    if (promptIndex < 0) {
+        return undefined;
+    }
+    const content = visible.slice(promptIndex + 1)
+        .filter(({ character }) => !/^\s$/u.test(character));
+    if (content.length > 0 && !content.every((entry) => entry.dim)) {
+        return undefined;
+    }
+    return {
+        digest: createHash("sha256").update(composerLine).digest("hex")
+    };
+}
+/**
+ * Infer a viewport only from fixed-width visible-buffer rows. Trimmed captures
+ * deliberately return undefined: a short content row is not proof of a short
+ * terminal. This keeps the fallback provider-neutral and fail-closed only on
+ * positive geometry evidence.
+ */
+function inferCodexVisibleViewportColumns(screen) {
+    const rows = screen.replace(/\r\n?/gu, "\n").split("\n")
+        .map(stripTerminalEscapeSequences);
+    const widthOneRows = rows.filter((row) => /^[\x20-\x7e›»·─━╭╮╰╯│]*$/u.test(row));
+    const maxWidth = widthOneRows.reduce((maximum, row) => Math.max(maximum, Array.from(row).length), 0);
+    if (maxWidth < 20) {
+        return undefined;
+    }
+    const paddedAtMax = widthOneRows.filter((row) => row.endsWith(" ") && Array.from(row).length === maxWidth);
+    const composerAtMax = paddedAtMax.some((row) => CODEX_COMPOSER_MARKER.test(row.trimEnd()));
+    return paddedAtMax.length >= 3 && composerAtMax
+        ? maxWidth
+        : undefined;
+}
+function hasTruncatedCodexStatusSessionLine(screen) {
+    return screen.replace(/\r\n?/gu, "\n").split("\n").some((line) => {
+        const match = /^\s*│\s*Session:\s*([^│\s]+).*│?\s*$/iu.exec(line);
+        if (!match) {
+            return false;
+        }
+        return !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu
+            .test(match[1]);
+    });
+}
+function codexNativeInspectionComposerMismatchDiagnostic(screen, plan) {
+    const expectedRows = CODEX_NATIVE_STATUS_POPUP_BY_PROFILE[plan.behaviorProfile];
+    if (!expectedRows) {
+        return "composer_not_exact";
+    }
+    const lines = screen.replace(/\r\n?/gu, "\n").split("\n");
+    let composerIndex = -1;
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        if (CODEX_COMPOSER_MARKER.test(lines[index])) {
+            composerIndex = index;
+            break;
+        }
+    }
+    if (composerIndex < 0 ||
+        lines[composerIndex].replace(/^[›»]\s?/u, "").trimEnd() !== plan.command) {
+        return "composer_not_exact";
+    }
+    const footerIndex = lines.findIndex((line, index) => index > composerIndex && CODEX_COMPOSER_FOOTER.test(line.trim()));
+    const popupRows = lines.slice(composerIndex + 1, footerIndex < 0 ? lines.length : footerIndex).filter((line) => line.trim().length > 0);
+    if (popupRows.length === 0) {
+        return "composer_not_exact";
+    }
+    const logicalRows = [];
+    let observedTruncation = false;
+    for (const row of popupRows) {
+        const trimmed = row.trim().replace(/\s+/gu, " ");
+        if (trimmed.startsWith("/")) {
+            logicalRows.push(trimmed);
+        }
+        else if (logicalRows.length > 0) {
+            logicalRows[logicalRows.length - 1] += ` ${trimmed}`;
+            observedTruncation = true;
+        }
+        else {
+            return "composer_not_exact";
+        }
+        observedTruncation ||= trimmed.endsWith("…");
+    }
+    const normalizedExpected = expectedRows.map((row) => row.trim().replace(/\s+/gu, " "));
+    const everyKnownPrefix = logicalRows.length <= normalizedExpected.length &&
+        logicalRows.every((row, index) => {
+            const withoutEllipsis = row.endsWith("…")
+                ? row.slice(0, -1).trimEnd()
+                : row;
+            return normalizedExpected[index]?.startsWith(withoutEllipsis) === true;
+        });
+    return observedTruncation && everyKnownPrefix
+        ? "composer_viewport_truncated"
+        : "composer_not_exact";
+}
 function exactCodexComposerCapture(screen, expectedText) {
     const lines = screen.replace(/\r\n?/gu, "\n").split("\n");
     const expectedComparable = composerComparableText(expectedText);
@@ -1471,7 +1849,7 @@ function exactCodexComposerCapture(screen, expectedText) {
             ...region.slice(1).map((line) => line.startsWith("  ") ? line.slice(2) : line)
         ];
         const comparable = composerComparableText(bodyRows.join("\n"));
-        const exactVisibleDraft = codexComposerRowsMatchExpected(bodyRows, expectedComparable);
+        const exactVisibleDraft = terminalComposerRowsMatchExpected(bodyRows, expectedComparable);
         const exactLargePastePlaceholder = expectedCharacterCount > CODEX_LARGE_PASTE_CHAR_THRESHOLD &&
             comparable === largePasteComparable;
         if (!exactVisibleDraft && !exactLargePastePlaceholder) {
@@ -1489,9 +1867,10 @@ function exactCodexComposerCapture(screen, expectedText) {
     return matches[0];
 }
 /**
- * Codex paints wrapped composer content as independent terminal rows, so tmux
- * cannot distinguish a visual wrap from an authored newline. Align the rows
- * against the exact text AKK injected instead of joining every row with `\n`.
+ * Terminal UIs paint wrapped composer content as independent screen rows, so
+ * a provider capture cannot distinguish a visual wrap from an authored
+ * newline. Align the rows against the exact text AKK injected instead of
+ * joining every row with `\n`.
  *
  * Only row boundaries are ambiguous: they may consume an authored newline, an
  * omitted run of ASCII spaces at a word wrap, or no character at a CJK/token
@@ -1499,7 +1878,7 @@ function exactCodexComposerCapture(screen, expectedText) {
  * empty row can only advance through an authored newline (plus terminal-trimmed
  * spaces before it), so blank-line structure is preserved.
  */
-function codexComposerRowsMatchExpected(rows, expectedText) {
+function terminalComposerRowsMatchExpected(rows, expectedText) {
     const expected = composerComparableText(expectedText);
     if (rows.length === 0) {
         return expected.length === 0;
@@ -1570,11 +1949,11 @@ function exactClaudeComposerCapture(screen, expectedText) {
     if (region.length === 0 || !/^\s*❯(?:\s|$)/u.test(region[0])) {
         return undefined;
     }
-    const body = [
+    const bodyRows = [
         region[0].replace(/^\s*❯\s?/u, ""),
         ...region.slice(1).map((line) => line.startsWith("  ") ? line.slice(2) : line)
-    ].join("\n");
-    if (composerComparableText(body) !== composerComparableText(expectedText)) {
+    ];
+    if (!terminalComposerRowsMatchExpected(bodyRows, expectedText)) {
         return undefined;
     }
     return {