@scotthuang/agent-knock-knock 0.12.8 → 0.12.11

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.12.11 - 2026-08-14
+
+### Fixed
+
+- Allow managed close to retire a Turn when its exact bound Codex or Claude Code process is conclusively absent, without falling into the managed/raw close deadlock.
+- Stop terminal-monitor relaunch loops for verified-dead accepted Turns, while preserving completion-first settlement when the exact rollout or transcript already contains a durable result.
+- Recover verified-dead stall and close transitions idempotently across event/state/ledger crash windows without replaying terminal input.
+
+### Security
+
+- Require a complete process inventory, exact Session and Turn binding generation, canonical terminal endpoint, process incarnation, dispatch ledger, and append-only native-acceptance receipts before dead-process cleanup; malformed, partial, conflicting, or unavailable evidence remains fail-closed.
+- Distinguish durable completion as present, absent, or unverifiable for both Codex rollouts and Claude transcripts. Unverifiable evidence may stop orphan-monitor churn but cannot resolve the dispatch, renew the Turn, or trigger terminal input.
+
+### Changed
+
+- Keep action contract 16 and Store writer protocol 5 unchanged; no new public action or Store authority is introduced.
+
+## 0.12.10 - 2026-08-13
+
+### Fixed
+
+- Scope Codex and Claude Code approval fingerprints to one adapter-isolated, exact unredacted prompt region, so unrelated terminal output can continue scrolling across review, authorization, and dispatch reservation without invalidating the same visible request.
+- Normalize managed approval locking to terminal, Store writer, then Turn state order, eliminating the writer/state inversion that could amplify approval delays under concurrent monitor activity.
+- Support the complete Codex 0.147 command, edit, permission, and MCP approval menus, including multi-choice decline/cancel rows and the permission deny shortcut.
+
+### Changed
+
+- Publish action contract 16. Whole-screen digests and excerpts are diagnostic only; v15 approval fingerprints and terminal-scoped approval tokens require a fresh `list` or `status` after upgrade.
+- Store writer protocol remains 5.
+
+### Security
+
+- Revalidate the exact prompt-region digest with terminal, process, action, request, policy, and working-directory authority before approval input; missing, incomplete, duplicated, reordered, spoofed, or changed prompt evidence sends zero keys.
+- Keep raw prompt text local to the adapter and out of status, Store records, tokens, logs, and failure diagnostics; only its SHA-256 digest participates in authorization.
+
 ## 0.12.8 - 2026-08-13
 
 ### Fixed

package/README.md

@@ -89,6 +89,8 @@ v15 generalizes the human-priority Codex path. It covers a status-card-only Sess
 
 v15 also preserves the separation between human-confirmed Codex approval and managed attribution. When `list` can prove one exact visible Codex approval prompt, it may advertise a terminal-scoped `approve` even when the foreground rollout UUID is temporarily unavailable. The authority may be either one exact current AKK dispatch owner or one exact bound managed Session whose dispatch owner is already released; the latter covers a task that the human entered directly in the pane. After the user reviews the current `status` fingerprint and explicitly confirms, AKK revalidates the Store/terminal/process snapshot, token, and approval fingerprint immediately before sending the exact key once. This action does not attribute the approval to a Turn, mutate Session identity, or create a durable approval receipt, so an uncertain transport result must not be retried blindly. It is never available to auto-approve. Known native-thread changes, unresolved dispatches, transitions, stale tokens, or changed prompts remain blocked.
 
