chainlesschain 0.162.189 → 0.162.197

package/src/harness/jsonl-session-store.js

@@ -3,28 +3,481 @@
  */
 
 import {
+  constants as fsConstants,
   existsSync,
-  mkdirSync,
   appendFileSync,
   readFileSync,
   readdirSync,
   copyFileSync,
+  renameSync,
   rmSync,
+  openSync,
+  closeSync,
+  fstatSync,
+  lstatSync,
+  readSync,
+  ftruncateSync,
 } from "node:fs";
 import { join, basename, resolve } from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { TextDecoder } from "node:util";
 import { getHomeDir } from "../lib/paths.js";
+import { ensurePrivateDirectory, ensurePrivateFile } from "../lib/secure-fs.js";
 import {
   computeEventHash,
-  latestChainHash,
-  verifyTranscriptText,
   TRANSCRIPT_CHAIN_STATUS,
 } from "./transcript-integrity.js";
 import { withFileLock } from "../lib/with-file-lock.js";
+import {
+  decodeVerifiedPersistedMessage,
+  DURABLE_SYSTEM_MESSAGE_KINDS,
+  encodePersistedMessage,
+  markDurableSystemMessage,
+  projectCanonicalResumeMessages,
+  sanitizePersistedMessage,
+  SESSION_FORK_AUTHORITY_FIELD,
+} from "../lib/session-message-provenance.js";
+import {
+  iterateFileLinesSync,
+  iterateFileLinesReverseSync,
+} from "../lib/file-lines.js";
+import {
+  emptySessionMeta,
+  applyEventToSessionMeta,
+  listIndexedSessions,
+  publicSessionMeta,
+  readLatestSessionActivity,
+  readSessionMeta,
+  recordSessionDeleted,
+  recordSessionEvent,
+  recordSessionActivity,
+  replaceSessionMeta,
+} from "./session-list-index.js";
+
+let securedSessionsDir = null;
+let securedSessionsDirIdentity = null;
+
+// Deterministic process-crash injection for the independent session-scale
+// gate. The hooks are inert unless the dedicated child process opts in; this
+// keeps production behavior and ordinary tests on the exact same append path.
+export const _sessionScaleFaultHooks = Object.seal({
+  afterTranscriptAppend: null,
+  afterForkCopy: null,
+  afterForkLineage: null,
+  afterForkPublish: null,
+  afterForkMeta: null,
+});
+
+export const WS_TURN_EVENT = "ws_turn";
+export const WS_TURN_CLAIM_EVENT = "ws_turn_claim";
+export const WS_TURN_SCHEMA_VERSION = 1;
+export const WS_TURN_REQUEST_ID_MAX_BYTES = 128;
+const WS_TURN_CONTENT_MAX_BYTES = 4 * 1024 * 1024;
+const WS_TURN_REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@-]*$/;
+const WS_TURN_INPUT_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const WS_TURN_CLAIM_ID_PATTERN = /^claim-[0-9a-f-]{36}$/;
+const WS_TURN_FAILURE_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+
+function wsTurnError(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function hasExactKeys(value, expectedKeys) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value).sort();
+  const expected = [...expectedKeys].sort();
+  return (
+    actual.length === expected.length &&
+    actual.every((key, index) => key === expected[index])
+  );
+}
+
+export function normalizeWsTurnRequestId(value) {
+  if (typeof value !== "string") {
+    throw wsTurnError(
+      "Canonical WebSocket turns require a string request id",
+      "CC_WS_REQUEST_ID_REQUIRED",
+    );
+  }
+  const canonical = value.normalize("NFC");
+  if (
+    canonical !== value ||
+    !WS_TURN_REQUEST_ID_PATTERN.test(canonical) ||
+    Buffer.byteLength(canonical, "utf8") > WS_TURN_REQUEST_ID_MAX_BYTES
+  ) {
+    throw wsTurnError(
+      "WebSocket request id is not bounded canonical ASCII",
+      "CC_WS_REQUEST_ID_INVALID",
+    );
+  }
+  return canonical;
+}
+
+function normalizeWsTurnContent(value, role) {
+  if (
+    typeof value !== "string" ||
+    (role === "assistant" && value.trim().length === 0)
+  ) {
+    throw wsTurnError(
+      `Canonical WebSocket ${role} content is invalid`,
+      role === "assistant"
+        ? "CC_WS_EMPTY_ASSISTANT_RESPONSE"
+        : "CC_WS_USER_MESSAGE_INVALID",
+    );
+  }
+  if (Buffer.byteLength(value, "utf8") > WS_TURN_CONTENT_MAX_BYTES) {
+    throw wsTurnError(
+      `Canonical WebSocket ${role} content exceeds the durable event limit`,
+      "CC_WS_TURN_CONTENT_TOO_LARGE",
+    );
+  }
+  return value;
+}
+
+function normalizeWsTurnInputDigest(value) {
+  if (typeof value !== "string" || !WS_TURN_INPUT_DIGEST_PATTERN.test(value)) {
+    throw wsTurnError(
+      "Canonical WebSocket turn input digest is invalid",
+      "CC_WS_TURN_INPUT_DIGEST_INVALID",
+    );
+  }
+  return value;
+}
+
+function normalizeWsTurnClaimId(value) {
+  if (typeof value !== "string" || !WS_TURN_CLAIM_ID_PATTERN.test(value)) {
+    throw wsTurnError(
+      "Canonical WebSocket turn claim id is invalid",
+      "CC_WS_TURN_CLAIM_ID_INVALID",
+    );
+  }
+  return value;
+}
+
+function normalizeWsTurnFailureCode(value) {
+  if (typeof value !== "string" || !WS_TURN_FAILURE_CODE_PATTERN.test(value)) {
+    throw wsTurnError(
+      "Canonical WebSocket turn failure code is invalid",
+      "CC_WS_TURN_FAILURE_CODE_INVALID",
+    );
+  }
+  return value;
+}
+
+export function createWsTurnClaimId() {
+  return `claim-${randomUUID()}`;
+}
+
+export function computeWsTurnInputDigest(user) {
+  const content = normalizeWsTurnContent(user, "user");
+  return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+
+function canonicalWsTurnClaimData({ requestId, inputDigest, opaqueClaimId }) {
+  return Object.freeze({
+    schemaVersion: WS_TURN_SCHEMA_VERSION,
+    requestId: normalizeWsTurnRequestId(requestId),
+    inputDigest: normalizeWsTurnInputDigest(inputDigest),
+    opaqueClaimId: normalizeWsTurnClaimId(opaqueClaimId),
+  });
+}
+
+function canonicalWsTurnCompletedData({
+  requestId,
+  inputDigest = null,
+  opaqueClaimId = null,
+  user,
+  assistant,
+}) {
+  const normalizedUser = normalizeWsTurnContent(user, "user");
+  const hasClaimAuthority = inputDigest != null || opaqueClaimId != null;
+  const data = {
+    schemaVersion: WS_TURN_SCHEMA_VERSION,
+    requestId: normalizeWsTurnRequestId(requestId),
+    outcome: "completed",
+    user: Object.freeze({
+      role: "user",
+      content: normalizedUser,
+    }),
+    assistant: Object.freeze({
+      role: "assistant",
+      content: normalizeWsTurnContent(assistant, "assistant"),
+    }),
+  };
+  if (hasClaimAuthority) {
+    data.inputDigest = normalizeWsTurnInputDigest(inputDigest);
+    data.opaqueClaimId = normalizeWsTurnClaimId(opaqueClaimId);
+    if (data.inputDigest !== computeWsTurnInputDigest(normalizedUser)) {
+      throw wsTurnError(
+        "WebSocket turn settlement input does not match its durable claim",
+        "CC_WS_TURN_INPUT_DIGEST_MISMATCH",
+      );
+    }
+  }
+  return Object.freeze(data);
+}
+
+function canonicalWsTurnFailedData({
+  requestId,
+  inputDigest,
+  opaqueClaimId,
+  failureCode,
+}) {
+  return Object.freeze({
+    schemaVersion: WS_TURN_SCHEMA_VERSION,
+    requestId: normalizeWsTurnRequestId(requestId),
+    inputDigest: normalizeWsTurnInputDigest(inputDigest),
+    opaqueClaimId: normalizeWsTurnClaimId(opaqueClaimId),
+    outcome: "failed",
+    failure: Object.freeze({ code: normalizeWsTurnFailureCode(failureCode) }),
+  });
+}
+
+export function projectWsTurnClaim(event) {
+  if (event?.type !== WS_TURN_CLAIM_EVENT) return null;
+  try {
+    if (
+      !hasExactKeys(event.data, [
+        "schemaVersion",
+        "requestId",
+        "inputDigest",
+        "opaqueClaimId",
+      ])
+    ) {
+      return null;
+    }
+    const data = canonicalWsTurnClaimData(event.data || {});
+    if (event.data?.schemaVersion !== WS_TURN_SCHEMA_VERSION) return null;
+    return Object.freeze({
+      ...data,
+      eventHash: typeof event.hash === "string" ? event.hash : null,
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function projectWsTurnSettlement(event) {
+  if (event?.type !== WS_TURN_EVENT) return null;
+  try {
+    if (event.data?.outcome === "failed") {
+      if (
+        !hasExactKeys(event.data, [
+          "schemaVersion",
+          "requestId",
+          "inputDigest",
+          "opaqueClaimId",
+          "outcome",
+          "failure",
+        ]) ||
+        !hasExactKeys(event.data?.failure, ["code"])
+      ) {
+        return null;
+      }
+      const data = canonicalWsTurnFailedData({
+        requestId: event.data?.requestId,
+        inputDigest: event.data?.inputDigest,
+        opaqueClaimId: event.data?.opaqueClaimId,
+        failureCode: event.data?.failure?.code,
+      });
+      if (event.data?.schemaVersion !== WS_TURN_SCHEMA_VERSION) return null;
+      return Object.freeze({
+        ...data,
+        eventHash: typeof event.hash === "string" ? event.hash : null,
+      });
+    }
+    const claimedSettlement =
+      event.data?.inputDigest != null || event.data?.opaqueClaimId != null;
+    if (
+      !hasExactKeys(
+        event.data,
+        claimedSettlement
+          ? [
+              "schemaVersion",
+              "requestId",
+              "inputDigest",
+              "opaqueClaimId",
+              "outcome",
+              "user",
+              "assistant",
+            ]
+          : ["schemaVersion", "requestId", "outcome", "user", "assistant"],
+      ) ||
+      !hasExactKeys(event.data?.user, ["role", "content"]) ||
+      !hasExactKeys(event.data?.assistant, ["role", "content"])
+    ) {
+      return null;
+    }
+    const data = canonicalWsTurnCompletedData({
+      requestId: event.data?.requestId,
+      inputDigest: event.data?.inputDigest,
+      opaqueClaimId: event.data?.opaqueClaimId,
+      user: event.data?.user?.content,
+      assistant: event.data?.assistant?.content,
+    });
+    if (
+      event.data?.schemaVersion !== WS_TURN_SCHEMA_VERSION ||
+      event.data?.outcome !== "completed" ||
+      event.data?.user?.role !== "user" ||
+      event.data?.assistant?.role !== "assistant"
+    ) {
+      return null;
+    }
+    return Object.freeze({
+      ...data,
+      eventHash: typeof event.hash === "string" ? event.hash : null,
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function projectWsTurnMessages(event) {
+  const settlement = projectWsTurnSettlement(event);
+  return settlement?.outcome === "completed" ? settlement : null;
+}
+
+function wsTurnAuthorityError(message, code = "CC_WS_TURN_AUTHORITY_INVALID") {
+  return wsTurnError(message, code);
+}
+
+export function createWsTurnLifecycleReducer({
+  requestId,
+  inputDigest = null,
+} = {}) {
+  const canonicalRequestId = normalizeWsTurnRequestId(requestId);
+  const expectedInputDigest =
+    inputDigest == null ? null : normalizeWsTurnInputDigest(inputDigest);
+  let claim = null;
+  let settlement = null;
+
+  return {
+    accept(event) {
+      if (
+        event?.type !== WS_TURN_CLAIM_EVENT &&
+        event?.type !== WS_TURN_EVENT
+      ) {
+        return;
+      }
+      if (event?.data?.requestId !== canonicalRequestId) return;
+
+      if (event.type === WS_TURN_CLAIM_EVENT) {
+        const projected = projectWsTurnClaim(event);
+        if (!projected?.eventHash) {
+          throw wsTurnAuthorityError(
+            "WebSocket request claim is malformed or unchained",
+          );
+        }
+        if (claim || settlement) {
+          throw wsTurnAuthorityError(
+            "WebSocket request has duplicate or out-of-order claim authority",
+            "CC_WS_TURN_CLAIM_DUPLICATE",
+          );
+        }
+        claim = projected;
+        return;
+      }
+
+      const projected = projectWsTurnSettlement(event);
+      if (!projected?.eventHash) {
+        throw wsTurnAuthorityError(
+          "WebSocket request settlement is malformed or unchained",
+        );
+      }
+      if (settlement) {
+        throw wsTurnAuthorityError(
+          "WebSocket request has multiple durable settlements",
+          "CC_WS_TURN_IDEMPOTENCY_DUPLICATE",
+        );
+      }
+      const claimedSettlement = projected.opaqueClaimId != null;
+      if (claimedSettlement) {
+        if (
+          !claim ||
+          claim.opaqueClaimId !== projected.opaqueClaimId ||
+          claim.inputDigest !== projected.inputDigest
+        ) {
+          throw wsTurnAuthorityError(
+            "WebSocket request settlement does not match its preceding claim",
+            "CC_WS_TURN_CLAIM_MISMATCH",
+          );
+        }
+      } else if (claim) {
+        throw wsTurnAuthorityError(
+          "Claimed WebSocket request used a legacy unfenced settlement",
+          "CC_WS_TURN_CLAIM_MISMATCH",
+        );
+      }
+      settlement = projected;
+    },
+    finish(authority = {}) {
+      const durableInputDigest =
+        claim?.inputDigest ||
+        settlement?.inputDigest ||
+        (settlement?.outcome === "completed"
+          ? computeWsTurnInputDigest(settlement.user.content)
+          : null);
+      if (
+        expectedInputDigest &&
+        durableInputDigest &&
+        expectedInputDigest !== durableInputDigest
+      ) {
+        throw wsTurnAuthorityError(
+          "WebSocket request id was already claimed with different input",
+          "CC_WS_REQUEST_ID_CONFLICT",
+        );
+      }
+      const status = settlement?.outcome || (claim ? "pending" : "none");
+      return Object.freeze({
+        requestId: canonicalRequestId,
+        inputDigest: durableInputDigest || expectedInputDigest,
+        status,
+        claim,
+        settlement,
+        turn: settlement?.outcome === "completed" ? settlement : null,
+        headHash:
+          typeof authority.headHash === "string" ? authority.headHash : null,
+        eventCount: Number.isSafeInteger(authority.eventCount)
+          ? authority.eventCount
+          : 0,
+      });
+    },
+  };
+}
+
+function runSessionScaleFaultHook(name, payload) {
+  if (process.env.CC_SESSION_SCALE_FAULT_INJECTION !== "1") return;
+  const hook = _sessionScaleFaultHooks[name];
+  if (typeof hook === "function") hook(payload);
+}
 
 function getSessionsDir() {
   const dir = join(getHomeDir(), "sessions");
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  let current = null;
+  try {
+    current = lstatSync(dir);
+  } catch {
+    // The owner-only helper below creates a missing directory and surfaces any
+    // other unsafe filesystem state with its canonical error.
+  }
+  const currentIdentity = current ? `${current.dev}:${current.ino}` : null;
+  const unsafePosixMode =
+    process.platform !== "win32" &&
+    current !== null &&
+    (current.mode & 0o777) !== 0o700;
+  if (
+    securedSessionsDir !== dir ||
+    currentIdentity === null ||
+    currentIdentity !== securedSessionsDirIdentity ||
+    unsafePosixMode
+  ) {
+    ensurePrivateDirectory(dir);
+    securedSessionsDir = dir;
+    const secured = lstatSync(dir);
+    securedSessionsDirIdentity = `${secured.dev}:${secured.ino}`;
+  }
   return dir;
 }
 
@@ -61,42 +514,687 @@ export function appendTokenUsage(sessionId, usage) {
   appendEvent(sessionId, "token_usage", usage || {});
 }
 
-// Chain-tail cache: hash of the last chained record per session, so appends
-// stay O(1) instead of re-reading the file. Keyed per process — two processes
-// appending the SAME session concurrently could fork the chain (verify would
-// then flag it), but the store has always assumed a single writer per session.
-const _chainTailCache = new Map();
+function inspectPhysicalTail(filePath, { dryRun = false } = {}) {
+  const result = {
+    action: "none",
+    changed: false,
+    discardedBytes: 0,
+    discardedRecords: 0,
+    fileSize: 0,
+  };
+  if (!existsSync(filePath)) return result;
+  const fd = openSync(filePath, "r+");
+  let normalizeNewline = false;
+  try {
+    const size = fstatSync(fd).size;
+    result.fileSize = size;
+    if (size > 0) {
+      const lastByte = Buffer.allocUnsafe(1);
+      readSync(fd, lastByte, 0, 1, size - 1);
+      if (lastByte[0] !== 0x0a) {
+        // Locate the beginning of the physical tail using bounded reverse IO.
+        let cursor = size;
+        let tailStart = 0;
+        let found = false;
+        const chunkSize = 64 * 1024;
+        while (cursor > 0 && !found) {
+          const length = Math.min(chunkSize, cursor);
+          cursor -= length;
+          const chunk = Buffer.allocUnsafe(length);
+          readSync(fd, chunk, 0, length, cursor);
+          const newline = chunk.lastIndexOf(0x0a);
+          if (newline >= 0) {
+            tailStart = cursor + newline + 1;
+            found = true;
+          }
+        }
+        const tail = Buffer.allocUnsafe(size - tailStart);
+        if (tail.length > 0) readSync(fd, tail, 0, tail.length, tailStart);
+        try {
+          const text = new TextDecoder("utf-8", { fatal: true }).decode(tail);
+          JSON.parse(text);
+          // A valid legacy/manual last record merely lacks its newline; retain
+          // it and normalize before appending the next chained event.
+          result.action = "normalize-newline";
+          result.changed = true;
+          normalizeNewline = !dryRun;
+        } catch {
+          // Crash tail: discard only the one incomplete physical record.
+          result.action = "discard-partial-record";
+          result.changed = true;
+          result.discardedBytes = size - tailStart;
+          result.discardedRecords = 1;
+          if (!dryRun) ftruncateSync(fd, tailStart);
+        }
+      }
+    }
+  } finally {
+    closeSync(fd);
+  }
+  if (normalizeNewline) {
+    appendFileSync(filePath, "\n", { encoding: "utf8", mode: 0o600 });
+  }
+  if (!dryRun && result.changed) ensurePrivateFile(filePath);
+  return result;
+}
 
-function _resolveChainTail(sessionId, filePath) {
-  if (!existsSync(filePath)) {
-    // Missing file self-heals a stale cache entry (file deleted externally,
-    // or a test tearing down the sessions dir between cases).
-    _chainTailCache.set(sessionId, null);
-    return null;
+/**
+ * Repair at most one crash-truncated physical tail and resolve the chain hash.
+ * This is called only while the transcript's cross-process lock is held, so a
+ * second writer can never reuse a stale in-process hash.
+ */
+function _resolveChainTail(filePath) {
+  if (!existsSync(filePath)) return { prevHash: null, recovery: null };
+  // Fast path: almost every append follows a newline-terminated record. Read
+  // that tail once and avoid opening the file a second time just to inspect its
+  // last byte. The slow repair path runs only for an unterminated crash tail.
+  const initial = iterateFileLinesReverseSync(filePath);
+  const first = initial.next();
+  if (!first.done && first.value.terminated) {
+    try {
+      let current = first;
+      while (!current.done) {
+        try {
+          const event = JSON.parse(current.value.line);
+          return {
+            prevHash: typeof event?.hash === "string" ? event.hash : null,
+            recovery: null,
+          };
+        } catch {
+          current = initial.next();
+        }
+      }
+      return { prevHash: null, recovery: null };
+    } finally {
+      initial.return?.();
+    }
   }
-  const cached = _chainTailCache.get(sessionId);
-  if (cached !== undefined) return cached;
-  const tail = latestChainHash(readFileSync(filePath, "utf-8"));
-  _chainTailCache.set(sessionId, tail);
-  return tail;
+  initial.return?.();
+
+  const recovery = inspectPhysicalTail(filePath);
+  for (const { line } of iterateFileLinesReverseSync(filePath)) {
+    try {
+      const event = JSON.parse(line);
+      return {
+        prevHash: typeof event?.hash === "string" ? event.hash : null,
+        recovery: recovery.changed ? recovery : null,
+      };
+    } catch {
+      // A malformed historical line is verified separately; keep searching so
+      // this append never chains from arbitrary bytes.
+    }
+  }
+  return { prevHash: null, recovery: recovery.changed ? recovery : null };
 }
 
-export function appendEvent(sessionId, type, data) {
+function readVerifiedWsAuthorityLocked(
+  sessionId,
+  filePath,
+  requestId,
+  inputDigest,
+) {
+  const reducer = createWsTurnLifecycleReducer({ requestId, inputDigest });
+  const verification = verifyTranscriptFile(filePath, {
+    onVerifiedEvent: (event) => reducer.accept(event),
+  });
+  assertVerifiedTranscriptAnchor(sessionId, verification);
+  const authority = Object.freeze({
+    headHash: verification.lastHash,
+    eventCount: verification.chainedEvents,
+  });
+  return Object.freeze({
+    authority,
+    state: reducer.finish(authority),
+    messages: Object.freeze([...rebuildVerifiedMessagesFromFile(filePath)]),
+  });
+}
+
+function appendVerifiedWsAuthorityEventLocked(
+  sessionId,
+  filePath,
+  type,
+  data,
+  previousHeadHash,
+  { verifySettlement = true } = {},
+) {
+  const core = { type, timestamp: Date.now(), data };
+  const hash = computeEventHash(previousHeadHash, core);
+  const event = { ...core, prevHash: previousHeadHash, hash };
+  appendFileSync(filePath, `${JSON.stringify(event)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  ensurePrivateFile(filePath);
+  runSessionScaleFaultHook("afterTranscriptAppend", {
+    sessionId,
+    type,
+    event,
+    filePath,
+  });
+  try {
+    recordSessionEvent(getSessionsDir(), sessionId, event, hash);
+  } catch (cause) {
+    const error = new Error(
+      `Session authority anchor could not be persisted: ${sessionId}`,
+      { cause },
+    );
+    error.code = "SESSION_INDEX_ANCHOR_FAILED";
+    error.sessionId = sessionId;
+    error.commitState = "unknown";
+    throw error;
+  }
+  if (verifySettlement) {
+    const verification = verifyTranscriptFile(filePath);
+    try {
+      assertVerifiedTranscriptAnchor(sessionId, verification);
+    } catch (cause) {
+      const error = new Error(
+        `Session authority settlement could not be verified: ${sessionId}`,
+        { cause },
+      );
+      error.code = "SESSION_INDEX_ANCHOR_FAILED";
+      error.sessionId = sessionId;
+      error.commitState = "unknown";
+      throw error;
+    }
+    if (verification.lastHash !== hash || event.prevHash !== previousHeadHash) {
+      const error = new Error(
+        `Session authority settlement head is not durable: ${sessionId}`,
+      );
+      error.code = "SESSION_INDEX_ANCHOR_FAILED";
+      error.sessionId = sessionId;
+      error.commitState = "unknown";
+      throw error;
+    }
+  }
+  return Object.freeze({ hash, event });
+}
+
+function withVerifiedWsTurnLock(sessionId, task) {
+  const filePath = sessionPath(sessionId);
+  return withFileLock(filePath, () => task(filePath), {
+    failIfUnavailable: true,
+    timeoutMs: 30_000,
+    retryMs: 1,
+    maxRetryMs: 8,
+    retryJitterMs: 4,
+    yieldAfterReleaseMs: 2,
+  });
+}
+
+function encodeEventMessageProvenance(type, data) {
+  if (
+    (type === "compact" || type === "checkpoint_timeline_commit") &&
+    data &&
+    typeof data === "object" &&
+    !Array.isArray(data) &&
+    Array.isArray(data.messages)
+  ) {
+    return {
+      ...data,
+      messages: data.messages.map(encodePersistedMessage),
+    };
+  }
+  if (type === "system") return encodePersistedMessage(data);
+  return data;
+}
+
+const SESSION_AUTHORITY_RECOVERY_TEXT_LIMITS = Object.freeze({
+  safetyId: 512,
+  safetyIdentity: 512,
+  safetyPlanIdentity: 1024,
+  safetyCoverage: 64,
+  restorePhase: 64,
+  branchSessionId: 512,
+});
+const SESSION_AUTHORITY_RECOVERY_CREATED_PATH_LIMIT = 256;
+const SESSION_AUTHORITY_RECOVERY_PATH_LENGTH_LIMIT = 4096;
+
+function sanitizeSessionAuthorityRecoveryEvidence(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const evidence = {};
+  for (const [field, limit] of Object.entries(
+    SESSION_AUTHORITY_RECOVERY_TEXT_LIMITS,
+  )) {
+    if (typeof value[field] === "string" && value[field].length > 0) {
+      evidence[field] = value[field].slice(0, limit);
+    }
+  }
+  if (Array.isArray(value.createdPaths)) {
+    evidence.createdPaths = Object.freeze(
+      value.createdPaths
+        .filter((item) => typeof item === "string")
+        .slice(0, SESSION_AUTHORITY_RECOVERY_CREATED_PATH_LIMIT)
+        .map((item) =>
+          item.slice(0, SESSION_AUTHORITY_RECOVERY_PATH_LENGTH_LIMIT),
+        ),
+    );
+  }
+  return Object.keys(evidence).length > 0 ? Object.freeze(evidence) : null;
+}
+
+function appendEventLocked(
+  sessionId,
+  type,
+  data,
+  { expectedHeadHash, compareHead = false, requireIndexAnchor = false } = {},
+) {
   const filePath = sessionPath(sessionId);
-  withFileLock(
+  return withFileLock(
     filePath,
     () => {
-      const prevHash = _resolveChainTail(sessionId, filePath);
-      const core = { type, timestamp: Date.now(), data };
+      const existingMeta = readSessionMeta(getSessionsDir(), sessionId);
+      if (
+        !existsSync(filePath) &&
+        existingMeta?.deleted === true &&
+        type !== "session_start"
+      ) {
+        const error = new Error(`Session was deleted: ${sessionId}`);
+        error.code = "SESSION_DELETED";
+        throw error;
+      }
+      const { prevHash, recovery } = _resolveChainTail(filePath);
+      if (compareHead && prevHash !== (expectedHeadHash || null)) {
+        const error = new Error(
+          `Session revision changed for ${sessionId}; refresh the checkpoint timeline`,
+        );
+        error.code = "SESSION_REVISION_STALE";
+        error.expectedHeadHash = expectedHeadHash || null;
+        error.actualHeadHash = prevHash;
+        throw error;
+      }
+      const persistedData = encodeEventMessageProvenance(type, data);
+      const core = { type, timestamp: Date.now(), data: persistedData };
       const hash = computeEventHash(prevHash, core);
-      const line = JSON.stringify({ ...core, prevHash, hash }) + "\n";
-      appendFileSync(filePath, line, "utf-8");
-      _chainTailCache.set(sessionId, hash);
+      const event = { ...core, prevHash, hash };
+      const line = JSON.stringify(event) + "\n";
+      appendFileSync(filePath, line, { encoding: "utf8", mode: 0o600 });
+      ensurePrivateFile(filePath);
+      runSessionScaleFaultHook("afterTranscriptAppend", {
+        sessionId,
+        type,
+        event,
+        filePath,
+      });
+      try {
+        recordSessionEvent(getSessionsDir(), sessionId, event, hash);
+      } catch (cause) {
+        if (requireIndexAnchor) {
+          const error = new Error(
+            `Session authority anchor could not be persisted: ${sessionId}`,
+            { cause },
+          );
+          error.code = "SESSION_INDEX_ANCHOR_FAILED";
+          error.sessionId = sessionId;
+          throw error;
+        }
+        // The metadata index is explicitly rebuildable. Never turn a committed
+        // transcript event into an apparent failure that a caller may retry.
+      }
+      if (requireIndexAnchor) {
+        const verification = verifyTranscriptFile(filePath);
+        const anchoredMeta = readSessionMeta(getSessionsDir(), sessionId);
+        const anchored =
+          verification.status === TRANSCRIPT_CHAIN_STATUS.VERIFIED &&
+          verification.malformedLines === 0 &&
+          !verification.truncatedTail &&
+          anchoredMeta?.deleted !== true &&
+          anchoredMeta?.last_hash === hash &&
+          Number(anchoredMeta?.event_count) === verification.chainedEvents;
+        if (!anchored) {
+          const error = new Error(
+            `Session authority anchor does not match the transcript: ${sessionId}`,
+          );
+          error.code = "SESSION_INDEX_ANCHOR_FAILED";
+          error.sessionId = sessionId;
+          error.verification = verification;
+          throw error;
+        }
+      }
+      return { hash, recovery };
+    },
+    {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+      yieldAfterReleaseMs: 2,
     },
-    { failIfUnavailable: true },
   );
 }
 
+export function appendEvent(sessionId, type, data) {
+  return appendEventLocked(sessionId, type, data);
+}
+
+/**
+ * Append an authority-bearing event only when both the transcript and its
+ * crash/tail-truncation anchor are durably updated and still agree.
+ */
+export function appendAuthorityEvent(sessionId, type, data) {
+  return appendEventLocked(sessionId, type, data, {
+    requireIndexAnchor: true,
+  });
+}
+
+/**
+ * Compare-and-append for revisioned IDE actions. The head check and append run
+ * under the transcript's canonical writer lock, so a stale preview can never
+ * commit after another session writer advances the chain.
+ */
+export function appendEventIfHead(
+  sessionId,
+  type,
+  data,
+  expectedHeadHash = null,
+) {
+  return appendEventLocked(sessionId, type, data, {
+    expectedHeadHash,
+    compareHead: true,
+  });
+}
+
+/** Authority-bearing compare-and-append with a mandatory index anchor. */
+export function appendAuthorityEventIfHead(
+  sessionId,
+  type,
+  data,
+  expectedHeadHash = null,
+) {
+  return appendEventLocked(sessionId, type, data, {
+    expectedHeadHash,
+    compareHead: true,
+    requireIndexAnchor: true,
+  });
+}
+
+/**
+ * Run a synchronous authority transaction while holding the canonical
+ * transcript writer lock for its whole lifetime.
+ *
+ * A sequence of separate compare-and-appends leaves a gap between commits:
+ * callers may mutate an external resource after the first event, then lose the
+ * second CAS to another session writer. This primitive closes that gap. It
+ * validates the transcript + sidecar anchor and the caller's expected head
+ * before invoking `task`, then keeps every authority append on the same locked
+ * chain. The callback must be synchronous; retaining the writer beyond the
+ * lock lifetime would make the apparent transaction unsafe.
+ *
+ * External mutations may register bounded, recovery-only evidence through the
+ * writer. It is attached only when final settlement is unverifiable; the
+ * callback's arbitrary return value is never copied into an error.
+ *
+ * This is a transaction-scoped writer lease, not a general host/session lease
+ * and not a filesystem power-loss transaction. Callers that coordinate an
+ * external resource must still journal crash recovery for that resource.
+ */
+export function withSessionAuthorityTransaction(
+  sessionId,
+  expectedHeadHash,
+  task,
+) {
+  if (typeof task !== "function") {
+    throw new TypeError("Session authority transaction callback is required");
+  }
+  if (task.constructor?.name === "AsyncFunction") {
+    throw new TypeError(
+      "Session authority transaction callback must be synchronous",
+    );
+  }
+
+  const filePath = sessionPath(sessionId);
+  return withFileLock(
+    filePath,
+    () => {
+      const existingMeta = readSessionMeta(getSessionsDir(), sessionId);
+      if (!existsSync(filePath) && existingMeta?.deleted === true) {
+        const error = new Error(`Session was deleted: ${sessionId}`);
+        error.code = "SESSION_DELETED";
+        throw error;
+      }
+      if (!existsSync(filePath) && existingMeta !== null) {
+        throw unverifiedTranscriptError(sessionId, {
+          status: "missing",
+          reason: "session sidecar exists without its transcript",
+          lastHash: null,
+          chainedEvents: 0,
+        });
+      }
+
+      let currentHeadHash = null;
+      if (existsSync(filePath)) {
+        // Normalize or discard only an incomplete physical tail before the
+        // verified sample. The existing sidecar already anchors the last
+        // complete event, so a crash tail never becomes transaction authority.
+        _resolveChainTail(filePath);
+        const verification = verifyTranscriptFile(filePath);
+        assertVerifiedTranscriptAnchor(sessionId, verification);
+        currentHeadHash = verification.lastHash;
+      }
+
+      const expected = expectedHeadHash || null;
+      if (currentHeadHash !== expected) {
+        const error = new Error(
+          `Session revision changed for ${sessionId}; refresh the checkpoint timeline`,
+        );
+        error.code = "SESSION_REVISION_STALE";
+        error.expectedHeadHash = expected;
+        error.actualHeadHash = currentHeadHash;
+        throw error;
+      }
+
+      let appendAttempts = 0;
+      let writerActive = true;
+      let writerPoisoned = false;
+      let transactionRecoveryEvidence = null;
+      const writer = Object.freeze({
+        initialHeadHash: currentHeadHash,
+        currentHeadHash: () => currentHeadHash,
+        retainRecoveryEvidence(evidence) {
+          if (!writerActive) {
+            const error = new Error(
+              `Session authority transaction is already closed: ${sessionId}`,
+            );
+            error.code = "SESSION_AUTHORITY_TRANSACTION_CLOSED";
+            throw error;
+          }
+          const sanitized = sanitizeSessionAuthorityRecoveryEvidence(evidence);
+          if (sanitized) {
+            transactionRecoveryEvidence = Object.freeze({
+              ...(transactionRecoveryEvidence || {}),
+              ...sanitized,
+            });
+          }
+          return transactionRecoveryEvidence;
+        },
+        appendAuthorityEvent(type, data) {
+          if (!writerActive) {
+            const error = new Error(
+              `Session authority transaction is already closed: ${sessionId}`,
+            );
+            error.code = "SESSION_AUTHORITY_TRANSACTION_CLOSED";
+            throw error;
+          }
+          if (writerPoisoned) {
+            const error = new Error(
+              `Session authority transaction writer is poisoned: ${sessionId}`,
+            );
+            error.code = "SESSION_AUTHORITY_TRANSACTION_POISONED";
+            error.commitState = "unknown";
+            throw error;
+          }
+          const persistedData = encodeEventMessageProvenance(type, data);
+          appendAttempts += 1;
+          let appended;
+          try {
+            appended = appendVerifiedWsAuthorityEventLocked(
+              sessionId,
+              filePath,
+              type,
+              persistedData,
+              currentHeadHash,
+              { verifySettlement: false },
+            );
+          } catch (error) {
+            // Bytes may already have reached the transcript before a
+            // sidecar/activity failure. The actual head is then unknown, so a
+            // second append from this writer would risk forking the chain.
+            writerPoisoned = true;
+            if (error && !error.commitState) error.commitState = "unknown";
+            throw error;
+          }
+          currentHeadHash = appended.hash;
+          return appended;
+        },
+      });
+
+      let result;
+      let bodyError = null;
+      let bodyThrew = false;
+      try {
+        result = task(writer);
+        if (result && typeof result.then === "function") {
+          const error = new TypeError(
+            "Session authority transaction callback must be synchronous",
+          );
+          error.code = "SESSION_AUTHORITY_TRANSACTION_ASYNC";
+          error.commitState = "unknown";
+          throw error;
+        }
+      } catch (error) {
+        bodyThrew = true;
+        bodyError = error;
+      } finally {
+        // A callback can retain this object or return a Promise/thenable. Revoke
+        // it before settlement and before releasing the lock so no later
+        // microtask can append outside the transaction critical section.
+        writerActive = false;
+      }
+
+      if (appendAttempts > 0) {
+        try {
+          const verification = verifyTranscriptFile(filePath);
+          assertVerifiedTranscriptAnchor(sessionId, verification);
+          if (verification.lastHash !== currentHeadHash) {
+            throw new Error(
+              `Session authority settlement head is not durable: ${sessionId}`,
+            );
+          }
+        } catch (cause) {
+          const error = new Error(
+            `Session authority transaction could not be verified: ${sessionId}`,
+            { cause },
+          );
+          error.code = "SESSION_INDEX_ANCHOR_FAILED";
+          error.sessionId = sessionId;
+          error.commitState = "unknown";
+          if (bodyThrew) error.transactionError = bodyError;
+          if (transactionRecoveryEvidence) {
+            // Never attach the arbitrary callback result. Callers must opt in
+            // to this bounded recovery-only projection before settlement.
+            error.transactionRecoveryEvidence = transactionRecoveryEvidence;
+          }
+          throw error;
+        }
+      }
+      if (bodyThrew) throw bodyError;
+      return result;
+    },
+    {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+      yieldAfterReleaseMs: 2,
+    },
+  );
+}
+
+function verifyTranscriptFile(filePath, options = {}) {
+  const onVerifiedEvent =
+    typeof options.onVerifiedEvent === "function"
+      ? options.onVerifiedEvent
+      : null;
+  const ioMetrics = options.ioMetrics ?? null;
+  const result = {
+    status: TRANSCRIPT_CHAIN_STATUS.EMPTY,
+    chainedEvents: 0,
+    legacyEvents: 0,
+    malformedLines: 0,
+    truncatedTail: false,
+    firstInvalidLine: null,
+    reason: null,
+    lastHash: null,
+  };
+  let lastHash = null;
+  let sawChain = false;
+  const tampered = (lineNo, reason) => ({
+    ...result,
+    status: TRANSCRIPT_CHAIN_STATUS.TAMPERED,
+    firstInvalidLine: lineNo,
+    reason,
+  });
+
+  for (const { line, lineNo, terminated } of iterateFileLinesSync(filePath, {
+    ioMetrics,
+  })) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      result.malformedLines += 1;
+      if (!terminated) {
+        result.truncatedTail = true;
+        continue;
+      }
+      if (sawChain) {
+        return tampered(lineNo, "malformed line inside hash chain");
+      }
+      continue;
+    }
+
+    if (event && typeof event.hash === "string") {
+      const expectedPrev = sawChain ? lastHash : null;
+      if ((event.prevHash ?? null) !== expectedPrev) {
+        return tampered(
+          lineNo,
+          sawChain
+            ? "hash chain linkage broken (record deleted, inserted, or reordered)"
+            : "chain does not start at a genesis record (head records removed)",
+        );
+      }
+      if (computeEventHash(expectedPrev, event) !== event.hash) {
+        return tampered(lineNo, "event content does not match its hash");
+      }
+      sawChain = true;
+      lastHash = event.hash;
+      result.lastHash = lastHash;
+      result.chainedEvents += 1;
+      onVerifiedEvent?.(event);
+    } else {
+      if (sawChain) {
+        return tampered(
+          lineNo,
+          "unchained record after hash chain started (manual append or downgrade write)",
+        );
+      }
+      result.legacyEvents += 1;
+    }
+  }
+
+  if (result.chainedEvents > 0) {
+    result.status =
+      result.legacyEvents > 0
+        ? TRANSCRIPT_CHAIN_STATUS.PARTIAL
+        : TRANSCRIPT_CHAIN_STATUS.VERIFIED;
+  } else if (result.legacyEvents > 0 || result.malformedLines > 0) {
+    result.status = TRANSCRIPT_CHAIN_STATUS.LEGACY;
+  }
+  return result;
+}
+
 /**
  * Verify a session transcript's hash chain (tamper-evidence).
  * Statuses: verified | partial (legacy prefix + valid chain) | legacy
@@ -112,7 +1210,7 @@ export function verifySession(sessionId) {
   }
   return {
     sessionId,
-    ...verifyTranscriptText(readFileSync(filePath, "utf-8")),
+    ...verifyTranscriptFile(filePath),
   };
 }
 
@@ -125,6 +1223,137 @@ export function verifyAllSessions(options = {}) {
     .map((file) => verifySession(basename(file, ".jsonl")));
 }
 
+function indexedProjectionMatchesTranscript(meta, verification, validation) {
+  return (
+    verification.status === TRANSCRIPT_CHAIN_STATUS.VERIFIED &&
+    validation.valid === true &&
+    meta?.deleted !== true &&
+    Number(meta?.event_count) === validation.eventCount &&
+    (meta?.last_hash ?? null) === (verification.lastHash ?? null)
+  );
+}
+
+/**
+ * Diagnose and repair the final physical transcript record plus its rebuildable
+ * metadata projection. Interior corruption and hash-chain tampering are never
+ * rewritten: repair may append a missing newline, discard one crash-partial
+ * record, or rebuild a stale sidecar/activity index from a healthy transcript.
+ */
+export function repairSession(sessionId, options = {}) {
+  const dryRun = options.dryRun === true;
+  if (isUnsafeSessionId(sessionId)) {
+    return {
+      sessionId,
+      dryRun,
+      changed: false,
+      healthy: false,
+      status: "invalid-id",
+      reason: "invalid session id",
+    };
+  }
+  const filePath = sessionPath(sessionId);
+  if (!existsSync(filePath)) {
+    return {
+      sessionId,
+      dryRun,
+      changed: false,
+      healthy: false,
+      status: "not-found",
+      reason: "session file not found",
+    };
+  }
+
+  const result = withFileLock(
+    filePath,
+    () => {
+      const dir = getSessionsDir();
+      const before = verifyTranscriptFile(filePath);
+      const beforeValidation = validateJsonlSession(sessionId);
+      const repair = inspectPhysicalTail(filePath, { dryRun });
+      const after = dryRun ? null : verifyTranscriptFile(filePath);
+      const afterValidation = dryRun ? null : validateJsonlSession(sessionId);
+      const effective = after || before;
+      const effectiveValidation = afterValidation || beforeValidation;
+      const transcriptHealthy =
+        effective.status !== TRANSCRIPT_CHAIN_STATUS.TAMPERED &&
+        !(dryRun
+          ? before.truncatedTail || repair.changed
+          : after.truncatedTail) &&
+        effectiveValidation.valid;
+      const currentMeta = readSessionMeta(dir, sessionId);
+      const currentActivity = readLatestSessionActivity(dir, sessionId);
+      const indexRepairRequired =
+        transcriptHealthy &&
+        (!indexedProjectionMatchesTranscript(
+          currentMeta,
+          effective,
+          effectiveValidation,
+        ) ||
+          !indexedProjectionMatchesTranscript(
+            currentActivity,
+            effective,
+            effectiveValidation,
+          ));
+      let indexRebuilt = false;
+      let indexRepairError = null;
+      if (!dryRun && indexRepairRequired) {
+        try {
+          rebuildSessionMetaUnlocked(dir, sessionId, filePath);
+          indexRebuilt = true;
+        } catch (cause) {
+          indexRepairError = {
+            code: cause?.code || null,
+            message: String(cause?.message || cause),
+          };
+        }
+      }
+      const healthy = dryRun
+        ? transcriptHealthy && !repair.changed && !indexRepairRequired
+        : transcriptHealthy && (!indexRepairRequired || indexRebuilt);
+      return {
+        sessionId,
+        dryRun,
+        changed: repair.changed || indexRebuilt,
+        physicalChanged: repair.changed,
+        indexChanged: indexRebuilt,
+        wouldChange: dryRun && (repair.changed || indexRepairRequired),
+        action:
+          repair.action === "none" && indexRepairRequired
+            ? "rebuild-index"
+            : repair.action,
+        physicalAction: repair.action,
+        indexAction: indexRepairRequired ? "rebuild-index" : "none",
+        indexRepairRequired,
+        indexRebuilt,
+        indexRepairError,
+        discardedBytes: repair.discardedBytes,
+        discardedRecords: repair.discardedRecords,
+        healthy,
+        transcriptHealthy,
+        status: effective.status,
+        before,
+        after,
+        beforeValidation,
+        afterValidation,
+        reason:
+          effective.status === TRANSCRIPT_CHAIN_STATUS.TAMPERED
+            ? effective.reason || "transcript remains tampered"
+            : !effectiveValidation.valid
+              ? effectiveValidation.reason ||
+                "transcript remains structurally invalid"
+              : indexRepairError
+                ? `session metadata index rebuild failed: ${indexRepairError.message}`
+                : indexRepairRequired && dryRun
+                  ? "session metadata index requires rebuild"
+                  : null,
+      };
+    },
+    { failIfUnavailable: true },
+  );
+
+  return result;
+}
+
 /** All locally-stored session ids (the source of truth a mirror derives from). */
 export function listSessionIds() {
   const dir = getSessionsDir();
@@ -134,6 +1363,20 @@ export function listSessionIds() {
     .map((file) => basename(file, ".jsonl"));
 }
 
+/** Resolve an exact id or one unambiguous prefix without reading transcripts. */
+export function resolveSessionId(input) {
+  if (isUnsafeSessionId(input)) return null;
+  if (sessionExists(input)) return input;
+  const matches = listSessionIds().filter((id) => id.startsWith(input));
+  if (matches.length > 1) {
+    const error = new Error(`Ambiguous session id prefix: ${input}`);
+    error.code = "AMBIGUOUS_SESSION_ID";
+    error.matches = matches.slice(0, 20);
+    throw error;
+  }
+  return matches[0] || null;
+}
+
 export { TRANSCRIPT_CHAIN_STATUS };
 
 export function startSession(sessionId, meta = {}) {
@@ -141,21 +1384,248 @@ export function startSession(sessionId, meta = {}) {
     sessionId ||
     `session-${Date.now()}-${createHash("sha256").update(Math.random().toString()).digest("hex").slice(0, 6)}`;
 
-  appendEvent(id, "session_start", {
-    title: meta.title || "Untitled",
-    provider: meta.provider || "",
-    model: meta.model || "",
+  appendEvent(id, "session_start", {
+    title: meta.title || "Untitled",
+    provider: meta.provider || "",
+    model: meta.model || "",
+  });
+
+  return id;
+}
+
+export function appendUserMessage(sessionId, content) {
+  appendEvent(sessionId, "user_message", { role: "user", content });
+}
+
+export function appendAssistantMessage(sessionId, content) {
+  appendEvent(sessionId, "assistant_message", { role: "assistant", content });
+}
+
+function wsTurnLifecycleResult(snapshot, overrides = {}) {
+  return Object.freeze({
+    ...snapshot.state,
+    messages: snapshot.messages,
+    ...overrides,
+  });
+}
+
+/**
+ * Claim one canonical WebSocket request before any model/tool execution.
+ * Full chain verification, metadata-anchor validation, expected-head CAS and
+ * claim append all execute under the cross-process transcript writer lock.
+ */
+export function claimWsTurnIfHead(
+  sessionId,
+  { requestId, user, inputDigest, opaqueClaimId },
+  expectedHeadHash = null,
+) {
+  const normalizedUser = normalizeWsTurnContent(user, "user");
+  const computedDigest = computeWsTurnInputDigest(normalizedUser);
+  const canonicalDigest = normalizeWsTurnInputDigest(
+    inputDigest || computedDigest,
+  );
+  if (canonicalDigest !== computedDigest) {
+    throw wsTurnAuthorityError(
+      "WebSocket request input does not match its proposed claim digest",
+      "CC_WS_TURN_INPUT_DIGEST_MISMATCH",
+    );
+  }
+  const data = canonicalWsTurnClaimData({
+    requestId,
+    inputDigest: canonicalDigest,
+    opaqueClaimId,
   });
 
-  return id;
+  return withVerifiedWsTurnLock(sessionId, (filePath) => {
+    const snapshot = readVerifiedWsAuthorityLocked(
+      sessionId,
+      filePath,
+      data.requestId,
+      data.inputDigest,
+    );
+    if (snapshot.state.status !== "none") {
+      return wsTurnLifecycleResult(snapshot, {
+        acquired: false,
+        deduplicated: true,
+      });
+    }
+    if (snapshot.authority.headHash !== (expectedHeadHash || null)) {
+      const error = new Error(
+        `Session revision changed for ${sessionId}; refresh the canonical turn authority`,
+      );
+      error.code = "SESSION_REVISION_STALE";
+      error.expectedHeadHash = expectedHeadHash || null;
+      error.actualHeadHash = snapshot.authority.headHash;
+      throw error;
+    }
+    const appended = appendVerifiedWsAuthorityEventLocked(
+      sessionId,
+      filePath,
+      WS_TURN_CLAIM_EVENT,
+      data,
+      snapshot.authority.headHash,
+    );
+    const claim = projectWsTurnClaim(appended.event);
+    return Object.freeze({
+      ...snapshot.state,
+      status: "pending",
+      claim,
+      headHash: appended.hash,
+      eventCount: snapshot.authority.eventCount + 1,
+      messages: snapshot.messages,
+      acquired: true,
+      deduplicated: false,
+    });
+  });
 }
 
-export function appendUserMessage(sessionId, content) {
-  appendEvent(sessionId, "user_message", { role: "user", content });
+/** Settle only the exact durable claim that fenced model/tool execution. */
+export function settleWsTurnClaim(
+  sessionId,
+  {
+    requestId,
+    inputDigest,
+    opaqueClaimId,
+    outcome,
+    user,
+    assistant,
+    failureCode = "CC_WS_TURN_FAILED",
+  },
+) {
+  const identity = canonicalWsTurnClaimData({
+    requestId,
+    inputDigest,
+    opaqueClaimId,
+  });
+  const data =
+    outcome === "completed"
+      ? canonicalWsTurnCompletedData({
+          ...identity,
+          user,
+          assistant,
+        })
+      : outcome === "failed"
+        ? canonicalWsTurnFailedData({
+            ...identity,
+            failureCode,
+          })
+        : (() => {
+            throw wsTurnAuthorityError(
+              "WebSocket turn settlement outcome is invalid",
+              "CC_WS_TURN_OUTCOME_INVALID",
+            );
+          })();
+
+  return withVerifiedWsTurnLock(sessionId, (filePath) => {
+    const snapshot = readVerifiedWsAuthorityLocked(
+      sessionId,
+      filePath,
+      identity.requestId,
+      identity.inputDigest,
+    );
+    if (snapshot.state.settlement) {
+      if (snapshot.state.settlement.opaqueClaimId !== identity.opaqueClaimId) {
+        throw wsTurnAuthorityError(
+          "WebSocket request is settled by a different durable claim",
+          "CC_WS_TURN_CLAIM_NOT_OWNER",
+        );
+      }
+      return wsTurnLifecycleResult(snapshot, {
+        acquired: false,
+        deduplicated: true,
+      });
+    }
+    if (
+      snapshot.state.status !== "pending" ||
+      snapshot.state.claim?.opaqueClaimId !== identity.opaqueClaimId
+    ) {
+      throw wsTurnAuthorityError(
+        "WebSocket request has no matching pending claim to settle",
+        "CC_WS_TURN_CLAIM_NOT_OWNER",
+      );
+    }
+    const appended = appendVerifiedWsAuthorityEventLocked(
+      sessionId,
+      filePath,
+      WS_TURN_EVENT,
+      data,
+      snapshot.authority.headHash,
+    );
+    const settlement = projectWsTurnSettlement(appended.event);
+    return Object.freeze({
+      ...snapshot.state,
+      status: settlement.outcome,
+      settlement,
+      turn: settlement.outcome === "completed" ? settlement : null,
+      headHash: appended.hash,
+      eventCount: snapshot.authority.eventCount + 1,
+      messages:
+        settlement.outcome === "completed"
+          ? Object.freeze([
+              ...snapshot.messages,
+              settlement.user,
+              settlement.assistant,
+            ])
+          : snapshot.messages,
+      acquired: false,
+      deduplicated: false,
+    });
+  });
 }
 
-export function appendAssistantMessage(sessionId, content) {
-  appendEvent(sessionId, "assistant_message", { role: "assistant", content });
+/**
+ * Compatibility-only atomic settlement for callers that already hold a full
+ * response. Canonical WS handlers must use claimWsTurnIfHead() first.
+ */
+export function appendWsTurnIfHead(
+  sessionId,
+  { requestId, user, assistant },
+  expectedHeadHash = null,
+) {
+  const data = canonicalWsTurnCompletedData({ requestId, user, assistant });
+  const inputDigest = computeWsTurnInputDigest(data.user.content);
+  return withVerifiedWsTurnLock(sessionId, (filePath) => {
+    const snapshot = readVerifiedWsAuthorityLocked(
+      sessionId,
+      filePath,
+      data.requestId,
+      inputDigest,
+    );
+    if (snapshot.state.status === "completed") {
+      return Object.freeze({
+        ...snapshot.state.turn,
+        hash: snapshot.state.turn.eventHash,
+        deduplicated: true,
+      });
+    }
+    if (snapshot.state.status !== "none") {
+      throw wsTurnAuthorityError(
+        "WebSocket request already has claimed lifecycle authority",
+        "CC_WS_TURN_CLAIM_REQUIRED",
+      );
+    }
+    if (snapshot.authority.headHash !== (expectedHeadHash || null)) {
+      const error = new Error(
+        `Session revision changed for ${sessionId}; refresh the checkpoint timeline`,
+      );
+      error.code = "SESSION_REVISION_STALE";
+      error.expectedHeadHash = expectedHeadHash || null;
+      error.actualHeadHash = snapshot.authority.headHash;
+      throw error;
+    }
+    const appended = appendVerifiedWsAuthorityEventLocked(
+      sessionId,
+      filePath,
+      WS_TURN_EVENT,
+      data,
+      snapshot.authority.headHash,
+    );
+    return Object.freeze({
+      ...projectWsTurnMessages(appended.event),
+      hash: appended.hash,
+      deduplicated: false,
+    });
+  });
 }
 
 export function appendToolCall(sessionId, toolName, args) {
@@ -242,19 +1712,59 @@ export function appendCompactEvent(sessionId, stats) {
   appendEvent(sessionId, "compact", stats);
 }
 
+function canonicalReplayFingerprint(messages) {
+  return JSON.stringify(
+    projectCanonicalResumeMessages(messages, { strict: true }).map(
+      encodePersistedMessage,
+    ),
+  );
+}
+
+/**
+ * Persist a compact checkpoint only while the verified active replay still
+ * equals the caller's last known projection. Head-only CAS is insufficient for
+ * a long-lived REPL: it could sample a newer head that already contains turns
+ * absent from its local context and then accidentally hide those turns.
+ */
+export function appendCompactEventIfMessagesMatch(
+  sessionId,
+  stats,
+  expectedMessages,
+) {
+  const expectedFingerprint = canonicalReplayFingerprint(expectedMessages);
+  const persistedData = encodeEventMessageProvenance("compact", stats);
+  return withVerifiedWsTurnLock(sessionId, (filePath) => {
+    const verification = verifyTranscriptFile(filePath);
+    assertVerifiedTranscriptAnchor(sessionId, verification);
+    const actualMessages = rebuildVerifiedMessagesFromFile(filePath);
+    if (canonicalReplayFingerprint(actualMessages) !== expectedFingerprint) {
+      const error = new Error(
+        `Session messages changed for ${sessionId}; refresh before compacting`,
+      );
+      error.code = "SESSION_REVISION_STALE";
+      error.actualHeadHash = verification.lastHash;
+      throw error;
+    }
+    return appendVerifiedWsAuthorityEventLocked(
+      sessionId,
+      filePath,
+      "compact",
+      persistedData,
+      verification.lastHash,
+    );
+  });
+}
+
 export function readEvents(sessionId) {
   if (isUnsafeSessionId(sessionId)) return []; // traversal id → treat as empty
   const filePath = sessionPath(sessionId);
   if (!existsSync(filePath)) return [];
 
-  const content = readFileSync(filePath, "utf-8");
   const events = [];
-
-  for (const line of content.split("\n")) {
-    if (!line.trim()) continue;
+  for (const { line } of iterateFileLinesSync(filePath)) {
     try {
       events.push(JSON.parse(line));
-    } catch (_e) {
+    } catch {
       // Skip malformed lines
     }
   }
@@ -262,6 +1772,216 @@ export function readEvents(sessionId) {
   return events;
 }
 
+function unverifiedTranscriptError(sessionId, verification) {
+  const error = new Error(
+    `session transcript is not fully verified and anchored (${verification.status})`,
+  );
+  error.code = "SESSION_TRANSCRIPT_UNVERIFIED";
+  error.sessionId = sessionId;
+  error.verification = verification;
+  return error;
+}
+
+function assertVerifiedTranscriptAnchor(sessionId, verification) {
+  const meta = readSessionMeta(getSessionsDir(), sessionId);
+  const trustedStatus =
+    verification.status === TRANSCRIPT_CHAIN_STATUS.VERIFIED;
+  const anchoredHead =
+    meta?.deleted !== true &&
+    meta?.last_hash === verification.lastHash &&
+    Number(meta?.event_count) === verification.chainedEvents;
+  if (
+    !trustedStatus ||
+    !anchoredHead ||
+    verification.malformedLines > 0 ||
+    verification.truncatedTail
+  ) {
+    throw unverifiedTranscriptError(sessionId, verification);
+  }
+}
+
+/**
+ * Fold a fully verified transcript into a caller-owned projection.
+ *
+ * The projection factory and its `accept(event)` / `finish(authority)` methods
+ * execute while the canonical writer lock is held. Hash-chain verification,
+ * event reduction, and the independently persisted head/count check share one
+ * forward transcript pass. `finish()` may call `authority.readMessages()` to
+ * recover only the active context with bounded reverse IO (latest compact
+ * checkpoint plus its suffix).
+ *
+ * This removes the mandatory all-event array from resume projections. It does
+ * not make verification IO sublinear: authenticating a plain chained JSONL
+ * transcript remains O(N), and the local sidecar is not an anti-rollback
+ * anchor or a cross-process lease.
+ */
+export function readVerifiedProjection(
+  sessionId,
+  createProjection,
+  options = {},
+) {
+  if (typeof createProjection !== "function") {
+    throw new TypeError("Verified transcript projection factory is required");
+  }
+  if (isUnsafeSessionId(sessionId)) {
+    const error = new Error(
+      `unsafe session id: ${String(sessionId).slice(0, 60)}`,
+    );
+    error.code = "SESSION_TRANSCRIPT_UNVERIFIED";
+    error.sessionId = sessionId;
+    throw error;
+  }
+  const filePath = sessionPath(sessionId);
+
+  return withFileLock(
+    filePath,
+    () => {
+      const projection = createProjection();
+      if (
+        !projection ||
+        typeof projection.accept !== "function" ||
+        typeof projection.finish !== "function"
+      ) {
+        throw new TypeError(
+          "Verified transcript projection must provide accept() and finish()",
+        );
+      }
+      if (!existsSync(filePath)) {
+        return projection.finish(
+          Object.freeze({
+            headHash: null,
+            eventCount: 0,
+            readMessages: () => [],
+          }),
+        );
+      }
+      const verification = verifyTranscriptFile(filePath, {
+        ioMetrics: options.ioMetrics,
+        onVerifiedEvent: (event) => projection.accept(event),
+      });
+      assertVerifiedTranscriptAnchor(sessionId, verification);
+      return projection.finish(
+        Object.freeze({
+          headHash: verification.lastHash,
+          eventCount: verification.chainedEvents,
+          readMessages: () =>
+            rebuildVerifiedMessagesFromFile(filePath, {
+              ioMetrics: options.messageIoMetrics,
+            }),
+        }),
+      );
+    },
+    {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+      yieldAfterReleaseMs: 2,
+    },
+  );
+}
+
+/**
+ * Compatibility reader for consumers that still require the complete event
+ * array. New resume projections should use `readVerifiedProjection()` so their
+ * heap is bounded by active context plus reducer authority state.
+ */
+export function readVerifiedEvents(sessionId) {
+  return readVerifiedProjection(sessionId, () => {
+    const events = [];
+    return {
+      accept(event) {
+        events.push(event);
+      },
+      finish() {
+        return events;
+      },
+    };
+  });
+}
+
+/**
+ * Read the active context only after transcript and sidecar-anchor validation.
+ * Unlike the compatibility `rebuildMessages()` reader, this is allowed to
+ * restore hash-covered durable system-message provenance.
+ */
+export function readVerifiedMessages(sessionId, options = {}) {
+  return readVerifiedProjection(
+    sessionId,
+    () => ({
+      accept() {},
+      finish(authority) {
+        return Object.freeze([...authority.readMessages()]);
+      },
+    }),
+    options,
+  );
+}
+
+/**
+ * Read the verified head, active messages, and (when present) one durable
+ * WebSocket request settlement from the same locked transcript sample.
+ * Tracking only the requested id keeps idempotency lookup heap-bounded.
+ */
+export function readVerifiedWsTurnState(sessionId, requestId, options = {}) {
+  const canonicalRequestId = normalizeWsTurnRequestId(requestId);
+  const inputDigest =
+    options.inputDigest == null
+      ? null
+      : normalizeWsTurnInputDigest(options.inputDigest);
+  return readVerifiedProjection(
+    sessionId,
+    () => {
+      const reducer = createWsTurnLifecycleReducer({
+        requestId: canonicalRequestId,
+        inputDigest,
+      });
+      return {
+        accept(event) {
+          reducer.accept(event);
+        },
+        finish(authority) {
+          const state = reducer.finish(authority);
+          return Object.freeze({
+            sessionId,
+            ...state,
+            messages: Object.freeze([...authority.readMessages()]),
+          });
+        },
+      };
+    },
+    options,
+  );
+}
+
+/**
+ * Return the newest event matching a type/predicate using bounded reverse IO.
+ * This is the recovery path for snapshots and ledgers: callers never need to
+ * materialize a multi-gigabyte transcript merely to inspect its latest state.
+ */
+export function findLatestEvent(sessionId, type, predicate = null) {
+  if (isUnsafeSessionId(sessionId)) return null;
+  const filePath = sessionPath(sessionId);
+  if (!existsSync(filePath)) return null;
+  const wanted = Array.isArray(type) ? new Set(type) : null;
+  for (const { line } of iterateFileLinesReverseSync(filePath)) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const typeMatches = wanted
+      ? wanted.has(event?.type)
+      : type == null || event?.type === type;
+    if (!typeMatches) continue;
+    if (typeof predicate === "function" && !predicate(event)) continue;
+    return event;
+  }
+  return null;
+}
+
 /**
  * A replayable chat message must be a `{ role, content }` object — guard
  * against a corrupt / partially-written / hand-edited event whose `data` is
@@ -272,32 +1992,35 @@ function isReplayableMessage(m) {
   return Boolean(m) && typeof m === "object" && typeof m.role === "string";
 }
 
-export function rebuildMessages(sessionId) {
-  const events = readEvents(sessionId);
-  const messages = [];
-  let lastCompactIndex = -1;
-
-  // A `compact` event carries the pre-compaction snapshot in data.messages. A
-  // malformed compact line (type present but data null / messages not an array)
-  // must not crash the resume — skip it and look further back.
-  for (let i = events.length - 1; i >= 0; i--) {
-    const e = events[i];
-    if (e && e.type === "compact" && Array.isArray(e.data?.messages)) {
-      lastCompactIndex = i;
-      break;
+function rebuildMessagesFromFile(
+  filePath,
+  options = {},
+  decodeMessage = sanitizePersistedMessage,
+) {
+  const ioMetrics = options?.ioMetrics ?? null;
+  // Scan newest-first and stop at the latest valid compact checkpoint. Memory
+  // is therefore proportional to the active context suffix, not transcript
+  // size. Without a compact event the full conversation is necessarily the
+  // replay state, but the file itself is still never loaded as one giant string.
+  const suffix = [];
+  let checkpoint = [];
+  for (const { line } of iterateFileLinesReverseSync(filePath, { ioMetrics })) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
     }
-  }
-
-  if (lastCompactIndex >= 0) {
-    for (const m of events[lastCompactIndex].data.messages) {
-      if (isReplayableMessage(m)) messages.push(m);
+    if (
+      (event?.type === "compact" ||
+        event?.type === "checkpoint_timeline_commit") &&
+      Array.isArray(event.data?.messages)
+    ) {
+      checkpoint = event.data.messages
+        .map(decodeMessage)
+        .filter(isReplayableMessage);
+      break;
     }
-  }
-
-  const startIndex = lastCompactIndex >= 0 ? lastCompactIndex + 1 : 0;
-
-  for (let i = startIndex; i < events.length; i++) {
-    const event = events[i];
     if (
       event &&
       (event.type === "user_message" ||
@@ -305,11 +2028,33 @@ export function rebuildMessages(sessionId) {
         event.type === "system") &&
       isReplayableMessage(event.data)
     ) {
-      messages.push(event.data);
+      suffix.push(decodeMessage(event.data));
+    } else if (event?.type === WS_TURN_EVENT) {
+      const turn = projectWsTurnMessages(event);
+      if (turn) {
+        // The file is scanned newest-first. Push the pair in reverse so the
+        // final suffix.reverse() restores user → assistant atomically.
+        suffix.push(turn.assistant, turn.user);
+      }
     }
   }
+  suffix.reverse();
+  return [...checkpoint, ...suffix];
+}
+
+function rebuildVerifiedMessagesFromFile(filePath, options = {}) {
+  return rebuildMessagesFromFile(
+    filePath,
+    options,
+    decodeVerifiedPersistedMessage,
+  );
+}
 
-  return messages;
+export function rebuildMessages(sessionId, options = {}) {
+  if (isUnsafeSessionId(sessionId)) return [];
+  const filePath = sessionPath(sessionId);
+  if (!existsSync(filePath)) return [];
+  return rebuildMessagesFromFile(filePath, options);
 }
 
 /** ISO string for a numeric ms timestamp, or "" when missing / non-finite /
@@ -325,51 +2070,79 @@ export function toIsoSafe(ts) {
   return Number.isNaN(d.getTime()) ? "" : d.toISOString();
 }
 
+function rebuildSessionMetaUnlocked(dir, sessionId, filePath) {
+  let meta = emptySessionMeta(sessionId);
+  for (const { line } of iterateFileLinesSync(filePath)) {
+    try {
+      const event = JSON.parse(line);
+      meta = applyEventToSessionMeta(meta, event, event?.hash);
+    } catch {
+      // The validator/repair path reports malformed records. The index remains
+      // a best-effort projection over all intact events.
+    }
+  }
+  return replaceSessionMeta(dir, meta);
+}
+
+function rebuildSessionMeta(sessionId) {
+  const dir = getSessionsDir();
+  const filePath = sessionPath(sessionId);
+  if (!existsSync(filePath)) return null;
+  return withFileLock(
+    filePath,
+    () => rebuildSessionMetaUnlocked(dir, sessionId, filePath),
+    {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+    },
+  );
+}
+
+/** Read canonical session metadata without loading the transcript body. */
+export function getJsonlSessionMetadata(sessionId) {
+  if (isUnsafeSessionId(sessionId) || !sessionExists(sessionId)) return null;
+  const dir = getSessionsDir();
+  const meta = readSessionMeta(dir, sessionId) || rebuildSessionMeta(sessionId);
+  return meta ? publicSessionMeta(meta) : null;
+}
+
 export function listJsonlSessions(options = {}) {
   const dir = getSessionsDir();
   if (!existsSync(dir)) return [];
 
   const limit = options.limit || 20;
-  const files = readdirSync(dir)
-    .filter((f) => f.endsWith(".jsonl"))
-    .map((f) => {
-      const id = basename(f, ".jsonl");
-      const events = readEvents(id);
-      const startEvent = events.find((e) => e.type === "session_start");
-      const lastEvent = events[events.length - 1];
-      const messageCount = events.filter(
-        (e) => e.type === "user_message" || e.type === "assistant_message",
-      ).length;
-      // cc session rename appends session_rename events; the LAST one wins.
-      let renamedTitle = null;
-      for (const e of events) {
-        if (e.type === "session_rename" && e.data?.title) {
-          renamedTitle = e.data.title;
-        }
-      }
-
-      return {
-        id,
-        title: renamedTitle || startEvent?.data?.title || "Untitled",
-        provider: startEvent?.data?.provider || "",
-        model: startEvent?.data?.model || "",
-        message_count: messageCount,
-        created_at: toIsoSafe(startEvent?.timestamp),
-        updated_at: toIsoSafe(lastEvent?.timestamp),
-        _lastTs: lastEvent?.timestamp || 0,
-        _eventCount: events.length,
-      };
-    })
-    .sort((a, b) => {
-      // Primary: numeric timestamp descending
-      if (b._lastTs !== a._lastTs) return b._lastTs - a._lastTs;
-      // Tiebreak when ms collides: more events = more recent activity
-      return b._eventCount - a._eventCount;
-    })
-    .slice(0, limit)
-    .map(({ _lastTs, _eventCount, ...rest }) => rest);
+  const sessionIds = listSessionIds();
+  let indexed = listIndexedSessions(dir, {
+    limit,
+    hasSession: (id) => sessionExists(id),
+  });
 
-  return files;
+  // First use after upgrade (or a lost/corrupt rebuildable index): stream each
+  // legacy transcript once to seed its small sidecar and activity record.
+  const expected = Math.min(Math.max(0, Number(limit) || 0), sessionIds.length);
+  if (indexed.length < expected) {
+    const rebuilt = [];
+    for (const id of sessionIds) {
+      const meta = readSessionMeta(dir, id);
+      rebuilt.push(meta || rebuildSessionMeta(id));
+    }
+    // Directory enumeration order is not activity order. Re-append the rebuilt
+    // snapshots oldest-first so reverse journal reads preserve the transcript
+    // timestamps even on the first post-upgrade listing.
+    for (const meta of rebuilt
+      .filter(Boolean)
+      .sort((a, b) => (a.updated_at_ms || 0) - (b.updated_at_ms || 0))) {
+      recordSessionActivity(dir, meta);
+    }
+    indexed = listIndexedSessions(dir, {
+      limit,
+      hasSession: (id) => sessionExists(id),
+    });
+  }
+  return indexed;
 }
 
 /**
@@ -387,6 +2160,41 @@ export function renameSession(sessionId, title) {
   return { id: sessionId, title: normalized.slice(0, 200) };
 }
 
+/** Delete the canonical transcript under its writer lock and publish a
+ * rebuildable tombstone so an already-waiting stale writer cannot resurrect
+ * the session after the deletion commits. */
+export function deleteJsonlSession(sessionId) {
+  if (isUnsafeSessionId(sessionId)) return false;
+  const filePath = sessionPath(sessionId);
+  if (!existsSync(filePath)) return false;
+  return withFileLock(
+    filePath,
+    () => {
+      if (!existsSync(filePath)) return false;
+      rmSync(filePath, { force: true });
+      try {
+        recordSessionDeleted(getSessionsDir(), sessionId);
+      } catch (error) {
+        // writeMetaAtomic precedes the activity-journal append. If only the
+        // rebuildable journal lock/release failed, the durable sidecar still
+        // prevents a stale writer from resurrecting this deleted session.
+        if (readSessionMeta(getSessionsDir(), sessionId)?.deleted !== true) {
+          throw error;
+        }
+      }
+      return true;
+    },
+    {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+      yieldAfterReleaseMs: 2,
+    },
+  );
+}
+
 /**
  * Prune old sessions (gap-analysis 2026-07-11 P1 "保留期限"): delete session
  * transcripts whose LAST activity is older than `olderThanDays`, always
@@ -419,9 +2227,7 @@ export function pruneJsonlSessions(options = {}) {
       continue;
     }
     try {
-      rmSync(sessionPath(s.id), { force: true });
-      _chainTailCache.delete(s.id);
-      deleted.push(s.id);
+      if (deleteJsonlSession(s.id)) deleted.push(s.id);
     } catch {
       /* per-file failures never abort the sweep */
     }
@@ -434,31 +2240,405 @@ export function pruneJsonlSessions(options = {}) {
   };
 }
 
-export function forkSession(sourceId) {
-  const events = readEvents(sourceId);
-  if (events.length === 0) return null;
-
-  const newId = `session-${Date.now()}-${createHash("sha256").update(Math.random().toString()).digest("hex").slice(0, 6)}`;
-  const filePath = sessionPath(newId);
+function compareFilePrefix(candidatePath, fullPath) {
+  const candidateFd = openSync(candidatePath, "r");
+  const fullFd = openSync(fullPath, "r");
+  try {
+    const candidateSize = fstatSync(candidateFd).size;
+    const fullSize = fstatSync(fullFd).size;
+    if (candidateSize > fullSize) {
+      return { matches: false, candidateSize, fullSize };
+    }
+    const candidateBuffer = Buffer.allocUnsafe(64 * 1024);
+    const fullBuffer = Buffer.allocUnsafe(64 * 1024);
+    let offset = 0;
+    while (offset < candidateSize) {
+      const length = Math.min(candidateBuffer.length, candidateSize - offset);
+      const candidateRead = readSync(
+        candidateFd,
+        candidateBuffer,
+        0,
+        length,
+        offset,
+      );
+      const fullRead = readSync(fullFd, fullBuffer, 0, length, offset);
+      if (
+        candidateRead !== length ||
+        fullRead !== length ||
+        !candidateBuffer
+          .subarray(0, length)
+          .equals(fullBuffer.subarray(0, length))
+      ) {
+        return { matches: false, candidateSize, fullSize };
+      }
+      offset += length;
+    }
+    return { matches: true, candidateSize, fullSize };
+  } finally {
+    closeSync(candidateFd);
+    closeSync(fullFd);
+  }
+}
 
-  for (const event of events) {
-    const line = JSON.stringify(event) + "\n";
-    appendFileSync(filePath, line, "utf-8");
+const SESSION_FORK_AUTHORITY_SCHEMA =
+  "chainlesschain.session-fork-authority/v1";
+
+function normalizeForkRequestId(options) {
+  const requestId = options?.requestId ?? "default";
+  if (
+    typeof requestId !== "string" ||
+    requestId.length === 0 ||
+    Buffer.byteLength(requestId, "utf8") > 256
+  ) {
+    throw new TypeError(
+      "fork requestId must be a non-empty string <= 256 bytes",
+    );
   }
+  return requestId;
+}
 
-  appendEvent(newId, "system", {
-    role: "system",
-    content: `[Forked from session ${sourceId}]`,
-  });
+/**
+ * Copy one verified source revision into an idempotent successor. The target is
+ * bound to (sourceId, requestId), while its lineage record commits the source
+ * revision selected by the first completed attempt. Callers that intentionally
+ * need separate forks must pass separate requestId values.
+ */
+export function forkSession(sourceId, options = {}) {
+  if (isUnsafeSessionId(sourceId)) return null;
+  const requestId = normalizeForkRequestId(options);
+  const sourcePath = sessionPath(sourceId);
+  if (!existsSync(sourcePath)) return null;
+
+  return withFileLock(
+    sourcePath,
+    () => {
+      if (!existsSync(sourcePath)) return null;
+      const sourceVerification = verifyTranscriptFile(sourcePath);
+      assertVerifiedTranscriptAnchor(sourceId, sourceVerification);
+      const forkIdentity = JSON.stringify({
+        schemaVersion: 1,
+        sourceSessionId: sourceId,
+        requestId,
+      });
+      const forkDigest = createHash("sha256")
+        .update(forkIdentity, "utf8")
+        .digest("hex");
+      const requestDigest = `sha256:${forkDigest}`;
+      const newId = `session-fork-${forkDigest.slice(0, 32)}`;
+      const filePath = sessionPath(newId);
+      const sessionsDir = getSessionsDir();
+      const pendingPath = join(sessionsDir, `${newId}.fork.pending`);
+      const persistedData = encodeEventMessageProvenance(
+        "system",
+        markDurableSystemMessage(
+          {
+            role: "system",
+            content: `[Forked from session ${sourceId}]`,
+          },
+          DURABLE_SYSTEM_MESSAGE_KINDS.FORK_LINEAGE,
+        ),
+      );
 
-  return newId;
+      return withFileLock(
+        filePath,
+        () => {
+          let targetMeta = readSessionMeta(sessionsDir, newId);
+          const finalExists = existsSync(filePath);
+          const pendingExists = existsSync(pendingPath);
+          if (finalExists && pendingExists) {
+            throw unverifiedTranscriptError(
+              newId,
+              verifyTranscriptFile(filePath),
+            );
+          }
+          if (!finalExists && targetMeta !== null) {
+            throw unverifiedTranscriptError(newId, {
+              status: "not-found",
+              chainedEvents: 0,
+              malformedLines: 0,
+              truncatedTail: false,
+              lastHash: null,
+            });
+          }
+          let workingPath = finalExists ? filePath : pendingPath;
+          if (!finalExists && !pendingExists) {
+            if (targetMeta !== null) {
+              throw unverifiedTranscriptError(newId, {
+                status: "not-found",
+                chainedEvents: 0,
+                malformedLines: 0,
+                truncatedTail: false,
+                lastHash: null,
+              });
+            }
+            copyFileSync(sourcePath, workingPath, fsConstants.COPYFILE_EXCL);
+            ensurePrivateFile(workingPath);
+            runSessionScaleFaultHook("afterForkCopy", {
+              sourceId,
+              sessionId: newId,
+              filePath: workingPath,
+            });
+          } else {
+            const prefix = compareFilePrefix(workingPath, sourcePath);
+            if (prefix.matches && prefix.candidateSize < prefix.fullSize) {
+              if (targetMeta !== null) {
+                throw unverifiedTranscriptError(
+                  newId,
+                  verifyTranscriptFile(workingPath),
+                );
+              }
+              // copyFileSync can leave an exact byte prefix after a hard exit.
+              // The deterministic target lock and prefix proof make replacing
+              // only that unpublished target safe and crash-resumable.
+              rmSync(workingPath, { force: true });
+              copyFileSync(sourcePath, workingPath, fsConstants.COPYFILE_EXCL);
+              ensurePrivateFile(workingPath);
+              runSessionScaleFaultHook("afterForkCopy", {
+                sourceId,
+                sessionId: newId,
+                filePath: workingPath,
+              });
+            }
+          }
+
+          const inspectTarget = () => {
+            let sourceBoundaryHash = null;
+            let lineageEvent = null;
+            let lineageEventIndex = null;
+            let lineageAuthority = null;
+            let matchingLineageEvents = 0;
+            let eventIndex = 0;
+            const verification = verifyTranscriptFile(workingPath, {
+              onVerifiedEvent(event) {
+                eventIndex += 1;
+                if (eventIndex === sourceVerification.chainedEvents) {
+                  sourceBoundaryHash = event.hash;
+                }
+                const authority = event?.data?.[SESSION_FORK_AUTHORITY_FIELD];
+                if (
+                  event?.type === "system" &&
+                  authority?.schema === SESSION_FORK_AUTHORITY_SCHEMA &&
+                  authority?.requestDigest === requestDigest &&
+                  authority?.sourceSessionId === sourceId
+                ) {
+                  matchingLineageEvents += 1;
+                  lineageEvent = event;
+                  lineageEventIndex = eventIndex;
+                  lineageAuthority = authority;
+                }
+              },
+            });
+            return {
+              verification,
+              sourceBoundaryHash,
+              lineageEvent,
+              lineageEventIndex,
+              lineageAuthority,
+              matchingLineageEvents,
+            };
+          };
+
+          let target = inspectTarget();
+          if (
+            target.sourceBoundaryHash === sourceVerification.lastHash &&
+            target.verification.chainedEvents ===
+              sourceVerification.chainedEvents &&
+            target.verification.truncatedTail &&
+            targetMeta === null
+          ) {
+            // A hard exit can cut the one lineage append. Discard only that
+            // unanchored physical tail, then prove the copied source again.
+            inspectPhysicalTail(workingPath);
+            target = inspectTarget();
+          }
+
+          const cleanTarget =
+            target.verification.status === TRANSCRIPT_CHAIN_STATUS.VERIFIED &&
+            target.verification.malformedLines === 0 &&
+            !target.verification.truncatedTail;
+          const exactSourceCopy =
+            cleanTarget &&
+            target.sourceBoundaryHash === sourceVerification.lastHash &&
+            target.verification.chainedEvents ===
+              sourceVerification.chainedEvents;
+
+          if (exactSourceCopy) {
+            if (targetMeta !== null) {
+              throw unverifiedTranscriptError(newId, target.verification);
+            }
+            const { prevHash } = _resolveChainTail(workingPath);
+            if (prevHash !== sourceVerification.lastHash) {
+              const error = new Error(
+                `Fork source changed while copying: ${sourceId}`,
+              );
+              error.code = "SESSION_REVISION_STALE";
+              throw error;
+            }
+            const forkAuthority = {
+              schema: SESSION_FORK_AUTHORITY_SCHEMA,
+              requestDigest,
+              sourceSessionId: sourceId,
+              sourceHeadHash: sourceVerification.lastHash,
+              sourceEventCount: sourceVerification.chainedEvents,
+            };
+            const core = {
+              type: "system",
+              timestamp: Date.now(),
+              data: {
+                ...persistedData,
+                [SESSION_FORK_AUTHORITY_FIELD]: forkAuthority,
+              },
+            };
+            const hash = computeEventHash(prevHash, core);
+            appendFileSync(
+              workingPath,
+              `${JSON.stringify({ ...core, prevHash, hash })}\n`,
+              { encoding: "utf8", mode: 0o600 },
+            );
+            ensurePrivateFile(workingPath);
+            runSessionScaleFaultHook("afterForkLineage", {
+              sourceId,
+              sessionId: newId,
+              filePath: workingPath,
+              event: { ...core, prevHash, hash },
+            });
+            target = inspectTarget();
+            targetMeta = readSessionMeta(sessionsDir, newId);
+          }
+
+          const authority = target.lineageAuthority;
+          const authorityEventCount = Number(authority?.sourceEventCount);
+          const creationEventCount = authorityEventCount + 1;
+          const expectedAuthority = {
+            schema: SESSION_FORK_AUTHORITY_SCHEMA,
+            requestDigest,
+            sourceSessionId: sourceId,
+            sourceHeadHash: authority?.sourceHeadHash,
+            sourceEventCount: authorityEventCount,
+          };
+          const lineageMatches =
+            target.matchingLineageEvents === 1 &&
+            target.lineageEvent?.type === "system" &&
+            Number.isSafeInteger(authorityEventCount) &&
+            authorityEventCount > 0 &&
+            typeof authority?.sourceHeadHash === "string" &&
+            target.lineageEventIndex === creationEventCount &&
+            target.lineageEvent?.prevHash === authority.sourceHeadHash &&
+            JSON.stringify(target.lineageEvent?.data) ===
+              JSON.stringify({
+                ...persistedData,
+                [SESSION_FORK_AUTHORITY_FIELD]: expectedAuthority,
+              });
+          if (
+            target.verification.status !== TRANSCRIPT_CHAIN_STATUS.VERIFIED ||
+            target.verification.chainedEvents < creationEventCount ||
+            !lineageMatches ||
+            target.verification.malformedLines > 0 ||
+            target.verification.truncatedTail
+          ) {
+            throw unverifiedTranscriptError(newId, target.verification);
+          }
+
+          const anchorMatchesTarget =
+            targetMeta?.deleted !== true &&
+            targetMeta?.last_hash === target.verification.lastHash &&
+            Number(targetMeta?.event_count) ===
+              target.verification.chainedEvents;
+          if (anchorMatchesTarget) {
+            const activity = readLatestSessionActivity(sessionsDir, newId);
+            if (
+              activity?.deleted === true ||
+              activity?.last_hash !== targetMeta.last_hash ||
+              Number(activity?.event_count) !== Number(targetMeta.event_count)
+            ) {
+              recordSessionActivity(sessionsDir, targetMeta);
+            }
+            return newId;
+          }
+
+          // A completed or progressed successor with a non-matching anchor is a
+          // rollback/conflict, never a crash prefix that this request may bless.
+          if (
+            targetMeta !== null ||
+            target.verification.chainedEvents > creationEventCount
+          ) {
+            throw unverifiedTranscriptError(newId, target.verification);
+          }
+
+          let sourceAuthorityHash = null;
+          if (authorityEventCount === sourceVerification.chainedEvents) {
+            sourceAuthorityHash = sourceVerification.lastHash;
+          } else if (authorityEventCount < sourceVerification.chainedEvents) {
+            let index = 0;
+            const authorityVerification = verifyTranscriptFile(sourcePath, {
+              onVerifiedEvent(event) {
+                index += 1;
+                if (index === authorityEventCount) {
+                  sourceAuthorityHash = event.hash;
+                }
+              },
+            });
+            assertVerifiedTranscriptAnchor(sourceId, authorityVerification);
+          }
+          if (sourceAuthorityHash !== authority.sourceHeadHash) {
+            const error = new Error(
+              `Fork source revision no longer contains the claimed authority: ${sourceId}`,
+            );
+            error.code = "SESSION_REVISION_STALE";
+            throw error;
+          }
+
+          if (workingPath === pendingPath) {
+            if (existsSync(filePath)) {
+              throw unverifiedTranscriptError(
+                newId,
+                verifyTranscriptFile(filePath),
+              );
+            }
+            renameSync(pendingPath, filePath);
+            workingPath = filePath;
+            ensurePrivateFile(workingPath);
+            runSessionScaleFaultHook("afterForkPublish", {
+              sourceId,
+              sessionId: newId,
+              filePath: workingPath,
+            });
+          }
+
+          rebuildSessionMetaUnlocked(sessionsDir, newId, filePath);
+          runSessionScaleFaultHook("afterForkMeta", {
+            sourceId,
+            sessionId: newId,
+            filePath,
+          });
+          assertVerifiedTranscriptAnchor(newId, target.verification);
+          return newId;
+        },
+        {
+          failIfUnavailable: true,
+          timeoutMs: 30_000,
+          retryMs: 1,
+          maxRetryMs: 8,
+          retryJitterMs: 4,
+        },
+      );
+    },
+    {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+      yieldAfterReleaseMs: 2,
+    },
+  );
 }
 
 /**
  * Create an independent BRANCH session ("从这里分支" — P0-3's fourth restore
  * action) that keeps a parent's conversation up to a chosen turn and diverges
- * from there. Unlike forkSession() (whole-session copy, random id, no lineage),
- * this writes ONLY the caller-supplied pre-branch messages under a deterministic
+ * from there. Unlike forkSession() (a whole-session copy with revision-scoped
+ * request identity), this writes ONLY the caller-supplied pre-branch messages
  * id (see deriveBranchSessionId) and records parent lineage — so the origin
  * session is never touched (preservesParent) and a replayed branch request
  * resolves to the SAME file instead of a duplicate (idempotent).
@@ -483,35 +2663,214 @@ export function createBranchSession({
       `unsafe branch session id: ${String(branchSessionId).slice(0, 60)}`,
     );
   }
-  // Idempotent: a replayed branch request resolves to the existing branch
-  // rather than doubling it (matches deriveBranchId's determinism).
-  if (existsSync(sessionPath(branchSessionId))) {
-    return { branchSessionId, created: false, messages: 0 };
-  }
-
-  startSession(branchSessionId, {
-    title: meta.title || `Branch of ${parentSessionId ?? "session"}`,
-    provider: meta.provider || "",
-    model: meta.model || "",
-  });
-  appendEvent(branchSessionId, "session_branch", {
-    parentSessionId: parentSessionId == null ? null : String(parentSessionId),
-    parentTurnId: parentTurnId == null ? null : String(parentTurnId),
+  // Validate and clone the complete message projection before creating the
+  // deterministic branch file. A validation failure must leave no partial
+  // session that would make a later, valid retry look idempotently complete.
+  const canonicalMessages = projectCanonicalResumeMessages(messages, {
+    strict: true,
   });
-
+  if (
+    (parentSessionId !== null && typeof parentSessionId !== "string") ||
+    (parentTurnId !== null && typeof parentTurnId !== "string")
+  ) {
+    throw new TypeError("Branch lineage ids must be strings or null");
+  }
+  const branchParentSessionId = parentSessionId;
+  const branchParentTurnId = parentTurnId;
+  const cleanMeta = sanitizePersistedMessage(meta);
+  if (!cleanMeta || typeof cleanMeta !== "object") {
+    throw new TypeError("Branch metadata must contain JSON-safe data");
+  }
+  const startData = {
+    title:
+      typeof cleanMeta.title === "string" && cleanMeta.title
+        ? cleanMeta.title
+        : `Branch of ${branchParentSessionId ?? "session"}`,
+    provider: typeof cleanMeta.provider === "string" ? cleanMeta.provider : "",
+    model: typeof cleanMeta.model === "string" ? cleanMeta.model : "",
+  };
+  const plannedEvents = [
+    { type: "session_start", data: startData },
+    {
+      type: "session_branch",
+      data: {
+        parentSessionId: branchParentSessionId,
+        parentTurnId: branchParentTurnId,
+      },
+    },
+  ];
   let count = 0;
-  for (const m of Array.isArray(messages) ? messages : []) {
-    if (!m || m.role == null) continue;
+  for (const m of canonicalMessages) {
     if (m.role === "user") {
-      appendUserMessage(branchSessionId, m.content);
+      plannedEvents.push({
+        type: "user_message",
+        data: { role: "user", content: m.content },
+      });
       count += 1;
     } else if (m.role === "assistant") {
-      appendAssistantMessage(branchSessionId, m.content);
+      plannedEvents.push({
+        type: "assistant_message",
+        data: { role: "assistant", content: m.content },
+      });
+      count += 1;
+    } else if (m.role === "system") {
+      plannedEvents.push({
+        type: "system",
+        data: encodePersistedMessage(m),
+      });
       count += 1;
     }
-    // system prompt + tool scaffolding are re-established on resume; skip here.
+    // Host prompts and tool scaffolding are re-established on resume. The
+    // canonical projection above retains only explicitly durable systems.
   }
-  return { branchSessionId, created: true, messages: count };
+  const inputDigest = `sha256:${createHash("sha256")
+    .update(JSON.stringify(plannedEvents), "utf8")
+    .digest("hex")}`;
+  plannedEvents.push({
+    type: "session_branch_complete",
+    data: {
+      schemaVersion: 1,
+      inputDigest,
+      messageCount: count,
+    },
+  });
+
+  const filePath = sessionPath(branchSessionId);
+  const sessionsDir = getSessionsDir();
+  return withFileLock(
+    filePath,
+    () => {
+      if (existsSync(filePath)) inspectPhysicalTail(filePath);
+      let verification = existsSync(filePath)
+        ? verifyTranscriptFile(filePath)
+        : {
+            status: TRANSCRIPT_CHAIN_STATUS.EMPTY,
+            chainedEvents: 0,
+            malformedLines: 0,
+            truncatedTail: false,
+            lastHash: null,
+          };
+      if (
+        verification.status !== TRANSCRIPT_CHAIN_STATUS.EMPTY &&
+        verification.status !== TRANSCRIPT_CHAIN_STATUS.VERIFIED
+      ) {
+        throw unverifiedTranscriptError(branchSessionId, verification);
+      }
+      const existingEvents = existsSync(filePath)
+        ? readEvents(branchSessionId)
+        : [];
+      const prefixMatches = existingEvents
+        .slice(0, Math.min(existingEvents.length, plannedEvents.length))
+        .every(
+          (event, index) =>
+            event.type === plannedEvents[index].type &&
+            JSON.stringify(event.data) ===
+              JSON.stringify(plannedEvents[index].data),
+        );
+      if (!prefixMatches) {
+        const error = new Error(
+          `Branch session conflicts with its deterministic input: ${branchSessionId}`,
+        );
+        error.code = "SESSION_BRANCH_CONFLICT";
+        throw error;
+      }
+
+      // Once the exact completion marker is anchored, later branch turns are
+      // outside the idempotent creation transaction. A replay resolves to that
+      // progressed branch, but an unanchored suffix is never re-blessed.
+      if (existingEvents.length > plannedEvents.length) {
+        assertVerifiedTranscriptAnchor(branchSessionId, verification);
+        return { branchSessionId, created: false, messages: 0 };
+      }
+
+      // A crashed writer can leave a hash-valid planned prefix ahead of its
+      // sidecar. Only advance an existing anchor along that exact prefix. Never
+      // lower or replace a higher/different anchor: doing so would legitimize a
+      // truncated deterministic branch and permanently discard later turns.
+      const anchoredMeta = readSessionMeta(sessionsDir, branchSessionId);
+      const anchoredCount = Number(anchoredMeta?.event_count);
+      const anchorMatchesCurrent =
+        anchoredMeta?.deleted !== true &&
+        anchoredMeta?.last_hash === verification.lastHash &&
+        anchoredCount === verification.chainedEvents;
+      const anchorIsStrictPriorPrefix =
+        anchoredMeta?.deleted !== true &&
+        Number.isSafeInteger(anchoredCount) &&
+        anchoredCount >= 0 &&
+        anchoredCount < verification.chainedEvents &&
+        verification.chainedEvents === existingEvents.length &&
+        (anchoredCount === 0
+          ? anchoredMeta?.last_hash === null
+          : existingEvents[anchoredCount - 1]?.hash ===
+            anchoredMeta?.last_hash);
+      if (
+        anchoredMeta !== null &&
+        !anchorMatchesCurrent &&
+        !anchorIsStrictPriorPrefix
+      ) {
+        throw unverifiedTranscriptError(branchSessionId, verification);
+      }
+      if (existsSync(filePath) && !anchorMatchesCurrent) {
+        rebuildSessionMetaUnlocked(sessionsDir, branchSessionId, filePath);
+      }
+      if (existingEvents.length > 0) {
+        assertVerifiedTranscriptAnchor(branchSessionId, verification);
+      }
+      if (existingEvents.length === plannedEvents.length) {
+        return { branchSessionId, created: false, messages: 0 };
+      }
+
+      let prevHash = verification.lastHash;
+      for (
+        let index = existingEvents.length;
+        index < plannedEvents.length;
+        index += 1
+      ) {
+        const planned = plannedEvents[index];
+        const core = {
+          type: planned.type,
+          timestamp: Date.now(),
+          data: planned.data,
+        };
+        const hash = computeEventHash(prevHash, core);
+        const event = { ...core, prevHash, hash };
+        appendFileSync(filePath, `${JSON.stringify(event)}\n`, {
+          encoding: "utf8",
+          mode: 0o600,
+        });
+        ensurePrivateFile(filePath);
+        runSessionScaleFaultHook("afterTranscriptAppend", {
+          sessionId: branchSessionId,
+          type: planned.type,
+          event,
+          filePath,
+        });
+        prevHash = hash;
+      }
+
+      verification = verifyTranscriptFile(filePath);
+      if (
+        verification.status !== TRANSCRIPT_CHAIN_STATUS.VERIFIED ||
+        verification.chainedEvents !== plannedEvents.length ||
+        verification.lastHash !== prevHash ||
+        verification.malformedLines > 0 ||
+        verification.truncatedTail
+      ) {
+        throw unverifiedTranscriptError(branchSessionId, verification);
+      }
+      rebuildSessionMetaUnlocked(sessionsDir, branchSessionId, filePath);
+      assertVerifiedTranscriptAnchor(branchSessionId, verification);
+      return { branchSessionId, created: true, messages: count };
+    },
+    {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+      yieldAfterReleaseMs: 2,
+    },
+  );
 }
 
 export function sessionExists(sessionId) {
@@ -618,30 +2977,48 @@ export function validateJsonlSession(sessionId) {
     };
   }
 
-  const lines = readFileSync(filePath, "utf-8").split("\n");
   let malformedLines = 0;
-  const events = [];
-
-  for (const line of lines) {
-    if (!line.trim()) continue;
+  let eventCount = 0;
+  let messageCount = 0;
+  let invalidWsTurns = 0;
+  let invalidWsClaims = 0;
+  let hasStartEvent = false;
+  for (const { line } of iterateFileLinesSync(filePath)) {
     try {
-      events.push(JSON.parse(line));
+      const event = JSON.parse(line);
+      eventCount += 1;
+      if (event?.type === "session_start") hasStartEvent = true;
+      if (
+        event?.type === "user_message" ||
+        event?.type === "assistant_message"
+      ) {
+        messageCount += 1;
+      } else if (event?.type === WS_TURN_EVENT) {
+        const settlement = projectWsTurnSettlement(event);
+        if (!settlement) invalidWsTurns += 1;
+        else if (settlement.outcome === "completed") messageCount += 2;
+      } else if (
+        event?.type === WS_TURN_CLAIM_EVENT &&
+        !projectWsTurnClaim(event)
+      ) {
+        invalidWsClaims += 1;
+      }
     } catch {
       malformedLines++;
     }
   }
 
-  const hasStartEvent = events.some((event) => event.type === "session_start");
-  const messageCount = events.filter(
-    (event) =>
-      event.type === "user_message" || event.type === "assistant_message",
-  ).length;
-
   return {
     sessionId,
-    valid: malformedLines === 0 && hasStartEvent,
+    valid:
+      malformedLines === 0 &&
+      invalidWsTurns === 0 &&
+      invalidWsClaims === 0 &&
+      hasStartEvent,
     malformedLines,
-    eventCount: events.length,
+    invalidWsTurns,
+    invalidWsClaims,
+    eventCount,
     messageCount,
     hasStartEvent,
   };
@@ -709,10 +3086,17 @@ function performLegacySessionMigration(sourcePath, options) {
       appendLegacyMessage(sessionId, message);
     }
     if (legacy.summary) {
-      appendEvent(sessionId, "system", {
-        role: "system",
-        content: `[Migrated Summary]\n${legacy.summary}`,
-      });
+      appendEvent(
+        sessionId,
+        "system",
+        markDurableSystemMessage(
+          {
+            role: "system",
+            content: `[Migrated Summary]\n${legacy.summary}`,
+          },
+          DURABLE_SYSTEM_MESSAGE_KINDS.MIGRATION_SUMMARY,
+        ),
+      );
     }
 
     const validation = validateJsonlSession(sessionId);