@scotthuang/agent-knock-knock 0.11.3 → 0.11.5

package/dist/src/cli.js

@@ -24,7 +24,7 @@ import { StaticTerminalControlProvider, TmuxTerminalControlProvider, terminalPan
 import { parseTerminalConversationId } from "./terminal-agent-adapter.js";
 import { createProductionTerminalAgentRegistry } from "./terminal-agent-registry.js";
 import { parseProcessElapsedSeconds, StaticTerminalProcessSource, SystemTerminalProcessSource } from "./terminal-process-source.js";
-import { TerminalAgentBridge, TerminalInputNotStartedError } from "./terminal-agent-bridge.js";
+import { isExactClaudeNativeInspectionIdleComposer, NativeInspectionSubmissionError, TerminalAgentBridge, TerminalInputNotStartedError } from "./terminal-agent-bridge.js";
 import { evaluateApprovalPolicy } from "./approval-policy.js";
 import { evaluateDoctorCapabilities, runDoctorCapabilityProbes } from "./doctor-capabilities.js";
 import { runOpenClawChainDiagnostics } from "./openclaw-doctor.js";
@@ -256,6 +256,9 @@ async function runCommand(commandName, options) {
     else if (commandName === "list-resumable-threads" || commandName === "threads") {
         await runListResumableThreads(options);
     }
+    else if (commandName === "native-inspect" || commandName === "native-status") {
+        await runNativeInspect(options);
+    }
     else if (commandName === "resume-thread") {
         await runResumeThread(options);
     }
@@ -706,7 +709,10 @@ function loadClaudeAgentRows(options = {}, observation = {}) {
                 ...(Number.isSafeInteger(Number(row.startedAt)) && Number(row.startedAt) > 0
                     ? { startedAt: Number(row.startedAt) }
                     : {}),
-                ...(stringValue(row.status) ? { status: stringValue(row.status) } : {})
+                ...(stringValue(row.status) ? { status: stringValue(row.status) } : {}),
+                ...(stringValue(row.waitingFor)
+                    ? { waitingFor: stringValue(row.waitingFor) }
+                    : {})
             }];
     });
 }
@@ -904,6 +910,9 @@ function createTerminalAgentBridge(options, terminalProvider = createTerminalCon
                 runtime?.nativeProcessBirth ||
                 runtime?.nativeRollout ||
                 runtime?.requireNativeProcessUuid ||
+                runtime?.requireExactClaudeAgentRow ||
+                runtime?.nativeProcessStartedAt ||
+                runtime?.exactClaudeAgentState ||
                 runtime?.requireNativeRolloutIdentity ||
                 runtime?.expectedNativeSessionId ||
                 runtime?.expectedEmptyNativeSession ||
@@ -931,6 +940,38 @@ function createTerminalAgentBridge(options, terminalProvider = createTerminalCon
                 agent,
                 pid
             });
