@scotthuang/agent-knock-knock 0.12.36 → 0.13.0

package/dist/src/mutation-transaction.js

@@ -49,21 +49,25 @@ export function capabilityGatedRepositoryPairOperation(required, bound, operatio
 /** Acquire terminal -> writer -> optional state and release in reverse. */
 export async function withCanonicalMutationLocks(ports, operation) {
     const transaction = {};
-    return withAcquiredScope(transaction, "terminal", ports.resources.terminal, ports.acquireTerminal, (terminal) => ports.withStoreWriter(async () => {
-        const storeWriter = createScope(transaction, "storeWriter", ports.resources.storeWriter);
-        const invoke = (state) => operation({ terminal, storeWriter, ...(state ? { state } : {}) }, ports.resources);
-        try {
-            if (!ports.acquireState)
-                return await invoke();
-            const stateResource = ports.resources.state;
-            if (!stateResource)
-                throw new Error("state mutation lock requires a canonical resource");
-            return await withAcquiredScope(transaction, "state", stateResource, ports.acquireState, invoke);
-        }
-        finally {
-            expireScope(storeWriter);
-        }
-    }));
+    return withAcquiredScope(transaction, "terminal", ports.resources.terminal, ports.acquireTerminal, async (terminal) => {
+        await ports.afterTerminalAcquired?.();
+        return ports.withStoreWriter(async () => {
+            const storeWriter = createScope(transaction, "storeWriter", ports.resources.storeWriter);
+            const invoke = (state) => operation({ terminal, storeWriter, ...(state ? { state } : {}) }, ports.resources);
+            try {
+                if (!ports.acquireState)
+                    return await invoke();
+                const stateResource = ports.resources.state;
+                if (!stateResource) {
+                    throw new Error("state mutation lock requires a canonical resource");
+                }
+                return await withAcquiredScope(transaction, "state", stateResource, ports.acquireState, invoke);
+            }
+            finally {
+                expireScope(storeWriter);
+            }
+        });
+    });
 }
 /** Add one state scope to the currently active terminal + writer transaction. */
 export async function withCanonicalStateMutationLock(scopes, resources, state, operation) {

package/dist/src/mutation-transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutation-transaction.js","sourceRoot":"","sources":["../../src/mutation-transaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mutation-transaction.js","sourceRoot":"","sources":["../../src/mutation-transaction.ts"],"names":[],"mappings":"AAoBA,MAAM,YAAY,GAAG,IAAI,OAAO,EAAmG,CAAC;AACpI,MAAM,UAAU,yBAAyB,CAAQ,GAAW,EAAE,KAAY,IAAI,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACrH,SAAS,WAAW,CAAyB,WAAmB,EAAE,IAAU,EAAE,QAAmC;IAC/G,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAwB,CAAC;IACvD,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzD,OAAO,KAAK,CAAC;AACf,CAAC;AACD,SAAS,WAAW,CAAC,KAA+B,IAAU,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC3F,KAAK,UAAU,iBAAiB,CAC9B,WAAmB,EAAE,IAAU,EAAE,QAAmC,EAAE,OAAoC,EAC1G,SAA0D;IAE1D,MAAM,OAAO,GAAG,MAAM,OAAO,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACvD,IAAI,CAAC;QAAC,OAAO,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;IAAC,CAAC;YAC9B,CAAC;QAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAAC,OAAO,EAAE,CAAC;IAAC,CAAC;AAC5C,CAAC;AACD,SAAS,kBAAkB,CACzB,MAA6C,EAAE,SAAkC,EACjF,QAA8B;IAC9B,IAAI,WAA+B,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3E,MAAM,IAAI,KAAK,CAAC,iDAAiD,IAAI,QAAQ,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,WAAW,IAAI,WAAW,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACjF,CAAC;QACD,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IACnC,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,kCAAkC,CAEhD,QAAkB,EAAE,KAAY,EAChC,SAAwD;IACxD,OAAO,CAAC,MAA2B,EAAE,SAAiD,EAAE,GAAG,IAAU,EAAE,EAAE;QACvG,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAChD,OAAO,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,KAAiB,EAAE,GAAG,IAAI,CAAC,CAAC;IAChE,CAAC,CAAC;AACJ,CAAC;AACD,MAAM,UAAU,sCAAsC,CAEW,QAAkB,EAAE,KAA+B,EAClH,SAAkF;IAClF,OAAO,CAAC,MAA2B,EAAE,SAAiD,EAAE,GAAG,IAAU,EAAE,EAAE;QACvG,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAChD,OAAO,SAAS,CACd,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAsB,EAC1C,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAuB,EAC3C,GAAG,IAAI,CACR,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAGD,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,KAAY,EAAE,SAC0E;IAExF,MAAM,WAAW,GAAG,EAAE,CAAC;IACvB,OAAO,iBAAiB,CACtB,WAAW,EACX,UAAU,EACV,KAAK,CAAC,SAAS,CAAC,QAAQ,EACxB,KAAK,CAAC,eAAe,EACrB,KAAK,EAAE,QAAQ,EAAE,EAAE;QACjB,MAAM,KAAK,CAAC,qBAAqB,EAAE,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC,eAAe,CAAC,KAAK,IAAI,EAAE;YACtC,MAAM,WAAW,GAAG,WAAW,CAC7B,WAAW,EAAE,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,CACxD,CAAC;YACF,MAAM,MAAM,GAAG,CAAC,KAA8B,EAAE,EAAE,CAAC,SAAS,CAC1D,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAC7B,EACvB,KAAK,CAAC,SAAqC,CAC5C,CAAC;YACF,IAAI,CAAC;gBACH,IAAI,CAAC,KAAK,CAAC,YAAY;oBAAE,OAAO,MAAM,MAAM,EAAE,CAAC;gBAC/C,MAAM,aAAa,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC;gBAC5C,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnB,MAAM,IAAI,KAAK,CACb,mDAAmD,CACpD,CAAC;gBACJ,CAAC;gBACD,OAAO,MAAM,iBAAiB,CAC5B,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,YAAY,EAAE,MAAM,CAChE,CAAC;YACJ,CAAC;oBAAS,CAAC;gBAAC,WAAW,CAAC,WAAW,CAAC,CAAC;YAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,MAA+B,EAC/B,SAAqC,EACrC,KAGE,EACF,SAGoB;IAEpB,MAAM,WAAW,GAAG,kBAAkB,CACpC,MAAM,EACN,SAAS,EACT,CAAC,UAAU,EAAE,aAAa,CAAC,CAC5B,CAAC;IACF,OAAO,iBAAiB,CACtB,WAAW,EACX,OAAO,EACP,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,OAAO,EACb,CAAC,UAAU,EAAE,EAAE,CAAC,SAAS,CACvB,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,EAChC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,CACpB,CAClC,CACF,CAAC;AACJ,CAAC"}

package/dist/src/native-thread-lifecycle-cli-adapter.d.ts

@@ -4,12 +4,41 @@ import { type ManagedSessionState } from "./managed-session.js";
 import { type LifecycleTerminalObservation, type NativeThreadLifecycleQueryPorts } from "./native-thread-lifecycle-query-service.js";
 import { type Conversation } from "./protocol.js";
 import type { TerminalAgentAdapter, TerminalControlRef, TerminalRuntimeIdentity, TerminalThreadLifecycleCapabilities } from "./terminal-agent-adapter.js";
-import { type ResolvedTerminalConversation } from "./terminal-agent-bridge.js";
+import { type ResolvedTerminalConversation, type TerminalAgentBridge } from "./terminal-agent-bridge.js";
 import { type CodexAllowedCompanionSet } from "./terminal-authority-policy.js";
 import type { TerminalNativeIdentity } from "./terminal-binding-authority.js";
 import type { TerminalDispatchLedgerDocument } from "./terminal-dispatch-ledger-codec.js";
 import type { TerminalRuntimeCliAdapter } from "./terminal-runtime-cli-adapter.js";
 export type NativeLifecycleCliOptions = Readonly<Record<string, unknown>>;
+export declare const CODEX_FOREGROUND_IDENTIFICATION_TTL_MS = 30000;
+export declare const CODEX_FOREGROUND_IDENTIFICATION_SCROLLBACK_LINES = 240;
+/**
+ * Short-lived diagnostic evidence returned only to the in-process caller.
+ *
+ * This is deliberately not a Store binding or an authorization token. The
+ * caller must remain inside the same terminal lock and must still use the
+ * ordinary request-acceptance path before creating durable Session authority.
+ */
+export interface CodexForegroundIdentificationProof {
+    readonly terminalId: string;
+    readonly pid: number;
+    readonly processUuid: string;
+    readonly processBirth: string;
+    readonly realCwd: string;
+    readonly nativeThreadId: string;
+    readonly agentVersion: string;
+    readonly behaviorProfile: string;
+    readonly evidenceFingerprint: string;
+    readonly postProbeScreenDigest: string;
+    readonly observationScrollbackLines: typeof CODEX_FOREGROUND_IDENTIFICATION_SCROLLBACK_LINES;
+    readonly observedAt: string;
+    readonly expiresAt: string;
+    readonly terminalSubmission: {
+        readonly command: "/status";
+        readonly enterCount: 1;
+        readonly materialization: NativeInspectionSubmission["materialization"];
+    };
+}
 export interface NativeLifecycleSnapshot {
     readonly identity?: TerminalNativeIdentity;
     readonly runtimeIdentity?: TerminalNativeIdentity;
@@ -67,7 +96,7 @@ interface NativeLifecycleIdentityPorts {
         processBirth: string;
     };
     runtimeForLiveIdentity(input: {
-        terminal: ResolvedTerminalConversation;
+        terminal: LifecycleTerminalObservation;
         identity?: TerminalNativeIdentity;
         expectedEmptyNativeSession?: boolean;
         physicalOnly?: boolean;
@@ -140,7 +169,13 @@ export interface NativeThreadLifecycleCliFacade {
     agentAdapter(options: NativeLifecycleCliOptions, agent: ExecutorKind): TerminalAgentAdapter;
     runList(options: NativeLifecycleCliOptions): Promise<void>;
     runInspect(options: NativeLifecycleCliOptions): Promise<void>;
-    assertSameInspectionTerminal(expected: ResolvedTerminalConversation, actual: ResolvedTerminalConversation, stage: string): void;
+    runIdentifyForeground(options: NativeLifecycleCliOptions): Promise<void>;
+    identifyCodexForegroundWhileLocked(input: {
+        options: NativeLifecycleCliOptions;
+        terminal: LifecycleTerminalObservation;
+        expectedTerminalToken: string;
+    }): Promise<CodexForegroundIdentificationProof>;
+    assertSameInspectionTerminal(expected: LifecycleTerminalObservation, actual: LifecycleTerminalObservation, stage: string): void;
     codexLatentClearResumeObservation(input: {
         screen?: string;
         agentVersion?: string;
@@ -151,4 +186,5 @@ export interface NativeThreadLifecycleCliFacade {
     nativeInspectionComposerEmpty(agent: ExecutorKind, screen?: string): boolean;
 }
 export declare function createNativeThreadLifecycleCliAdapter(ports: CreateNativeThreadLifecycleCliAdapterInput): NativeThreadLifecycleCliFacade;
+type NativeInspectionSubmission = Awaited<ReturnType<TerminalAgentBridge["submitNativeInspection"]>>;
 export {};

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

@@ -13,6 +13,8 @@ import { listManagedSessions, loadNativeThreadTransition } from "./session-store
 import { isExactClaudeNativeInspectionIdleComposer, NativeInspectionSubmissionError } from "./terminal-agent-bridge.js";
 import { terminalControlAliasMatches, selectRootTerminalProcesses, withCodexCompanionFences } from "./terminal-authority-policy.js";
 import { nonBlankString } from "./value-guards.js";
+export const CODEX_FOREGROUND_IDENTIFICATION_TTL_MS = 30_000;
+export const CODEX_FOREGROUND_IDENTIFICATION_SCROLLBACK_LINES = 240;
 export function createNativeThreadLifecycleCliAdapter(ports) {
     const app = new NativeThreadLifecycleCliApplication(ports);
     return Object.freeze({
@@ -24,6 +26,8 @@ export function createNativeThreadLifecycleCliAdapter(ports) {
         agentAdapter: (options, agent) => app.agentAdapter(options, agent),
         runList: (options) => app.runList(options),
         runInspect: (options) => app.runInspect(options),
+        runIdentifyForeground: (options) => app.runIdentifyForeground(options),
+        identifyCodexForegroundWhileLocked: (input) => app.identifyCodexForegroundWhileLocked(input),
         assertSameInspectionTerminal: (expected, actual, stage) => app.assertSameInspectionTerminal(expected, actual, stage),
         codexLatentClearResumeObservation,
         nativeInspectionComposerEmpty
@@ -323,6 +327,10 @@ class NativeThreadLifecycleCliApplication {
     }
     assertInspectionReady(input) {
         const { options, terminal, terminalStatus, session } = input;
+        if (terminalStatus?.interaction_state !== undefined) {
+            throw new Error(`terminal ${terminal.terminalControl.target} is waiting for a native ` +
+                "questionnaire response; answer or cancel it before native inspection");
+        }
         if (terminalStatus && (terminalStatus.reachable !== true ||
             terminalStatus.activity_state !== "idle" ||
             terminalStatus.approval_state.blocked === true)) {
@@ -462,6 +470,271 @@ class NativeThreadLifecycleCliApplication {
             throw new Error("Claude composer contains input or is not at the exact idle frame; refusing automated terminal input");
         }
     }
+    validateForegroundIdentificationOptions(options) {
+        if (options.command !== undefined || options.message !== undefined) {
+            throw new Error("foreground identification does not accept a command or message payload");
+        }
+        return required(nonBlankString(options.expectedTerminalToken), "--expected-terminal-token is required");
+    }
+    async runIdentifyForeground(options) {
+        const expectedTerminalToken = this.validateForegroundIdentificationOptions(options);
+        const terminal = await this.resolveLifecycleTerminal(options);
+        if (terminal.agent !== "codex") {
+            throw new Error("foreground identification currently supports only Codex terminals");
+        }
+        const storeDir = this.ports.state.storeDir(options);
+        const release = this.ports.state.acquireTerminal(storeDir, terminal.terminalControl, { timeoutMs: 30_000 });
+        try {
+            const proof = await this.identifyCodexForegroundWhileLocked({
+                options,
+                terminal,
+                expectedTerminalToken
+            });
+            this.ports.output.print({
+                status: "observed",
+                inspection: "identify_foreground",
+                terminal_id: proof.terminalId,
+                agent: "codex",
+                agent_version: proof.agentVersion,
+                behavior_profile: proof.behaviorProfile,
+                native_thread_id: proof.nativeThreadId,
+                foreground_proof: {
+                    scope: "ephemeral_diagnostic_only",
+                    observed_at: proof.observedAt,
+                    expires_at: proof.expiresAt,
+                    ttl_ms: CODEX_FOREGROUND_IDENTIFICATION_TTL_MS,
+                    grants_authority: false
+                },
+                terminal_submission: {
+                    command: proof.terminalSubmission.command,
+                    enter_count: proof.terminalSubmission.enterCount,
+                    materialization_kind: proof.terminalSubmission.materialization.kind
+                },
+                store_mutation: false,
+                session_created: false,
+                turn_created: false,
+                receipt_created: false,
+                monitor_created: false,
+                callback_created: false
+            });
+        }
+        finally {
+            release();
+        }
+    }
+    async identifyCodexForegroundWhileLocked(input) {
+        if (input.terminal.agent !== "codex") {
+            throw new Error("foreground identification currently supports only Codex terminals");
+        }
+        if (!nonBlankString(input.expectedTerminalToken)) {
+            throw new Error("foreground identification requires a terminal token");
+        }
+        const bridge = this.ports.runtime.forOptions(input.options).createBridge();
+        const physicalRuntime = this.ports.identity.runtimeForLiveIdentity({
+            terminal: input.terminal,
+            physicalOnly: true
+        });
+        const terminal = await bridge.resolveStoredTerminal("codex", input.terminal.pid, input.terminal.terminalControl, physicalRuntime);
+        this.assertSameInspectionTerminal(input.terminal, terminal, "while waiting for foreground-identification control");
+        const realCwd = this.realForegroundWorkspace(terminal);
+        const processIncarnation = this.ports.identity.processIncarnation(terminal.pid);
+        this.assertForegroundPhysicalToken({
+            terminal,
+            processIncarnation,
+            expectedTerminalToken: input.expectedTerminalToken
+        });
+        const runtimeFacade = this.ports.runtime.forOptions(input.options);
+        const agentVersion = required(nonBlankString(runtimeFacade.agentVersionForRunningProcess("codex", terminal.pid)), "Codex foreground identification requires a verified running version");
+        const adapter = runtimeFacade.createAgentRegistry().require("codex");
+        const capability = adapter.probeNativeInspection?.(agentVersion);
+        if (capability?.status !== "supported" ||
+            capability.statusInspection !== true) {
+            throw new Error(capability?.reason ??
+                "Codex foreground identification has no supported /status profile");
+        }
+        const plan = adapter.planNativeInspection?.({ kind: "status" }, capability);
+        if (!plan ||
+            plan.operation.kind !== "status" ||
+            plan.command !== "/status" ||
+            plan.effect !== "read_only" ||
+            plan.expectedResult.presentation !== "inline") {
+            throw new Error("the Codex adapter did not produce the closed inline /status plan");
+        }
+        const initialStatus = await bridge.status("codex", terminal.terminalControl, {
+            runtime: physicalRuntime,
+            scrollbackLines: CODEX_FOREGROUND_IDENTIFICATION_SCROLLBACK_LINES
+        });
+        this.assertInspectionReady({
+            options: input.options,
+            terminal,
+            terminalStatus: initialStatus
+        });
+        this.assertForegroundHasNoLifecycleTransition(input.options, terminal);
+        await this.assertInspectionComposerReady({
+            options: input.options,
+            terminal
+        });
+        const context = {
+            options: input.options,
+            terminal,
+            snapshot: {
+                codexCompanions: { additional: [] },
+                capabilities: adapter.probeThreadLifecycle?.(agentVersion) ?? {
+                    status: "unknown",
+                    agentVersion,
+                    newThread: false,
+                    resumeExact: false,
+                    reason: "thread lifecycle capability is outside this diagnostic"
+                },
+                version: agentVersion,
+                bindingToken: input.expectedTerminalToken,
+                bindingTokens: [input.expectedTerminalToken]
+            },
+            bridge,
+            plan,
+            runtime: physicalRuntime,
+            expectedBindingToken: input.expectedTerminalToken,
+            foregroundBoundary: {
+                processUuid: processIncarnation.processUuid,
+                processBirth: processIncarnation.processBirth,
+                realCwd,
+                agentVersion,
+                expectedTerminalToken: input.expectedTerminalToken
+            }
+        };
+        const submission = await this.submitInspection(context);
+        try {
+            const observed = await this.observeStableInspection(context, submission);
+            const finalTerminal = await bridge.resolveStoredTerminal("codex", terminal.pid, terminal.terminalControl, physicalRuntime);
+            const finalStatus = required(await this.assertFreshForegroundBoundary({
+                context,
+                terminal: finalTerminal,
+                stage: "after foreground identification",
+                requireReadyScreen: true
+            }), "Codex foreground status revalidation is unavailable");
+            const nativeThreadId = required(isExactNativeThreadId(observed.observation.nativeThreadId)
+                ? observed.observation.nativeThreadId
+                : undefined, "Codex /status did not prove one exact foreground native thread");
+            const evidenceFingerprint = required(nonBlankString(observed.observation.evidenceFingerprint), "Codex /status did not produce exact evidence");
+            const postProbeScreenDigest = required(nonBlankString(finalStatus.screen.digest), "Codex foreground screen digest is unavailable");
+            const observedScreenDigest = required(bareNativeInspectionScreenDigest(observed.screenDigest), "Codex foreground observation screen digest is malformed");
+            if (observedScreenDigest !== postProbeScreenDigest) {
+                throw new Error("Codex screen changed after the stable /status observation");
+            }
+            const observedAt = new Date();
+            const proof = {
+                terminalId: terminal.conversationId,
+                pid: terminal.pid,
+                processUuid: processIncarnation.processUuid,
+                processBirth: processIncarnation.processBirth,
+                realCwd,
+                nativeThreadId,
+                agentVersion,
+                behaviorProfile: plan.behaviorProfile,
+                evidenceFingerprint,
+                postProbeScreenDigest,
+                observationScrollbackLines: CODEX_FOREGROUND_IDENTIFICATION_SCROLLBACK_LINES,
+                observedAt: observedAt.toISOString(),
+                expiresAt: new Date(observedAt.getTime() + CODEX_FOREGROUND_IDENTIFICATION_TTL_MS).toISOString(),
+                terminalSubmission: Object.freeze({
+                    command: "/status",
+                    enterCount: 1,
+                    materialization: submission.materialization
+                })
+            };
+            return Object.freeze(proof);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            if (/do not retry automatically/iu.test(detail))
+                throw error;
+            throw new Error("Codex foreground-identification Enter was dispatched exactly once, " +
+                "but its postcondition became uncertain; do not retry automatically: " +
+                detail);
+        }
+    }
+    async assertFreshForegroundBoundary(input) {
+        const boundary = required(input.context.foregroundBoundary, "foreground-identification boundary is missing");
+        this.assertSameInspectionTerminal(input.context.terminal, input.terminal, input.stage);
+        if (this.realForegroundWorkspace(input.terminal) !== boundary.realCwd) {
+            throw new Error(`terminal real cwd changed ${input.stage}; refresh AKK list`);
+        }
+        const processIncarnation = this.ports.identity.processIncarnation(input.terminal.pid);
+        if (processIncarnation.processUuid !== boundary.processUuid ||
+            processIncarnation.processBirth !== boundary.processBirth) {
+            throw new Error(`Codex process incarnation changed ${input.stage}; refresh AKK list`);
+        }
+        this.assertForegroundPhysicalToken({
+            terminal: input.terminal,
+            processIncarnation,
+            expectedTerminalToken: boundary.expectedTerminalToken
+        });
+        const currentVersion = this.ports.runtime.forOptions(input.context.options)
+            .agentVersionForRunningProcess("codex", input.terminal.pid);
+        if (currentVersion !== boundary.agentVersion) {
+            throw new Error(`Codex version changed ${input.stage}; refresh AKK list`);
+        }
+        this.assertInspectionReady({
+            options: input.context.options,
+            terminal: input.terminal
+        });
+        this.assertForegroundHasNoLifecycleTransition(input.context.options, input.terminal);
+        if (!input.requireReadyScreen) {
+            return undefined;
+        }
+        const status = await input.context.bridge.status("codex", input.terminal.terminalControl, {
+            runtime: input.context.runtime,
+            scrollbackLines: CODEX_FOREGROUND_IDENTIFICATION_SCROLLBACK_LINES
+        });
+        this.assertInspectionReady({
+            options: input.context.options,
+            terminal: input.terminal,
+            terminalStatus: status
+        });
+        await this.assertInspectionComposerReady({
+            options: input.context.options,
+            terminal: input.terminal
+        });
+        return status;
+    }
+    assertForegroundPhysicalToken(input) {
+        const actual = unmanagedTerminalBindingToken({
+            terminalId: input.terminal.conversationId,
+            terminalControl: input.terminal.terminalControl,
+            agent: "codex",
+            pid: input.terminal.pid,
+            workspace: input.terminal.terminalControl.currentPath ?? "",
+            processUuid: input.processIncarnation.processUuid,
+            processBirth: input.processIncarnation.processBirth
+        });
+        if (actual !== input.expectedTerminalToken) {
+            throw new Error("the physical terminal token is stale; refresh AKK list");
+        }
+    }
+    realForegroundWorkspace(terminal) {
+        const cwd = required(nonBlankString(terminal.terminalControl.currentPath), "Codex terminal cwd is unavailable");
+        let realCwd;
+        try {
+            realCwd = fs.realpathSync(cwd);
+        }
+        catch {
+            throw new Error("Codex terminal cwd cannot be resolved exactly");
+        }
+        if (!fs.statSync(realCwd).isDirectory()) {
+            throw new Error("Codex terminal cwd is not a directory");
+        }
+        return realCwd;
+    }
+    assertForegroundHasNoLifecycleTransition(options, terminal) {
+        const storeDir = this.ports.state.storeDir(options);
+        const related = listManagedSessions(storeDir).filter((session) => Boolean(session.binding && terminalControlAliasMatches(session.binding.terminal_id, session.binding.terminal_control, terminal.conversationId, terminal.terminalControl)));
+        const unresolved = related.find((session) => ["transitioning", "quarantined"].includes(session.status) ||
+            this.ports.state.hasUnresolvedTransition(storeDir, session));
+        if (unresolved) {
+            throw new Error(`managed Session ${unresolved.session_id} has an unresolved ` +
+                "native-thread transition");
+        }
+    }
     validateInspectionOptions(options) {
         const inspection = required(nonBlankString(options.inspection), "--inspection is required");
         if (inspection !== "status") {
@@ -551,10 +824,20 @@ class NativeThreadLifecycleCliApplication {
                 runtime: context.runtime,
                 beforeEnter: async () => {
                     const terminal = await context.bridge.resolveStoredTerminal(context.terminal.agent, context.terminal.pid, context.terminal.terminalControl, context.runtime);
-                    await this.assertFreshInspectionBoundary({
-                        context, terminal,
-                        stage: "immediately before native status submission"
-                    });
+                    if (context.foregroundBoundary) {
+                        await this.assertFreshForegroundBoundary({
+                            context,
+                            terminal,
+                            stage: "immediately before native status submission",
+                            requireReadyScreen: false
+                        });
+                    }
+                    else {
+                        await this.assertFreshInspectionBoundary({
+                            context, terminal,
+                            stage: "immediately before native status submission"
+                        });
+                    }
                 }
             });
         }
@@ -610,9 +893,15 @@ class NativeThreadLifecycleCliApplication {
             : context.runtime;
         let fingerprint;
         let stable;
+        let stableScreenDigest;
         let count = 0;
         for (let attempt = 0; attempt < 50; attempt += 1) {
-            const observed = await context.bridge.observeNativeInspection(context.terminal.agent, context.terminal.terminalControl, request, { runtime: postEnterRuntime, scrollbackLines: 240 });
+            const observed = await context.bridge.observeNativeInspection(context.terminal.agent, context.terminal.terminalControl, request, {
+                runtime: postEnterRuntime,
+                scrollbackLines: context.foregroundBoundary
+                    ? CODEX_FOREGROUND_IDENTIFICATION_SCROLLBACK_LINES
+                    : 240
+            });
             if (freshInspectionObservation(context.plan, submission.preEnterScreenDigest, observed)) {
                 if (fingerprint === observed.observation.evidenceFingerprint)
                     count += 1;
@@ -621,20 +910,27 @@ class NativeThreadLifecycleCliApplication {
                     count = 1;
                 }
                 stable = observed.observation;
+                stableScreenDigest = observed.screenDigest;
                 if (count >= 2)
                     break;
             }
             else {
                 fingerprint = undefined;
                 stable = undefined;
+                stableScreenDigest = undefined;
                 count = 0;
             }
             await this.ports.runtime.sleep(100);
         }
-        if (!stable || count < 2) {
+        if (!stable || !stableScreenDigest || count < 2) {
             throw new Error("native status inspection Enter was dispatched exactly once, but a fresh exact status result was not proven; do not retry automatically");
         }
-        return { observation: stable, request, postEnterRuntime };
+        return {
+            observation: stable,
+            request,
+            postEnterRuntime,
+            screenDigest: stableScreenDigest
+        };
     }
     async dismissInspection(context, observed) {
         if (context.plan.expectedResult.presentation !== "modal")
@@ -724,12 +1020,16 @@ class NativeThreadLifecycleCliApplication {
         });
     }
 }
+function bareNativeInspectionScreenDigest(fingerprint) {
+    return /^sha256:([0-9a-f]{64})$/u.exec(fingerprint)?.[1];
+}
 function freshInspectionObservation(plan, preEnterScreenDigest, observed) {
     return observed.status.reachable === true &&
         (plan.expectedResult.presentation === "inline"
             ? observed.status.activity_state === "idle"
             : !["working", "awaiting_approval"].includes(observed.status.activity_state)) &&
         observed.status.approval_state.blocked !== true &&
+        observed.status.interaction_state === undefined &&
         observed.screenDigest !== preEnterScreenDigest &&
         observed.observation.status === "observed" &&
         observed.observation.result?.kind === "native_status" &&