@scotthuang/agent-knock-knock 0.12.37 → 0.13.0

package/dist/src/terminal-watch-cli-adapter.js

@@ -5,11 +5,17 @@ import { createTerminalWatchOpenClawCallbackRoute, parseCallbackRoute } from "./
 import { captureClaudeTranscriptAnchor, captureClaudeHumanStartedActiveTaskAnchor, observeClaudeUserExplicitFallbackTranscript, observeClaudeHumanStartedActiveTask } from "./claude-local-transcript-provider.js";
 import { claudeRuntimeCompatibilityWarning } from "./claude-lifecycle-compatibility.js";
 import { codexRuntimeCompatibilityProfile } from "./codex-lifecycle-compatibility.js";
-import { captureCodexCandidateSetRolloutAcceptanceAnchor, captureCodexRolloutAcceptanceAnchor, detectCodexBoundRolloutCompletion, detectCodexCandidateSetRolloutAcceptance, detectCodexRolloutAcceptance, captureCodexHumanStartedActiveTaskAnchor, observeCodexHumanStartedActiveTask } from "./terminal-submission-acceptance.js";
+import { captureTerminalInteractionRuntimeOffer, TerminalInteractionDispatchReservedError, TerminalInteractionInputNotStartedError } from "./terminal-agent-bridge.js";
+import { executorForConversation, turnIdForConversation } from "./protocol.js";
+import { rolloutFileIdentityMatches } from "./terminal-binding-authority.js";
+import { captureCodexCandidateSetRolloutAcceptanceAnchor, captureCodexRolloutAcceptanceAnchor, detectCodexBoundQuestionnaireAttribution, detectCodexBoundRolloutCompletion, detectCodexCandidateSetRolloutAcceptance, detectCodexRolloutAcceptance, captureCodexHumanStartedActiveTaskAnchor, observeCodexHumanStartedActiveTask } from "./terminal-submission-acceptance.js";
+import { createTerminalInteractionAggregate, hashTerminalInteractionResponse, reduceTerminalInteractionAggregate } from "./terminal-interaction-core.js";
+import { selectTerminalInteractionResponder } from "./terminal-interaction-authority.js";
+import { validateAnyTerminalInteractionProjection, validateTerminalInteractionSubjectResponse } from "./terminal-interaction-protocol.js";
 import { sameTerminalControlEvidenceIncarnation, terminalControlEvidence } from "./terminal-control-ref.js";
 import { createTerminalWatchCallbackCliAdapter, resolveTerminalWatchOpenClawCallback, resolveTerminalWatchOpenClawCallbackContext } from "./terminal-watch-callback-cli-adapter.js";
 import { createTerminalWatchService, terminalWatchObservationFence } from "./terminal-watch-service.js";
