@scotthuang/agent-knock-knock 0.11.3 → 0.11.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.11.4 - 2026-08-09
+
+### Added
+
+- Add an adapter-owned, version-scoped native status inspection for Codex 0.146.0 and 0.146.1, exposed through a closed `native_inspect(status)` action that returns a bounded and redacted fresh `/status` result without creating a Session, Turn, receipt, monitor, callback, or Store state.
+
+### Security
+
+- Keep ordinary `send` and `respond` slash-command rejection intact while serializing native inspection with terminal mutations, revalidating the exact terminal, process, binding, version, idle composer, and ownership state, and dispatching at most one Enter only after the versioned 121 ms materialization boundary.
+- Fail closed after identity drift, ambiguous or stale status evidence, and uncertain submission outcomes without blind retries or a second Enter.
+
 ## 0.11.3 - 2026-08-08
 
 ### Fixed

package/README.md

@@ -87,6 +87,8 @@ Human-friendly selectors such as `only`, `codex`, `claude`, a terminal ID, or `@
 
 Native clear/new/resume operations are explicit lifecycle actions, separate from ordinary Turn creation. A successful new/clear creates a new native thread and AKK Session; resume activates the exact historical native thread and its corresponding Session. Each successful lifecycle transition creates no Turn. The next ordinary send creates the first Turn in the selected context. AKK serializes the transition, verifies the resulting native identity, and advances the terminal binding generation so work and callbacks from the previous context cannot cross the boundary.
 
+AKK status and native status inspection are different operations. `agent_knock_knock_status` (and `/akk status`) reads AKK Turn state plus a bounded current terminal screen; it does not execute the coding agent's `/status`. When an idle terminal row advertises `native_inspect`, `agent_knock_knock_native_inspect` can execute only its prefilled, version-scoped inspection with the exact `terminal_id`, `inspection="status"`, and fresh `expected_binding_token`. Initial support is Codex-only and limited to versions 0.146.0 and 0.146.1. It creates no Session, Turn, receipt, monitor, or callback. Claude native commands, `/usage`, `/model`, `/compact`, arbitrary slash strings, and unsupported Codex versions remain unavailable. In particular, bare Codex `/usage` opens an interactive menu whose later Enter can select an account-side usage-limit reset; do not automate it as a read-only inspection.
+
 ## Optional: Natural-Language Delegation
 
 The quick start uses direct `/akk ...` commands, which bypass the model and work without plugin tool access. To let OpenClaw decide to use AKK from a natural-language request, grant the optional `agent-knock-knock` tools in the applicable tool policy.
@@ -132,7 +134,7 @@ If you also want standalone shell commands such as `agent-knock-knock doctor`, i
 npm install -g @scotthuang/agent-knock-knock
 ```
 
-Standalone `agent-knock-knock list` and `status` are read-only with respect to managed-turn state by default. Passing `--reconcile` explicitly enables controlled reconciliation; OpenClaw does this for `/akk list`, `/akk status`, and the corresponding plugin tools.
+Standalone `agent-knock-knock list` and AKK `status` are read-only with respect to managed-turn state by default. Passing `--reconcile` explicitly enables controlled reconciliation; OpenClaw does this for `/akk list`, `/akk status`, and the corresponding plugin tools. This AKK status path does not run native Codex `/status`; the separately advertised `native_inspect` action owns that bounded terminal input.
 
 ### Alternative: Install from npm
 
@@ -226,11 +228,15 @@ Selectors fail closed: `only` works only with one actionable target, `latest` re
 
 To change native context, first copy the full `terminal_id` from `/akk list`; lifecycle commands do not accept an ordinary-send `@short-ref` or loose agent selector. `/akk threads <exact-terminal-id>` lists exact, same-workspace candidates with a deterministic number, a collision-safe display-only `@short-id`, an opaque snapshot handle, and the complete UUID. `/akk resume-thread <exact-terminal-id>` without a selection shows that list. A complete UUID remains compatible. A number or short ID resolves only against the latest list displayed in the same OpenClaw session, while an opaque handle names its exact snapshot; all expire after five minutes and fail after terminal, process, workspace, binding, candidate-set, or relevant action changes. None is ever passed to Codex or Claude Code as native identity: AKK resolves the saved tuple back to its full UUID and fresh evidence tokens first. `previous` (or `刚才那个`) is advertised only when the current Session's latest committed lifecycle transition identifies exactly one currently verified resumable source; it never guesses from title, recency, or static lineage. `/akk new-thread` and its human alias `/akk clear-thread` start a clean context. AKK does not poll bindings in the background: if a recorded owner process exits, the next lifecycle listing can classify that sole historical binding as resumable, and the resume mutation compare-and-swap detaches it before touching the terminal. Live, stale, expired, unsupported, busy, ambiguous, active-elsewhere, or unverifiable transitions fail closed. Do not send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, or `/btw`, Claude `/branch`, or any other first-line native slash command as an ordinary task or answer; use an advertised AKK action, express the request in natural language, or enter an unsupported native command manually in tmux.
 