+v16 makes that approval fingerprint prompt-scoped. The authority hashes the adapter-isolated, exact unredacted approval region together with the terminal/process identity, decision keys and label, prompt kind, working directory, reason/detail, and any request or policy evidence. The whole-screen digest and redacted excerpt remain diagnostic only: test output or other scrollback outside the approval region may change before execution, after authorization, or after the at-most-once dispatch reservation without invalidating the same reviewed prompt. A change inside the region—including the command or an otherwise identically redacted secret, choices, highlighted option, prompt kind, or request identity—or a change in the bound process, working directory, or request evidence still rejects with zero approval keys. If the adapter cannot isolate one complete bounded prompt region, approval fails closed. The raw prompt region is never returned, persisted, or logged. Fingerprints and terminal-scoped approval tokens issued under v15's whole-screen authority are intentionally stale; refresh `list` and `status` before approving after upgrade.
+
 Human-friendly selectors such as `only`, `codex`, `claude`, a terminal ID, or `@short-ref` remain a discovery layer. A natural-language tool call may preserve one only when the user explicitly named it; otherwise use the exact selector returned by `AKK list`, or omit it and require a unique eligible pane. When strict continuation is safe, a managed row pre-fills its authoritative `session_id`; a rollout-backed Codex row instead uses the exact terminal selector and `expected_terminal_token` for follow-current continuation. Merely observing a mismatch or an unbound rollout inventory never mutates the Store. AKK advertises the fenced send only when it can prove a single source claim, an exact live terminal/process incarnation, an idle empty composer, a stable complete rollout inventory, and no unresolved Turn, transition, dispatch, or approval. A foreground ambiguity inside that complete inventory may be resolved after the real request is accepted; incomplete, stale, or unverifiable evidence remains blocked. The same terminal row may advertise status, manual approval, cancellation, or orphan-close with its own prefilled `conversation_id` compatibility selector and, where required, a fresh token. Never infer, guess, or reuse compatibility selectors or tokens.
 
 An exact human switch while the old Session still has one active Turn is a decision point, not an automatic redirect. In that case the terminal row may expose `handoff_decision` instead of a follow-current send. Its nested `choices.take_over_current.action` is the only authoritative supersede action: after explicit user confirmation, invoke its complete `agent_knock_knock_close` arguments unchanged (`turn_id`, `reason="superseded_by_human_context_switch"`, and `expected_handoff_token`). The snapshot-bound close records the old Turn's disposition and sends no terminal input. Then list again and use only the newly advertised follow-current send; never chain the old token into a send. Choosing `keep_source` changes no AKK state: restore the old native thread in the Codex or Claude TUI, then refresh the list. A completed/changed Turn or another human thread switch makes the decision token stale and requires a fresh decision.
@@ -242,13 +244,13 @@ To ask AKK itself to change native context, first copy the full `terminal_id` fr
 
 To request a native Codex status card or Claude Status panel, first run `agent_knock_knock_list` and use only that terminal row's advertised `native_inspect` action. The structured tool schema is closed to `inspection="status"`; callers cannot provide `/status` or another slash command as text. AKK serializes the inspection with terminal mutations, revalidates the fresh token and exact terminal identity, and returns only after it proves one fresh bounded status result and an idle postcondition. Codex status probes additionally require an exact viewport of at least 80 columns to preserve the full Session UUID, cross the versioned paste-settle boundary, and dispatch Enter exactly once. An initially narrow or unknown viewport fails before text input with a widen/zoom diagnostic; post-injection viewport or composer drift fails closed before Enter and leaves the draft for manual inspection. Codex `/status` and that viewport requirement apply only to operations that must prove the UUID before terminal input. An otherwise eligible terminal-scoped ordinary task can send once and bind from exact native acceptance afterward, so it does not run `/status` or fail merely because the pane is narrow. For Claude, the inspection safely dismisses the exact modal once. It never turns ordinary `send` or `respond` into a slash-command escape hatch.
 