+            if (runtime?.requireExactClaudeAgentRow === true) {
+                if (agent !== "claude" ||
+                    !Number.isSafeInteger(runtime.nativeProcessStartedAt) ||
+                    Number(runtime.nativeProcessStartedAt) <= 0 ||
+                    !runtime.nativeSessionId) {
+                    throw new Error(`native ${agent} inspection has an incomplete exact process identity; ` +
+                        "refresh list before controlling the terminal");
+                }
+                const agentRows = loadClaudeAgentRows(options, { required: true });
+                const observation = adapter.observeThreadLifecycle?.({
+                    operation: { kind: "new_thread" },
+                    phase: "before",
+                    pid,
+                    processStartedAt: runtime.nativeProcessStartedAt,
+                    cwd: snapshot.cwd ?? pane.currentPath,
+                    agentRows
+                });
+                const exactRows = agentRows.filter((row) => row.pid === pid);
+                const expectedState = runtime.exactClaudeAgentState ?? "idle";
+                const stateMatches = expectedState === "idle"
+                    ? observation?.idle === true
+                    : (observation?.idle === false &&
+                        exactRows.length === 1 &&
+                        exactRows[0].status === "waiting" &&
+                        exactRows[0].waitingFor === "dialog open");
+                if (observation?.status !== "observed" ||
+                    !stateMatches ||
+                    observation.nativeThreadId !== runtime.nativeSessionId) {
+                    throw new Error(`native Claude agents identity, cwd, or idle state changed for process ${pid}; ` +
+                        "refresh list before controlling the terminal");
+                }
+            }
             return {
                 terminalControl: {
                     ...terminalControl,
@@ -2782,6 +2823,13 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
         resumeExact: false,
         reason: "native thread lifecycle is unavailable"
     };
+    const nativeInspectionCapability = bridge.registry.require(session.agent)
+        .probeNativeInspection?.(agentVersion) ?? {
+        status: "unsupported",
+        agentVersion,
+        statusInspection: false,
+        reason: "native inspection is unavailable"
+    };
     const lifecycleBindingToken = unmanagedTerminalBindingToken({
         terminalId: bridge.terminalConversationId(session),
         terminalControl,
@@ -2795,6 +2843,10 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
     });
     const codexLifecycleIncarnationAvailable = session.agent !== "codex" ||
         Boolean(nativeProcessUuid && nativeProcessBirth);
+    const nativeInspectionHasBlockingTurn = listConversations(storeDirFromOptions(options)).some((turn) => isDiscoverableTmuxConversation(turn) &&
+        terminalKeyForManagedConversation(turn) ===
+            terminalControlSelectorKey(terminalControl) &&
+        SESSION_SEND_BLOCKING_STATUSES.has(turn.status));
     const entry = {
         id: bridge.terminalConversationId(session),
         short_ref: sessionShortRef(bridge.terminalConversationId(session)),
@@ -2815,6 +2867,7 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
         native_agent_identity_evidence: nativeProcessEvidence,
         agent_version: agentVersion,
         native_thread_lifecycle: lifecycleCapability,
+        native_inspection: nativeInspectionCapability,
         lifecycle_binding_token: lifecycleBindingToken,
         confidence: session.confidence,
         reason: session.reason,
@@ -2849,7 +2902,18 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
                 codexLifecycleIncarnationAvailable,
             list_resumable_threads: lifecycleCapability.status === "supported" &&
                 lifecycleCapability.resumeExact === true &&
-                codexLifecycleIncarnationAvailable
+                codexLifecycleIncarnationAvailable,
+            native_inspect: nativeInspectionCapability.status === "supported" &&
+                nativeInspectionCapability.statusInspection === true &&
+                nativeInspectionComposerEmpty(session.agent, terminalState.screen_excerpt) &&
+                terminalControl.capabilities.includes("send_keys") &&
+                terminalControl.capabilities.includes("screen_status") &&
+                (session.agent === "codex"
+                    ? codexLifecycleIncarnationAvailable
+                    : Boolean(nativeAgentIdentity?.sessionId &&
+                        nativeAgentIdentity.processUuid)) &&
+                orphanedDispatch === undefined &&
+                !nativeInspectionHasBlockingTurn
         }
     };
     const availableActions = availableListActions(entry);