+To request the native Codex status card, first run `agent_knock_knock_list` and use only that terminal row's advertised `native_inspect` action. The structured tool schema is closed to `inspection="status"`; callers cannot provide `/status` or another slash command as text. AKK serializes the inspection with terminal mutations, revalidates the fresh token and exact terminal identity, and returns only after it proves one fresh bounded status result and an idle postcondition. It never turns ordinary `send` or `respond` into a slash-command escape hatch.
+
+The top-level v7 `action_contracts` documents this closed inspection alongside the existing lifecycle and Turn actions; `available_actions` remains the only current-action authority.
+
 For natural-language tool use, `agent_knock_knock_list` is terminal-first. Each live pane appears exactly once in `terminals[]`; `process_state` reports whether its coding-agent process is alive and `activity_state` reports the parsed screen state. `managed.session_id` identifies the continuing AKK session, `managed.current_turn` is its optional active Turn, and `managed.recent_turn` is retained history; retained Turns do not occupy the terminal. Pass `all=true` to include older entries in `managed.history`. By default, `unavailable_managed_turns[]` contains attention-needed records whose pane cannot be presented as a live terminal; `all=true` also includes retained unavailable history.
 
-Use only an `available_actions` entry returned in that snapshot, begin with its prefilled authoritative arguments, and supply every `missing_required` field. A managed Session's `send` uses its prefilled `session_id` and creates a new Turn. For first attach only, use a discovery selector explicitly named by the user or the unmanaged raw-terminal row's prefilled `selector`; do not infer or reuse one. `respond` is available only while a Turn is `waiting_for_openclaw`; it uses `turn_id` and keeps the answer inside that Turn. Managed status, approval, cancellation, renewal, callback retry, and close also use the exact `turn_id`. A raw terminal may be controlled only through the exact status, approval, cancellation, or orphan-close action that its own row advertises with a prefilled `conversation_id`; never construct or guess one. For an ordinary send, add only `request`—`timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK revalidates availability before every side effect.
+Use only an `available_actions` entry returned in that snapshot, begin with its prefilled authoritative arguments, and supply every `missing_required` field. A managed Session's `send` uses its prefilled `session_id` and creates a new Turn. For first attach only, use a discovery selector explicitly named by the user or the unmanaged raw-terminal row's prefilled `selector`; do not infer or reuse one. `respond` is available only while a Turn is `waiting_for_openclaw`; it uses `turn_id` and keeps the answer inside that Turn. Managed status, approval, cancellation, renewal, callback retry, and close also use the exact `turn_id`. Native inspection instead uses the exact terminal row's `terminal_id`, closed `inspection`, and snapshot-bound `expected_binding_token`; do not substitute AKK status or ordinary send. A raw terminal may be controlled only through the exact status, approval, cancellation, or orphan-close action that its own row advertises with a prefilled `conversation_id`; never construct or guess one. For an ordinary send, add only `request`—`timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK revalidates availability before every side effect.
 
-The top-level v6 `action_contracts` adds `list_resumable_threads`, `new_thread`, `resume_thread`, and the conflict-only `reconcile_binding` recovery action. The terminal row advertises `list_resumable_threads` and, when currently safe, `new_thread`. Listing is read-only with respect to Session/Turn state, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` row retains its complete UUID and exact prefilled `resume_thread` action. If `previous` is present, use only its exact prefilled action for a natural-language “刚才那个” request. Numbers, short IDs, and handles are human display/navigation aids, never tool arguments or authoritative native identity. The `new_thread` and `resume_thread` mutations require the fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. A binding conflict may advertise `reconcile_binding` only when one exact Session claim can be safely CAS-detached using its listed revision, binding token, and live terminal token; this never adopts the replacement thread, sends terminal input, or creates a Turn. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. A lifecycle result contains Session and native-thread identities but no `turn_id` because no work was sent.
+The top-level action contracts include `native_inspect`, `list_resumable_threads`, `new_thread`, `resume_thread`, and the conflict-only `reconcile_binding` recovery action. A supported idle Codex terminal may advertise `native_inspect` with its exact terminal ID, the closed `status` inspection kind, and a fresh binding token. The terminal row also advertises `list_resumable_threads` and, when currently safe, `new_thread`. Thread listing is read-only with respect to Session/Turn state, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` row retains its complete UUID and exact prefilled `resume_thread` action. If `previous` is present, use only its exact prefilled action for a natural-language “刚才那个” request. Numbers, short IDs, and handles are human display/navigation aids, never tool arguments or authoritative native identity. The `new_thread` and `resume_thread` mutations require the fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. A binding conflict may advertise `reconcile_binding` only when one exact Session claim can be safely CAS-detached using its listed revision, binding token, and live terminal token; this never adopts the replacement thread, sends terminal input, or creates a Turn. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. Native inspection and lifecycle results contain no `turn_id` because no work was sent.
 
 Workspace is not a routing boundary. AKK can list, inspect, and control verified panes across projects; when more than one target matches, use a selector to choose one explicitly.
 