-The top-level v15 `action_contracts` documents this closed inspection alongside human-priority current-pane send/approval, lifecycle, and Turn actions. `available_actions` remains the authority for ordinary current actions. Two deliberate nested exceptions require explicit user confirmation: an active human-handoff conflict may expose the snapshot-bound `handoff_decision.choices.take_over_current.action`, while a collateral terminal-wide unresolved Turn may appear in `blocking_turns[]` with its exact Store-only `recovery_action`. An active handoff source Turn is never generically closable through `blocking_turns`; it remains governed only by the snapshot-bound handoff decision. Copy only the complete listed action, then refresh the list before doing anything else.
+The top-level v16 `action_contracts` documents this closed inspection alongside human-priority current-pane send/approval, lifecycle, and Turn actions. `available_actions` remains the authority for ordinary current actions. Two deliberate nested exceptions require explicit user confirmation: an active human-handoff conflict may expose the snapshot-bound `handoff_decision.choices.take_over_current.action`, while a collateral terminal-wide unresolved Turn may appear in `blocking_turns[]` with its exact Store-only `recovery_action`. An active handoff source Turn is never generically closable through `blocking_turns`; it remains governed only by the snapshot-bound handoff decision. Copy only the complete listed action, then refresh the list before doing anything else.
 
 For natural-language tool use, `agent_knock_knock_list` is terminal-first. Each live pane appears exactly once in `terminals[]`; `process_state` reports whether its coding-agent process is alive and `activity_state` reports the parsed screen state. `managed.session_id` identifies the continuing AKK session, `managed.current_turn` is its optional active Turn, and `managed.recent_turn` is retained history; retained Turns do not occupy the terminal. A human-driven native-thread mismatch remains honestly classified as `management_state="conflict"`; its `handoff_state` is `external_handoff_adoptable` only when the row advertises the fenced follow-current `send`, otherwise it is `external_handoff_blocked`. Listing never performs the adoption. Pass `all=true` to include older entries in `managed.history`. By default, `unavailable_managed_turns[]` contains attention-needed records whose pane cannot be presented as a live terminal; `all=true` also includes retained unavailable history.
 
 Use only an `available_actions` entry returned in that snapshot, begin with its prefilled authoritative arguments, and supply every `missing_required` field. The only additional action sources are a terminal row's nested `handoff_decision.choices.take_over_current.action` and an exact `blocking_turns[].recovery_action`; both require explicit user confirmation and must be copied whole. When advertised, a managed Session's strict `send` uses its prefilled `session_id` and creates a new Turn only in that Session's native context. A terminal-scoped follow-current `send` instead carries the selected row's exact full `selector` and `expected_terminal_token`; preserve both and add only `request`. This is the human-priority path when the pane is exact but its foreground Codex UUID is not yet attributable. Legacy first attach may still use a discovery selector explicitly named by the user or the unmanaged raw-terminal row's prefilled `selector`; do not infer or reuse one. `respond` is available only while a Turn is `waiting_for_openclaw`; it uses `turn_id` and keeps the answer inside that Turn. Managed status, approval, cancellation, renewal, callback retry, and close also use the exact `turn_id`. Native inspection instead uses the exact terminal row's `terminal_id`, closed `inspection`, and snapshot-bound `expected_binding_token`; do not substitute AKK status or ordinary send. A terminal-scoped manual Codex approval may use the exact listed `conversation_id` plus `expected_terminal_token` and the latest status fingerprint; it never authorizes auto-approve or changes managed identity. Other raw controls may be used only through the exact action their row advertises. `timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK revalidates availability before every side effect.
 
-The top-level v15 action contracts include `send`, manual `approve`, `native_inspect`, `list_resumable_threads`, `new_thread`, `resume_thread`, and the conflict-only `reconcile_binding` recovery action. `send` has two deliberately different managed scopes: `session_exact` uses `session_id` for strict context, while `terminal_follow_current` uses the exact terminal `selector` plus `expected_terminal_token` for follow-current current-pane context. Manual Codex approval likewise has a strict managed-Turn form and a separately advertised terminal-scoped form; only the latter carries the terminal token, and neither permits the model to enable automatic approval. A supported idle Codex or Claude Code terminal may advertise `native_inspect` with its exact terminal ID, the closed `status` inspection kind, and a fresh binding token. The terminal row also advertises `list_resumable_threads` and, when currently safe, `new_thread`. Thread listing is read-only with respect to Session/Turn state, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` row retains its complete UUID and exact prefilled `resume_thread` action. If `previous` is present, use only its exact prefilled action for a natural-language “刚才那个” request. Numbers, short IDs, and handles are human display/navigation aids, never tool arguments or authoritative native identity. The `new_thread` and `resume_thread` mutations require the fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. `reconcile_binding` remains a low-level compatibility/recovery action for a safely detachable conflict when no ordinary follow-current send is appropriate; it never adopts the replacement thread, sends terminal input, or creates a Turn. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. Native inspection and lifecycle results contain no `turn_id` because no work was sent.
+The top-level v16 action contracts include `send`, manual `approve`, `native_inspect`, `list_resumable_threads`, `new_thread`, `resume_thread`, and the conflict-only `reconcile_binding` recovery action. `send` has two deliberately different managed scopes: `session_exact` uses `session_id` for strict context, while `terminal_follow_current` uses the exact terminal `selector` plus `expected_terminal_token` for follow-current current-pane context. Manual Codex approval likewise has a strict managed-Turn form and a separately advertised terminal-scoped form; only the latter carries the terminal token, and neither permits the model to enable automatic approval. A supported idle Codex or Claude Code terminal may advertise `native_inspect` with its exact terminal ID, the closed `status` inspection kind, and a fresh binding token. The terminal row also advertises `list_resumable_threads` and, when currently safe, `new_thread`. Thread listing is read-only with respect to Session/Turn state, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` row retains its complete UUID and exact prefilled `resume_thread` action. If `previous` is present, use only its exact prefilled action for a natural-language “刚才那个” request. Numbers, short IDs, and handles are human display/navigation aids, never tool arguments or authoritative native identity. The `new_thread` and `resume_thread` mutations require the fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. `reconcile_binding` remains a low-level compatibility/recovery action for a safely detachable conflict when no ordinary follow-current send is appropriate; it never adopts the replacement thread, sends terminal input, or creates a Turn. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. Native inspection and lifecycle results contain no `turn_id` because no work was sent.
 
 Workspace is not a routing boundary. AKK can list, inspect, and control verified panes across projects; when more than one target matches, use a selector to choose one explicitly.
 

package/dist/src/claude-local-transcript-provider.d.ts

@@ -1,6 +1,6 @@
 import type { ClaudeAgentRow } from "./claude-terminal-agent-adapter.js";
 import type { TerminalCompletionEvidence, TerminalDurableCompletionRequest, TerminalThreadLifecycleCandidate, TerminalThreadLifecycleCandidateProvider, TerminalThreadLifecycleCandidateRequest, TerminalThreadLifecycleCandidateToken, TerminalThreadLifecycleCandidateValidation, TerminalThreadFileToken } from "./terminal-agent-adapter.js";
-import type { TerminalSubmissionAcceptanceEvidence } from "./terminal-submission-acceptance.js";
+import { type TerminalSubmissionAcceptanceEvidence } from "./terminal-submission-acceptance.js";
 export interface ClaudeTranscriptAnchor {
     schema_version: 1;
     session_id: string;
@@ -27,6 +27,18 @@ export interface DetectClaudeTranscriptCompletionOptions {
     agentRows: readonly ClaudeAgentRow[];
     maxTurnBytes?: number;
 }
+export interface ObserveClaudeDeadProcessCompletionOptions extends DetectClaudeTranscriptCompletionOptions {
+    acceptanceEvidence: unknown;
+}
+export type ClaudeDeadProcessCompletionObservation = {
+    status: "present";
+    completion: TerminalCompletionEvidence;
+} | {
+    status: "absent";
+} | {
+    status: "unverifiable";
+    reason: string;
+};
 export interface ClaudeHistoricalSessionSummary {
     id: string;
     cwd: string;
@@ -95,6 +107,14 @@ export declare function captureClaudeTranscriptAnchor(options: CaptureClaudeTran
  * background-work, and chain ambiguity.
  */
 export declare function detectClaudeTranscriptCompletion(request: TerminalDurableCompletionRequest, options: DetectClaudeTranscriptCompletionOptions): TerminalCompletionEvidence | undefined;
+/**
+ * Observes completion after the exact bound Claude process is independently
+ * proven dead. Unlike the ordinary live monitor detector, this API separates
+ * a stable, fully inspected transcript with no completion from a transcript
+ * that cannot be inspected or tied back to the durable native-acceptance
+ * receipt. Callers may treat only `absent` as authority for orphan cleanup.
+ */
+export declare function observeClaudeDeadProcessTranscriptCompletion(request: TerminalDurableCompletionRequest, options: ObserveClaudeDeadProcessCompletionOptions): ClaudeDeadProcessCompletionObservation;
 /**
  * Detects native acceptance as soon as Claude appends the unique root user
  * row matching the managed request after the immutable pre-send byte anchor.

package/dist/src/claude-local-transcript-provider.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { claudeLifecycleBehaviorProfile, claudeLifecycleSourceVersionSupported, DEFAULT_CLAUDE_LIFECYCLE_VERSION, supportedClaudeLifecycleVersions } from "./claude-lifecycle-compatibility.js";
 import { redactString } from "./runtime-log.js";
+import { validateTerminalSubmissionAcceptanceEvidence } from "./terminal-submission-acceptance.js";
 const CLAUDE_TRANSCRIPT_ANCHOR_VERSION = 1;
 const CLAUDE_TRANSCRIPT_MAX_TURN_BYTES = 64 * 1024 * 1024;
 const CLAUDE_SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
@@ -440,6 +441,46 @@ export function detectClaudeTranscriptCompletion(request, options) {
     }
     return completionFromRecords(snapshot);
 }
+/**
+ * Observes completion after the exact bound Claude process is independently
+ * proven dead. Unlike the ordinary live monitor detector, this API separates
+ * a stable, fully inspected transcript with no completion from a transcript
+ * that cannot be inspected or tied back to the durable native-acceptance
+ * receipt. Callers may treat only `absent` as authority for orphan cleanup.
+ */
+export function observeClaudeDeadProcessTranscriptCompletion(request, options) {
+    try {
+        const snapshot = readClaudeTranscriptTurnSnapshot(request, options, "idle", "verified_dead_process");
+        if (!snapshot) {
+            return {
+                status: "unverifiable",
+                reason: "Claude transcript could not be read with exact dead-process authority"
+            };
+        }
+        const observedAcceptance = acceptanceEvidenceFromSnapshot(snapshot);
+        if (!observedAcceptance) {
+            throw new Error("the exact accepted Claude prompt is absent from the anchored transcript");
+        }
+        const persistedAcceptance = validateTerminalSubmissionAcceptanceEvidence(options.acceptanceEvidence, {
+            source: "claude_transcript",
+            nativeThreadId: snapshot.sessionId,
+            requestHash: snapshot.expectedRequestHash
+        });
+        assertSameClaudeTranscriptAcceptance(persistedAcceptance, observedAcceptance, snapshot);
+        const completion = completionFromRecords(snapshot, {
+            requireVerifiableCompletionSignal: true
+        });
+        return completion
+            ? { status: "present", completion }
+            : { status: "absent" };
+    }
+    catch (error) {
+        return {
+            status: "unverifiable",
+            reason: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
 /**
  * Detects native acceptance as soon as Claude appends the unique root user
  * row matching the managed request after the immutable pre-send byte anchor.
@@ -451,6 +492,9 @@ export function detectClaudeTranscriptAcceptance(request, options) {
     if (!snapshot) {
         return undefined;
     }
+    return acceptanceEvidenceFromSnapshot(snapshot);
+}
+function acceptanceEvidenceFromSnapshot(snapshot) {
     const prompt = matchingManagedPrompt(snapshot);
     if (!prompt) {
         return undefined;
@@ -483,6 +527,35 @@ export function detectClaudeTranscriptAcceptance(request, options) {
         evidenceFingerprint: sha256Hex(JSON.stringify(evidenceBase))
     };
 }
+function assertSameClaudeTranscriptAcceptance(persisted, observed, snapshot) {
+    const persistedMetadata = isRecord(persisted.metadata)
+        ? persisted.metadata
+        : undefined;
+    const observedMetadata = isRecord(observed.metadata)
+        ? observed.metadata
+        : undefined;
+    const persistedEndOffset = nonNegativeInteger(persistedMetadata?.observed_end_offset_bytes);
+    if (persisted.source !== "claude_transcript" ||
+        persisted.kind !== "native_user_turn" ||
+        persisted.acceptanceId !== observed.acceptanceId ||
+        persisted.acceptedAt !== observed.acceptedAt ||
+        persisted.anchorFingerprint !== observed.anchorFingerprint ||
+        !persistedMetadata ||
+        !observedMetadata ||
+        persistedMetadata.prompt_uuid !== observedMetadata.prompt_uuid ||
+        persistedMetadata.claude_version !== observedMetadata.claude_version ||
+        persistedMetadata.transcript_file_id !==
+            observedMetadata.transcript_file_id ||
+        persistedMetadata.anchor_offset_bytes !==
+            observedMetadata.anchor_offset_bytes ||
+        persistedMetadata.agent_started_at_ms !==
+            observedMetadata.agent_started_at_ms ||
+        persistedEndOffset === undefined ||
+        persistedEndOffset <= snapshot.anchor.offset_bytes ||
+        persistedEndOffset > snapshot.observedEndOffsetBytes) {
+        throw new Error("persisted Claude acceptance evidence does not match the exact anchored prompt");
+    }
+}
 /**
  * Detects exactly one unresolved foreground Bash tool use for the current
  * AKK-managed Claude turn. It uses the same anchored, owner-private,
@@ -496,10 +569,16 @@ export function detectClaudeTranscriptPendingApproval(request, options) {
     }
     return pendingApprovalFromRecords(snapshot);
 }
-function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus) {
+function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus, readMode = "live_monitor") {
+    const unavailable = (reason) => {
+        if (readMode === "verified_dead_process") {
+            throw new Error(reason);
+        }
+        return undefined;
+    };
     const anchor = transcriptAnchorFromContext(request.context);
     if (!anchor) {
-        return undefined;
+        return unavailable("Claude transcript anchor is unavailable");
     }
     const sessionId = nonEmptyString(request.sessionId);
     const cwd = nonEmptyString(request.cwd);
@@ -516,7 +595,7 @@ function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus)
         expectedRequestHash !== requestTextHash ||
         startedAtMs === undefined ||
         capturedAtMs === undefined) {
-        return undefined;
+        return unavailable("Claude transcript request metadata cannot be verified");
     }
     if (anchor.schema_version !== CLAUDE_TRANSCRIPT_ANCHOR_VERSION ||
         anchor.session_id !== sessionId ||
@@ -538,15 +617,15 @@ function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus)
         throw new Error("the Claude process session identity changed after the managed send");
     }
     if (requiredAgentStatus && agent.status !== requiredAgentStatus) {
-        return undefined;
+        return unavailable(`the exact Claude process is ${agent.status}, not ${requiredAgentStatus}`);
     }
     const projectsRoot = projectsRootPath(path.resolve(options.claudeHome ?? defaultClaudeHome()));
     if (!isRealDirectory(projectsRoot)) {
-        return undefined;
+        return unavailable("Claude transcript projects directory is unavailable");
     }
     const opened = openAnchoredTranscript(projectsRoot, anchor);
     if (!opened) {
-        return undefined;
+        return unavailable("the anchored Claude transcript is unavailable");
     }
     try {
         if (anchor.file_existed &&
@@ -558,20 +637,24 @@ function readClaudeTranscriptTurnSnapshot(request, options, requiredAgentStatus)
         }
         const bytesToRead = opened.stat.size - anchor.offset_bytes;
         if (bytesToRead === 0) {
-            return undefined;
+            return unavailable("the anchored Claude transcript contains no post-send records");
         }
         const maxTurnBytes = positiveInteger(options.maxTurnBytes) ??
             CLAUDE_TRANSCRIPT_MAX_TURN_BYTES;
         if (bytesToRead > maxTurnBytes) {
             throw new Error("Claude transcript turn exceeded the bounded local read limit");
         }
+        if (readMode === "verified_dead_process" &&
+            !fileEndsWithNewline(opened.fd, opened.stat.size)) {
+            throw new Error("Claude transcript ends with an incomplete JSONL record");
+        }
         const records = readCompleteJsonlRecords(opened.fd, anchor.offset_bytes, bytesToRead);
         const stableStat = fs.fstatSync(opened.fd);
         if (!sameStableTranscriptFile(opened.stat, stableStat)) {
-            return undefined;
+            return unavailable("Claude transcript changed while dead-process completion was inspected");
         }
         if (records.length === 0) {
-            return undefined;
+            return unavailable("Claude transcript contains no complete post-send records");
         }
         const fileIdentity = `${opened.stat.dev}:${opened.stat.ino}`;
         return {
@@ -618,7 +701,7 @@ function matchingManagedPrompt(snapshot) {
     assertSupportedRecord(prompt, snapshot.sessionId, snapshot.cwd);
     return prompt;
 }
-function completionFromRecords(snapshot) {
+function completionFromRecords(snapshot, options = {}) {
     const { records, sessionId, transcriptFileId: fileId } = snapshot;
     const prompt = matchingManagedPrompt(snapshot);
     if (!prompt) {
@@ -636,7 +719,20 @@ function completionFromRecords(snapshot) {
         record.isSidechain !== true &&
         nonEmptyString(record.agentId) === undefined &&
         userPromptText(record) !== undefined);
+    if (options.requireVerifiableCompletionSignal === true &&
+        nextHumanPromptIndex >= 0) {
+        const nextHumanPrompt = records[nextHumanPromptIndex];
+        if (!nextHumanPrompt || uuidValue(nextHumanPrompt.uuid) === undefined) {
+            throw new Error("Claude transcript next human prompt has no stable UUID");
+        }
+        assertSupportedRecord(nextHumanPrompt, sessionId, snapshot.cwd);
+    }
     const turnRecords = records.slice(promptIndex, nextHumanPromptIndex < 0 ? records.length : nextHumanPromptIndex);
+    if (options.requireVerifiableCompletionSignal === true &&
+        turnRecords.some((record) => (["user", "assistant", "system"].includes(String(record.type)) ||
+            hasTurnCompletionSignal(record)) && uuidValue(record.uuid) === undefined)) {
+        throw new Error("Claude transcript turn contains a completion-relevant record without a stable UUID");
+    }
     const recordsByUuid = new Map();
     for (const record of turnRecords) {
         const uuid = uuidValue(record.uuid);
@@ -658,16 +754,23 @@ function completionFromRecords(snapshot) {
         assertSupportedRecord(record, sessionId);
     }
     assertSameClaudeVersion(...descendants);
+    const absentOrUnverifiable = () => {
+        if (options.requireVerifiableCompletionSignal === true &&
+            descendants.some(hasTurnCompletionSignal)) {
+            throw new Error("Claude transcript contains a completion signal without one complete verifiable completion chain");
+        }
+        return undefined;
+    };
     if (descendants.some((record) => record.isSidechain === true ||
         nonEmptyString(record.agentId) !== undefined ||
         hasUnresolvedBackgroundWork(record))) {
-        return undefined;
+        return absentOrUnverifiable();
     }
     if (hasUnresolvedToolUse(descendants)) {
-        return undefined;
+        return absentOrUnverifiable();
     }
     if (descendants.some(hasBlockingStopSummary)) {
-        return undefined;
+        return absentOrUnverifiable();
     }
     const durations = descendantRecords(turnRecords, recordsByUuid, promptUuid, (record) => record.type === "system" && record.subtype === "turn_duration");
     if (durations.length > 1) {
@@ -682,7 +785,7 @@ function completionFromRecords(snapshot) {
         const lastDescendant = [...turnRecords].reverse().find((record) => uuidValue(record.uuid) !== undefined &&
             descendantChain(recordsByUuid, promptUuid, record) !== undefined);
         if (!failure || failure !== lastDescendant) {
-            return undefined;
+            return absentOrUnverifiable();
         }
         assertSupportedRecord(failure, sessionId);
         assertSameClaudeVersion(prompt, failure);
@@ -711,7 +814,7 @@ function completionFromRecords(snapshot) {
     }
     const chain = descendantChain(recordsByUuid, promptUuid, duration);
     if (!chain) {
-        return undefined;
+        return absentOrUnverifiable();
     }
     const finalAssistant = [...chain].reverse().find((record) => record.type === "assistant" &&
         isRecord(record.message) &&
@@ -731,6 +834,9 @@ function completionFromRecords(snapshot) {
     }
     const assistantText = assistantTextForMessage(turnRecords, recordsByUuid, promptUuid, finalAssistant);
     if (!assistantText) {
+        if (options.requireVerifiableCompletionSignal === true) {
+            throw new Error("Claude completion signal has no verifiable assistant text");
+        }
         return undefined;
     }
     const promptId = nonEmptyString(prompt.promptId);