@scotthuang/agent-knock-knock 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.10.0 - 2026-08-06
+
+### Added
+
+- Add capability-scoped native-thread lifecycle controls for starting or clearing context, listing verified same-workspace resume candidates, and resuming one exact Codex or Claude Code native thread in the existing tmux pane.
+- Add the optional OpenClaw tools `agent_knock_knock_new_thread`, `agent_knock_knock_list_resumable_threads`, and `agent_knock_knock_resume_thread`, plus `/akk new-thread`, `/akk clear-thread`, `/akk threads`, and `/akk resume-thread` human-facing commands.
+- Publish the v5 list/action contract with exact terminal lifecycle targets, complete native-thread identities, fresh compare-and-swap binding tokens, per-candidate evidence fingerprints, and capability-gated availability.
+
+### Changed
+
+- Keep ordinary sends scoped to the current native context: each accepted send creates a new Turn, while a successful native lifecycle transition creates or activates an AKK Session and creates no Turn.
+- Treat a sole historical Session whose recorded coding-agent PID has conclusively exited as resumable on the next lifecycle listing; the resume mutation compare-and-swap detaches that stale binding before terminal input, without background polling.
+- Let human-facing lifecycle slash commands fetch a fresh binding token internally immediately before mutation; plugin tools retain the explicit token so OpenClaw follows an auditable list-then-mutate flow.
+- Record terminal binding generations and native-thread transition lineage so sends after new/clear or resume target only the newly verified context.
+- Upgrade the Store writer protocol to v3. The first mutation of a v1 or v2 predecessor durably materializes authoritative Session records before publishing the new manifest, quarantines ambiguous bindings, and leaves existing Turn state and event logs unchanged.
+
+### Security
+
+- Serialize native-thread transitions against sends, approvals, monitors, callbacks, and recovery; require an exact idle terminal with no unresolved Turn and fail closed on unsupported, ambiguous, stale, active-elsewhere, or unverifiable native identity evidence.
+- Fence old monitors, receipts, approvals, callbacks, and recovery mutations to their original terminal incarnation, native thread, AKK Session, Turn, and binding generation.
+- Reject every first-line native slash command at the ordinary send/respond boundary before creating Session, Turn, ledger, or terminal side effects, including lifecycle-changing `/clear`, `/new`, `/resume`, Codex `/fork`/side threads, and Claude `/branch`.
+
+## 0.9.0 - 2026-08-05
+
+### Added
+
+- Add a durable AKK `session_id` for the continuing native coding-agent context and a unique `turn_id` for every accepted terminal dispatch.
+- Add an explicit `respond(turn_id, answer)` path for questions and blocked requests that must continue the same in-flight turn.
+
+### Changed
+
+- Make ordinary sends to an existing AKK Session target its `session_id` and create a new Turn, while managed status, approval, cancellation, retry, renewal, and close operations target an exact `turn_id`.
+- Keep first attach and raw-terminal control compatibility narrow and list-driven: an unmanaged row may prefill its own `selector` for initial send or `conversation_id` for an advertised raw status, approval, cancellation, or orphan-close action; callers must never construct, guess, or reuse either value.
+- Publish the v4 list/action contract with terminal → session → turn history, and include both identities in messages, callbacks, delivery ledgers, and recovery output.
+- Treat existing `conversation_id` values as legacy Store aliases; new records keep `conversation_id` equal to `turn_id`, while legacy records receive in-memory identity fallbacks.
+- Upgrade the Store writer protocol to v2 and atomically migrate exact v1 manifests on the first mutation while preserving legacy Turn records.
+
+### Security
+
+- Fail closed when native Codex or Claude Code session evidence is unavailable or changes, when persisted identity fields conflict, or when callback identity sources disagree.
+- Fence terminal receipts and late callbacks to the exact Store, Session, Turn, message, and native process incarnation so stale work cannot cross execution boundaries.
+
 ## 0.8.1 - 2026-08-03
 
 ### Fixed

package/README.md

@@ -53,7 +53,7 @@ The second command proves that AKK can find the one eligible idle pane, revalida
 
 **Delegate from anywhere.** Use any configured OpenClaw channel to hand work to a local coding agent while you are away from your computer. AKK reports when the agent needs attention or finishes, and you can continue from chat or the shared terminal.
 
