@scotthuang/agent-knock-knock 0.12.18 → 0.12.19

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

@@ -1,17 +1,18 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
+import { callbackRouteForConversation } from "./callback-route-authority.js";
 import { parseCallbackRoute } from "./callback-transport.js";
-import { captureClaudeHumanStartedActiveTaskAnchor, observeClaudeHumanStartedActiveTask } from "./claude-local-transcript-provider.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 { captureCodexHumanStartedActiveTaskAnchor, observeCodexHumanStartedActiveTask } from "./terminal-submission-acceptance.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 { createTerminalWatchStore, terminalWatchIdentityFingerprint } from "./terminal-watch-store.js";
+import { createClaudeUserExplicitFallbackWatchAnchor, createCodexUserExplicitFallbackWatchAnchor, createTerminalWatchStore, isUserExplicitFallbackWatch, terminalUserExplicitFallbackWatchId, terminalWatchIdentityFingerprint } 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) {
@@ -81,6 +82,162 @@ export function createTerminalWatchCliAdapter(dependencies) {
             }
         });
     }
+    async function prepareUserExplicitFallbackWatch(input) {
+        const callbackRoute = callbackRouteForUserExplicitFallback(input.options);
+        if (!callbackRoute)
+            return undefined;
+        await bestEffortStabilizePriorFallbackWatch(input.options, input.terminal.conversationId, input.requestHash);
+        const observed = await exactTerminalForWatch(input.terminal.conversationId, input.options, dependencies);
+        const rawTerminal = observed.rawTerminal;
+        assertSameUserExplicitFallbackTerminal(input.terminal, rawTerminal);
+        const agentVersion = requiredString(rawTerminal.agent_version, "running coding-agent version");
+        let anchor;
+        if (input.terminal.agent === "codex") {
+            const inventory = rawTerminal._codex_open_root_rollout_inventory;
+            const acceptanceAnchor = isRecord(inventory)
+                ? captureCodexCandidateSetRolloutAcceptanceAnchor({
+                    inventory: inventory,
+                    now: dependencies.now()
+                })
+                : captureCodexRolloutAcceptanceAnchor({
+                    nativeThreadId: requiredString(rawTerminal.native_agent_session_id, "Codex native thread id"),
+                    processUuid: requiredString(rawTerminal.native_agent_process_uuid, "Codex process UUID"),
+                    processBirth: requiredString(rawTerminal.native_agent_process_birth, "Codex process birth"),
+                    mode: "existing",
+                    rollout: codexIdentity(rawTerminal).rollout,
+                    now: dependencies.now()
+                });
+            anchor = createCodexUserExplicitFallbackWatchAnchor({
+                acceptanceAnchor,
+                requestHash: input.requestHash,
+                codexVersion: agentVersion
+            });
+        }
+        else {
+            const transcriptAnchor = captureClaudeTranscriptAnchor({
+                sessionId: requiredString(rawTerminal.native_agent_session_id, "Claude native session id"),
+                cwd: terminalWorkspace(rawTerminal),
+                pid: positiveInteger(rawTerminal.pid, "Claude PID"),
+                claudeHome: stringValue(input.options.claudeHome),
+                agentRows: dependencies.loadClaudeAgentRows(input.options, { required: true }),
+                now: dependencies.now()
+            });
+            if (!transcriptAnchor) {
+                throw new Error("Claude transcript anchor is unavailable before terminal input");
+            }
+            anchor = createClaudeUserExplicitFallbackWatchAnchor({
+                transcriptAnchor,
+                requestHash: input.requestHash,
+                claudeVersion: agentVersion
+            });
+        }
+        return {
+            watchId: terminalUserExplicitFallbackWatchId({
+                messageId: input.messageId,
+                physicalToken: input.physicalToken,
+                requestHash: input.requestHash
+            }),
+            terminalId: input.terminal.conversationId,
+            agent: input.terminal.agent,
+            pid: input.terminal.pid,
+            terminalEndpoint: terminalControlEvidence(input.terminal.terminalControl),
+            terminalIdentity: terminalWatchIdentity(rawTerminal, input.physicalToken),
+            physicalToken: input.physicalToken,
+            requestHash: input.requestHash,
+            callbackRoute,
+            openclawSession: callbackRoute.controller_session_id,
+            openclawBin: stringValue(input.options.openclawBin) ?? "openclaw",
+            timeoutMs: positiveMinutes(input.options.hardTimeoutMinutes ??
+                input.options.agentHardTimeoutMinutes, DEFAULT_TERMINAL_WATCH_HARD_TIMEOUT_MINUTES) * 60_000,
+            anchor
+        };
+    }
+    async function attachUserExplicitFallbackWatch(input) {
+        let observed;
+        try {
+            observed = await dependencies.observeExactTerminal({
+                options: input.options,
+                terminalId: input.prepared.terminalId
+            });
+        }
+        catch {
+            // Observation itself is best effort after the user's physical Send.
+            // Persist the exact pre-Send identity and let the durable provider
+            // artifact settle or invalidate the Watch.
+        }
+        if (observed?.state === "available") {
+            assertPreparedFallbackTerminal(input.prepared, observed.rawTerminal);
+        }
+        // An absent or temporarily unavailable terminal after Enter is not a
+        // callback veto. The immutable pre-Send provider anchor and terminal
+        // identity remain sufficient to recover a completion already on disk.
+        const service = serviceFor(input.options);
+        let watch;
+        try {
+            watch = service.create({
+                watch_id: input.prepared.watchId,
+                agent: input.prepared.agent,
+                terminal: input.prepared.terminalIdentity,
+                anchor: input.prepared.anchor,
+                callback_route: input.prepared.callbackRoute,
+                openclaw_session: input.prepared.openclawSession,
+                openclaw_bin: input.prepared.openclawBin,
+                timeout_ms: input.prepared.timeoutMs
+            });
+        }
+        catch (error) {
+            const existing = service.list().find((candidate) => candidate.watch_id === input.prepared.watchId);
+            if (!existing ||
+                !isUserExplicitFallbackWatch(existing) ||
+                existing.anchor.anchor_fingerprint !==
+                    input.prepared.anchor.anchor_fingerprint) {
+                throw error;
+            }
+            watch = existing;
+        }
+        return {
+            callback_expected: true,
+            callback_mode: "terminal_watch",
+            watch_id: watch.watch_id
+        };
+    }
+    async function bestEffortStabilizePriorFallbackWatch(options, terminalId, requestHash) {
+        try {
+            const service = serviceFor(options);
+            const prior = service.list().filter((watch) => watch.status === "active" &&
+                isUserExplicitFallbackWatch(watch) &&
+                watch.terminal.terminal_id === terminalId &&
+                watch.anchor.request_hash === requestHash);
+            for (const watch of prior) {
+                try {
+                    await service.reconcile(watch.watch_id);
+                }
+                catch {
+                    // A prior callback must never delay or veto the new user Send.
+                }
+            }
+        }
+        catch {
+            // Store or observer failure is callback-only degradation. The caller
+            // still captures the new pre-Send anchor and physical Send proceeds.
+        }
+    }
+    function userExplicitFallbackWatchReceipt(input) {
+        try {
+            const watch = serviceFor(input.options).get(input.watchId);
+            if (!isUserExplicitFallbackWatch(watch) || !watch.callback_route) {
+                return undefined;
+            }
+            return {
+                callback_expected: true,
+                callback_mode: "terminal_watch",
+                watch_id: watch.watch_id
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
     async function runWatch(options) {
         const terminalId = requiredString(options.terminal, "--terminal");
         const callbackRoute = Object.hasOwn(options, "callbackRoute")
@@ -172,6 +329,9 @@ export function createTerminalWatchCliAdapter(dependencies) {
             .map(publicTerminalWatch);
     }
     return Object.freeze({
+        prepareUserExplicitFallbackWatch,
+        attachUserExplicitFallbackWatch,
+        userExplicitFallbackWatchReceipt,
         runWatch,
         runUnwatch,
         runWatchStatus,
@@ -185,7 +345,13 @@ function assertWatchAnchorVersion(anchor, terminal) {
     const artifactVersion = anchor.schema ===
         "agent-knock-knock/codex-human-started-active-task-anchor"
         ? anchor.codex_version
-        : anchor.claude_version;
+        : anchor.schema ===
+            "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 !== runningVersion) {
         throw new Error(`the active task artifact reports ${artifactVersion}, not the running ` +
             `coding-agent version ${runningVersion}; no Terminal Watch was created`);
@@ -202,6 +368,37 @@ function routeBoundWatchCallbackRoute(template, watch) {
         controller_session_id: watch.openclaw_session
     });
 }
+function callbackRouteForUserExplicitFallback(options) {
+    if (Object.hasOwn(options, "callbackRoute")) {
+        return parseCallbackRoute(options.callbackRoute);
+    }
+    const openclawSession = stringValue(options.openclawSession);
+    return callbackRouteForConversation({
+        gateway_method: options.gatewayMethod,
+        gateway_session: options.gatewaySession ?? openclawSession,
+        openclaw_session: openclawSession,
+        openclaw_bin: options.openclawBin,
+        gateway_url: options.gatewayUrl
+    });
+}
+function assertSameUserExplicitFallbackTerminal(expected, observed) {
+    if (requiredString(observed.id, "terminal id") !== expected.conversationId ||
+        terminalAgent(observed) !== expected.agent ||
+        positiveInteger(observed.pid, "terminal PID") !== expected.pid ||
+        !isRecord(observed.terminal_control) ||
+        !sameTerminalControlEvidenceIncarnation(expected.terminalControl, observed.terminal_control)) {
+        throw new Error("terminal changed before the user-explicit fallback Watch anchor was captured");
+    }
+}
+function assertPreparedFallbackTerminal(prepared, observed) {
+    if (requiredString(observed.id, "terminal id") !== prepared.terminalId ||
+        terminalAgent(observed) !== prepared.agent ||
+        positiveInteger(observed.pid, "terminal PID") !== prepared.pid ||
+        !isRecord(observed.terminal_control) ||
+        !sameTerminalControlEvidenceIncarnation(prepared.terminalEndpoint, observed.terminal_control)) {
+        throw new Error("terminal changed before the user-explicit fallback Watch was attached");
+    }
+}
 async function exactTerminalForWatch(terminalId, options, dependencies) {
     const observation = await dependencies.observeExactTerminal({
         options,
@@ -280,8 +477,22 @@ async function observeTerminalWatch(watch, options, dependencies) {
         ? exactTerminal.terminal
         : undefined;
     const terminalMatches = rawTerminal
-        ? terminalMatchesWatch(rawTerminal, watch)
+        ? isUserExplicitFallbackWatch(watch)
+            ? terminalMatchesUserExplicitFallbackWatch(rawTerminal, watch)
+            : terminalMatchesWatch(rawTerminal, watch)
         : false;
+    if (isUserExplicitFallbackWatch(watch)) {
+        return observeUserExplicitFallbackTerminalWatch({
+            watch,
+            exactTerminal,
+            rawTerminal,
+            projectedTerminal,
+            terminalMatches,
+            observedAt,
+            options,
+            dependencies
+        });
+    }
     const observation = watch.anchor.schema ===
         "agent-knock-knock/codex-human-started-active-task-anchor"
         ? observeCodexHumanStartedActiveTask({
@@ -291,13 +502,18 @@ async function observeTerminalWatch(watch, options, dependencies) {
                 : codexIdentityForWatch(watch),
             resumeOffsetBytes: watch.observation_checkpoint.safe_resume_offset_bytes
         })
-        : observeClaudeHumanStartedActiveTask({
-            anchor: watch.anchor,
-            claudeHome: stringValue(options.claudeHome),
-            agentRows: dependencies.loadClaudeAgentRows(options, { required: true }),
-            resumeOffsetBytes: watch.observation_checkpoint.safe_resume_offset_bytes,
-            checkpoint: claudeObservationCheckpoint(watch)
-        });
+        : watch.anchor.schema ===
+            "agent-knock-knock/claude-human-started-active-task-anchor"
+            ? observeClaudeHumanStartedActiveTask({
+                anchor: watch.anchor,
+                claudeHome: stringValue(options.claudeHome),
+                agentRows: dependencies.loadClaudeAgentRows(options, { required: true }),
+                resumeOffsetBytes: watch.observation_checkpoint.safe_resume_offset_bytes,
+                checkpoint: claudeObservationCheckpoint(watch)
+            })
+            : (() => {
+                throw new Error("terminal Watch anchor is unsupported");
+            })();
     if (observation.status === "invalidated") {
         return invalidatedObservation(watch, observedAt, "task_anchor_invalidated");
     }
@@ -375,6 +591,342 @@ async function observeTerminalWatch(watch, options, dependencies) {
         observation_checkpoint: observationCheckpoint
     };
 }
+async function observeUserExplicitFallbackTerminalWatch(input) {
+    const { watch, exactTerminal, rawTerminal, terminalMatches, observedAt, options, dependencies } = input;
+    const fence = terminalWatchObservationFence(watch);
+    if (watch.anchor.schema ===
+        "agent-knock-knock/codex-user-explicit-fallback-watch-anchor") {
+        const anchor = watch.anchor.acceptance_anchor;
+        const persistedCheckpoint = codexFallbackObservationCheckpoint(watch);
+        let acceptance;
+        let currentIdentity;
+        let acceptedCheckpoint;
+        if (persistedCheckpoint.acceptance_evidence &&
+            persistedCheckpoint.accepted_identity) {
+            acceptance = persistedCheckpoint.acceptance_evidence;
+            currentIdentity = {
+                sessionId: persistedCheckpoint.accepted_identity.native_thread_id,
+                processUuid: persistedCheckpoint.accepted_identity.process_uuid,
+                processBirth: persistedCheckpoint.accepted_identity.process_birth,
+                rollout: persistedCheckpoint.accepted_identity.rollout
+            };
+            acceptedCheckpoint = persistedCheckpoint;
+        }
+        else if (anchor.version === 3) {
+            const inventory = rawTerminal?._codex_open_root_rollout_inventory;
+            if (!isRecord(inventory)) {
+                return fallbackPendingOrTerminalObservation({
+                    watch,
+                    exactTerminal,
+                    rawTerminal,
+                    terminalMatches,
+                    observedAt,
+                    reasonCode: "codex_rollout_inventory_unavailable"
+                });
+            }
+            const result = detectCodexCandidateSetRolloutAcceptance({
+                anchor,
+                currentInventory: inventory,
+                requestHash: watch.anchor.request_hash
+            });
+            if (result.status === "uncertain") {
+                if (result.code === "candidate_scan_invalid") {
+                    return {
+                        ...fence,
+                        kind: "unavailable",
+                        observed_at: observedAt,
+                        reason_code: "native_acceptance_scan_unavailable"
+                    };
+                }
+                return invalidatedObservation(watch, observedAt, `native_acceptance_${result.code}`);
+            }
+            if (result.status === "pending") {
+                return fallbackPendingOrTerminalObservation({
+                    watch,
+                    exactTerminal,
+                    rawTerminal,
+                    terminalMatches,
+                    observedAt
+                });
+            }
+            acceptance = result.evidence;
+            currentIdentity = result.identity;
+            acceptedCheckpoint = codexFallbackAcceptedCheckpoint(watch, acceptance, currentIdentity);
+        }
+        else {
+            try {
+                currentIdentity = anchor.version === 1
+                    ? {
+                        sessionId: anchor.native_thread_id,
+                        processUuid: anchor.process_uuid,
+                        processBirth: anchor.process_birth,
+                        rollout: anchor.rollout
+                    }
+                    : rawTerminal
+                        ? codexIdentity(rawTerminal)
+                        : (() => {
+                            throw new Error("Codex pre-materialization identity is unavailable");
+                        })();
+                acceptance = detectCodexRolloutAcceptance({
+                    anchor,
+                    currentIdentity,
+                    requestHash: watch.anchor.request_hash
+                });
+            }
+            catch (error) {
+                if (retryableProviderError(error)) {
+                    return {
+                        ...fence,
+                        kind: "unavailable",
+                        observed_at: observedAt,
+                        reason_code: "native_acceptance_scan_unavailable"
+                    };
+                }
+                return invalidatedObservation(watch, observedAt, "native_acceptance_identity_changed");
+            }
+            if (!acceptance) {
+                return fallbackPendingOrTerminalObservation({
+                    watch,
+                    exactTerminal,
+                    rawTerminal,
+                    terminalMatches,
+                    observedAt
+                });
+            }
+            acceptedCheckpoint = codexFallbackAcceptedCheckpoint(watch, acceptance, currentIdentity);
+        }
+        if (!acceptance || !acceptedCheckpoint) {
+            throw new Error("Codex fallback Watch acceptance checkpoint is incomplete");
+        }
+        const completion = detectCodexBoundRolloutCompletion({
+            anchor,
+            acceptanceEvidence: acceptance,
+            currentIdentity,
+            requestHash: watch.anchor.request_hash
+        });
+        if (completion.status === "completed") {
+            return fallbackCompletionObservation(watch, observedAt, completion.completion, completion.diagnostics.observed_end_offset_bytes, codexFallbackAcceptedCheckpoint(watch, acceptance, currentIdentity));
+        }
+        if (completion.status === "failure") {
+            if (completion.diagnostics.code === "rollout_unreadable") {
+                return {
+                    ...fence,
+                    kind: "unavailable",
+                    observed_at: observedAt,
+                    safe_resume_offset_bytes: acceptedCheckpoint.safe_resume_offset_bytes,
+                    observation_checkpoint: acceptedCheckpoint,
+                    reason_code: "accepted_rollout_unavailable"
+                };
+            }
+            return invalidatedObservation(watch, observedAt, `native_completion_${completion.diagnostics.code}`);
+        }
+        return fallbackPendingOrTerminalObservation({
+            watch,
+            exactTerminal,
+            rawTerminal,
+            terminalMatches,
+            observedAt,
+            observedEndOffsetBytes: completion.diagnostics.observed_end_offset_bytes,
+            observationCheckpoint: codexFallbackAcceptedCheckpoint(watch, acceptance, currentIdentity)
+        });
+    }
+    if (watch.anchor.schema !==
+        "agent-knock-knock/claude-user-explicit-fallback-watch-anchor") {
+        throw new Error("user-explicit fallback Watch anchor is unsupported");
+    }
+    const request = {
+        sessionId: watch.anchor.transcript_anchor.session_id,
+        cwd: watch.anchor.transcript_anchor.cwd,
+        requestHash: watch.anchor.request_hash,
+        startedAt: watch.anchor.captured_at,
+        context: {
+            claudeTranscriptAnchor: watch.anchor.transcript_anchor,
+            pid: watch.anchor.transcript_anchor.pid
+        }
+    };
+    const persistedCheckpoint = claudeFallbackObservationCheckpoint(watch);
+    const observation = observeClaudeUserExplicitFallbackTranscript(request, {
+        claudeHome: stringValue(options.claudeHome),
+        // This observer is transcript-authoritative by design. Completion must
+        // remain recoverable after the exact pane/process leaves discovery.
+        acceptanceEvidence: persistedCheckpoint.acceptance_evidence
+    });
+    if (observation.status === "unavailable") {
+        return {
+            ...fence,
+            kind: "unavailable",
+            observed_at: observedAt,
+            reason_code: "native_acceptance_scan_unavailable"
+        };
+    }
+    const acceptance = observation.acceptance;
+    if (!acceptance) {
+        return fallbackPendingOrTerminalObservation({
+            watch,
+            exactTerminal,
+            rawTerminal,
+            terminalMatches,
+            observedAt
+        });
+    }
+    const acceptedCheckpoint = claudeFallbackAcceptedCheckpoint(watch, acceptance);
+    if (observation.status === "completed") {
+        return fallbackCompletionObservation(watch, observedAt, observation.completion, observation.observedEndOffsetBytes, acceptedCheckpoint);
+    }
+    return fallbackPendingOrTerminalObservation({
+        watch,
+        exactTerminal,
+        rawTerminal,
+        terminalMatches,
+        observedAt,
+        observedEndOffsetBytes: observation.observedEndOffsetBytes,
+        observationCheckpoint: acceptedCheckpoint
+    });
+}
+function fallbackPendingOrTerminalObservation(input) {
+    if (input.exactTerminal.state === "unavailable") {
+        return {
+            ...terminalWatchObservationFence(input.watch),
+            kind: "unavailable",
+            observed_at: input.observedAt,
+            reason_code: input.reasonCode ?? "terminal_observation_unavailable"
+        };
+    }
+    if (input.exactTerminal.state === "absent" || !input.rawTerminal) {
+        return invalidatedObservation(input.watch, input.observedAt, "terminal_process_unavailable");
+    }
+    if (!input.terminalMatches) {
+        return invalidatedObservation(input.watch, input.observedAt, "terminal_identity_changed");
+    }
+    if (input.reasonCode) {
+        return {
+            ...terminalWatchObservationFence(input.watch),
+            kind: "unavailable",
+            observed_at: input.observedAt,
+            reason_code: input.reasonCode
+        };
+    }
+    return fallbackPendingObservation(input.watch, input.observedAt, input.observedEndOffsetBytes, input.observationCheckpoint);
+}
+function fallbackPendingObservation(watch, observedAt, observedEndOffsetBytes, observationCheckpoint) {
+    const effectiveCheckpoint = observationCheckpoint ?? (watch.anchor.schema ===
+        "agent-knock-knock/codex-user-explicit-fallback-watch-anchor"
+        ? watch.observation_checkpoint
+        : undefined);
+    const safeResumeOffsetBytes = effectiveCheckpoint
+        ?.safe_resume_offset_bytes ?? fallbackResumeOffset(watch, observedEndOffsetBytes);
+    return {
+        ...terminalWatchObservationFence(watch),
+        kind: "pending",
+        observed_at: observedAt,
+        safe_resume_offset_bytes: safeResumeOffsetBytes,
+        ...(effectiveCheckpoint
+            ? { observation_checkpoint: effectiveCheckpoint }
+            : {})
+    };
+}
+function codexFallbackObservationCheckpoint(watch) {
+    const checkpoint = watch.observation_checkpoint;
+    if (!("schema" in checkpoint) ||
+        checkpoint.schema !==
+            "agent-knock-knock/codex-user-explicit-fallback-watch-checkpoint") {
+        throw new Error("Codex fallback Watch has no exact acceptance checkpoint");
+    }
+    return checkpoint;
+}
+function claudeFallbackObservationCheckpoint(watch) {
+    const checkpoint = watch.observation_checkpoint;
+    if (!("schema" in checkpoint) ||
+        checkpoint.schema !==
+            "agent-knock-knock/claude-user-explicit-fallback-watch-checkpoint") {
+        throw new Error("Claude fallback Watch has no exact acceptance checkpoint");
+    }
+    return checkpoint;
+}
+function codexFallbackAcceptedCheckpoint(watch, acceptanceEvidence, currentIdentity) {
+    const nativeThreadId = requiredString(currentIdentity.sessionId, "accepted Codex native thread id");
+    const processUuid = requiredString(currentIdentity.processUuid, "accepted Codex process UUID");
+    const processBirth = requiredString(currentIdentity.processBirth, "accepted Codex process birth");
+    const rollout = currentIdentity.rollout;
+    if (!rollout) {
+        throw new Error("accepted Codex rollout identity is unavailable");
+    }
+    const acceptanceOffset = numericMetadata(acceptanceEvidence.metadata, "observed_end_offset_bytes");
+    if (acceptanceOffset === undefined) {
+        throw new Error("accepted Codex rollout boundary is unavailable");
+    }
+    return {
+        schema: "agent-knock-knock/codex-user-explicit-fallback-watch-checkpoint",
+        version: 1,
+        safe_resume_offset_bytes: fallbackResumeOffset(watch, acceptanceOffset),
+        acceptance_evidence: acceptanceEvidence,
+        accepted_identity: {
+            native_thread_id: nativeThreadId,
+            process_uuid: processUuid,
+            process_birth: processBirth,
+            rollout
+        }
+    };
+}
+function claudeFallbackAcceptedCheckpoint(watch, acceptanceEvidence) {
+    const acceptanceOffset = numericMetadata(acceptanceEvidence.metadata, "observed_end_offset_bytes");
+    if (acceptanceOffset === undefined) {
+        throw new Error("accepted Claude transcript boundary is unavailable");
+    }
+    const promptUuid = requiredString(acceptanceEvidence.acceptanceId, "accepted Claude prompt UUID");
+    return {
+        schema: "agent-knock-knock/claude-user-explicit-fallback-watch-checkpoint",
+        version: 1,
+        safe_resume_offset_bytes: fallbackResumeOffset(watch, acceptanceOffset),
+        acceptance_evidence: acceptanceEvidence,
+        accepted_prompt_uuid: promptUuid
+    };
+}
+function fallbackCompletionObservation(watch, observedAt, completion, observedEndOffsetBytes, observationCheckpoint) {
+    const safeResumeOffsetBytes = observationCheckpoint
+        ?.safe_resume_offset_bytes ?? fallbackResumeOffset(watch, observedEndOffsetBytes);
+    const kind = completion.outcome === "failure" ? "failed" : "completed";
+    return {
+        ...terminalWatchObservationFence(watch),
+        kind,
+        observed_at: observedAt,
+        safe_resume_offset_bytes: safeResumeOffsetBytes,
+        ...(observationCheckpoint
+            ? { observation_checkpoint: observationCheckpoint }
+            : {}),
+        evidence_fingerprint: sha256({
+            kind,
+            watch_id: watch.watch_id,
+            completion_id: completion.id ?? null,
+            completion_timestamp: completion.timestamp ?? null,
+            anchor_fingerprint: watch.anchor.anchor_fingerprint
+        }),
+        reason_code: completion.outcome === "failure"
+            ? "anchored_task_failed"
+            : "anchored_task_completed",
+        completion_text: completion.text.slice(0, 4000),
+        completion_id: completion.id,
+        completion_timestamp: completion.timestamp
+    };
+}
+function fallbackResumeOffset(watch, observedEndOffsetBytes) {
+    return Math.max(watch.observation_checkpoint.safe_resume_offset_bytes, Number.isSafeInteger(observedEndOffsetBytes) &&
+        Number(observedEndOffsetBytes) >= 0
+        ? Number(observedEndOffsetBytes)
+        : 0);
+}
+function numericMetadata(metadata, field) {
+    const value = metadata?.[field];
+    return Number.isSafeInteger(value) && Number(value) >= 0
+        ? Number(value)
+        : undefined;
+}
+function retryableProviderError(error) {
+    return isRecord(error) && typeof error.code === "string" && new Set([
+        "EACCES", "EAGAIN", "EBUSY", "EIO", "EMFILE", "ENFILE", "ENOENT",
+        "EPERM", "ESTALE", "ETIMEDOUT"
+    ]).has(error.code);
+}
 function claudeObservationCheckpoint(watch) {
     const checkpoint = watch.observation_checkpoint;
     if (!("schema" in checkpoint) ||
@@ -406,6 +958,31 @@ function terminalMatchesWatch(terminal, watch) {
         return false;
     }
 }
+function terminalMatchesUserExplicitFallbackWatch(terminal, watch) {
+    try {
+        if (!isUserExplicitFallbackWatch(watch) ||
+            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)) {
+            return false;
+        }
+        if (watch.anchor.schema ===
+            "agent-knock-knock/codex-user-explicit-fallback-watch-anchor") {
+            return requiredString(terminal.native_agent_process_uuid, "Codex process UUID") === watch.anchor.acceptance_anchor.process_uuid &&
+                requiredString(terminal.native_agent_process_birth, "Codex process birth") === watch.anchor.acceptance_anchor.process_birth;
+        }
+        return watch.anchor.schema ===
+            "agent-knock-knock/claude-user-explicit-fallback-watch-anchor" &&
+            positiveInteger(terminal.pid, "Claude PID") ===
+                watch.anchor.transcript_anchor.pid;
+    }
+    catch {
+        return false;
+    }
+}
 function terminalWatchIdentity(terminal, bindingToken) {
     const terminalControl = terminal.terminal_control;
     return {
@@ -447,24 +1024,28 @@ function codexIdentityForWatch(watch) {
 function publicTerminalWatch(watch) {
     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-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-human-started-active-task-anchor" ||
+                watch.anchor.schema ===
+                    "agent-knock-knock/claude-user-explicit-fallback-watch-anchor")
             ? claudeRuntimeCompatibilityWarning(watch.anchor.claude_version)
             : undefined;
+    const userExplicitFallback = isUserExplicitFallbackWatch(watch);
     return {
         watch_id: watch.watch_id,
-        source: "human_started_terminal_watch",
+        source: userExplicitFallback
+            ? "terminal_user_explicit_fallback_watch"
+            : "human_started_terminal_watch",
         agent: watch.agent,
         terminal_id: watch.terminal.terminal_id,
-        native_thread_id: watch.anchor.schema ===
-            "agent-knock-knock/codex-human-started-active-task-anchor"
-            ? watch.anchor.native_thread_id
-            : watch.anchor.session_id,
+        native_thread_id: terminalWatchNativeThreadId(watch),
         workspace: watch.terminal.workspace,
         status: watch.status,
         activity_state: watch.status === "active" ? "watching" : "settled",
@@ -510,6 +1091,20 @@ function publicTerminalWatch(watch) {
         }
     };
 }
+function terminalWatchNativeThreadId(watch) {
+    switch (watch.anchor.schema) {
+        case "agent-knock-knock/codex-human-started-active-task-anchor":
+            return watch.anchor.native_thread_id;
+        case "agent-knock-knock/claude-human-started-active-task-anchor":
+            return watch.anchor.session_id;
+        case "agent-knock-knock/codex-user-explicit-fallback-watch-anchor":
+            return watch.anchor.acceptance_anchor.version === 1
+                ? watch.anchor.acceptance_anchor.native_thread_id
+                : undefined;
+        case "agent-knock-knock/claude-user-explicit-fallback-watch-anchor":
+            return watch.anchor.transcript_anchor.session_id;
+    }
+}
 function approvalFingerprint(terminal) {
     if (terminal.activity_state !== "awaiting_approval")
         return undefined;