@scotthuang/agent-knock-knock 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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

package/README.md

@@ -82,9 +82,11 @@ tmux terminal / process incarnation
       └─ 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, an unmanaged raw-terminal row may instead offer `send` with that row's prefilled `selector`; AKK binds the verified native context to an AKK session before accepting the new Turn. Never construct, guess, or copy that selector from another row. 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.
+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. When an AKK session already exists, `AKK list` pre-fills its authoritative `session_id` for send and the exact `turn_id` for managed controls. A first-attach send from an unmanaged raw-terminal row uses only that row's prefilled `selector`. The same row may advertise a raw status, approval, cancellation, or orphan-close action with its own prefilled `conversation_id` compatibility selector. Use only the exact returned action and never construct, guess, or reuse either compatibility selector. Native clear/new/resume operations are separate lifecycle features and are not performed as part of ordinary Turn creation.
+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
 
@@ -210,6 +212,10 @@ 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 respond <turn-selector>: <answer>
 /akk cancel <turn-selector>
@@ -217,11 +223,15 @@ The core command surface is intentionally small:
 
 `/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. These names and `@short-ref` are human-facing resolution inputs; 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, constructed, copied, or reused elsewhere. 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.
 
-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, an unmanaged raw-terminal row's `send` uses that row's prefilled `selector`; do not construct or reuse it. `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 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.
+
+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.
 
@@ -233,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. |
@@ -295,7 +305,7 @@ With the global npm CLI installed, start with `agent-knock-knock doctor`. It run
 | Source changes do not appear | Build, reinstall from the checkout, and restart the Gateway. |
 | 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 | 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. |
+| `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. |
@@ -337,9 +347,9 @@ 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 Turn 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. Writer protocol 1 is the one supported predecessor: inspection reports it as `upgradeable`, and the first mutation validates every stored Session/Turn identity before atomically upgrading only the manifest to protocol 2. Conversation state and `created_at` are 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 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 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.
 

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

@@ -31,7 +31,7 @@ export interface CodingAgentSessionProvider {
     getCapabilities(): Promise<AgentSessionCapabilities>;
     listHistoricalSessions(): Promise<CodexSessionSummary[]>;
     listActiveSessions(): Promise<ActiveCodexProcess[]>;
-    resolveActiveSessionIdentityForPid(pid: number, cwd?: string): Promise<ActiveAgentSessionIdentity | undefined>;
+    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.