-**Orchestrate specialist agents.** OpenClaw can coordinate handoffs: Claude Code can plan, Codex can implement, and Claude Code can review. At any point, you can take over the live terminal, keep working yourself, then hand the same task back to OpenClaw with its context intact.
+**Orchestrate specialist agents.** OpenClaw can coordinate handoffs: Claude Code can plan, Codex can implement, and Claude Code can review. At any point, you can take over the live terminal, keep working yourself, then hand the same native session back to OpenClaw with its context intact.
 
 ![Agent Knock Knock cover: OpenClaw knocking on coding agents' door](docs/assets/agent-knock-knock-cover.jpg)
 
@@ -61,14 +61,33 @@ The second command proves that AKK can find the one eligible idle pane, revalida
 
 AKK connects OpenClaw to Codex or Claude Code already running inside tmux:
 
-1. OpenClaw sends a task or follow-up through the AKK plugin.
-2. AKK finds an eligible agent pane and writes only the user-facing task into that terminal.
-3. AKK monitors the same pane for reliable approval, completion, cancellation, and failure evidence.
-4. AKK reports the result to the originating OpenClaw conversation.
-5. A human can attach to the same tmux session at any time and continue directly.
+1. OpenClaw selects an AKK session and sends the next user-facing request.
+2. AKK verifies the bound agent pane, creates a new Turn, and writes only that request into the terminal.
+3. AKK monitors the same pane for reliable approval, completion, cancellation, and failure evidence correlated to that Turn.
+4. AKK reports the result, `session_id`, and `turn_id` to the originating OpenClaw conversation.
+5. A human can attach to the same tmux terminal at any time and continue directly.
 
 AKK is local-first. It has no hosted control plane or telemetry and does not change the coding agent's configured permission mode.
 
+### Terminal, native session, AKK session, and Turn
+
+AKK keeps four identities separate:
+
+```text
+tmux terminal / process incarnation
+└─ native Codex or Claude Code session
+   └─ AKK session (session_id)
+      ├─ Turn 1 (turn_id)
+      ├─ Turn 2 (turn_id)
+      └─ Turn 3 (turn_id)
+```
+
+Once an AKK session exists, an ordinary `send(session_id, request)` creates a new `turn_id` while preserving the native coding-agent context. On first attach only, `send` may instead use a discovery selector explicitly named by the user, or the exact `selector` prefilled by an unmanaged raw-terminal row. AKK binds the verified native context to an AKK session before accepting the new Turn. Never infer a selector, copy one from another row, or pass one as `session_id`. The `turn_id` is not a destination for later ordinary sends; it is the exact identity used for status, approval, cancellation, renewal, callback retry, close, and callback correlation. If a Turn is `waiting_for_openclaw`, `respond(turn_id, answer)` supplies the answer inside that same Turn instead of creating another one.
+
+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 an AKK session already exists, `AKK list` pre-fills its authoritative `session_id` for send and the exact `turn_id` for managed controls. The same raw terminal row may advertise status, approval, cancellation, or orphan-close with its own prefilled `conversation_id` compatibility selector. Never infer, guess, or reuse compatibility selectors.
+
+Native clear/new/resume operations are explicit lifecycle actions, separate from ordinary Turn creation. A successful new/clear creates a new native thread and AKK Session; resume activates the exact historical native thread and its corresponding Session. Each successful lifecycle transition creates no Turn. The next ordinary send creates the first Turn in the selected context. AKK serializes the transition, verifies the resulting native identity, and advances the terminal binding generation so work and callbacks from the previous context cannot cross the boundary.
+
 ## Optional: Natural-Language Delegation
 
 The quick start uses direct `/akk ...` commands, which bypass the model and work without plugin tool access. To let OpenClaw decide to use AKK from a natural-language request, grant the optional `agent-knock-knock` tools in the applicable tool policy.
@@ -193,17 +212,26 @@ The core command surface is intentionally small:
 /akk <task>
 /akk <selector>: <message>
 /akk list
+/akk threads <exact-terminal-id>
+/akk new-thread <exact-terminal-id>
+/akk clear-thread <exact-terminal-id>
+/akk resume-thread <exact-terminal-id> [native-thread-uuid]
 /akk status [only|latest|codex|claude|@short-ref]
-/akk cancel <session-selector>
+/akk respond <turn-selector>: <answer>
+/akk cancel <turn-selector>
 ```
 
 `/akk list` performs a controlled reconciliation across managed turns, and `/akk status` limits reconciliation to the selected turn. This can close records whose idle retention has elapsed and restore eligible missing monitors, but it does not send terminal input or retry callback delivery. Standalone shell queries are read-only unless `--reconcile` is explicitly passed, and resolving a selector never changes turn state.
 
-Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and `codex` or `claude` must identify exactly one eligible pane. `AKK list` shows stable short references while JSON output retains the authoritative full IDs. Before every terminal operation, AKK revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories still match; every send also revalidates the idle prompt immediately before typing.
+Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and `codex` or `claude` must identify exactly one eligible pane. These names and `@short-ref` are human-facing resolution inputs; a natural-language tool call may preserve one explicitly named by the user, but must not infer one. Managed JSON actions contain the authoritative full `session_id` or `turn_id`. For first attach, an unmanaged raw-terminal row's send action may instead contain its own prefilled `selector`; its advertised raw controls may contain that row's prefilled `conversation_id`. Neither compatibility selector may be guessed, copied from another row, or passed in an authoritative ID field. Before every terminal operation, AKK revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories still match; every send also revalidates the idle prompt immediately before typing.
+
+To change native context, first copy the full `terminal_id` from `/akk list`; lifecycle commands do not accept `@short-ref` or loose agent selectors. `/akk threads <exact-terminal-id>` lists exact, same-workspace resume candidates. `/akk resume-thread <exact-terminal-id>` without a UUID shows the same candidates and asks you to choose; with a complete returned UUID it performs the transition. `/akk new-thread` and its human alias `/akk clear-thread` start a clean context. For these slash forms, AKK reads a fresh lifecycle snapshot and immediately supplies its compare-and-swap binding token internally, so you do not copy the token yourself. AKK does not poll bindings in the background: if a recorded owner process exits, the next lifecycle listing can classify that sole historical binding as resumable, and the resume mutation compare-and-swap detaches it before touching the terminal. Live, stale-token, unsupported, busy, ambiguous, active-elsewhere, or unverifiable transitions fail closed. Do not send `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, or `/btw`, Claude `/branch`, or any other first-line native slash command as an ordinary task or answer; use an advertised AKK action, express the request in natural language, or enter an unsupported native command manually in tmux.
+
+For natural-language tool use, `agent_knock_knock_list` is terminal-first. Each live pane appears exactly once in `terminals[]`; `process_state` reports whether its coding-agent process is alive and `activity_state` reports the parsed screen state. `managed.session_id` identifies the continuing AKK session, `managed.current_turn` is its optional active Turn, and `managed.recent_turn` is retained history; retained Turns do not occupy the terminal. Pass `all=true` to include older entries in `managed.history`. By default, `unavailable_managed_turns[]` contains attention-needed records whose pane cannot be presented as a live terminal; `all=true` also includes retained unavailable history.
 
-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. Its optional `managed.current_turn` is the authoritative active AKK turn, while `managed.recent_turn` is retained history and does not occupy the terminal. Pass `all=true` to include older entries in `managed.history`. By default, `unavailable_managed_turns[]` contains attention-needed records whose pane cannot be presented as a live terminal; `all=true` also includes retained unavailable history.
+Use only an `available_actions` entry returned in that snapshot, begin with its prefilled authoritative arguments, and supply every `missing_required` field. A managed Session's `send` uses its prefilled `session_id` and creates a new Turn. For first attach only, use a discovery selector explicitly named by the user or the unmanaged raw-terminal row's prefilled `selector`; do not infer or reuse one. `respond` is available only while a Turn is `waiting_for_openclaw`; it uses `turn_id` and keeps the answer inside that Turn. Managed status, approval, cancellation, renewal, callback retry, and close also use the exact `turn_id`. A raw terminal may be controlled only through the exact status, approval, cancellation, or orphan-close action that its own row advertises with a prefilled `conversation_id`; never construct or guess one. For an ordinary send, add only `request`—`timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK revalidates availability before every side effect.
 
-Use only an `available_actions` entry returned in that snapshot, begin with its prefilled authoritative arguments, and supply every `missing_required` field. A terminal's `send` action starts a new managed turn; a managed turn's `follow_up` action continues that exact turn through the same `agent_knock_knock_send` tool. Status, approval, cancellation, renewal, callback retry, and close use `conversation_id`. For an ordinary send or follow-up, add only `request`—`timeoutSeconds` is unsupported, and monitoring limits should be omitted unless the user explicitly asks to change them. AKK revalidates availability before every side effect.
+The top-level v5 `action_contracts` adds `list_resumable_threads`, `new_thread`, and `resume_thread`. The terminal row advertises `list_resumable_threads` and, when currently safe, `new_thread`. Listing is read-only, takes only the full `terminal_id`, and returns a fresh `expected_binding_token` plus candidate rows; each `resumable=true` candidate row advertises its own `resume_thread` action. The `new_thread` and `resume_thread` mutations require that fresh token, and resume additionally requires the candidate's complete `native_thread_id` and opaque `candidate_token`. Never construct, guess, truncate, combine across snapshots, or reuse those values after another terminal action. A lifecycle result contains Session and native-thread identities but no `turn_id` because no work was sent.
 
 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.
 
@@ -215,7 +243,7 @@ AKK works without project-specific plugin configuration. It reads these optional
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `storeDir` | `~/.agent-knock-knock/store` | Stable Store root for the compatibility manifest and managed conversations. |
+| `storeDir` | `~/.agent-knock-knock/store` | Stable Store root for the compatibility manifest, authoritative managed Sessions, and Turn records. |
 | `openclawBin` | Auto-detected | OpenClaw CLI used for callback delivery. |
 | `codexHome` | Auto-detected | Optional Codex home used to identify Codex sessions running in tmux. |
 | `idleTimeoutMinutes` | `10080` | Idle retention checked during controlled reconciliation. |
@@ -275,9 +303,9 @@ With the global npm CLI installed, start with `agent-knock-knock doctor`. It run
 | No eligible terminal is available | Start Codex or Claude Code inside tmux as the same OS user, then run `AKK list`. |
 | The npm installer or callbacks cannot find a local OpenClaw CLI | Set `openclawBin` and pass `--openclaw-bin` to `install-openclaw`. |
 | Source changes do not appear | Build, reinstall from the checkout, and restart the Gateway. |
-| Terminal task is `stalled` | Inspect `status` and the terminal; use `/akk renew only <minutes>` only when exactly one live stalled task needs more monitoring time. |
-| Task is `callback_failed` | Run `/akk retry-callback only` when it is the only actionable failed callback, or use its `@short-ref`. |
-| `AKK list` reports an orphaned terminal dispatch | Inspect the named pane first, then run the exact `/akk close ... --expected-message-id ...` recovery command returned by `list`. AKK leaves the coding agent and tmux pane running. |
+| Terminal Turn is `stalled` | Inspect `status` and the terminal; use `/akk renew only <minutes>` only when exactly one live stalled Turn needs more monitoring time. |
+| Turn is `callback_failed` | Run `/akk retry-callback only` when it is the only actionable failed callback, or use its `@short-ref`. |
+| `AKK list` reports an orphaned terminal dispatch or lifecycle transition | Inspect the named pane first, then run the exact `/akk close ...` recovery command returned by `list`. It contains exactly one fresh `--expected-message-id ...` or `--expected-transition-id ...` fence; do not construct, substitute, or reuse it. AKK leaves the coding agent and tmux pane running. |
 | Claude permission is not offered through AKK | Resolve unsupported dialogs in the terminal. The AKK path requires the exact supported one-time Bash prompt for the current managed turn. |
 | Claude request was not auto-approved | Check `autoApprove.enabled`, the agent, the rule's canonical `workspaces`, and the exact command vector. The request must also have matching current screen and local transcript evidence. |
 | Claude monitor becomes `stalled` | Check the Claude version and `status`, then inspect the terminal. Unknown transcript schemas, background work, identity changes, and ambiguous turns intentionally fail closed. |
@@ -319,11 +347,11 @@ gh workflow run clawhub-publish.yml --ref vX.Y.Z -f dry_run=false
 
 ## Storage and Logs
 
-Managed state now lives in the stable `~/.agent-knock-knock/store` root. Its manifest prevents an incompatible AKK writer from changing task state. Directories use mode `0700`; state and log files use `0600`.
+Managed state now lives in the stable `~/.agent-knock-knock/store` root. Its manifest prevents an incompatible AKK writer from changing authoritative Session or Turn state. Directories use mode `0700`; state and log files use `0600`.
 
-The manifest checks storage format and writer behavior separately. An unknown `format_version` is not read. When the format is readable but `writer_protocol` differs, normal queries remain available, explicit reconciliation reports `skipped`, and every mutation fails closed before terminal or Gateway side effects.
+The manifest checks storage format and writer behavior separately. An unknown `format_version` is not read. The current writer protocol is 3, and writer protocols 1 and 2 are its supported predecessors: inspection reports either as `upgradeable`. Before the first mutation publishes a protocol-3 manifest, AKK validates the predecessor Turn records, deterministically derives and durably materializes authoritative Session records, and quarantines ambiguous Session bindings instead of routing through them. Existing Turn state and event logs remain unchanged, and the manifest's `created_at` is preserved. Any other writer-protocol mismatch remains readable for normal queries, while explicit reconciliation reports `skipped` and every mutation fails closed before terminal or Gateway side effects.
 
-The former `~/.agent-knock-knock/conversations` directory is left untouched; AKK does not read or migrate it. Existing Codex and Claude Code tmux panes remain available through live discovery, while their old managed-turn IDs, callback associations, and follow-up records are not carried into the new Store. Compatible future upgrades continue using the stable Store rather than creating a directory per package version.
+The former `~/.agent-knock-knock/conversations` directory is left untouched; AKK does not read or migrate it. Existing Codex and Claude Code tmux panes remain available through live discovery, while their old managed-turn IDs, callback associations, and legacy conversation aliases are not carried into the new Store. Compatible future upgrades continue using the stable Store rather than creating a directory per package version.
 
 Runtime logs redact common secrets and default to 14-day retention. Configure storage and logging with `--store-dir`, `AKK_LOG_DIR`, `AKK_LOG_LEVEL`, and `AKK_LOG_RETENTION_DAYS`; use a dedicated custom log directory.
 

package/dist/src/agent-session-provider.d.ts

@@ -14,11 +14,24 @@ export interface AgentSessionCapabilities {
 export interface ForkContextOptions extends RolloutExcerptOptions {
     sessionId: string;
 }
+export interface ActiveAgentSessionIdentity {
+    sessionId: string;
+    processUuid?: string;
+    processBirth?: string;
+    rollout?: {
+        fd: string;
+        device: string;
+        inode: string;
+        path: string;
+    };
+    evidence: string;
+}
 export interface CodingAgentSessionProvider {
     agent: CodingAgentSessionProviderAgent;
     getCapabilities(): Promise<AgentSessionCapabilities>;
     listHistoricalSessions(): Promise<CodexSessionSummary[]>;
     listActiveSessions(): Promise<ActiveCodexProcess[]>;
+    resolveActiveSessionIdentityForPid(pid: number, cwd?: string, preferredSessionId?: string, allowedCompanionIdentity?: ActiveAgentSessionIdentity, allowedAdditionalIdentities?: readonly ActiveAgentSessionIdentity[]): Promise<ActiveAgentSessionIdentity | undefined>;
     getSession(sessionId: string): Promise<CodexSessionSummary | undefined>;
     getForkContext(options: ForkContextOptions): Promise<ForkContextPackage | undefined>;
 }

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

@@ -1,5 +1,5 @@
 import type { ClaudeAgentRow } from "./claude-terminal-agent-adapter.js";
-import type { TerminalCompletionEvidence, TerminalDurableCompletionRequest } from "./terminal-agent-adapter.js";
+import type { TerminalCompletionEvidence, TerminalDurableCompletionRequest, TerminalThreadLifecycleCandidate, TerminalThreadLifecycleCandidateProvider, TerminalThreadLifecycleCandidateRequest, TerminalThreadLifecycleCandidateToken, TerminalThreadLifecycleCandidateValidation, TerminalThreadFileToken } from "./terminal-agent-adapter.js";
 export interface ClaudeTranscriptAnchor {
     schema_version: 1;
     session_id: string;
@@ -26,6 +26,17 @@ export interface DetectClaudeTranscriptCompletionOptions {
     agentRows: readonly ClaudeAgentRow[];
     maxTurnBytes?: number;
 }
+export interface ClaudeHistoricalSessionSummary {
+    id: string;
+    cwd: string;
+    transcriptPath: string;
+    updatedAtMs: number;
+    claudeVersion: string;
+    rootInteractive: true;
+    fileToken: TerminalThreadFileToken;
+    metadataFingerprint: string;
+    candidateToken: TerminalThreadLifecycleCandidateToken;
+}
 /**
  * Process-local evidence for one pending, foreground Claude Bash permission.
  * `command` is intentionally raw so the caller can apply the exact command
@@ -47,6 +58,23 @@ export interface ClaudeTranscriptPendingApprovalEvidence {
     observedEndOffsetBytes: number;
 }
 export declare function defaultClaudeHome(): string;
+/** List exact, root-interactive Claude sessions from owner-private transcripts. */
+export declare function listClaudeHistoricalSessions(options: {
+    cwd: string;
+    claudeHome?: string;
+    agentVersion?: string;
+}): ClaudeHistoricalSessionSummary[];
+export declare function listClaudeThreadLifecycleCandidates(options: {
+    cwd: string;
+    claudeHome?: string;
+    agentVersion: string;
+}): TerminalThreadLifecycleCandidate[];
+export declare function createClaudeThreadLifecycleCandidateProvider(options?: {
+    claudeHome?: string;
+}): TerminalThreadLifecycleCandidateProvider;
+export declare function revalidateClaudeThreadLifecycleCandidate(candidate: TerminalThreadLifecycleCandidate | TerminalThreadLifecycleCandidateToken, options: TerminalThreadLifecycleCandidateRequest & {
+    claudeHome?: string;
+}): TerminalThreadLifecycleCandidateValidation;
 /**
  * Records the immutable file boundary immediately before AKK submits a turn.
  * No transcript contents are retained in conversation state.

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

@@ -11,10 +11,323 @@ const CLAUDE_TRANSCRIPT_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]
 const NO_FOLLOW_FLAG = typeof fs.constants.O_NOFOLLOW === "number"
     ? fs.constants.O_NOFOLLOW
     : 0;
+const CLAUDE_LIFECYCLE_VERSION = "2.1.218";
+const CLAUDE_HISTORICAL_METADATA_MAX_BYTES = 1024 * 1024;
 export function defaultClaudeHome() {
     const configured = process.env.CLAUDE_CONFIG_DIR?.trim();
     return configured || path.join(os.homedir(), ".claude");
 }
+/** List exact, root-interactive Claude sessions from owner-private transcripts. */
+export function listClaudeHistoricalSessions(options) {
+    if (!options.cwd || !path.isAbsolute(options.cwd)) {
+        throw new Error("Claude lifecycle candidate discovery requires an absolute cwd");
+    }
+    const cwd = path.resolve(options.cwd);
+    const claudeHome = path.resolve(options.claudeHome ?? defaultClaudeHome());
+    const agentVersion = options.agentVersion ?? CLAUDE_LIFECYCLE_VERSION;
+    if (agentVersion !== CLAUDE_LIFECYCLE_VERSION) {
+        throw new Error(`Claude lifecycle candidates require exact version ${CLAUDE_LIFECYCLE_VERSION}`);
+    }
+    const projectsRoot = projectsRootPath(claudeHome);
+    if (!isRealDirectory(projectsRoot)) {
+        return [];
+    }
+    const projectRelative = path.dirname(expectedTranscriptRelativePath("00000000-0000-0000-0000-000000000000", cwd));
+    const projectDirectory = path.join(projectsRoot, projectRelative);
+    if (!isRealDirectory(projectDirectory)) {
+        return [];
+    }
+    return fs.readdirSync(projectDirectory, { withFileTypes: true })
+        .flatMap((entry) => {
+        if (!entry.isFile() || entry.isSymbolicLink()) {
+            return [];
+        }
+        const match = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/iu.exec(entry.name);
+        if (!match) {
+            return [];
+        }
+        try {
+            const summary = inspectClaudeHistoricalSession({
+                projectsRoot,
+                cwd,
+                sessionId: match[1].toLowerCase(),
+                agentVersion
+            });
+            return summary ? [summary] : [];
+        }
+        catch {
+            // Unsafe, malformed, or unstable transcript files are not candidates.
+            return [];
+        }
+    })
+        .sort((left, right) => right.updatedAtMs - left.updatedAtMs);
+}
+export function listClaudeThreadLifecycleCandidates(options) {
+    return listClaudeHistoricalSessions(options).map((session) => ({
+        agent: "claude",
+        nativeThreadId: session.id,
+        cwd: session.cwd,
+        source: "claude_transcript",
+        rootInteractive: true,
+        fileToken: session.fileToken,
+        agentVersion: session.claudeVersion,
+        updatedAtMs: session.updatedAtMs,
+        metadataFingerprint: session.metadataFingerprint,
+        candidateToken: session.candidateToken
+    }));
+}
+export function createClaudeThreadLifecycleCandidateProvider(options = {}) {
+    return {
+        async listThreadLifecycleCandidates(request) {
+            return listClaudeThreadLifecycleCandidates({
+                cwd: request.cwd,
+                agentVersion: request.agentVersion,
+                claudeHome: options.claudeHome
+            });
+        },
+        async revalidateThreadLifecycleCandidate(candidate, request) {
+            return revalidateClaudeThreadLifecycleCandidate(candidate, {
+                ...request,
+                claudeHome: options.claudeHome
+            });
+        }
+    };
+}
+export function revalidateClaudeThreadLifecycleCandidate(candidate, options) {
+    try {
+        const token = "candidateToken" in candidate
+            ? candidate.candidateToken
+            : candidate;
+        if (token.schema !== "agent-knock-knock/thread-candidate-token" ||
+            token.version !== 1 ||
+            token.agent !== "claude" ||
+            token.source !== "claude_transcript" ||
+            token.agentVersion !== options.agentVersion ||
+            !path.isAbsolute(options.cwd) ||
+            !path.isAbsolute(token.cwd) ||
+            path.resolve(token.cwd) !== path.resolve(options.cwd) ||
+            !CLAUDE_SESSION_ID_PATTERN.test(token.nativeThreadId) ||
+            options.agentVersion !== CLAUDE_LIFECYCLE_VERSION) {
+            return {
+                status: "unsafe",
+                reason: "candidate is not an exact Claude root-interactive session"
+            };
+        }
+        const claudeHome = path.resolve(options.claudeHome ?? defaultClaudeHome());
+        const summary = inspectClaudeHistoricalSession({
+            projectsRoot: projectsRootPath(claudeHome),
+            cwd: path.resolve(options.cwd),
+            sessionId: token.nativeThreadId.toLowerCase(),
+            agentVersion: options.agentVersion
+        });
+        if (!summary) {
+            return {
+                status: "unavailable",
+                reason: "the Claude transcript no longer exists"
+            };
+        }
+        const current = {
+            agent: "claude",
+            nativeThreadId: summary.id,
+            cwd: summary.cwd,
+            source: "claude_transcript",
+            rootInteractive: true,
+            fileToken: summary.fileToken,
+            agentVersion: summary.claudeVersion,
+            updatedAtMs: summary.updatedAtMs,
+            metadataFingerprint: summary.metadataFingerprint,
+            candidateToken: summary.candidateToken
+        };
+        if (!sameClaudeThreadFileToken(token.fileToken, current.fileToken) ||
+            token.metadataFingerprint !== current.metadataFingerprint) {
+            return {
+                status: "changed",
+                candidate: current,
+                reason: "the Claude transcript changed after candidate discovery"
+            };
+        }
+        return { status: "valid", candidate: current };
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT") {
+            return {
+                status: "unavailable",
+                reason: "the Claude transcript no longer exists"
+            };
+        }
+        return {
+            status: "unsafe",
+            reason: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function inspectClaudeHistoricalSession({ projectsRoot, cwd, sessionId, agentVersion }) {
+    if (!isRealDirectory(projectsRoot) ||
+        !CLAUDE_SESSION_ID_PATTERN.test(sessionId) ||
+        agentVersion !== CLAUDE_LIFECYCLE_VERSION) {
+        return undefined;
+    }
+    const relativePath = expectedTranscriptRelativePath(sessionId, cwd);
+    const opened = openRelativeTranscript(projectsRoot, relativePath);
+    if (!opened) {
+        return undefined;
+    }
+    try {
+        const transcriptPath = fs.realpathSync(path.join(projectsRoot, opened.relativePath));
+        const realProjectsRoot = fs.realpathSync(projectsRoot);
+        const relative = path.relative(realProjectsRoot, transcriptPath);
+        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new Error("Claude transcript resolves outside the projects directory");
+        }
+        const metadata = readClaudeHistoricalMetadata(opened.fd, opened.stat.size);
+        if (!metadata) {
+            return undefined;
+        }
+        if (metadata.sessionId !== sessionId ||
+            !path.isAbsolute(metadata.cwd) ||
+            normalizePath(metadata.cwd) !== normalizePath(cwd) ||
+            metadata.version !== agentVersion ||
+            metadata.isSidechain !== false ||
+            metadata.entrypoint !== "cli" ||
+            metadata.agentId !== undefined ||
+            metadata.teamName !== undefined ||
+            metadata.loopSession ||
+            ![undefined, "interactive", "main"].includes(metadata.sessionKind)) {
+            return undefined;
+        }
+        const stable = fs.fstatSync(opened.fd);
+        if (stable.dev !== opened.stat.dev ||
+            stable.ino !== opened.stat.ino ||
+            stable.size !== opened.stat.size ||
+            stable.mtimeMs !== opened.stat.mtimeMs ||
+            fs.realpathSync(path.join(projectsRoot, opened.relativePath)) !==
+                transcriptPath) {
+            throw new Error("Claude transcript changed while it was inspected");
+        }
+        const fileToken = {
+            path: transcriptPath,
+            device: String(stable.dev),
+            inode: String(stable.ino),
+            size: stable.size,
+            mtimeMs: stable.mtimeMs
+        };
+        const metadataFingerprint = createHash("sha256")
+            .update(JSON.stringify({
+            sessionId,
+            cwd: path.resolve(cwd),
+            version: metadata.version,
+            entrypoint: metadata.entrypoint,
+            sessionKind: metadata.sessionKind ?? null,
+            transcriptPath
+        }))
+            .digest("hex");
+        const candidateToken = {
+            schema: "agent-knock-knock/thread-candidate-token",
+            version: 1,
+            agent: "claude",
+            nativeThreadId: sessionId,
+            cwd: path.resolve(cwd),
+            source: "claude_transcript",
+            agentVersion: metadata.version,
+            fileToken,
+            metadataFingerprint
+        };
+        return {
+            id: sessionId,
+            cwd: path.resolve(cwd),
+            transcriptPath,
+            updatedAtMs: stable.mtimeMs,
+            claudeVersion: metadata.version,
+            rootInteractive: true,
+            fileToken,
+            metadataFingerprint,
+            candidateToken
+        };
+    }
+    finally {
+        fs.closeSync(opened.fd);
+    }
+}
+function readClaudeHistoricalMetadata(fd, fileSize) {
+    if (fileSize <= 0 || !Number.isSafeInteger(fileSize)) {
+        return undefined;
+    }
+    const bytesToRead = Math.min(fileSize, CLAUDE_HISTORICAL_METADATA_MAX_BYTES);
+    const buffer = Buffer.allocUnsafe(bytesToRead);
+    const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, 0);
+    if (bytesRead !== bytesToRead) {
+        throw new Error("Claude transcript changed while metadata was read");
+    }
+    const text = buffer.subarray(0, bytesRead).toString("utf8");
+    const lastCompleteNewline = text.lastIndexOf("\n");
+    if (lastCompleteNewline < 0) {
+        if (fileSize > bytesRead) {
+            throw new Error("Claude transcript metadata line exceeds the read limit");
+        }
+        return undefined;
+    }
+    const completeLines = text.slice(0, lastCompleteNewline).split("\n");
+    for (const line of completeLines) {
+        if (!line.trim()) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error("Claude transcript contains invalid root metadata JSONL");
+        }
+        if (!isRecord(parsed)) {
+            throw new Error("Claude transcript root metadata must be an object");
+        }
+        const sessionId = nonEmptyString(parsed.sessionId);
+        if (!sessionId) {
+            continue;
+        }
+        const cwd = nonEmptyString(parsed.cwd);
+        const version = nonEmptyString(parsed.version);
+        const entrypoint = nonEmptyString(parsed.entrypoint);
+        const hasIdentityMetadata = cwd !== undefined ||
+            version !== undefined ||
+            entrypoint !== undefined ||
+            typeof parsed.isSidechain === "boolean" ||
+            nonEmptyString(parsed.agentId) !== undefined ||
+            nonEmptyString(parsed.teamName) !== undefined ||
+            nonEmptyString(parsed.sessionKind) !== undefined;
+        if (!hasIdentityMetadata) {
+            // Claude 2.1.218 can prepend mode/permission-mode records carrying only
+            // sessionId. Continue to the first full root transcript record.
+            continue;
+        }
+        if (!cwd || !version || !entrypoint || typeof parsed.isSidechain !== "boolean") {
+            throw new Error("Claude transcript has incomplete root session metadata");
+        }
+        const sessionKind = nonEmptyString(parsed.sessionKind);
+        return {
+            sessionId: sessionId.toLowerCase(),
+            cwd,
+            version,
+            isSidechain: parsed.isSidechain,
+            entrypoint,
+            agentId: nonEmptyString(parsed.agentId),
+            teamName: nonEmptyString(parsed.teamName),
+            sessionKind,
+            loopSession: parsed.isLoop === true ||
+                parsed.isLoopSession === true ||
+                parsed.loopSession === true ||
+                sessionKind === "loop"
+        };
+    }
+    return undefined;
+}
+function sameClaudeThreadFileToken(left, right) {
+    return left.path === right.path &&
+        left.device === right.device &&
+        left.inode === right.inode &&
+        left.size === right.size &&
+        left.mtimeMs === right.mtimeMs;
+}
 /**
  * Records the immutable file boundary immediately before AKK submits a turn.
  * No transcript contents are retained in conversation state.