@@ -339,10 +345,14 @@ is not currently required for publishing.
 ```bash
 npm run build
 npm run typecheck
-npm test
+npm run test:fast
 ```
 
-See [CONTRIBUTING.md](https://github.com/scotthuang/agent-knock-knock/blob/main/CONTRIBUTING.md) for the development and pull request workflow. For local OpenClaw testing, rebuild, run `node dist/src/cli.js install-openclaw`, and restart the Gateway.
+Use the fast tier for the inner loop, add the integration files mapped to the
+subsystem you changed, and run `npm test` once before opening a pull request.
+`npm test` remains the complete suite. See [Testing](docs/testing.md) for the
+tier manifest, targeted integration map, profiling command, and release gates,
+and [CONTRIBUTING.md](https://github.com/scotthuang/agent-knock-knock/blob/main/CONTRIBUTING.md) for the development and pull request workflow. For local OpenClaw testing, rebuild, run `node dist/src/cli.js install-openclaw`, and restart the Gateway.
 
 ### Maintainer Release
 

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 { 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);
     }
@@ -2782,6 +2785,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 +2805,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 +2829,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 +2864,16 @@ 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 &&
+                session.agent === "codex" &&
+                codexComposerEmpty(terminalState.screen_excerpt) &&
+                terminalControl.capabilities.includes("send_keys") &&
+                terminalControl.capabilities.includes("screen_status") &&
+                codexLifecycleIncarnationAvailable &&
+                orphanedDispatch === undefined &&
+                !nativeInspectionHasBlockingTurn
         }
     };
     const availableActions = availableListActions(entry);
@@ -2973,9 +2997,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 +3623,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 +3891,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 +3963,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 +4124,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 +6019,280 @@ 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 !== "codex") {
+        throw new Error("native status inspection currently supports only Codex 0.146.0 and 0.146.1");
+    }
+    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({ expectedTerminal, actualTerminal, expectedBindingToken, expectedVersion, actualSnapshot, stage }) {
+    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");
+    }
+}
+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");
+        }
+        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 assertCodexComposerReadyForAutomatedInput({
+            options,
+            terminalControl: terminal.terminalControl
+        });
+        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({
+                        expectedTerminal: terminal,
+                        actualTerminal: finalTerminal,
+                        expectedBindingToken,
+                        expectedVersion: snapshot.version,
+                        actualSnapshot: finalSnapshot,
+                        stage: "immediately before native status submission"
+                    });
+                    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;
+            let stableEvidenceFingerprint;
+            let stableObservation;
+            let stableCount = 0;
+            for (let attempt = 0; attempt < 50; attempt += 1) {
+                const observed = await bridge.observeNativeInspection(terminal.agent, terminal.terminalControl, {
+                    operation: plan.operation,
+                    previousScreenFingerprint: submission.preEnterScreenDigest,
+                    preEnterEvidenceInventory: submission.preEnterEvidenceInventory,
+                    expectedNativeThreadId,
+                    expectedAgentVersion: snapshot.version
+                }, { runtime, scrollbackLines: 240 });
+                const observation = observed.observation;
+                if (observed.status.reachable === true &&
+                    observed.status.activity_state === "idle" &&
+                    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 idle status result was not proven; do not retry automatically");
+            }
+            const finalTerminal = await resolveLifecycleTerminal(options);
+            const finalSnapshot = await currentLifecycleSnapshot(options, finalTerminal);
+            assertNativeInspectionSnapshotUnchanged({
+                expectedTerminal: terminal,
+                actualTerminal: finalTerminal,
+                expectedBindingToken,
+                expectedVersion: snapshot.version,
+                actualSnapshot: finalSnapshot,
+                stage: "after native status inspection"
+            });
+            const finalStatus = await bridge.status(finalTerminal.agent, finalTerminal.terminalControl, { runtime });
+            assertTerminalNativeInspectionReady({
+                options,
+                terminal: finalTerminal,
+                terminalStatus: finalStatus,
+                session: finalSnapshot.session
+            });
+            await assertCodexComposerReadyForAutomatedInput({
+                options,
+                terminalControl: finalTerminal.terminalControl
+            });
+            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
+                },
+                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 +10960,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) &&
@@ -19112,6 +19440,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>