-import { createClaudeUserExplicitFallbackWatchAnchor, createCodexUserExplicitFallbackWatchAnchor, createTerminalActivityWatchAnchor, createTerminalWatchStore, isTerminalActivityWatch, isUserExplicitFallbackWatch, terminalUserExplicitFallbackWatchId } from "./terminal-watch-store.js";
+import { assertTerminalWatchManualInteractionSummary, createClaudeUserExplicitFallbackWatchAnchor, createCodexUserExplicitFallbackWatchAnchor, createTerminalActivityWatchAnchor, createTerminalWatchStore, isTerminalActivityWatch, isUserExplicitFallbackWatch, terminalWatchNotificationOnlyRoute, terminalWatchRevision, terminalUserExplicitFallbackWatchId } from "./terminal-watch-store.js";
 import { isRecord, nonBlankString as stringValue } from "./value-guards.js";
 const DEFAULT_TERMINAL_WATCH_HARD_TIMEOUT_MINUTES = 720;
 export function createTerminalWatchCliAdapter(dependencies) {
@@ -27,9 +33,11 @@ export function createTerminalWatchCliAdapter(dependencies) {
             observe: (watch) => observeTerminalWatch(watch, options, dependencies),
             resolveCallback: explicitRoute
                 ? (watch) => ({
-                    route: options.callbackRouteControllerScope === "route_bound_v1"
-                        ? routeBoundWatchCallbackRoute(explicitRoute, watch)
-                        : explicitRoute
+                    route: watch.interaction_policy === "notify_only"
+                        ? terminalWatchNotificationOnlyRoute(explicitRoute)
+                        : options.callbackRouteControllerScope === "route_bound_v1"
+                            ? routeBoundWatchCallbackRoute(explicitRoute, watch)
+                            : explicitRoute
                 })
                 : resolveTerminalWatchOpenClawCallback,
             resolveCallbackContext: explicitRoute
@@ -49,6 +57,18 @@ export function createTerminalWatchCliAdapter(dependencies) {
                         error_code: "terminal_watch_callback_agent_invalid"
                     };
                 }
+                const manualInteraction = metadata.manual_interaction;
+                if (manualInteraction !== undefined) {
+                    try {
+                        assertTerminalWatchManualInteractionSummary(manualInteraction);
+                    }
+                    catch {
+                        return {
+                            disposition: "permanent_failure",
+                            error_code: "terminal_watch_callback_interaction_invalid"
+                        };
+                    }
+                }
                 callback.deliver({
                     watchId: input.envelope.source.kind === "terminal_watch"
                         ? input.envelope.source.watch_id
@@ -72,6 +92,7 @@ export function createTerminalWatchCliAdapter(dependencies) {
                     detail: typeof metadata.reason_code === "string"
                         ? metadata.reason_code
                         : undefined,
+                    manualInteraction,
                     completionText: typeof metadata.completion_text === "string"
                         ? metadata.completion_text
                         : undefined
@@ -343,10 +364,8 @@ export function createTerminalWatchCliAdapter(dependencies) {
         const watch = service.cancel(requiredWatchId(options.watch));
         dependencies.printJson({ watch: publicTerminalWatch(watch) });
     }
-    function runWatchStatus(options) {
-        const watch = serviceFor(options).get(requiredWatchId(options.watch));
-        dependencies.printJson({ watch: publicTerminalWatch(watch) });
-    }
+    const runWatchStatus = createTerminalWatchStatusRunner(dependencies, serviceFor);
+    const runRespondInteraction = createTerminalWatchInteractionResponder(dependencies, serviceFor);
     async function runReconcileWatches(options) {
         dependencies.printJson(await serviceFor(options).reconcileAll());
     }
@@ -376,11 +395,254 @@ export function createTerminalWatchCliAdapter(dependencies) {
         runWatch,
         runUnwatch,
         runWatchStatus,
+        runRespondInteraction,
         runReconcileWatches,
         listPublicWatches,
         scanPublicWatchesForExactObservation
     });
 }
+function createTerminalWatchStatusRunner(dependencies, serviceFor) {
+    return async (options) => {
+        const service = serviceFor(options);
+        const watchId = requiredWatchId(options.watch);
+        const interactionAccess = watchStatusInteractionAccess(service.get(watchId), options);
+        const watch = await service.reconcile(watchId);
+        dependencies.printJson({
+            watch: publicTerminalWatch(watch, [], interactionAccess)
+        });
+    };
+}
+function createTerminalWatchInteractionResponder(dependencies, serviceFor) {
+    return async function runRespondInteraction(options) {
+        const watchId = requiredWatchId(options.watch);
+        const interactionId = requiredString(options.interaction, "--interaction is required");
+        const expectedFingerprint = requiredSha256(options.expectedInteractionFingerprint, "interaction prompt fingerprint");
+        const expectedExpiresAt = requiredTimestamp(options.expectedInteractionExpiresAt, "--expected-interaction-expires-at");
+        const responseValue = parseWatchInteractionResponse(options.responseJson);
+        const storeDir = dependencies.storeDirFromOptions(options);
+        const repository = createTerminalWatchStore(storeDir, {
+            acquire: dependencies.acquireFileLock
+        });
+        const service = serviceFor(options);
+        const displayed = await service.reconcile(watchId);
+        assertWatchControllerSession(displayed, options.openclawSession);
+        const displayedInteraction = requiredExecutableWatchInteraction(displayed, interactionId, expectedFingerprint);
+        const response = validateTerminalInteractionSubjectResponse(responseValue, displayedInteraction.projection, { now: dependencies.now(), allowExpiredForLiveRecapture: true });
+        if (response.subject.kind !== "terminal_watch" ||
+            response.subject.watch_id !== watchId) {
+            throw new Error("--response-json subject watch_id does not match --watch");
+        }
+        const exact = await exactTerminalForWatch(displayed.terminal.terminal_id, options, dependencies);
+        if (!terminalMatchesWatch(exact.rawTerminal, displayed)) {
+            throw new Error("terminal Watch identity changed before interaction response; refresh status");
+        }
+        const terminalControl = terminalControlForWatch(exact.rawTerminal);
+        const releaseTerminal = dependencies.acquireTerminalLock(storeDir, terminalControl);
+        try {
+            const withWriterLease = dependencies.withStoreWriterLeaseAsync ??
+                (async (_storeDir, operation) => operation());
+            await withWriterLease(storeDir, async () => {
+                let current = repository.load(watchId);
+                assertWatchControllerSession(current, options.openclawSession);
+                const executableInteraction = requiredExecutableWatchInteraction(current, interactionId, expectedFingerprint);
+                const decision = terminalWatchResponseDecision(current, exact.rawTerminal, executableInteraction.projection.surface_id, executableInteraction.projection.prompt_fingerprint, options, dependencies);
+                if (!decision.executable || decision.suppress) {
+                    throw new Error("a higher-priority terminal interaction responder owns this live questionnaire; refresh status");
+                }
+                const version = terminalWatchCapturedAgentVersion(current) ??
+                    requiredString(exact.rawTerminal.agent_version, "running coding-agent version");
+                const runtime = terminalInteractionRuntimeForWatch({
+                    watch: current,
+                    rawTerminal: exact.rawTerminal,
+                    checkpoint: current.observation_checkpoint,
+                    version,
+                    responseAuthority: "executable"
+                });
+                const bridge = dependencies.createBridge?.(options);
+                if (!bridge) {
+                    throw new Error("terminal interaction bridge is unavailable");
+                }
+                const attemptId = dependencies.randomUUID();
+                const responseHash = hashTerminalInteractionResponse(response);
+                let reserved = false;
+                let execution;
+                try {
+                    execution = await bridge.respondInteraction(current.agent, terminalControl, response, {
+                        agentVersion: version,
+                        expectedFingerprint,
+                        expectedExpiresAt,
+                        scrollbackLines: Number(options.scrollbackLines ?? 120),
+                        runtime,
+                        authorize: ({ projection, fingerprint }) => {
+                            const latest = repository.load(watchId);
+                            const interaction = requiredExecutableWatchInteraction(latest, interactionId, expectedFingerprint);
+                            const latestDecision = terminalWatchResponseDecision(latest, exact.rawTerminal, interaction.projection.surface_id, interaction.projection.prompt_fingerprint, options, dependencies);
+                            return projection.interaction_id === interactionId &&
+                                fingerprint === expectedFingerprint &&
+                                interaction.projection.subject.kind === "terminal_watch" &&
+                                projection.version === 2 &&
+                                projection.subject.kind === "terminal_watch" &&
+                                projection.subject.watch_id === watchId &&
+                                latestDecision.executable && !latestDecision.suppress
+                                ? { approved: true }
+                                : {
+                                    approved: false,
+                                    reason: "terminal Watch interaction authority changed before response"
+                                };
+                        },
+                        beforeDispatch: ({ projection, fingerprint }) => {
+                            if (reserved) {
+                                throw new Error("terminal Watch interaction response was already reserved");
+                            }
+                            current = repository.withWriterLease((scope) => scope.withWatchLock(watchId, () => {
+                                const latest = scope.load(watchId);
+                                const interaction = requiredExecutableWatchInteraction(latest, interactionId, expectedFingerprint);
+                                if (projection.interaction_id !== interactionId ||
+                                    fingerprint !== expectedFingerprint ||
+                                    interaction.aggregate.state !== "pending") {
+                                    throw new Error("terminal Watch interaction authority changed before dispatch");
+                                }
+                                const dispatchDecision = terminalWatchResponseDecision(latest, exact.rawTerminal, interaction.projection.surface_id, interaction.projection.prompt_fingerprint, options, dependencies);
+                                if (!dispatchDecision.executable ||
+                                    dispatchDecision.suppress) {
+                                    throw new TerminalInteractionInputNotStartedError("terminal Watch interaction ownership changed before dispatch");
+                                }
+                                const reservedAt = dependencies.now().toISOString();
+                                const aggregate = reduceTerminalInteractionAggregate(interaction.aggregate, {
+                                    type: "reserve",
+                                    attempt_id: attemptId,
+                                    response_hash: responseHash,
+                                    at: reservedAt
+                                });
+                                const saved = scope.save({
+                                    ...latest,
+                                    current_interaction: {
+                                        projection: interaction.projection,
+                                        aggregate
+                                    },
+                                    updated_at: reservedAt
+                                }, { expectedRevision: terminalWatchRevision(latest) });
+                                reserved = true;
+                                return saved;
+                            }));
+                        }
+                    });
+                }
+                catch (error) {
+                    if (reserved) {
+                        const state = error instanceof TerminalInteractionInputNotStartedError
+                            ? "release"
+                            : "response_uncertain";
+                        current = repository.withWriterLease((scope) => scope.withWatchLock(watchId, () => {
+                            const latest = scope.load(watchId);
+                            const interaction = latest.current_interaction;
+                            if (!interaction ||
+                                interaction.projection.interaction_id !== interactionId ||
+                                interaction.aggregate.state !== "reserved" ||
+                                interaction.aggregate.reservation?.attempt_id !== attemptId) {
+                                throw new Error("terminal Watch interaction reservation changed while settling failure");
+                            }
+                            const at = dependencies.now().toISOString();
+                            const aggregate = reduceTerminalInteractionAggregate(interaction.aggregate, state === "release"
+                                ? { type: "release" }
+                                : {
+                                    type: "response_uncertain",
+                                    at,
+                                    reason_code: "terminal_dispatch_uncertain"
+                                });
+                            const projection = state === "release"
+                                ? interaction.projection
+                                : {
+                                    ...interaction.projection,
+                                    state: "response_uncertain",
+                                    capabilities: {
+                                        ...interaction.projection.capabilities,
+                                        respond: false
+                                    }
+                                };
+                            return scope.save({
+                                ...latest,
+                                current_interaction: { projection, aggregate },
+                                updated_at: at
+                            }, { expectedRevision: terminalWatchRevision(latest) });
+                        }));
+                    }
+                    throw error;
+                }
+                if (!execution.responded) {
+                    dependencies.printJson({
+                        watch: publicTerminalWatch(current, [], true),
+                        interaction_id: interactionId,
+                        responded: false,
+                        blocked: execution.blocked,
+                        reason: execution.reason
+                    });
+                    return;
+                }
+                if (!reserved) {
+                    throw new TerminalInteractionDispatchReservedError("reservation_uncertain", "terminal Watch response was dispatched without a durable reservation");
+                }
+                current = repository.withWriterLease((scope) => scope.withWatchLock(watchId, () => {
+                    const latest = scope.load(watchId);
+                    const interaction = latest.current_interaction;
+                    if (!interaction ||
+                        interaction.projection.interaction_id !== interactionId ||
+                        interaction.aggregate.state !== "reserved" ||
+                        interaction.aggregate.reservation?.attempt_id !== attemptId) {
+                        throw new Error("terminal Watch interaction reservation changed after dispatch");
+                    }
+                    const answeredAt = dependencies.now().toISOString();
+                    const aggregate = reduceTerminalInteractionAggregate(interaction.aggregate, {
+                        type: "consume",
+                        at: answeredAt,
+                        reason_code: "terminal_response_dispatched"
+                    });
+                    return scope.save({
+                        ...latest,
+                        current_interaction: {
+                            projection: interaction.projection,
+                            aggregate
+                        },
+                        updated_at: answeredAt,
+                        last_activity_at: answeredAt,
+                        notification_outbox: latest.notification_outbox.map((notification) => notification.kind === "interaction_required" &&
+                            notification.evidence_fingerprint ===
+                                sha256({
+                                    schema: "agent-knock-knock/terminal-watch-interaction-event",
+                                    version: 1,
+                                    watch_id: watchId,
+                                    interaction_id: interactionId,
+                                    surface_id: interaction.projection.surface_id
+                                }) &&
+                            (notification.status === "pending" ||
+                                notification.status === "failed")
+                            ? {
+                                ...notification,
+                                status: "superseded",
+                                superseded_at: answeredAt,
+                                next_attempt_at: undefined,
+                                failed_at: undefined,
+                                last_error_code: undefined
+                            }
+                            : notification)
+                    }, { expectedRevision: terminalWatchRevision(latest) });
+                }));
+                dependencies.printJson({
+                    watch: publicTerminalWatch(current, [], true),
+                    interaction_id: interactionId,
+                    responded: true,
+                    blocked: false,
+                    question_id: execution.questionId,
+                    response_kind: execution.responseKind,
+                    outcome: execution.outcome
+                });
+            });
+        }
+        finally {
+            releaseTerminal();
+        }
+    };
+}
 function watchAnchorVersionWarnings(anchor, terminal) {
     const runningVersion = stringValue(terminal.agent_version);
     if (!runningVersion) {
@@ -413,7 +675,7 @@ function watchAnchorVersionWarnings(anchor, terminal) {
  */
 function routeBoundWatchCallbackRoute(template, watch) {
     return Object.freeze({
-        ...template,
+        ...parseCallbackRoute(template),
         controller_session_id: watch.openclaw_session
     });
 }
@@ -438,7 +700,8 @@ function callbackRouteForUserExplicitFallback(options) {
         return undefined;
     return createTerminalWatchOpenClawCallbackRoute({
         controllerSessionId,
-        openclawBin: options.openclawBin
+        openclawBin: options.openclawBin,
+        respond: true
     });
 }
 function assertSameUserExplicitFallbackTerminal(expected, observed) {
@@ -618,9 +881,12 @@ async function observeTerminalWatch(watch, options, dependencies) {
         return observeTerminalActivityWatch({
             watch,
             exactTerminal,
+            rawTerminal,
             projectedTerminal,
             terminalIdentityMatch: activityTerminalIdentity ?? "mismatch",
-            observedAt
+            observedAt,
+            options,
+            dependencies
         });
     }
     const observation = watch.anchor.schema ===
@@ -713,6 +979,18 @@ async function observeTerminalWatch(watch, options, dependencies) {
             reason_code: "terminal_waiting_for_approval"
         };
     }
+    const interaction = terminalWatchQuestionnaireObservation({
+        watch,
+        rawTerminal,
+        projectedTerminal,
+        terminalMatches: true,
+        observedAt,
+        observationCheckpoint,
+        options,
+        dependencies
+    });
+    if (interaction)
+        return interaction;
     return {
         ...fence,
         kind: "pending",
@@ -722,7 +1000,7 @@ async function observeTerminalWatch(watch, options, dependencies) {
     };
 }
 function observeTerminalActivityWatch(input) {
-    const { watch, exactTerminal, projectedTerminal, terminalIdentityMatch, observedAt } = input;
+    const { watch, exactTerminal, projectedTerminal, rawTerminal, terminalIdentityMatch, observedAt } = input;
     const fence = terminalWatchObservationFence(watch);
     if (exactTerminal.state === "unavailable") {
         return {
@@ -754,6 +1032,20 @@ function observeTerminalActivityWatch(input) {
             reason_code: "terminal_activity_unavailable"
         };
     }
+    if (rawTerminal) {
+        const interaction = terminalWatchQuestionnaireObservation({
+            watch,
+            rawTerminal,
+            projectedTerminal,
+            terminalMatches: true,
+            observedAt,
+            observationCheckpoint: terminalActivityObservationCheckpoint(watch),
+            options: input.options,
+            dependencies: input.dependencies
+        });
+        if (interaction)
+            return interaction;
+    }
     const state = terminalActivityState(projectedTerminal);
     const current = terminalActivityObservationCheckpoint(watch);
     const active = state === "working" || state === "awaiting_approval";
@@ -815,7 +1107,7 @@ function observeTerminalActivityWatch(input) {
     };
 }
 async function observeUserExplicitFallbackTerminalWatch(input) {
-    const { watch, exactTerminal, rawTerminal, terminalMatches, observedAt, options, dependencies } = input;
+    const { watch, exactTerminal, rawTerminal, projectedTerminal, terminalMatches, observedAt, options, dependencies } = input;
     const fence = terminalWatchObservationFence(watch);
     if (watch.anchor.schema ===
         "agent-knock-knock/codex-user-explicit-fallback-watch-anchor") {
@@ -943,6 +1235,19 @@ async function observeUserExplicitFallbackTerminalWatch(input) {
             }
             return invalidatedObservation(watch, observedAt, `native_completion_${completion.diagnostics.code}`);
         }
+        const interaction = fallbackQuestionnaireObservation({
+            watch,
+            exactTerminal,
+            rawTerminal,
+            projectedTerminal,
+            terminalMatches,
+            observedAt,
+            observationCheckpoint: codexFallbackAcceptedCheckpoint(watch, acceptance, currentIdentity),
+            options,
+            dependencies
+        });
+        if (interaction)
+            return interaction;
         return fallbackPendingOrTerminalObservation({
             watch,
             exactTerminal,
@@ -996,6 +1301,19 @@ async function observeUserExplicitFallbackTerminalWatch(input) {
     if (observation.status === "completed") {
         return fallbackCompletionObservation(watch, observedAt, observation.completion, observation.observedEndOffsetBytes, acceptedCheckpoint);
     }
+    const interaction = fallbackQuestionnaireObservation({
+        watch,
+        exactTerminal,
+        rawTerminal,
+        projectedTerminal,
+        terminalMatches,
+        observedAt,
+        observationCheckpoint: acceptedCheckpoint,
+        options,
+        dependencies
+    });
+    if (interaction)
+        return interaction;
     return fallbackPendingOrTerminalObservation({
         watch,
         exactTerminal,
@@ -1006,6 +1324,635 @@ async function observeUserExplicitFallbackTerminalWatch(input) {
         observationCheckpoint: acceptedCheckpoint
     });
 }
+function fallbackQuestionnaireObservation(input) {
+    if (input.exactTerminal.state !== "available" ||
+        !input.rawTerminal ||
+        !input.projectedTerminal ||
+        !input.terminalMatches) {
+        return undefined;
+    }
+    return terminalWatchQuestionnaireObservation({
+        ...input,
+        rawTerminal: input.rawTerminal,
+        projectedTerminal: input.projectedTerminal
+    }, true);
+}
+function terminalWatchQuestionnaireObservation(input, requireFallbackAttribution = false) {
+    if (!input.rawTerminal || !input.terminalMatches)
+        return undefined;
+    const rawTerminal = input.rawTerminal;
+    const screen = terminalWatchScreenExcerpt(rawTerminal, input.projectedTerminal);
+    const version = terminalWatchCapturedAgentVersion(input.watch) ??
+        stringValue(rawTerminal.agent_version);
+    if (!screen || !version)
+        return undefined;
+    const responseWatch = input.observationCheckpoint
+        ? {
+            ...input.watch,
+            observation_checkpoint: input.observationCheckpoint
+        }
+        : input.watch;
+    const captureOffer = (responseAuthority) => captureTerminalInteractionRuntimeOffer({
+        agent: input.watch.agent,
+        terminalControl: terminalControlForWatch(rawTerminal),
+        screen,
+        runtime: terminalInteractionRuntimeForWatch({
+            watch: responseWatch,
+            rawTerminal,
+            checkpoint: responseWatch.observation_checkpoint,
+            version,
+            responseAuthority
+        }),
+        now: new Date(input.observedAt),
+        approvalBlocked: Boolean(approvalFingerprint(input.projectedTerminal)),
+        trustedTerminalEvidence: input.watch.terminal.terminal_endpoint
+    });
+    let offer = captureOffer("notify_only");
+    if (!offer)
+        return undefined;
+    if (requireFallbackAttribution &&
+        !fallbackQuestionnaireContextMatches(input.watch, rawTerminal, input.observationCheckpoint ?? input.watch.observation_checkpoint, offer.nativeInspection)) {
+        return undefined;
+    }
+    const responseDecision = terminalWatchResponseDecision(responseWatch, rawTerminal, offer.surfaceId, offer.promptFingerprint, input.options, input.dependencies);
+    if (responseDecision.executable) {
+        const executableOffer = captureOffer("executable");
+        if (!executableOffer ||
+            executableOffer.surfaceId !== offer.surfaceId ||
+            executableOffer.projection.interaction_id !==
+                offer.projection.interaction_id) {
+            throw new Error("terminal Watch interaction surface changed during responder arbitration");
+        }
+        offer = executableOffer;
+    }
+    const currentInteraction = {
+        projection: offer.projection.version === 2 &&
+            offer.projection.subject.kind === "terminal_watch"
+            ? offer.projection
+            : (() => {
+                throw new Error("Watch interaction projection lost its Watch subject");
+            })(),
+        aggregate: createTerminalInteractionAggregate(offer.projection, input.observedAt)
+    };
+    const manualInteraction = terminalWatchManualInteractionSummary(offer.nativeInspection);
+    return {
+        ...terminalWatchObservationFence(input.watch),
+        kind: "interaction",
+        observed_at: input.observedAt,
+        last_activity_at: input.observedAt,
+        ...(input.observationCheckpoint
+            ? { observation_checkpoint: input.observationCheckpoint }
+            : {}),
+        evidence_fingerprint: sha256({
+            schema: "agent-knock-knock/terminal-watch-interaction-event",
+            version: 1,
+            watch_id: input.watch.watch_id,
+            interaction_id: offer.projection.interaction_id,
+            surface_id: offer.surfaceId
+        }),
+        reason_code: responseDecision.suppress
+            ? "terminal_questionnaire_managed_responder_precedence"
+            : currentInteraction.projection.capabilities.respond
+                ? "terminal_questionnaire_response_requested"
+                : "terminal_questionnaire_requires_manual_response",
+        current_interaction: currentInteraction,
+        ...(responseDecision.suppress
+            ? { suppress_notification: true }
+            : {}),
+        ...(!responseDecision.suppress &&
+            !currentInteraction.projection.capabilities.respond
+            ? { manual_interaction: manualInteraction }
+            : {})
+    };
+}
+/**
+ * Durable fallback completion remains bound to its accepted provider artifact
+ * even after the pane moves elsewhere. A live questionnaire is different: it
+ * may be attributed to a Watch only while that exact accepted native context
+ * is still the one rendered in the pane.
+ */
+function fallbackQuestionnaireContextMatches(watch, terminal, checkpoint, inspection) {
+    if (watch.anchor.schema !==
+        "agent-knock-knock/codex-user-explicit-fallback-watch-anchor") {
+        return true;
+    }
+    if (!("schema" in checkpoint) ||
+        checkpoint.schema !==
+            "agent-knock-knock/codex-user-explicit-fallback-watch-checkpoint" ||
+        !checkpoint.accepted_identity ||
+        !checkpoint.acceptance_evidence) {
+        return false;
+    }
+    const accepted = checkpoint.accepted_identity;
+    const exactLiveContext = stringValue(terminal.native_agent_session_id)?.toLowerCase() ===
+        accepted.native_thread_id &&
+        stringValue(terminal.native_agent_process_uuid) === accepted.process_uuid &&
+        stringValue(terminal.native_agent_process_birth) === accepted.process_birth &&
+        rolloutFileIdentityMatches(terminal.native_agent_rollout, accepted.rollout);
+    if (exactLiveContext)
+        return true;
+    const inventory = terminal._codex_open_root_rollout_inventory;
+    if (!isRecord(inventory))
+        return false;
+    const attribution = detectCodexBoundQuestionnaireAttribution({
+        currentInventory: inventory,
+        acceptedIdentity: {
+            sessionId: accepted.native_thread_id,
+            processUuid: accepted.process_uuid,
+            processBirth: accepted.process_birth,
+            rollout: accepted.rollout
+        },
+        acceptanceId: checkpoint.acceptance_evidence.acceptanceId,
+        screen: {
+            currentStep: inspection.current_step,
+            totalSteps: inspection.total_steps,
+            prompt: inspection.question.prompt,
+            responseKind: inspection.question.response_kind,
+            ...(inspection.question.options
+                ? {
+                    options: inspection.question.options.map((option) => ({
+                        label: option.label,
+                        ...(option.description
+                            ? { description: option.description }
+                            : {})
+                    }))
+                }
+                : {}),
+            exactShape: inspection.status === "actionable" &&
+                inspection.question.response_kind !== "multi_select"
+        }
+    });
+    return attribution.status === "matched";
+}
+function terminalWatchResponseDecision(watch, rawTerminal, surfaceId, promptFingerprint, options, dependencies) {
+    if (watch.status !== "active" ||
+        watch.interaction_policy !== "respond_when_exact" ||
+        isTerminalActivityWatch(watch) ||
+        !terminalWatchCandidateMatchesLiveContext(watch, rawTerminal) ||
+        (watch.callback_route !== undefined &&
+            watch.callback_route.capabilities?.respond !== true)) {
+        return { executable: false, suppress: false };
+    }
+    const terminalControl = terminalControlForWatch(rawTerminal);
+    let blockers;
+    try {
+        blockers = dependencies.terminalIncarnationBlockingTurns(dependencies.storeDirFromOptions(options), terminalControl);
+    }
+    catch {
+        return { executable: false, suppress: false };
+    }
+    let storedWatches;
+    try {
+        storedWatches = createTerminalWatchStore(dependencies.storeDirFromOptions(options), { acquire: dependencies.acquireFileLock }).list();
+    }
+    catch {
+        return { executable: false, suppress: false };
+    }
+    const currentIndex = storedWatches.findIndex((candidate) => candidate.watch_id === watch.watch_id);
+    if (currentIndex < 0) {
+        storedWatches.push(watch);
+    }
+    else {
+        storedWatches[currentIndex] = watch;
+    }
+    const candidates = storedWatches.flatMap((candidate) => {
+        const surfaceCandidate = terminalWatchSurfaceCandidate(candidate, watch, rawTerminal, surfaceId, promptFingerprint);
+        return surfaceCandidate ? [surfaceCandidate] : [];
+    });
+    const fences = [
+        ...blockers.flatMap((turn) => {
+            const fence = managedTerminalInteractionFence(turn, surfaceId, promptFingerprint, watch.agent);
+            return fence ? [fence] : [];
+        }),
+        ...candidates
+            .filter((candidate) => candidate.disposition === "fence")
+            .map((candidate) => ({
+            owner_session: candidate.watch.openclaw_session
+        }))
+    ];
+    if (fences.length > 0) {
+        return {
+            executable: false,
+            suppress: fences.some((fence) => fence.owner_session === watch.openclaw_session)
+        };
+    }
+    const claims = [
+        ...blockers.flatMap((turn) => {
+            const claim = managedTerminalInteractionResponderClaim(turn, surfaceId, promptFingerprint, watch.agent);
+            return claim ? [claim] : [];
+        }),
+        ...candidates
+            .filter((candidate) => candidate.disposition === "responder")
+            .map(({ watch: candidate }) => ({
+            owner_id: candidate.watch_id,
+            owner_session: candidate.openclaw_session,
+            surface_id: surfaceId,
+            responder_class: isUserExplicitFallbackWatch(candidate)
+                ? "exact_request_watch"
+                : "exact_task_watch",
+            response_authority: "executable",
+            created_at: candidate.created_at
+        }))
+    ];
+    const winner = selectTerminalInteractionResponder(claims);
+    const executable = winner?.owner_id === watch.watch_id;
+    return {
+        executable,
+        suppress: Boolean(winner &&
+            !executable &&
+            winner.owner_session === watch.openclaw_session)
+    };
+}
+function terminalWatchSurfaceCandidate(candidate, current, rawTerminal, surfaceId, promptFingerprint) {
+    if (candidate.status !== "active" ||
+        candidate.interaction_policy !== "respond_when_exact" ||
+        isTerminalActivityWatch(candidate) ||
+        candidate.terminal.terminal_id !== current.terminal.terminal_id ||
+        !terminalWatchCandidateMatchesLiveContext(candidate, rawTerminal) ||
+        (candidate.callback_route !== undefined &&
+            candidate.callback_route.capabilities?.respond !== true)) {
+        return undefined;
+    }
+    const persisted = candidate.current_interaction;
+    const samePersistedSurface = Boolean(persisted &&
+        persisted.projection.surface_id === surfaceId &&
+        persisted.projection.prompt_fingerprint === promptFingerprint);
+    if (candidate.watch_id !== current.watch_id) {
+        if (!samePersistedSurface ||
+            !terminalWatchesShareExactTask(candidate, current) ||
+            (persisted.aggregate.state === "pending" &&
+                (persisted.projection.response_authority !== "executable" ||
+                    persisted.projection.capabilities.respond !== true ||
+                    persisted.aggregate.response_authority !== "executable"))) {
+            return undefined;
+        }
+    }
+    return {
+        watch: candidate,
+        disposition: samePersistedSurface && persisted.aggregate.state !== "pending"
+            ? "fence"
+            : "responder"
+    };
+}
+function terminalWatchesShareExactTask(left, right) {
+    const leftKey = terminalWatchExactTaskKey(left);
+    const rightKey = terminalWatchExactTaskKey(right);
+    return leftKey !== undefined && leftKey === rightKey;
+}
+function terminalWatchExactTaskKey(watch) {
+    const anchor = watch.anchor;
+    if (anchor.schema ===
+        "agent-knock-knock/codex-human-started-active-task-anchor") {
+        return codexWatchTaskKey({
+            taskId: anchor.turn_id,
+            nativeSessionId: anchor.native_thread_id,
+            processUuid: anchor.process_uuid,
+            processBirth: anchor.process_birth,
+            rollout: anchor.rollout,
+            requestHash: anchor.request_hash
+        });
+    }
+    if (anchor.schema ===
+        "agent-knock-knock/codex-user-explicit-fallback-watch-anchor") {
+        const checkpoint = watch.observation_checkpoint;
+        if (!("schema" in checkpoint) ||
+            checkpoint.schema !==
+                "agent-knock-knock/codex-user-explicit-fallback-watch-checkpoint" ||
+            !checkpoint.accepted_identity ||
+            !checkpoint.acceptance_evidence)
+            return undefined;
+        return codexWatchTaskKey({
+            taskId: checkpoint.acceptance_evidence.acceptanceId,
+            nativeSessionId: checkpoint.accepted_identity.native_thread_id,
+            processUuid: checkpoint.accepted_identity.process_uuid,
+            processBirth: checkpoint.accepted_identity.process_birth,
+            rollout: checkpoint.accepted_identity.rollout,
+            requestHash: anchor.request_hash
+        });
+    }
+    if (anchor.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor") {
+        return claudeWatchTaskKey({
+            taskId: anchor.prompt_uuid,
+            nativeSessionId: anchor.session_id,
+            pid: anchor.pid,
+            agentStartedAtMs: anchor.agent_started_at_ms,
+            transcriptFileId: anchor.transcript_file_id,
+            cwd: anchor.cwd,
+            requestHash: anchor.request_hash
+        });
+    }
+    if (anchor.schema ===
+        "agent-knock-knock/claude-user-explicit-fallback-watch-anchor") {
+        const checkpoint = watch.observation_checkpoint;
+        if (!("schema" in checkpoint) ||
+            checkpoint.schema !==
+                "agent-knock-knock/claude-user-explicit-fallback-watch-checkpoint" ||
+            !checkpoint.accepted_prompt_uuid ||
+            !checkpoint.acceptance_evidence)
+            return undefined;
+        const transcriptFileId = stringValue(checkpoint.acceptance_evidence.metadata?.transcript_file_id);
+        if (!transcriptFileId)
+            return undefined;
+        return claudeWatchTaskKey({
+            taskId: checkpoint.accepted_prompt_uuid,
+            nativeSessionId: anchor.transcript_anchor.session_id,
+            pid: anchor.transcript_anchor.pid,
+            agentStartedAtMs: anchor.transcript_anchor.agent_started_at_ms,
+            transcriptFileId,
+            cwd: anchor.transcript_anchor.cwd,
+            requestHash: anchor.request_hash
+        });
+    }
+    return undefined;
+}
+function codexWatchTaskKey(input) {
+    const rollout = isRecord(input.rollout) ? input.rollout : undefined;
+    const device = stringValue(rollout?.device);
+    const inode = stringValue(rollout?.inode);
+    const rolloutPath = stringValue(rollout?.path);
+    if (!device || !inode || !rolloutPath)
+        return undefined;
+    return sha256({
+        agent: "codex",
+        task_id: input.taskId,
+        native_session_id: input.nativeSessionId.toLowerCase(),
+        process_uuid: input.processUuid,
+        process_birth: input.processBirth,
+        rollout: { device, inode, path: rolloutPath },
+        request_hash: input.requestHash
+    });
+}
+function claudeWatchTaskKey(input) {
+    if (!Number.isSafeInteger(input.pid) || input.pid <= 0 ||
+        !Number.isSafeInteger(input.agentStartedAtMs) ||
+        input.agentStartedAtMs <= 0)
+        return undefined;
+    return sha256({
+        agent: "claude",
+        task_id: input.taskId,
+        native_session_id: input.nativeSessionId,
+        pid: input.pid,
+        agent_started_at_ms: input.agentStartedAtMs,
+        transcript_file_id: input.transcriptFileId,
+        cwd: input.cwd,
+        request_hash: input.requestHash
+    });
+}
+function managedTerminalInteractionFence(turn, surfaceId, promptFingerprint, agent) {
+    const ownerSession = stringValue(turn.openclaw_session);
+    const takeover = isRecord(turn.native_session_takeover)
+        ? turn.native_session_takeover
+        : undefined;
+    if (ownerSession &&
+        executorForConversation(turn).kind === agent &&
+        stringValue(takeover?.terminal_bridge_last_interaction_surface_id) ===
+            surfaceId &&
+        stringValue(takeover?.terminal_bridge_last_interaction_fingerprint) ===
+            promptFingerprint &&
+        stringValue(takeover?.terminal_bridge_last_interaction_id) !== undefined &&
+        canonicalTimestamp(takeover?.terminal_bridge_last_interaction_at) !== undefined) {
+        return { owner_session: ownerSession };
+    }
+    const evidence = managedTerminalInteractionEvidence(turn, surfaceId, promptFingerprint, agent);
+    if (!evidence)
+        return undefined;
+    const dispatch = isRecord(evidence.takeover.terminal_bridge_interaction_dispatch)
+        ? evidence.takeover.terminal_bridge_interaction_dispatch
+        : undefined;
+    const dispatchState = stringValue(dispatch?.state);
+    const dispatchMatches = (dispatchState === "reserved" || dispatchState === "uncertain") &&
+        stringValue(dispatch?.interaction_id) ===
+            evidence.projection.interaction_id &&
+        stringValue(dispatch?.interaction_prompt_fingerprint) ===
+            promptFingerprint;
+    return evidence.projection.state === "response_uncertain" || dispatchMatches
+        ? { owner_session: evidence.ownerSession }
+        : undefined;
+}
+function canonicalTimestamp(value) {
+    const timestamp = stringValue(value);
+    return timestamp &&
+        Number.isFinite(Date.parse(timestamp)) &&
+        new Date(timestamp).toISOString() === timestamp
+        ? timestamp
+        : undefined;
+}
+function managedTerminalInteractionResponderClaim(turn, surfaceId, promptFingerprint, agent) {
+    const evidence = managedTerminalInteractionEvidence(turn, surfaceId, promptFingerprint, agent);
+    if (!evidence)
+        return undefined;
+    const createdAt = stringValue(evidence.notification.notified_at);
+    if (!createdAt ||
+        !Number.isFinite(Date.parse(createdAt)) ||
+        new Date(createdAt).toISOString() !== createdAt)
+        return undefined;
+    if (evidence.projection.state !== "pending" ||
+        evidence.projection.capabilities.respond !== true) {
+        return undefined;
+    }
+    return {
+        owner_id: evidence.ownerId,
+        owner_session: evidence.ownerSession,
+        surface_id: surfaceId,
+        responder_class: "managed_turn",
+        response_authority: "executable",
+        created_at: createdAt
+    };
+}
+function managedTerminalInteractionEvidence(turn, surfaceId, promptFingerprint, agent) {
+    const takeover = isRecord(turn.native_session_takeover)
+        ? turn.native_session_takeover
+        : undefined;
+    const notification = isRecord(takeover?.terminal_bridge_interaction_notification)
+        ? takeover.terminal_bridge_interaction_notification
+        : undefined;
+    if (!takeover ||
+        !notification ||
+        stringValue(notification.surface_id) !== surfaceId ||
+        stringValue(notification.prompt_fingerprint) !== promptFingerprint)
+        return undefined;
+    let ownerId;
+    try {
+        ownerId = turnIdForConversation(turn);
+    }
+    catch {
+        return undefined;
+    }
+    const ownerSession = stringValue(turn.openclaw_session);
+    if (!ownerSession)
+        return undefined;
+    const projection = (() => {
+        try {
+            return validateAnyTerminalInteractionProjection(notification.interaction_state);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (!projection ||
+        projection.interaction_id !== stringValue(notification.interaction_id) ||
+        projection.agent !== agent ||
+        projection.questions.length !== 1 ||
+        projection.questions[0]?.question_id !==
+            stringValue(notification.question_id) ||
+        (projection.version === 1
+            ? projection.turn_id !== ownerId
+            : projection.subject.kind !== "managed_turn" ||
+                projection.subject.turn_id !== ownerId))
+        return undefined;
+    return { ownerId, ownerSession, takeover, notification, projection };
+}
+function terminalWatchCandidateMatchesLiveContext(watch, terminal) {
+    if (!terminalMatchesWatch(terminal, watch))
+        return false;
+    const sessionId = stringValue(terminal.native_agent_session_id);
+    if (watch.anchor.schema ===
+        "agent-knock-knock/codex-human-started-active-task-anchor") {
+        return sessionId?.toLowerCase() === watch.anchor.native_thread_id &&
+            rolloutFileIdentityMatches(terminal.native_agent_rollout, watch.anchor.rollout);
+    }
+    if (watch.anchor.schema ===
+        "agent-knock-knock/codex-user-explicit-fallback-watch-anchor") {
+        const checkpoint = watch.observation_checkpoint;
+        return "schema" in checkpoint &&
+            checkpoint.schema ===
+                "agent-knock-knock/codex-user-explicit-fallback-watch-checkpoint" &&
+            checkpoint.accepted_identity !== undefined &&
+            sessionId?.toLowerCase() === checkpoint.accepted_identity.native_thread_id &&
+            rolloutFileIdentityMatches(terminal.native_agent_rollout, checkpoint.accepted_identity.rollout);
+    }
+    if (watch.anchor.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor") {
+        return sessionId === watch.anchor.session_id;
+    }
+    if (watch.anchor.schema ===
+        "agent-knock-knock/claude-user-explicit-fallback-watch-anchor") {
+        return sessionId === watch.anchor.transcript_anchor.session_id;
+    }
+    return false;
+}
+function terminalInteractionRuntimeForWatch(input) {
+    const { watch, rawTerminal, checkpoint } = input;
+    let nativeSessionId = stringValue(rawTerminal.native_agent_session_id);
+    let nativeProcessUuid = stringValue(rawTerminal.native_agent_process_uuid);
+    let nativeProcessBirth = stringValue(rawTerminal.native_agent_process_birth);
+    let nativeRollout = isRecord(rawTerminal.native_agent_rollout)
+        ? rawTerminal.native_agent_rollout
+        : undefined;
+    if (watch.anchor.schema ===
+        "agent-knock-knock/codex-human-started-active-task-anchor") {
+        nativeSessionId = watch.anchor.native_thread_id;
+        nativeProcessUuid = watch.anchor.process_uuid;
+        nativeProcessBirth = watch.anchor.process_birth;
+        nativeRollout = watch.anchor.rollout;
+    }
+    else if (watch.anchor.schema ===
+        "agent-knock-knock/codex-user-explicit-fallback-watch-anchor" &&
+        "schema" in checkpoint &&
+        checkpoint.schema ===
+            "agent-knock-knock/codex-user-explicit-fallback-watch-checkpoint" &&
+        checkpoint.accepted_identity) {
+        nativeSessionId = checkpoint.accepted_identity.native_thread_id;
+        nativeProcessUuid = checkpoint.accepted_identity.process_uuid;
+        nativeProcessBirth = checkpoint.accepted_identity.process_birth;
+        nativeRollout = checkpoint.accepted_identity.rollout;
+    }
+    else if (watch.anchor.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor") {
+        nativeSessionId = watch.anchor.session_id;
+    }
+    else if (watch.anchor.schema ===
+        "agent-knock-knock/claude-user-explicit-fallback-watch-anchor") {
+        nativeSessionId = watch.anchor.transcript_anchor.session_id;
+    }
+    const inventory = isRecord(rawTerminal._codex_open_root_rollout_inventory)
+        ? rawTerminal._codex_open_root_rollout_inventory
+        : undefined;
+    const allowedAdditionalNativeIdentities = inventory && nativeRollout
+        ? inventory.roots.filter((root) => !rolloutFileIdentityMatches(root.rollout, nativeRollout))
+            .map((root) => ({
+            sessionId: root.sessionId,
+            processUuid: root.processUuid,
+            processBirth: root.processBirth,
+            rollout: root.rollout
+        }))
+        : [];
+    const startedAt = Number(rawTerminal.native_agent_process_started_at);
+    return {
+        pid: positiveInteger(rawTerminal.pid, "terminal agent PID"),
+        agentVersion: input.version,
+        interactionSubject: {
+            kind: "terminal_watch",
+            watch_id: watch.watch_id,
+            anchor_fingerprint: watch.anchor.anchor_fingerprint
+        },
+        interactionResponseAuthority: input.responseAuthority,
+        nativeSessionId,
+        nativeProcessUuid,
+        nativeProcessBirth,
+        nativeRollout,
+        requireNativeProcessUuid: watch.agent === "claude" &&
+            !isTerminalActivityWatch(watch),
+        requireNativeRolloutIdentity: watch.agent === "codex" &&
+            !isTerminalActivityWatch(watch),
+        allowedAdditionalNativeIdentities,
+        ...(Number.isSafeInteger(startedAt) && startedAt > 0
+            ? { nativeProcessStartedAt: startedAt }
+            : {}),
+        cwd: watch.terminal.workspace,
+        conversationId: watch.terminal.terminal_id,
+        terminalTarget: terminalControlForWatch(rawTerminal).target
+    };
+}
+function terminalWatchScreenExcerpt(rawTerminal, projectedTerminal) {
+    const direct = stringValue(projectedTerminal.screen_excerpt) ??
+        stringValue(rawTerminal.screen_excerpt);
+    if (direct)
+        return direct;
+    const status = isRecord(rawTerminal._terminal_status_snapshot)
+        ? rawTerminal._terminal_status_snapshot
+        : undefined;
+    const screen = status && isRecord(status.screen) ? status.screen : undefined;
+    return stringValue(screen?.excerpt);
+}
+function terminalWatchManualInteractionSummary(inspection) {
+    const exposeQuestion = inspection.status === "actionable";
+    return {
+        kind: "questionnaire",
+        response_kind: inspection.question.response_kind,
+        required: inspection.question.required,
+        current_step: inspection.current_step,
+        total_steps: inspection.total_steps,
+        parser_status: inspection.status,
+        ...(exposeQuestion
+            ? {
+                prompt: boundedInteractionText(inspection.question.prompt, 1_000),
+                ...(inspection.question.options &&
+                    inspection.question.options.length > 0
+                    ? {
+                        options: inspection.question.options.slice(0, 8).map((option) => ({
+                            label: boundedInteractionText(option.label, 300),
+                            ...(option.description
+                                ? {
+                                    description: boundedInteractionText(option.description, 600)
+                                }
+                                : {})
+                        }))
+                    }
+                    : {})
+            }
+            : { manual_reason: inspection.reason })
+    };
+}
+function boundedInteractionText(value, maxCharacters) {
+    const normalized = value
+        .replace(/[\u0000-\u001F\u007F-\u009F]+/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim()
+        .slice(0, maxCharacters);
+    return normalized || "Native questionnaire";
+}
 function fallbackPendingOrTerminalObservation(input) {
     if (input.exactTerminal.state === "unavailable") {
         return {
@@ -1282,7 +2229,7 @@ function codexIdentityForWatch(watch) {
         rollout: watch.anchor.rollout
     };
 }
-function publicTerminalWatch(watch, additionalWarnings = []) {
+function publicTerminalWatch(watch, additionalWarnings = [], exposeInteraction = false) {
     const pending = watch.notification_outbox.filter(({ status }) => status === "pending" || status === "delivering" || status === "failed").length;
     const capturedAgentVersion = terminalWatchCapturedAgentVersion(watch);
     const compatibilityWarning = capturedAgentVersion === undefined
@@ -1300,6 +2247,22 @@ function publicTerminalWatch(watch, additionalWarnings = []) {
     const latestFailedCallback = [...watch.notification_outbox]
         .reverse()
         .find(({ status }) => status === "failed");
+    const currentInteraction = exposeInteraction && watch.status === "active" &&
+        watch.current_interaction &&
+        ["pending", "reserved", "response_uncertain"].includes(watch.current_interaction.aggregate.state)
+        ? watch.current_interaction
+        : undefined;
+    const interactionProjection = currentInteraction?.aggregate.state ===
+        "reserved"
+        ? {
+            ...currentInteraction.projection,
+            state: "response_uncertain",
+            capabilities: {
+                ...currentInteraction.projection.capabilities,
+                respond: false
+            }
+        }
+        : currentInteraction?.projection;
     return {
         watch_id: watch.watch_id,
         source: userExplicitFallback
@@ -1309,6 +2272,12 @@ function publicTerminalWatch(watch, additionalWarnings = []) {
                 : "user_selected_terminal_watch",
         watch_mode: terminalActivityFallback ? "terminal_activity" : "exact_task",
         confidence: terminalActivityFallback ? "best_effort" : "exact",
+        interaction_policy: watch.interaction_policy,
+        capabilities: {
+            interaction_notify: true,
+            interaction_respond: Boolean(interactionProjection?.state === "pending" &&
+                interactionProjection.capabilities.respond)
+        },
         agent: watch.agent,
         terminal_id: watch.terminal.terminal_id,
         native_thread_id: terminalWatchNativeThreadId(watch),
@@ -1334,6 +2303,12 @@ function publicTerminalWatch(watch, additionalWarnings = []) {
                 ? { last_error_code: latestFailedCallback.last_error_code }
                 : {})
         },
+        ...(interactionProjection
+            ? {
+                interaction_state: interactionProjection,
+                interaction_prompt_fingerprint: interactionProjection.prompt_fingerprint
+            }
+            : {}),
         ...(watch.settlement
             ? {
                 settlement: {
@@ -1359,10 +2334,29 @@ function publicTerminalWatch(watch, additionalWarnings = []) {
                         requires_user_intent: true
                     }
                 }
+                : {}),
+            ...(interactionProjection?.state === "pending" &&
+                interactionProjection.capabilities.respond
+                ? {
+                    respond_interaction: {
+                        tool: "agent_knock_knock_respond_interaction",
+                        arguments: { watch_id: watch.watch_id },
+                        requires_user_intent: true
+                    }
+                }
                 : {})
         }
     };
 }
+function watchStatusInteractionAccess(watch, options) {
+    if (!Object.hasOwn(options, "openclawSession"))
+        return false;
+    const requested = stringValue(options.openclawSession);
+    if (!requested || requested !== watch.openclaw_session) {
+        throw new Error(`terminal Watch ${watch.watch_id} belongs to a different controller session; executable interaction details were not disclosed`);
+    }
+    return true;
+}
 function terminalWatchCapturedAgentVersion(watch) {
     switch (watch.anchor.schema) {
         case "agent-knock-knock/codex-human-started-active-task-anchor":
@@ -1450,6 +2444,48 @@ function requiredSha256(value, label) {
     }
     return result;
 }
+function requiredTimestamp(value, label) {
+    const result = requiredString(value, label);
+    if (!Number.isFinite(Date.parse(result))) {
+        throw new Error(`${label} must be a valid timestamp`);
+    }
+    return result;
+}
+function parseWatchInteractionResponse(value) {
+    const serialized = requiredString(value, "--response-json");
+    try {
+        const parsed = JSON.parse(serialized);
+        if (!isRecord(parsed)) {
+            throw new Error("response must be an object");
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`--response-json is invalid: ${safeDiagnostic(error)}`);
+    }
+}
+function assertWatchControllerSession(watch, requestedValue) {
+    const requested = stringValue(requestedValue);
+    if (!requested || requested !== watch.openclaw_session) {
+        throw new Error(`terminal Watch ${watch.watch_id} belongs to a different controller session; no terminal input was sent`);
+    }
+}
+function requiredExecutableWatchInteraction(watch, interactionId, expectedFingerprint) {
+    if (watch.status !== "active") {
+        throw new Error(`terminal Watch ${watch.watch_id} is ${watch.status}`);
+    }
+    const interaction = watch.current_interaction;
+    if (watch.interaction_policy !== "respond_when_exact" ||
+        !interaction ||
+        interaction.aggregate.state !== "pending" ||
+        interaction.projection.interaction_id !== interactionId ||
+        interaction.projection.prompt_fingerprint !== expectedFingerprint ||
+        interaction.projection.response_authority !== "executable" ||
+        !interaction.projection.capabilities.respond) {
+        throw new Error("terminal Watch has no matching executable interaction offer; refresh status");
+    }
+    return interaction;
+}
 function positiveInteger(value, label) {
     const result = Number(value);
     if (!Number.isSafeInteger(result) || result <= 0) {