@scotthuang/agent-knock-knock 0.12.19 → 0.12.21

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

@@ -1,18 +1,15 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
-import { callbackRouteForConversation } from "./callback-route-authority.js";
+import { callbackRouteFingerprint, callbackRouteForConversation } from "./callback-route-authority.js";
 import { parseCallbackRoute } from "./callback-transport.js";
 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 { turnIdForConversation } from "./protocol.js";
-import { decideTerminalWatchExternalTaskAuthority } from "./terminal-action-projection.js";
-import { exactTerminalWatchAction } from "./terminal-list-renderer.js";
 import { captureCodexCandidateSetRolloutAcceptanceAnchor, captureCodexRolloutAcceptanceAnchor, detectCodexBoundRolloutCompletion, detectCodexCandidateSetRolloutAcceptance, detectCodexRolloutAcceptance, captureCodexHumanStartedActiveTaskAnchor, observeCodexHumanStartedActiveTask } from "./terminal-submission-acceptance.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, createTerminalWatchStore, isUserExplicitFallbackWatch, terminalUserExplicitFallbackWatchId, terminalWatchIdentityFingerprint } from "./terminal-watch-store.js";
+import { createClaudeUserExplicitFallbackWatchAnchor, createCodexUserExplicitFallbackWatchAnchor, createTerminalActivityWatchAnchor, createTerminalWatchStore, isTerminalActivityWatch, isUserExplicitFallbackWatch, 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) {
@@ -67,6 +64,11 @@ export function createTerminalWatchCliAdapter(dependencies) {
                         "string"
                         ? input.context.legacyOptions.openclawBin
                         : undefined,
+                    origin: metadata.watch_origin === "user_selected_terminal" ||
+                        metadata.watch_origin === "terminal_activity_fallback" ||
+                        metadata.watch_origin === "terminal_user_explicit_fallback"
+                        ? metadata.watch_origin
+                        : undefined,
                     detail: typeof metadata.reason_code === "string"
                         ? metadata.reason_code
                         : undefined,
@@ -245,57 +247,96 @@ export function createTerminalWatchCliAdapter(dependencies) {
             : undefined;
         const openclawSession = callbackRoute?.controller_session_id ??
             requiredString(options.openclawSession, "--openclaw-session");
-        const storeDir = dependencies.storeDirFromOptions(options);
-        const initiallyObserved = await exactTerminalForWatch(terminalId, options, dependencies);
-        const initiallyObservedBindingToken = bindingTokenForWatch(initiallyObserved.rawTerminal);
-        const initialTerminalControl = terminalControlForWatch(initiallyObserved.rawTerminal);
-        const releaseTerminal = dependencies.acquireTerminalLock(storeDir, initialTerminalControl);
-        let watch;
+        const observed = await exactTerminalForWatch(terminalId, options, dependencies);
+        const rawTerminal = observed.rawTerminal;
+        const projectedTerminal = observed.terminal;
+        // Endpoint evidence is the only indispensable observation authority. A
+        // manual Watch is read-only and therefore does not acquire terminal input
+        // authority or depend on managed-Turn ownership.
+        const terminalControl = terminalControlForWatch(rawTerminal);
+        const agent = terminalAgent(rawTerminal);
+        const warnings = [];
+        let anchor;
         try {
-            const observed = await exactTerminalForWatch(terminalId, options, dependencies);
-            const rawTerminal = observed.rawTerminal;
-            const projectedTerminal = observed.terminal;
-            const expectedBindingToken = bindingTokenForWatch(rawTerminal);
-            const terminalControl = terminalControlForWatch(rawTerminal);
-            if (!sameTerminalControlEvidenceIncarnation(initialTerminalControl, terminalControl) || expectedBindingToken !== initiallyObservedBindingToken) {
-                throw new Error("terminal binding changed while AKK acquired authority; refresh " +
-                    "AKK list and retry");
-            }
-            assertExternalTerminalWatchAuthority(storeDir, terminalControl, dependencies);
-            const watchService = serviceFor(options);
-            const existing = watchService.list().find((candidate) => candidate.status === "active" &&
-                candidate.terminal.terminal_id === terminalId);
-            if (existing) {
-                throw new Error(`terminal ${terminalId} is already monitored by Terminal Watch ` +
-                    `${existing.watch_id}; use watch-status instead of creating another`);
+            anchor = captureTerminalWatchAnchor(agent, rawTerminal, options, dependencies);
+        }
+        catch (error) {
+            warnings.push(`exact_task_anchor_unavailable: ${safeDiagnostic(error)}`);
+        }
+        if (anchor) {
+            warnings.push(...watchAnchorVersionWarnings(anchor, rawTerminal));
+        }
+        else {
+            if (!terminalControl.capabilities.includes("screen_status")) {
+                throw new Error("the exact terminal has neither a durable task anchor nor a " +
+                    "read-only screen-status observation path; no effective Watch " +
+                    "can be created");
             }
-            assertExactPublicWatchAction(projectedTerminal, terminalId);
-            const agent = terminalAgent(rawTerminal);
-            const anchor = captureTerminalWatchAnchor(agent, rawTerminal, options, dependencies);
-            if (!anchor) {
-                throw new Error("the exact terminal has no unique supported human-started active task");
+            if (warnings.length === 0) {
+                warnings.push("exact_task_anchor_unavailable: no unique supported task anchor was present");
             }
-            assertWatchAnchorVersion(anchor, rawTerminal);
-            watch = watchService.create({
-                agent,
-                terminal: terminalWatchIdentity(rawTerminal, expectedBindingToken),
-                anchor,
-                ...(callbackRoute === undefined
-                    ? {}
-                    : { callback_route: callbackRoute }),
-                openclaw_session: openclawSession,
-                openclaw_bin: stringValue(options.openclawBin) ?? "openclaw",
-                timeout_ms: positiveMinutes(options.hardTimeoutMinutes, DEFAULT_TERMINAL_WATCH_HARD_TIMEOUT_MINUTES) * 60_000,
-                approval_fingerprint: approvalFingerprint(projectedTerminal),
-                approval_reason_code: approvalFingerprint(projectedTerminal)
-                    ? "terminal_waiting_for_approval"
-                    : undefined
+            const initialActivityState = terminalActivityState(projectedTerminal);
+            anchor = createTerminalActivityWatchAnchor({
+                capturedAt: dependencies.now(),
+                terminalId,
+                pid: positiveInteger(rawTerminal.pid, "terminal PID"),
+                initialActivityState,
+                nativeProcessUuid: stringValue(rawTerminal.native_agent_process_uuid),
+                nativeProcessBirth: stringValue(rawTerminal.native_agent_process_birth),
+                agentVersion: stringValue(rawTerminal.agent_version)
             });
+            warnings.push("terminal_activity_fallback: observing the exact terminal/process activity epoch instead of claiming exact task completion");
+            if (initialActivityState === "idle" || initialActivityState === "unknown") {
+                warnings.push("terminal_activity_armed_for_next_activity: no active epoch is visible yet; Watch will wait to observe working or approval activity before stable idle can settle");
+            }
         }
-        finally {
-            releaseTerminal();
+        const binding = bestEffortBindingTokenForWatch(rawTerminal);
+        if (binding.warning)
+            warnings.push(binding.warning);
+        const terminalIdentity = terminalWatchIdentity(rawTerminal, binding.token);
+        const repository = createTerminalWatchStore(dependencies.storeDirFromOptions(options), { acquire: dependencies.acquireFileLock });
+        let existingCandidates = [];
+        let discoveryWarnings = [];
+        try {
+            const scan = repository.scanForReconciliation();
+            existingCandidates = scan.watches;
+            if (scan.errors.length > 0) {
+                discoveryWarnings = [
+                    `terminal_watch_store_entries_skipped: ignored ${scan.errors.length} ` +
+                        "invalid sibling Watch record(s) during idempotent discovery"
+                ];
+            }
         }
-        dependencies.printJson({ watch: publicTerminalWatch(watch) });
+        catch (error) {
+            discoveryWarnings = [
+                `terminal_watch_store_discovery_unavailable: ${safeDiagnostic(error)}; ` +
+                    "attempting the user-requested read-only Watch anyway"
+            ];
+        }
+        warnings.push(...discoveryWarnings);
+        const watchService = serviceFor(options);
+        const openclawBin = stringValue(options.openclawBin) ?? "openclaw";
+        const existing = existingCandidates.find((candidate) => sameManualWatchTarget(candidate, agent, terminalIdentity, anchor) &&
+            sameManualWatchCallbackAuthority(candidate, callbackRoute, openclawSession, openclawBin));
+        const watch = existing ?? watchService.create({
+            agent,
+            terminal: terminalIdentity,
+            anchor,
+            warnings,
+            ...(callbackRoute === undefined
+                ? {}
+                : { callback_route: callbackRoute }),
+            openclaw_session: openclawSession,
+            openclaw_bin: openclawBin,
+            timeout_ms: positiveMinutes(options.hardTimeoutMinutes, DEFAULT_TERMINAL_WATCH_HARD_TIMEOUT_MINUTES) * 60_000,
+            approval_fingerprint: approvalFingerprint(projectedTerminal),
+            approval_reason_code: approvalFingerprint(projectedTerminal)
+                ? "terminal_waiting_for_approval"
+                : undefined
+        });
+        dependencies.printJson({
+            watch: publicTerminalWatch(watch, existing ? discoveryWarnings : [])
+        });
     }
     async function runUnwatch(options) {
         const service = serviceFor(options);
@@ -326,7 +367,7 @@ export function createTerminalWatchCliAdapter(dependencies) {
     function publicTerminalWatches(watches, options) {
         return watches
             .filter((watch) => options.includeAll || watch.status === "active")
-            .map(publicTerminalWatch);
+            .map((watch) => publicTerminalWatch(watch));
     }
     return Object.freeze({
         prepareUserExplicitFallbackWatch,
@@ -340,8 +381,13 @@ export function createTerminalWatchCliAdapter(dependencies) {
         scanPublicWatchesForExactObservation
     });
 }
-function assertWatchAnchorVersion(anchor, terminal) {
-    const runningVersion = requiredString(terminal.agent_version, "running coding-agent version");
+function watchAnchorVersionWarnings(anchor, terminal) {
+    const runningVersion = stringValue(terminal.agent_version);
+    if (!runningVersion) {
+        return [
+            "running_agent_version_unavailable: exact task observation remains enabled"
+        ];
+    }
     const artifactVersion = anchor.schema ===
         "agent-knock-knock/codex-human-started-active-task-anchor"
         ? anchor.codex_version
@@ -349,13 +395,16 @@ function assertWatchAnchorVersion(anchor, terminal) {
             "agent-knock-knock/claude-human-started-active-task-anchor"
             ? anchor.claude_version
             : undefined;
-    if (!artifactVersion) {
-        throw new Error("manual Terminal Watch requires a human-started task anchor");
-    }
+    if (!artifactVersion)
+        return [];
     if (artifactVersion !== runningVersion) {
-        throw new Error(`the active task artifact reports ${artifactVersion}, not the running ` +
-            `coding-agent version ${runningVersion}; no Terminal Watch was created`);
+        return [
+            `the active task artifact reports ${artifactVersion}, not the running ` +
+                `coding-agent version ${runningVersion}; Watch remains enabled because ` +
+                "version evidence is advisory"
+        ];
     }
+    return [];
 }
 /**
  * A shared native-Host lifecycle owns no single controller session. Bind its
@@ -416,11 +465,89 @@ async function exactTerminalForWatch(terminalId, options, dependencies) {
 function bindingTokenForWatch(terminal) {
     return requiredSha256(terminal.lifecycle_binding_token, "current terminal binding token");
 }
-function assertExactPublicWatchAction(terminal, terminalId) {
-    if (!exactTerminalWatchAction(terminal, terminalId)) {
-        throw new Error("the exact terminal is not currently watchable; refresh AKK list and " +
-            "use only its current available_actions.watch");
+function bestEffortBindingTokenForWatch(terminal) {
+    try {
+        return { token: bindingTokenForWatch(terminal) };
+    }
+    catch {
+        const terminalControl = terminalControlForWatch(terminal);
+        return {
+            token: sha256({
+                schema: "agent-knock-knock/terminal-watch-observation-binding",
+                version: 1,
+                terminal_id: requiredString(terminal.id, "terminal id"),
+                agent: terminalAgent(terminal),
+                pid: positiveInteger(terminal.pid, "terminal PID"),
+                endpoint: terminalControlEvidence(terminalControl),
+                process_uuid: stringValue(terminal.native_agent_process_uuid) ?? null,
+                process_birth: stringValue(terminal.native_agent_process_birth) ?? null
+            }),
+            warning: "lifecycle_binding_token_unavailable: Watch used read-only terminal/process observation identity"
+        };
+    }
+}
+function terminalActivityState(terminal) {
+    const state = stringValue(terminal.activity_state);
+    return state === "awaiting_approval" || state === "working" ||
+        state === "idle"
+        ? state
+        : "unknown";
+}
+function sameManualWatchTarget(watch, agent, terminal, anchor) {
+    return watch.status === "active" &&
+        watch.agent === agent &&
+        watch.terminal.terminal_id === terminal.terminal_id &&
+        watch.terminal.workspace === terminal.workspace &&
+        sameTerminalControlEvidenceIncarnation(watch.terminal.terminal_endpoint, terminal.terminal_endpoint) &&
+        sameManualWatchAnchorTarget(watch.anchor, anchor);
+}
+function sameManualWatchAnchorTarget(left, right) {
+    if (left.schema !== right.schema)
+        return false;
+    if (left.schema ===
+        "agent-knock-knock/codex-human-started-active-task-anchor" &&
+        right.schema === left.schema) {
+        return left.turn_id === right.turn_id &&
+            left.process_uuid === right.process_uuid &&
+            left.process_birth === right.process_birth &&
+            left.rollout.device === right.rollout.device &&
+            left.rollout.inode === right.rollout.inode;
+    }
+    if (left.schema ===
+        "agent-knock-knock/claude-human-started-active-task-anchor" &&
+        right.schema === left.schema) {
+        return left.prompt_uuid === right.prompt_uuid &&
+            left.pid === right.pid &&
+            left.agent_started_at_ms === right.agent_started_at_ms &&
+            left.device === right.device &&
+            left.inode === right.inode;
+    }
+    if (left.schema === "agent-knock-knock/terminal-activity-watch-anchor" &&
+        right.schema === left.schema) {
+        return left.pid === right.pid &&
+            optionalIdentityCompatible(left.native_process_uuid, right.native_process_uuid) &&
+            optionalIdentityCompatible(left.native_process_birth, right.native_process_birth);
     }
+    return left.anchor_fingerprint === right.anchor_fingerprint;
+}
+function optionalIdentityCompatible(left, right) {
+    return left === undefined || right === undefined || left === right;
+}
+function sameManualWatchCallbackAuthority(watch, callbackRoute, openclawSession, openclawBin) {
+    if (watch.openclaw_session !== openclawSession)
+        return false;
+    if (callbackRoute === undefined) {
+        return watch.callback_route === undefined &&
+            watch.openclaw_bin === openclawBin;
+    }
+    return watch.callback_route !== undefined &&
+        callbackRouteFingerprint(watch.callback_route) ===
+            callbackRouteFingerprint(callbackRoute);
+}
+function safeDiagnostic(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.replace(/[\r\n\0]+/gu, " ").trim().slice(0, 500) ||
+        "unknown provider observation error";
 }
 function terminalControlForWatch(terminal) {
     if (!isRecord(terminal.terminal_control)) {
@@ -428,28 +555,6 @@ function terminalControlForWatch(terminal) {
     }
     return terminal.terminal_control;
 }
-function assertExternalTerminalWatchAuthority(storeDir, terminalControl, dependencies) {
-    const blockingTurn = dependencies.terminalIncarnationBlockingTurns(storeDir, terminalControl)[0];
-    const authority = decideTerminalWatchExternalTaskAuthority({
-        blockingTurn,
-        dispatchOwnership: blockingTurn
-            ? { state: "none" }
-            : dependencies.terminalDispatchOwnership(terminalControl)
-    });
-    if (authority.state === "external_task") {
-        return;
-    }
-    if (authority.state === "managed_turn") {
-        const turn = authority.conversation;
-        throw new Error(`Terminal Watch is unavailable: this task already belongs to AKK Turn ` +
-            `${turnIdForConversation(turn)} (${turn.status}) and is covered by the ` +
-            "managed Turn monitor/callback path. Use AKK status for that Turn.");
-    }
-    const reason = stringValue(authority.conflict.reason) ??
-        "terminal dispatch ownership is conflicted";
-    throw new Error(`Terminal Watch is unavailable because AKK cannot prove this is external ` +
-        `work: ${reason}. Refresh AKK list and resolve the ownership conflict.`);
-}
 function captureTerminalWatchAnchor(agent, terminal, options, dependencies) {
     if (agent === "codex") {
         return captureCodexHumanStartedActiveTaskAnchor({
@@ -476,10 +581,15 @@ async function observeTerminalWatch(watch, options, dependencies) {
     const projectedTerminal = exactTerminal.state === "available"
         ? exactTerminal.terminal
         : undefined;
+    const activityTerminalIdentity = rawTerminal && isTerminalActivityWatch(watch)
+        ? terminalActivityWatchIdentityMatch(rawTerminal, watch)
+        : undefined;
     const terminalMatches = rawTerminal
         ? isUserExplicitFallbackWatch(watch)
             ? terminalMatchesUserExplicitFallbackWatch(rawTerminal, watch)
-            : terminalMatchesWatch(rawTerminal, watch)
+            : isTerminalActivityWatch(watch)
+                ? activityTerminalIdentity === "match"
+                : terminalMatchesWatch(rawTerminal, watch)
         : false;
     if (isUserExplicitFallbackWatch(watch)) {
         return observeUserExplicitFallbackTerminalWatch({
@@ -493,6 +603,15 @@ async function observeTerminalWatch(watch, options, dependencies) {
             dependencies
         });
     }
+    if (isTerminalActivityWatch(watch)) {
+        return observeTerminalActivityWatch({
+            watch,
+            exactTerminal,
+            projectedTerminal,
+            terminalIdentityMatch: activityTerminalIdentity ?? "mismatch",
+            observedAt
+        });
+    }
     const observation = watch.anchor.schema ===
         "agent-knock-knock/codex-human-started-active-task-anchor"
         ? observeCodexHumanStartedActiveTask({
@@ -591,6 +710,99 @@ async function observeTerminalWatch(watch, options, dependencies) {
         observation_checkpoint: observationCheckpoint
     };
 }
+function observeTerminalActivityWatch(input) {
+    const { watch, exactTerminal, projectedTerminal, terminalIdentityMatch, observedAt } = input;
+    const fence = terminalWatchObservationFence(watch);
+    if (exactTerminal.state === "unavailable") {
+        return {
+            ...fence,
+            kind: "unavailable",
+            observed_at: observedAt,
+            reason_code: "terminal_observation_unavailable"
+        };
+    }
+    if (exactTerminal.state === "absent") {
+        return invalidatedObservation(watch, observedAt, "terminal_process_unavailable");
+    }
+    if (terminalIdentityMatch === "unavailable") {
+        return {
+            ...fence,
+            kind: "unavailable",
+            observed_at: observedAt,
+            reason_code: "terminal_identity_observation_incomplete"
+        };
+    }
+    if (terminalIdentityMatch === "mismatch") {
+        return invalidatedObservation(watch, observedAt, "terminal_identity_changed");
+    }
+    if (!projectedTerminal) {
+        return {
+            ...fence,
+            kind: "unavailable",
+            observed_at: observedAt,
+            reason_code: "terminal_activity_unavailable"
+        };
+    }
+    const state = terminalActivityState(projectedTerminal);
+    const current = terminalActivityObservationCheckpoint(watch);
+    const active = state === "working" || state === "awaiting_approval";
+    const hasSeenActivity = current.has_seen_activity || active;
+    const consecutiveIdle = state === "idle" && hasSeenActivity
+        ? current.last_activity_state === "idle"
+            ? current.consecutive_idle_observations + 1
+            : 1
+        : 0;
+    const checkpoint = {
+        ...current,
+        has_seen_activity: hasSeenActivity,
+        consecutive_idle_observations: consecutiveIdle,
+        last_activity_state: state
+    };
+    if (state === "unknown") {
+        return {
+            ...fence,
+            kind: "unavailable",
+            observed_at: observedAt,
+            observation_checkpoint: checkpoint,
+            reason_code: "terminal_activity_unknown"
+        };
+    }
+    if (state === "awaiting_approval") {
+        const approval = approvalFingerprint(projectedTerminal);
+        if (approval) {
+            return {
+                ...fence,
+                kind: "approval",
+                observed_at: observedAt,
+                last_activity_at: observedAt,
+                observation_checkpoint: checkpoint,
+                evidence_fingerprint: approval,
+                reason_code: "terminal_waiting_for_approval"
+            };
+        }
+    }
+    if (state === "idle" && hasSeenActivity && consecutiveIdle >= 2) {
+        return {
+            ...fence,
+            kind: "completed",
+            observed_at: observedAt,
+            observation_checkpoint: checkpoint,
+            evidence_fingerprint: sha256({
+                watch_id: watch.watch_id,
+                reason_code: "terminal_activity_became_stably_idle",
+                anchor_fingerprint: watch.anchor.anchor_fingerprint
+            }),
+            reason_code: "terminal_activity_became_stably_idle"
+        };
+    }
+    return {
+        ...fence,
+        kind: "pending",
+        observed_at: observedAt,
+        ...(active ? { last_activity_at: observedAt } : {}),
+        observation_checkpoint: checkpoint
+    };
+}
 async function observeUserExplicitFallbackTerminalWatch(input) {
     const { watch, exactTerminal, rawTerminal, terminalMatches, observedAt, options, dependencies } = input;
     const fence = terminalWatchObservationFence(watch);
@@ -944,20 +1156,49 @@ async function currentTerminalForWatch(watch, options, dependencies) {
 }
 function terminalMatchesWatch(terminal, watch) {
     try {
-        const agent = terminalAgent(terminal);
-        const current = terminalWatchIdentity(terminal, bindingTokenForWatch(terminal));
-        return agent === watch.agent &&
-            terminalWatchIdentityFingerprint({
-                agent,
-                terminal: current,
-                anchor: watch.anchor
-            }) === terminalWatchIdentityFingerprint(watch) &&
-            sameTerminalControlEvidenceIncarnation(current.terminal_endpoint, watch.terminal.terminal_endpoint);
+        return terminalAgent(terminal) === watch.agent &&
+            requiredString(terminal.id, "terminal id") ===
+                watch.terminal.terminal_id &&
+            terminalWorkspace(terminal) === watch.terminal.workspace &&
+            isRecord(terminal.terminal_control) &&
+            sameTerminalControlEvidenceIncarnation(terminal.terminal_control, watch.terminal.terminal_endpoint);
     }
     catch {
         return false;
     }
 }
+function terminalActivityWatchIdentityMatch(terminal, watch) {
+    try {
+        if (!isTerminalActivityWatch(watch) ||
+            terminalAgent(terminal) !== watch.agent ||
+            requiredString(terminal.id, "terminal id") !==
+                watch.terminal.terminal_id ||
+            terminalWorkspace(terminal) !== watch.terminal.workspace ||
+            positiveInteger(terminal.pid, "terminal PID") !== watch.anchor.pid) {
+            return "mismatch";
+        }
+        if (!isRecord(terminal.terminal_control)) {
+            return "unavailable";
+        }
+        if (!sameTerminalControlEvidenceIncarnation(terminal.terminal_control, watch.terminal.terminal_endpoint)) {
+            return "mismatch";
+        }
+        const processUuid = stringValue(terminal.native_agent_process_uuid);
+        const processBirth = stringValue(terminal.native_agent_process_birth);
+        if ((watch.anchor.native_process_uuid !== undefined && !processUuid) ||
+            (watch.anchor.native_process_birth !== undefined && !processBirth)) {
+            return "unavailable";
+        }
+        return (watch.anchor.native_process_uuid !== undefined &&
+            processUuid !== watch.anchor.native_process_uuid) || (watch.anchor.native_process_birth !== undefined &&
+            processBirth !== watch.anchor.native_process_birth)
+            ? "mismatch"
+            : "match";
+    }
+    catch {
+        return "unavailable";
+    }
+}
 function terminalMatchesUserExplicitFallbackWatch(terminal, watch) {
     try {
         if (!isUserExplicitFallbackWatch(watch) ||
@@ -983,6 +1224,15 @@ function terminalMatchesUserExplicitFallbackWatch(terminal, watch) {
         return false;
     }
 }
+function terminalActivityObservationCheckpoint(watch) {
+    const checkpoint = watch.observation_checkpoint;
+    if (!("schema" in checkpoint) ||
+        checkpoint.schema !==
+            "agent-knock-knock/terminal-activity-watch-checkpoint") {
+        throw new Error("terminal activity Watch has no activity checkpoint");
+    }
+    return checkpoint;
+}
 function terminalWatchIdentity(terminal, bindingToken) {
     const terminalControl = terminal.terminal_control;
     return {
@@ -1021,28 +1271,30 @@ function codexIdentityForWatch(watch) {
         rollout: watch.anchor.rollout
     };
 }
-function publicTerminalWatch(watch) {
+function publicTerminalWatch(watch, additionalWarnings = []) {
     const pending = watch.notification_outbox.filter(({ status }) => status === "pending" || status === "delivering" || status === "failed").length;
-    const compatibilityWarning = watch.agent === "codex" &&
-        (watch.anchor.schema ===
-            "agent-knock-knock/codex-human-started-active-task-anchor" ||
-            watch.anchor.schema ===
-                "agent-knock-knock/codex-user-explicit-fallback-watch-anchor")
-        ? codexRuntimeCompatibilityProfile(watch.anchor.codex_version)
-            ?.compatibilityWarning
-        : watch.agent === "claude" &&
-            (watch.anchor.schema ===
-                "agent-knock-knock/claude-human-started-active-task-anchor" ||
-                watch.anchor.schema ===
-                    "agent-knock-knock/claude-user-explicit-fallback-watch-anchor")
-            ? claudeRuntimeCompatibilityWarning(watch.anchor.claude_version)
-            : undefined;
+    const capturedAgentVersion = terminalWatchCapturedAgentVersion(watch);
+    const compatibilityWarning = capturedAgentVersion === undefined
+        ? undefined
+        : watch.agent === "codex"
+            ? codexRuntimeCompatibilityProfile(capturedAgentVersion)
+                ?.compatibilityWarning
+            : claudeRuntimeCompatibilityWarning(capturedAgentVersion);
     const userExplicitFallback = isUserExplicitFallbackWatch(watch);
+    const terminalActivityFallback = isTerminalActivityWatch(watch);
+    const warnings = [...new Set([
+            ...(watch.warnings ?? []),
+            ...additionalWarnings
+        ])];
     return {
         watch_id: watch.watch_id,
         source: userExplicitFallback
             ? "terminal_user_explicit_fallback_watch"
-            : "human_started_terminal_watch",
+            : terminalActivityFallback
+                ? "terminal_activity_watch"
+                : "user_selected_terminal_watch",
+        watch_mode: terminalActivityFallback ? "terminal_activity" : "exact_task",
+        confidence: terminalActivityFallback ? "best_effort" : "exact",
         agent: watch.agent,
         terminal_id: watch.terminal.terminal_id,
         native_thread_id: terminalWatchNativeThreadId(watch),
@@ -1056,6 +1308,9 @@ function publicTerminalWatch(watch) {
         ...(compatibilityWarning
             ? { compatibility_warning: compatibilityWarning }
             : {}),
+        ...(warnings.length > 0
+            ? { warnings }
+            : {}),
         callback: {
             pending,
             delivered: watch.notification_outbox.filter(({ status }) => status === "delivered").length,
@@ -1091,6 +1346,18 @@ function publicTerminalWatch(watch) {
         }
     };
 }
+function terminalWatchCapturedAgentVersion(watch) {
+    switch (watch.anchor.schema) {
+        case "agent-knock-knock/codex-human-started-active-task-anchor":
+        case "agent-knock-knock/codex-user-explicit-fallback-watch-anchor":
+            return watch.anchor.codex_version;
+        case "agent-knock-knock/claude-human-started-active-task-anchor":
+        case "agent-knock-knock/claude-user-explicit-fallback-watch-anchor":
+            return watch.anchor.claude_version;
+        case "agent-knock-knock/terminal-activity-watch-anchor":
+            return watch.anchor.agent_version;
+    }
+}
 function terminalWatchNativeThreadId(watch) {
     switch (watch.anchor.schema) {
         case "agent-knock-knock/codex-human-started-active-task-anchor":
@@ -1103,6 +1370,8 @@ function terminalWatchNativeThreadId(watch) {
                 : undefined;
         case "agent-knock-knock/claude-user-explicit-fallback-watch-anchor":
             return watch.anchor.transcript_anchor.session_id;
+        case "agent-knock-knock/terminal-activity-watch-anchor":
+            return undefined;
     }
 }
 function approvalFingerprint(terminal) {