@@ -2973,9 +3037,13 @@ function terminalFirstListProjection({ storeDir, terminals, managedSessions, ses
         const rawActions = mutationsAllowed
             ? discoveredRawActions
             : readOnlyListActions(discoveredRawActions);
-        const sessionAwareRawActions = authoritativeSession
+        const bindingAwareRawActions = authoritativeSession
             ? actionsForManagedSessionBinding(rawActions, authoritativeSession)
             : rawActions;
+        const sessionAwareRawActions = authoritativeSession &&
+            managedSessionHasUnresolvedNativeTransition(storeDir, authoritativeSession)
+            ? Object.fromEntries(Object.entries(bindingAwareRawActions).filter(([actionName]) => actionName !== "native_inspect"))
+            : bindingAwareRawActions;
         const soleBindingConflict = conflictingBoundSessionClaims.length === 1
             ? conflictingBoundSessionClaims[0]
             : undefined;
@@ -3595,7 +3663,7 @@ function sendActionForManagedSession(action, sessionId) {
 function actionsForManagedSessionBinding(actions, session) {
     const token = managedSessionBindingToken(session);
     const next = { ...actions };
-    for (const actionName of ["new_thread", "resume_thread"]) {
+    for (const actionName of ["new_thread", "resume_thread", "native_inspect"]) {
         const action = isRecord(next[actionName]) ? next[actionName] : undefined;
         if (!action) {
             continue;
@@ -3863,11 +3931,12 @@ function managedListApprovalState(conversation) {
 }
 function listActionContracts() {
     return {
-        version: 6,
+        version: 7,
         instructions: [
             "Treat terminals[] as the primary resource and use only actions present in available_actions.",
             "An existing managed session's ordinary send targets session_id and creates a new turn. A turn id is never an ordinary send target.",
             "Read-only native-thread listing targets an exact terminal_id. Native-thread new/resume mutations also use the listed expected_binding_token and never create a Turn.",
+            "Native inspection is a separate terminal action: use only its closed inspection enum and current exact terminal_id/token; AKK status does not execute a native slash command.",
             "A binding conflict may be detached only through its exact reconcile_binding action, which is snapshot-bound to the Session revision, binding, and live terminal identity and never adopts a replacement native thread.",
             "List resumable threads before resume; use only a complete native_thread_id and the action returned for that candidate.",
             "For first attach only, use a discovery selector explicitly named by the user or the selector prefilled by that unmanaged raw-terminal row's available send action; never infer, guess, or reuse one.",
@@ -3934,6 +4003,17 @@ function listActionContracts() {
                 required: ["terminal_id"],
                 side_effect_free: true
             },
+            native_inspect: {
+                tool: "agent_knock_knock_native_inspect",
+                target_argument: "terminal_id",
+                required: ["terminal_id", "inspection", "expected_binding_token"],
+                supported_inspections: ["status"],
+                creates_turn: false,
+                creates_session: false,
+                mutates_store: false,
+                sends_terminal_input: true,
+                candidate_source: "terminals[].available_actions.native_inspect"
+            },
             resume_thread: {
                 tool: "agent_knock_knock_resume_thread",
                 target_argument: "terminal_id",
@@ -4084,6 +4164,20 @@ function availableListActions(entry, { conversation } = {}) {
             arguments: { terminal_id: id }
         };
     }
+    if (terminalControlled &&
+        commands.native_inspect === true &&
+        entry.activity_state === "idle" &&
+        approvalState.blocked !== true &&
+        lifecycleBindingToken) {
+        actions.native_inspect = {
+            tool: "agent_knock_knock_native_inspect",
+            arguments: {
+                terminal_id: id,
+                inspection: "status",
+                expected_binding_token: lifecycleBindingToken
+            }
+        };
+    }
     if (managed &&
         commands.respond === true &&
         terminalBridgeReady &&
@@ -5965,6 +6059,452 @@ async function runListResumableThreads(options) {
         }))
     });
 }
+function assertSameNativeInspectionTerminal(expected, actual, stage) {
+    const expectedPath = expected.terminalControl.currentPath;
+    const actualPath = actual.terminalControl.currentPath;
+    if (actual.conversationId !== expected.conversationId ||
+        actual.agent !== expected.agent ||
+        actual.pid !== expected.pid ||
+        terminalControlSelectorKey(actual.terminalControl) !==
+            terminalControlSelectorKey(expected.terminalControl) ||
+        !expectedPath ||
+        !actualPath ||
+        path.resolve(actualPath) !== path.resolve(expectedPath)) {
+        throw new Error(`terminal identity, pane, or cwd changed ${stage}; refresh AKK list`);
+    }
+}
+function assertTerminalNativeInspectionReady({ options, terminal, terminalStatus, session }) {
+    if (terminalStatus &&
+        (terminalStatus.reachable !== true ||
+            terminalStatus.activity_state !== "idle" ||
+            terminalStatus.approval_state.blocked === true)) {
+        throw new Error(`terminal ${terminal.terminalControl.target} is not at a verified idle prompt ` +
+            `(${terminalStatus.activity_state}: ${terminalStatus.activity_reason})`);
+    }
+    const blocker = listConversations(storeDirFromOptions(options))
+        .filter(isDiscoverableTmuxConversation)
+        .find((turn) => terminalKeyForManagedConversation(turn) ===
+        terminalControlSelectorKey(terminal.terminalControl) &&
+        SESSION_SEND_BLOCKING_STATUSES.has(turn.status));
+    if (blocker) {
+        throw new Error(`terminal ${terminal.terminalControl.target} still has unresolved Turn ` +
+            `${turnIdForConversation(blocker)} (${blocker.status})`);
+    }
+    if (session &&
+        managedSessionHasUnresolvedNativeTransition(storeDirFromOptions(options), session)) {
+        throw new Error(`managed Session ${session.session_id} has an unresolved native-thread transition`);
+    }
+    const ownership = terminalDispatchOwnership(terminal.terminalControl);
+    if (ownership.state !== "none") {
+        throw new Error(`terminal ${terminal.terminalControl.target} has unresolved dispatch ` +
+            "ownership; resolve it before native inspection");
+    }
+    const orphaned = orphanedTerminalDispatchForRecovery(terminal.terminalControl);
+    if (orphaned) {
+        throw new Error(`terminal ${terminal.terminalControl.target} has unresolved ` +
+            `${String(orphaned.kind ?? "terminal")} input ` +
+            `(${String(orphaned.status ?? "unknown")})`);
+    }
+}
+function nativeInspectionRuntime({ terminal, snapshot }) {
+    if (terminal.agent === "claude") {
+        const identity = snapshot.runtimeIdentity;
+        if (!identity?.sessionId ||
+            !identity.processUuid ||
+            identity.sessionId !== snapshot.identity?.sessionId) {
+            throw new Error("Claude native status inspection requires one exact claude agents Session and process incarnation");
+        }
+        return {
+            ...terminalRuntimeForLiveIdentity({ terminal, identity }),
+            requireExactClaudeAgentRow: true,
+            nativeProcessStartedAt: identity.processStartedAt,
+            exactClaudeAgentState: "idle"
+        };
+    }
+    const exactRuntimeIdentity = snapshot.runtimeIdentity?.sessionId === snapshot.identity?.sessionId
+        ? snapshot.runtimeIdentity
+        : undefined;
+    const runtime = exactRuntimeIdentity
+        ? terminalRuntimeForLiveIdentity({
+            terminal,
+            identity: exactRuntimeIdentity
+        })
+        : {
+            ...terminalRuntimeForLiveIdentity({
+                terminal,
+                expectedEmptyNativeSession: true
+            }),
+            ...(snapshot.identity?.processUuid
+                ? { nativeProcessUuid: snapshot.identity.processUuid }
+                : {}),
+            ...(snapshot.identity?.processBirth
+                ? { nativeProcessBirth: snapshot.identity.processBirth }
+                : {}),
+            ...(snapshot.identity?.sessionId
+                ? { expectedNativeSessionId: snapshot.identity.sessionId }
+                : {})
+        };
+    return withCodexCompanionFences(runtime, snapshot.codexCompanions);
+}
+function assertNativeInspectionSnapshotUnchanged({ options, expectedTerminal, actualTerminal, expectedBindingToken, expectedVersion, actualSnapshot, stage, expectedClaudeState = "idle" }) {
+    assertSameNativeInspectionTerminal(expectedTerminal, actualTerminal, stage);
+    if (actualSnapshot.bindingToken !== expectedBindingToken) {
+        throw new Error(`terminal binding changed ${stage}; refresh AKK list`);
+    }
+    if (actualSnapshot.version !== expectedVersion) {
+        throw new Error(`coding-agent version changed ${stage}; refresh AKK list`);
+    }
+    const capability = actualSnapshot.adapter.probeNativeInspection?.(actualSnapshot.version);
+    if (capability?.status !== "supported" ||
+        capability.statusInspection !== true) {
+        throw new Error(capability?.reason ??
+            "native status inspection became unsupported; refresh AKK list");
+    }
+    assertNativeInspectionAgentIdentity({
+        options,
+        terminal: actualTerminal,
+        snapshot: actualSnapshot,
+        stage,
+        expectedClaudeState
+    });
+}
+function assertNativeInspectionAgentIdentity({ options, terminal, snapshot, stage, expectedClaudeState = "idle" }) {
+    if (terminal.agent !== "claude") {
+        return;
+    }
+    const identity = snapshot.runtimeIdentity;
+    if (!identity?.sessionId ||
+        !identity.processUuid ||
+        !Number.isSafeInteger(identity.processStartedAt) ||
+        Number(identity.processStartedAt) <= 0) {
+        throw new Error(`Claude process identity is incomplete ${stage}; refresh AKK list`);
+    }
+    const agentRows = loadClaudeAgentRows(options, { required: true });
+    const observation = snapshot.adapter.observeThreadLifecycle?.({
+        operation: { kind: "new_thread" },
+        phase: "before",
+        pid: terminal.pid,
+        processStartedAt: identity.processStartedAt,
+        cwd: terminal.terminalControl.currentPath,
+        agentRows
+    });
+    const exactRows = agentRows.filter((row) => row.pid === terminal.pid);
+    const stateMatches = expectedClaudeState === "idle"
+        ? observation?.idle === true
+        : (observation?.idle === false &&
+            exactRows.length === 1 &&
+            exactRows[0].status === "waiting" &&
+            exactRows[0].waitingFor === "dialog open");
+    if (observation?.status !== "observed" ||
+        !stateMatches ||
+        observation.nativeThreadId !== identity.sessionId) {
+        throw new Error(`Claude agents identity, cwd, or idle state changed ${stage}; refresh AKK list`);
+    }
+}
+async function assertNativeInspectionExclusiveOwnership({ options, terminal, snapshot }) {
+    // Claude's exact `claude agents` mapping makes global active ownership part
+    // of the 2.1.218 inspection profile. Keep the existing Codex #112 path
+    // unchanged: an unmanaged Codex pane may be inspected before a rollout
+    // identity exists, and its status card is the bounded identity evidence.
+    if (terminal.agent !== "claude") {
+        return;
+    }
+    const nativeThreadId = snapshot.identity?.sessionId ??
+        snapshot.session?.binding?.native_thread_id;
+    if (!isExactNativeThreadId(nativeThreadId)) {
+        throw new Error("native status inspection requires one exact current native Session identity");
+    }
+    await assertNativeThreadHasExclusiveOwnership({
+        options,
+        agent: terminal.agent,
+        currentPid: terminal.pid,
+        nativeThreadId,
+        storeDir: storeDirFromOptions(options),
+        terminalControl: terminal.terminalControl,
+        excludedManagedSessionId: snapshot.session?.session_id
+    });
+}
+async function runNativeInspect(options) {
+    const inspection = required(stringValue(options.inspection), "--inspection is required");
+    if (inspection !== "status") {
+        throw new Error("--inspection must be the closed value status; arbitrary native slash commands are not accepted");
+    }
+    if (options.command !== undefined || options.message !== undefined) {
+        throw new Error("native inspection does not accept a command or message payload");
+    }
+    const expectedBindingToken = required(stringValue(options.expectedBindingToken), "--expected-binding-token is required");
+    const storeDir = storeDirFromOptions(options);
+    const store = inspectStoreCompatibility(storeDir);
+    if (store.writable !== true) {
+        throw new Error("native inspection requires a compatible AKK Store so binding authority can be verified");
+    }
+    const initiallyResolved = await resolveLifecycleTerminal(options);
+    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDir, initiallyResolved.terminalControl), { timeoutMs: 30000 });
+    try {
+        const terminal = await resolveLifecycleTerminal(options);
+        assertSameNativeInspectionTerminal(initiallyResolved, terminal, "while waiting for native-inspection control");
+        const snapshot = await currentLifecycleSnapshot(options, terminal);
+        if (snapshot.bindingToken !== expectedBindingToken) {
+            throw new Error("terminal binding changed after it was listed; refresh AKK list and retry");
+        }
+        const capability = snapshot.adapter.probeNativeInspection?.(snapshot.version);
+        if (capability?.status !== "supported" ||
+            capability.statusInspection !== true) {
+            throw new Error(capability?.reason ??
+                "native status inspection is unavailable for this agent version");
+        }
+        const plan = snapshot.adapter.planNativeInspection?.({ kind: "status" }, capability);
+        if (!plan ||
+            plan.operation.kind !== "status" ||
+            plan.command !== "/status" ||
+            plan.effect !== "read_only") {
+            throw new Error("the agent adapter did not produce the closed native status inspection plan");
+        }
+        assertNativeInspectionAgentIdentity({
+            options,
+            terminal,
+            snapshot,
+            stage: "before native status inspection"
+        });
+        await assertNativeInspectionExclusiveOwnership({
+            options,
+            terminal,
+            snapshot
+        });
+        const runtime = nativeInspectionRuntime({ terminal, snapshot });
+        const bridge = createTerminalAgentBridge(options);
+        const initialStatus = await bridge.status(terminal.agent, terminal.terminalControl, { runtime });
+        assertTerminalNativeInspectionReady({
+            options,
+            terminal,
+            terminalStatus: initialStatus,
+            session: snapshot.session
+        });
+        await assertNativeInspectionComposerReadyForAutomatedInput({
+            options,
+            terminal
+        });
+        let submission;
+        try {
+            submission = await bridge.submitNativeInspection(terminal.agent, terminal.terminalControl, plan, {
+                runtime,
+                beforeEnter: async () => {
+                    const finalTerminal = await resolveLifecycleTerminal(options);
+                    const finalSnapshot = await currentLifecycleSnapshot(options, finalTerminal);
+                    assertNativeInspectionSnapshotUnchanged({
+                        options,
+                        expectedTerminal: terminal,
+                        actualTerminal: finalTerminal,
+                        expectedBindingToken,
+                        expectedVersion: snapshot.version,
+                        actualSnapshot: finalSnapshot,
+                        stage: "immediately before native status submission"
+                    });
+                    await assertNativeInspectionExclusiveOwnership({
+                        options,
+                        terminal: finalTerminal,
+                        snapshot: finalSnapshot
+                    });
+                    assertTerminalNativeInspectionReady({
+                        options,
+                        terminal: finalTerminal,
+                        session: finalSnapshot.session
+                    });
+                }
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            if (error instanceof NativeInspectionSubmissionError &&
+                error.doNotRetry !== true) {
+                throw new Error(`native status inspection did not start; refresh AKK list and retry if still desired: ${detail}`);
+            }
+            throw new Error("native status inspection did not cross a proven completion boundary; " +
+                `do not retry automatically: ${detail}`);
+        }
+        try {
+            const expectedNativeThreadId = snapshot.session?.binding?.native_thread_id ??
+                snapshot.identity?.sessionId;
+            const observationRequest = {
+                operation: plan.operation,
+                previousScreenFingerprint: submission.preEnterScreenDigest,
+                preEnterEvidenceInventory: submission.preEnterEvidenceInventory,
+                expectedNativeThreadId,
+                expectedAgentVersion: snapshot.version,
+                expectedCwd: terminal.terminalControl.currentPath
+            };
+            const postEnterRuntime = plan.expectedResult.presentation === "modal"
+                ? { ...runtime, exactClaudeAgentState: "status_dialog" }
+                : runtime;
+            let stableEvidenceFingerprint;
+            let stableObservation;
+            let stableCount = 0;
+            for (let attempt = 0; attempt < 50; attempt += 1) {
+                const observed = await bridge.observeNativeInspection(terminal.agent, terminal.terminalControl, observationRequest, { runtime: postEnterRuntime, scrollbackLines: 240 });
+                const observation = observed.observation;
+                if (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.screenDigest !== submission.preEnterScreenDigest &&
+                    observation.status === "observed" &&
+                    observation.result?.kind === "native_status" &&
+                    isExactNativeThreadId(observation.nativeThreadId) &&
+                    observation.evidenceFingerprint) {
+                    if (stableEvidenceFingerprint === observation.evidenceFingerprint) {
+                        stableCount += 1;
+                    }
+                    else {
+                        stableEvidenceFingerprint = observation.evidenceFingerprint;
+                        stableObservation = observation;
+                        stableCount = 1;
+                    }
+                    if (stableCount >= 2) {
+                        stableObservation = observation;
+                        break;
+                    }
+                }
+                else {
+                    stableEvidenceFingerprint = undefined;
+                    stableObservation = undefined;
+                    stableCount = 0;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+            if (!stableObservation || stableCount < 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");
+            }
+            let dismissal;
+            if (plan.expectedResult.presentation === "modal") {
+                if (!stableObservation.evidenceFingerprint) {
+                    throw new Error("native status modal lacks exact dismissal evidence; do not retry automatically");
+                }
+                try {
+                    dismissal = await bridge.dismissNativeInspection(terminal.agent, terminal.terminalControl, plan, observationRequest, stableObservation.evidenceFingerprint, {
+                        runtime: postEnterRuntime,
+                        scrollbackLines: 240,
+                        beforeDismiss: async () => {
+                            const dismissTerminal = await resolveLifecycleTerminal(options);
+                            const dismissSnapshot = await currentLifecycleSnapshot(options, dismissTerminal);
+                            assertNativeInspectionSnapshotUnchanged({
+                                options,
+                                expectedTerminal: terminal,
+                                actualTerminal: dismissTerminal,
+                                expectedBindingToken,
+                                expectedVersion: snapshot.version,
+                                actualSnapshot: dismissSnapshot,
+                                stage: "immediately before native status dismissal",
+                                expectedClaudeState: "status_dialog"
+                            });
+                            await assertNativeInspectionExclusiveOwnership({
+                                options,
+                                terminal: dismissTerminal,
+                                snapshot: dismissSnapshot
+                            });
+                            assertTerminalNativeInspectionReady({
+                                options,
+                                terminal: dismissTerminal,
+                                session: dismissSnapshot.session
+                            });
+                        }
+                    });
+                }
+                catch (error) {
+                    const detail = error instanceof Error ? error.message : String(error);
+                    throw new Error("native status panel was proven but safe dismissal failed; " +
+                        `do not retry automatically and dismiss it manually if still visible: ${detail}`);
+                }
+                let restoredIdle = false;
+                for (let attempt = 0; attempt < 50; attempt += 1) {
+                    const restored = await bridge.status(terminal.agent, terminal.terminalControl, { runtime });
+                    if (restored.reachable === true &&
+                        restored.activity_state === "idle" &&
+                        restored.approval_state.blocked !== true &&
+                        nativeInspectionComposerEmpty(terminal.agent, restored.screen.excerpt)) {
+                        restoredIdle = true;
+                        break;
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                }
+                if (!restoredIdle) {
+                    throw new Error("Claude Status panel dismissal was dispatched exactly once, but the original idle composer was not restored; do not retry automatically");
+                }
+            }
+            const finalTerminal = await resolveLifecycleTerminal(options);
+            const finalSnapshot = await currentLifecycleSnapshot(options, finalTerminal);
+            assertNativeInspectionSnapshotUnchanged({
+                options,
+                expectedTerminal: terminal,
+                actualTerminal: finalTerminal,
+                expectedBindingToken,
+                expectedVersion: snapshot.version,
+                actualSnapshot: finalSnapshot,
+                stage: "after native status inspection"
+            });
+            await assertNativeInspectionExclusiveOwnership({
+                options,
+                terminal: finalTerminal,
+                snapshot: finalSnapshot
+            });
+            const finalStatus = await bridge.status(finalTerminal.agent, finalTerminal.terminalControl, { runtime });
+            assertTerminalNativeInspectionReady({
+                options,
+                terminal: finalTerminal,
+                terminalStatus: finalStatus,
+                session: finalSnapshot.session
+            });
+            await assertNativeInspectionComposerReadyForAutomatedInput({
+                options,
+                terminal: finalTerminal
+            });
+            printJson({
+                status: "observed",
+                inspection: "status",
+                terminal_id: terminal.conversationId,
+                agent: terminal.agent,
+                agent_version: snapshot.version,
+                behavior_profile: plan.behaviorProfile,
+                native_thread_id: stableObservation.nativeThreadId,
+                native_status: stableObservation.result,
+                terminal_submission: {
+                    command: plan.command,
+                    enter_count: submission.enterCount,
+                    materialization: submission.materialization
+                },
+                ...(dismissal
+                    ? {
+                        terminal_dismissal: {
+                            keys: dismissal.keys,
+                            dismiss_count: dismissal.dismissCount,
+                            restored_idle: true
+                        }
+                    }
+                    : {}),
+                store_mutation: false,
+                session_created: false,
+                turn_created: false,
+                receipt_created: false,
+                monitor_created: false,
+                callback_created: false
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            if (/do not retry automatically/iu.test(detail)) {
+                throw error;
+            }
+            throw new Error("native status inspection Enter was dispatched exactly once, but its " +
+                `postcondition became uncertain; do not retry automatically: ${detail}`);
+        }
+    }
+    finally {
+        releaseTerminalLock();
+    }
+}
 function previousCommittedResumeCandidate({ storeDir, terminal, currentSession, candidates }) {
     if (!currentSession?.last_transition_id) {
         return undefined;
@@ -10632,8 +11172,8 @@ function assertOrdinaryTerminalPayloadDoesNotInvokeNativeLifecycle(payload) {
         return;
     }
     throw new Error(`ordinary send/respond cannot invoke native slash command /${reserved[1].toLowerCase()}; ` +
-        "use the advertised new-thread, resume-thread, or status action, or enter " +
-        "an unsupported native command manually in tmux");
+        "use an advertised dedicated native action when one exists, or enter " +
+        "the unsupported native command manually in tmux");
 }
 function isCompleteNativeRollout(value) {
     return isRecord(value) &&
@@ -10814,6 +11354,13 @@ function assertNativeAgentIdentityForRuntime({ runtime, currentIdentity, agent,
         throw new Error(`native ${agent} process incarnation cannot be verified for process ${pid}; ` +
             "refresh list before controlling the terminal");
     }
+    if (runtime?.nativeProcessStartedAt !== undefined &&
+        (!Number.isSafeInteger(runtime.nativeProcessStartedAt) ||
+            Number(runtime.nativeProcessStartedAt) <= 0 ||
+            currentIdentity?.processStartedAt !== runtime.nativeProcessStartedAt)) {
+        throw new Error(`native ${agent} process start changed for process ${pid}; ` +
+            "refresh list before controlling the terminal");
+    }
     if (!runtime?.nativeSessionId) {
         return;
     }
@@ -15695,6 +16242,27 @@ function codexComposerVisible(screen) {
         .slice(-8)
         .some((line) => /^[›»](?:\s|$)/u.test(line.trimEnd()));
 }
+function nativeInspectionComposerEmpty(agent, screen) {
+    return agent === "codex"
+        ? codexComposerEmpty(screen)
+        : isExactClaudeNativeInspectionIdleComposer(String(screen ?? ""));
+}
+async function assertNativeInspectionComposerReadyForAutomatedInput({ options, terminal }) {
+    if (terminal.agent === "codex") {
+        await assertCodexComposerReadyForAutomatedInput({
+            options,
+            terminalControl: terminal.terminalControl
+        });
+        return;
+    }
+    const screen = await createTerminalControlProvider(options).capture(terminal.terminalControl.target, {
+        scrollbackLines: 40,
+        socketPath: terminal.terminalControl.socketPath
+    });
+    if (!isExactClaudeNativeInspectionIdleComposer(screen)) {
+        throw new Error("Claude composer contains input or is not at the exact idle frame; refusing automated terminal input");
+    }
+}
 function codexComposerEmpty(screen) {
     const composers = String(screen ?? "")
         .split(/\r?\n/u)
@@ -15768,14 +16336,20 @@ function codexStyledComposerEmpty(screen) {
     return content.length === 0 || content.every((entry) => entry.dim);
 }
 function claudeComposerVisible(screen) {
-    return String(screen ?? "")
-        .split(/\r?\n/u)
+    const lines = String(screen ?? "").split(/\r?\n/u);
+    while (lines.length > 0 && lines.at(-1)?.trim() === "") {
+        lines.pop();
+    }
+    return lines
         .slice(-8)
         .some((line) => /^\s*❯(?:\s|$)/u.test(line));
 }
 function claudeComposerEmpty(screen) {
-    const composers = String(screen ?? "")
-        .split(/\r?\n/u)
+    const lines = String(screen ?? "").split(/\r?\n/u);
+    while (lines.length > 0 && lines.at(-1)?.trim() === "") {
+        lines.pop();
+    }
+    const composers = lines
         .slice(-8)
         .filter((line) => /^\s*❯(?:\s|$)/u.test(line));
     return composers.length === 1 && /^\s*❯\s*$/u.test(composers[0]);
@@ -19112,6 +19686,7 @@ function usage() {
   agent-knock-knock new-thread --terminal <exact-terminal-id> --expected-binding-token <token>
   agent-knock-knock clear-thread --terminal <exact-terminal-id> --expected-binding-token <token>
   agent-knock-knock list-resumable-threads --terminal <exact-terminal-id> [--selection-scope <opaque-scope>]
+  agent-knock-knock native-inspect --terminal <exact-terminal-id> --inspection status --expected-binding-token <token>
   agent-knock-knock resume-thread --terminal <exact-terminal-id> --native-thread <uuid> --expected-binding-token <token> --candidate-token <token>
   agent-knock-knock resume-thread --terminal <exact-terminal-id> (--selection-handle <handle> | --selection-snapshot <id> (--selection-number <n> | --selection-short-id <@id>)) --selection-scope <opaque-scope>
   agent-knock-knock reconcile-binding --terminal <exact-terminal-id> --conflicting-session <session-id> --expected-session-revision <n> --expected-binding-token <token> --expected-terminal-token <token>