@thaut/claude-ide 0.0.0-stage → 1.0.0

package/server/history-pages.ts

@@ -0,0 +1,513 @@
+import { goalCommand, recordText, type GoalRecord } from "./goal-state.ts";
+import { selectSessionBranch, eligibleBranchEntry, HistoryError } from "./session-branch.ts";
+export { HistoryError } from "./session-branch.ts";
+import { deriveTodos, type TodoItem } from "../shared/todos.ts";
+import fs from "node:fs/promises";
+import crypto from "node:crypto";
+import { PAGE_BYTES, PAGE_LIMIT, SESSION_BYTES, displayMessage } from "../shared/message-window.ts";
+import type { HistoryPage, SdkMessageLike } from "../shared/protocol.ts";
+
+type RecordLike = SdkMessageLike & { parentUuid?: string | null; logicalParentUuid?: string; isSidechain?: boolean; agentId?: string; sourceToolAssistantUUID?: string; teamName?: string; isMeta?: boolean; operation?: string; reason?: string; deliveryId?: string; commandUuid?: string; origin?: { kind?: string }; attachment?: { type?: string; prompt?: unknown; source_uuid?: string; delivery_id?: string; isMeta?: boolean; origin?: { kind?: string }; forwardedIntent?: unknown }; compactMetadata?: { preservedMessages?: { uuids: string[]; anchorUuid: string }; preservedSegment?: { headUuid: string; tailUuid: string; anchorUuid: string } } };
+type Entry = Pick<RecordLike, "type" | "subtype" | "uuid" | "parentUuid" | "logicalParentUuid" | "isSidechain" | "teamName" | "isMeta" | "isCompactSummary" | "compactMetadata"> & {
+  inherited?: boolean; goalCommand?: string;
+  uuid: string; offset: number; length: number; order: number; messageId?: string; timestamp?: string; agentId?: string; sourceToolAssistantUUID?: string; queued?: boolean; sourceUuid?: string; queuedKey?: string; queuedHash?: string; queuedFirstOrder?: number; attachmentType?: string; originKind?: string; queuedMeta?: boolean; queuedOriginKind?: string; queuedPrompt?: boolean; queuedForwarded?: boolean; interrupted?: boolean; localPrompt?: "caveat" | "record" | "output"; completedLocalCommand?: boolean; tools?: string[]; results?: string[]; todoItems?: (TodoItem & { id: string })[]; todoIds?: { id: string; taskId: string; isError: boolean }[];
+};
+type Index = { generation: string; inode: number; size: number; fileSize: number; mtime: number; entries: Map<string, Entry>; deliveries: { key: string; order: number }[]; legacyCopies: Map<string, { hash: string; mixedAt?: number }>; used: number; bytes: number };
+const indexes = new Map<string, Index>();
+// Keep only revision scalars when an offset index is evicted. Rebuilding an
+// unchanged file must retain its generation, including after an in-place rewrite.
+type Revision = { identity: string; generation: string; size: number; mtime: number; prefixLength: number; prefixHash: string };
+const revisions = new Map<string, Revision>();
+const REVISION_LIMIT = 1024;
+const locks = new Map<string, Promise<unknown>>();
+const INDEX_BUDGET = 32 * 1024 * 1024;
+
+
+/** Serialize indexing + reads per file. The cache contains offsets/links, never message bodies. */
+async function withIndex<T>(file: string | undefined, fn: (index: Index, handle: fs.FileHandle) => Promise<T>): Promise<T | undefined> {
+  if (!file) return undefined;
+  const previous = locks.get(file) ?? Promise.resolve();
+  const work = previous.catch(() => {}).then(async () => {
+    let handle: fs.FileHandle;
+    try { handle = await fs.open(file, "r"); } catch (e) { if ((e as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw e; }
+    try {
+      const stat = await handle.stat();
+      const identity = `${stat.dev}:${stat.ino}:${stat.birthtimeMs}`;
+      let revision = revisions.get(file);
+      const prefixLength = revision?.identity === identity && revision.prefixLength ? Math.min(revision.prefixLength, stat.size) : Math.min(4096, stat.size);
+      const prefix = Buffer.alloc(prefixLength);
+      let prefixRead = 0;
+      while (prefixRead < prefix.length) {
+        const { bytesRead } = await handle.read(prefix, prefixRead, prefix.length - prefixRead, prefixRead);
+        if (!bytesRead) throw new HistoryError(409, "会话文件已变化，请重新加载");
+        prefixRead += bytesRead;
+      }
+      const prefixHash = crypto.createHash("sha256").update(prefix).digest("hex");
+      if (!revision || revision.identity !== identity || stat.size < revision.size || stat.size === revision.size && stat.mtimeMs !== revision.mtime || revision.prefixLength > 0 && prefixHash !== revision.prefixHash) {
+        const generation = crypto.createHash("sha256").update(`${file}:${identity}:${stat.size}:${stat.mtimeMs}:${prefixHash}`).digest("hex");
+        revision = { identity, generation, size: stat.size, mtime: stat.mtimeMs, prefixLength, prefixHash };
+      }
+      revisions.delete(file); revisions.set(file, revision);
+      while (revisions.size > REVISION_LIMIT) revisions.delete(revisions.keys().next().value!);
+      let index = indexes.get(file);
+      if (!index || index.generation !== revision.generation) {
+        // Cache eviction must not invalidate a cursor for the same file. Revision
+        // checks live in the cursor; this identity remains stable across appends.
+        index = { generation: revision.generation, inode: stat.ino, size: 0, fileSize: 0, mtime: 0, entries: new Map(), deliveries: [], legacyCopies: new Map(), used: Date.now(), bytes: 0 };
+        indexes.set(file, index);
+      }
+      // Only complete lines are committed. A half-written final line is retried next time.
+      let pending: Buffer[] = [];
+      let pendingLength = 0;
+      let offset = index.size;
+      const end = stat.size;
+      for (let position = offset; position < end;) {
+        const chunk = Buffer.allocUnsafe(Math.min(256 * 1024, end - position));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+        if (!bytesRead) break;
+        const chunkStart = position;
+        position += bytesRead;
+        const data = chunk.subarray(0, bytesRead);
+        let start = 0;
+        for (;;) {
+          const nl = data.indexOf(10, start);
+          if (nl < 0) break;
+          const length = pendingLength + nl - start;
+          const line = pendingLength ? Buffer.concat([...pending, data.subarray(start, nl)], length) : data.subarray(start, nl);
+          try {
+            const r = JSON.parse(line.toString("utf8")) as RecordLike;
+            if (r.type === "queue-operation" && r.operation === "remove" && r.reason === "absorbed_mid_turn") {
+              const key = deliveryKey(r.deliveryId, r.commandUuid);
+              if (key) { index.deliveries.push({ key, order: offset }); index.bytes += 48 + key.length * 2; }
+            }
+            if (r.uuid && ["user", "assistant", "system", "attachment", "progress"].includes(r.type)) {
+              const message = r.message as { id?: string; content?: unknown } | undefined;
+              const content = message?.content;
+              const blocks = Array.isArray(content) ? content : [];
+              const queued = r.attachment?.type === "queued_command";
+              const queuedKey = queued ? deliveryKey(r.attachment!.delivery_id, r.attachment!.source_uuid) : undefined;
+              const queuedHash = queued ? crypto.createHash("sha256").update(JSON.stringify(r.attachment)).digest("hex") : undefined;
+              const previous = index.entries.get(r.uuid);
+              // Rewrites of the same attachment retain its membership position;
+              // a changed payload or key is a new copy at the current offset.
+              let queuedFirstOrder: number | undefined;
+              if (queued) queuedFirstOrder = previous?.queued && previous.queuedHash === queuedHash ? previous.queuedFirstOrder ?? offset : offset;
+              if (queuedKey?.startsWith("uuid:")) {
+                const hash = queuedHash!;
+                const copy = index.legacyCopies.get(queuedKey);
+                if (!copy) { index.legacyCopies.set(queuedKey, { hash }); index.bytes += 80 + (queuedKey.length + hash.length) * 2; }
+                else if (copy.hash !== hash && copy.mixedAt === undefined) copy.mixedAt = offset;
+              }
+              const command = goalCommand(r as GoalRecord);
+              const entry: Entry = { inherited: !!r.forkedFrom, goalCommand: command, uuid: r.uuid, type: r.type, subtype: r.subtype, parentUuid: r.parentUuid, logicalParentUuid: r.logicalParentUuid,
+                messageId: r.type === "assistant" && typeof message?.id === "string" && message.id ? message.id : undefined,
+                timestamp: typeof r.timestamp === "string" ? r.timestamp : undefined, agentId: r.agentId, sourceToolAssistantUUID: r.sourceToolAssistantUUID,
+                isSidechain: r.isSidechain, teamName: r.teamName, isMeta: r.isMeta, isCompactSummary: r.isCompactSummary, compactMetadata: r.compactMetadata ? {
+                  preservedMessages: r.compactMetadata.preservedMessages ? { uuids: r.compactMetadata.preservedMessages.uuids, anchorUuid: r.compactMetadata.preservedMessages.anchorUuid } : undefined,
+                  preservedSegment: r.compactMetadata.preservedSegment,
+                } : undefined,
+                queued, sourceUuid: nonemptyString(r.attachment?.source_uuid),
+                queuedKey, queuedHash, queuedFirstOrder,
+                attachmentType: r.attachment?.type, originKind: r.origin?.kind,
+                queuedMeta: r.attachment?.isMeta, queuedOriginKind: r.attachment?.origin?.kind, queuedPrompt: typeof r.attachment?.prompt === "string" || Array.isArray(r.attachment?.prompt),
+                queuedForwarded: forwardedIntent(r.attachment?.forwardedIntent), interrupted: r.type === "user" && interruptedContent(content),
+                localPrompt: r.promptSource === undefined ? localPrompt(content) : undefined,
+                tools: blocks.filter((b) => b.type === "tool_use").map((b) => b.id),
+                results: blocks.filter((b) => b.type === "tool_result").map((b) => b.tool_use_id),
+                todoItems: blocks.filter((b) => b.type === "tool_use" && ["TodoWrite", "TaskCreate", "TaskUpdate"].includes(b.name)).map((b) => {
+                  const input = b.input ?? {};
+                  return { kind: "tool", id: b.id, name: b.name, input: {
+                    taskId: input.taskId, subject: String(input.subject ?? "").slice(0, 1024), status: input.status, activeForm: input.activeForm,
+                    todos: Array.isArray(input.todos) ? input.todos.slice(0, 1024).map((t: Record<string, unknown>) => ({ ...t, content: String(t.content ?? "").slice(0, 1024) })) : undefined,
+                  } };
+                }),
+                todoIds: blocks.filter((b) => b.type === "tool_result").flatMap((b) => {
+                  const structured = (r.toolUseResult ?? r.tool_use_result) as { task?: { id?: string } } | undefined;
+                  const taskId = structured?.task?.id ?? (typeof b.content === "string" ? b.content.slice(0, 1000).match(/Task #(\d+)/)?.[1] : undefined);
+                  return taskId ? [{ id: b.tool_use_id, taskId, isError: !!b.is_error }] : [];
+                }),
+                offset, length, order: offset };
+              index.entries.set(r.uuid, entry);
+              index.bytes += 240 + (entry.goalCommand?.length ?? 0) * 2 + ((entry.queuedKey?.length ?? 0) + (entry.queuedHash?.length ?? 0)) * 2 + (entry.tools?.length ?? 0) * 100 + (entry.results?.length ?? 0) * 100 + JSON.stringify(entry.todoItems ?? []).length * 2 + JSON.stringify(entry.compactMetadata ?? {}).length * 2;
+            }
+          } catch { /* Ignore malformed records without retaining their payload. */ }
+          start = nl + 1;
+          offset = chunkStart + start;
+          pending = []; pendingLength = 0;
+        }
+        if (start < bytesRead) { pending.push(data.subarray(start)); pendingLength += bytesRead - start; }
+      }
+      index.size = offset;
+      index.fileSize = stat.size;
+      index.mtime = stat.mtimeMs;
+      index.used = Date.now();
+      revision.size = stat.size; revision.mtime = stat.mtimeMs;
+      if (!revision.prefixLength) { revision.prefixLength = prefixLength; revision.prefixHash = prefixHash; }
+      return await fn(index, handle);
+    } finally {
+      await handle.close();
+      let bytes = [...indexes.values()].reduce((n, v) => n + v.bytes, 0);
+      for (const [key, value] of [...indexes].sort((a, b) => a[1].used - b[1].used)) {
+        if (indexes.size <= 8 && bytes <= INDEX_BUDGET) break;
+        indexes.delete(key); bytes -= value.bytes;
+      }
+    }
+  });
+  locks.set(file, work);
+  try { return await work; } finally { if (locks.get(file) === work) locks.delete(file); }
+}
+
+/** Message display builds on the same native branch used for control state. */
+function branch(index: Index, anchor?: string | null, sidechain = false): Entry[] {
+  const entries = index.entries;
+  const eligible = (e: Entry) => eligibleBranchEntry(e, sidechain);
+  const { chain, tail, cutoff } = selectSessionBranch(entries, anchor, sidechain);
+  const completed = completeAssistantMessages(entries, chain, cutoff);
+  // The SDK subagent reader normalizes delivered chain entries only.
+  const trailing = sidechain ? [] : trailingQueued(entries, completed, tail, cutoff);
+  completed.push(...trailing);
+  const chainIds = new Set(completed.map((e) => e.uuid));
+  const commandOutputs = new Map<string, Entry[]>();
+  for (const e of entries.values()) {
+    if (e.order <= cutoff && e.type === "system" && e.subtype === "local_command" && e.parentUuid && chainIds.has(e.parentUuid) && !chainIds.has(e.uuid)) {
+      const list = commandOutputs.get(e.parentUuid) ?? []; list.push(e); commandOutputs.set(e.parentUuid, list);
+    }
+  }
+  const out = completed.flatMap((e) => [e, ...(commandOutputs.get(e.uuid) ?? [])]);
+  const trailingIds = new Set(trailing.map((e) => e.uuid));
+  const normalizedIds = new Set(out.map((e) => e.uuid));
+  const visibleQueued = new Set<string>();
+  const localCommands = completedLocalCommands(out);
+  // getSubagentMessages does not use queue-operation receipts.
+  const delivered = sidechain ? new Map<string, boolean>() : deliveredQueued(index, cutoff);
+  let next: "reply" | "prompt" | undefined;
+  for (let i = out.length - 1; i >= 0; i--) {
+    const e = out[i]!;
+    if (e.queued && (e.queuedFirstOrder ?? e.order) <= cutoff && e.queuedPrompt && !e.queuedForwarded && (delivered.get(e.uuid) ?? (next === "reply" || trailingIds.has(e.uuid))) &&
+      (sidechain || !e.queuedMeta || externalOrigin(e.queuedOriginKind))) visibleQueued.add(e.uuid);
+    if (e.type === "assistant" || e.results?.length || e.interrupted) next = "reply";
+    else if (e.type === "user" && !e.isMeta && !e.isCompactSummary && !localCommands.has(e.uuid)) next = "prompt";
+  }
+  return out.filter((e) => {
+    if (!eligible(e)) return false;
+    if (e.type === "user" || e.type === "assistant") return sidechain || !e.isMeta || externalOrigin(e.originKind);
+    if (e.type === "system") return !sidechain && ["compact_boundary", "local_command"].includes(e.subtype ?? "");
+    if (!visibleQueued.has(e.uuid) || e.sourceUuid && e.sourceUuid !== e.uuid && normalizedIds.has(e.sourceUuid)) return false;
+    if (e.sourceUuid) normalizedIds.add(e.sourceUuid);
+    return true;
+  }).map((e) => localCommands.has(e.uuid) ? { ...e, completedLocalCommand: true } : e);
+}
+
+const externalOrigin = (kind?: string) => ["channel", "observer", "observer-activity", "slack-ping", "peer"].includes(kind ?? "");
+const nonemptyString = (value: unknown) => typeof value === "string" && value ? value : undefined;
+const deliveryKey = (deliveryId: unknown, sourceUuid: unknown) => nonemptyString(deliveryId) ? `delivery:${deliveryId}` : nonemptyString(sourceUuid) ? `uuid:${sourceUuid}` : undefined;
+
+/** Confirm specific queued copies before intersecting with the current branch.
+ * A legacy source UUID with conflicting payloads is ambiguous, so retain the
+ * SDK fallback rather than assigning another command's delivery to it. */
+function deliveredQueued(index: Index, cutoff: number): Map<string, boolean> {
+  const counts = new Map<string, number>();
+  for (const op of index.deliveries) if (op.order <= cutoff) counts.set(op.key, (counts.get(op.key) ?? 0) + 1);
+  const groups = new Map<string, Entry[]>();
+  for (const e of index.entries.values()) if ((e.queuedFirstOrder ?? e.order) <= cutoff && e.queuedKey && counts.has(e.queuedKey)) {
+    const group = groups.get(e.queuedKey) ?? []; group.push(e); groups.set(e.queuedKey, group);
+  }
+  const out = new Map<string, boolean>();
+  for (const [key, group] of groups) {
+    const mixedAt = index.legacyCopies.get(key)?.mixedAt;
+    if (mixedAt !== undefined && mixedAt <= cutoff) continue;
+    group.sort((a, b) => (a.queuedFirstOrder ?? a.order) - (b.queuedFirstOrder ?? b.order));
+    const firstDelivered = group.length - counts.get(key)!;
+    group.forEach((e, i) => out.set(e.uuid, i >= firstDelivered));
+  }
+  return out;
+}
+
+function localPrompt(content: unknown): Entry["localPrompt"] {
+  const text = typeof content === "string" ? content : Array.isArray(content) ? content.findLast((b) => b?.type === "text")?.text : undefined;
+  if (typeof text !== "string") return undefined;
+  if (text.startsWith("<local-command-caveat>")) return "caveat";
+  if (text.startsWith("<command-name>")) return "record";
+  if (text.startsWith("<local-command-stdout>") || text.startsWith("<local-command-stderr>")) return "output";
+}
+
+function completedLocalCommands(chain: Entry[]): Set<string> {
+  const out = new Set<string>();
+  for (let i = 0; i < chain.length; i++) {
+    const e = chain[i]!;
+    if (e.type !== "user" || !e.isMeta || e.localPrompt !== "caveat") continue;
+    let record = false;
+    for (let j = i + 1; j < chain.length; j++) {
+      const next = chain[j]!;
+      if (next.type === "assistant") break;
+      if (next.type !== "user" || next.isMeta) continue;
+      if (next.localPrompt === "record" && !record) record = true;
+      else if (next.localPrompt !== "output" || !record) break;
+      out.add(next.uuid);
+    }
+  }
+  return out;
+}
+
+// Match the SDK's forwarded-intent schema: only a nonempty lineage is required;
+// malformed metadata must not suppress an otherwise visible queued prompt.
+function forwardedIntent(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const lineage = (value as { lineage?: unknown }).lineage;
+  return typeof lineage === "string" && lineage.length > 0;
+}
+
+// These SDK transcript sentinels terminate delivery, rather than beginning a new
+// user prompt. Keep only the classification in the offset index, never the text.
+const INTERRUPTION_PREFIXES = [
+  "[Request interrupted by user]",
+  "[Request interrupted by user for tool use]",
+  "[Tool call did not complete: the turn was ended to deliver the message that follows. Nothing refused it; re-run it if still needed.]",
+  "[Tool call interrupted: the session ended before this call's result was recorded, so its outcome is unknown. Check whether it took effect before relying on it or running it again.]",
+  "[Tool call result not in this copy: this session was copied from another session before that session recorded this call's result. The call may have finished there, may still be running there, or may never have run. Check whether it took effect before relying on it or running it again.]",
+  "The user doesn't want to take this action right now. STOP what you are doing and wait for the user to tell you how to proceed.",
+  "[Tool call skipped: the turn was stopped before this call ran, by the check whose denial is on another call in this batch. Nothing refused this call and it had no effects; re-run it if still needed.]",
+  "[Tool call skipped: the turn ended to deliver the message that follows before this call ran. Nothing refused it; re-run it if still needed.]",
+];
+function interruptedContent(content: unknown): boolean {
+  const sentinel = (value: unknown) => typeof value === "string" && INTERRUPTION_PREFIXES.some((prefix) => value.startsWith(prefix));
+  if (typeof content === "string") return sentinel(content);
+  return Array.isArray(content) && content.length > 0 && content.every((block) =>
+    sentinel(block?.type === "text" ? block.text : block?.type === "tool_result" && block.is_error === true ? block.content : undefined));
+}
+
+/** Only non-conversation descendants of the selected leaf may be pending prompts.
+ * Ancestors of abandoned conversation branches are excluded even if they also
+ * descend from the selected leaf. Keep traversal iterative for long tails. */
+function trailingQueued(entries: Map<string, Entry>, chain: Entry[], tail: Entry | undefined, cutoff: number): Entry[] {
+  if (!tail) return [];
+  const seen = new Set(chain.map((e) => e.uuid));
+  const blocked = new Set<string>();
+  const children = new Map<string, Entry[]>();
+  for (const e of entries.values()) {
+    if (e.order > cutoff) continue;
+    if (e.parentUuid && e.type !== "user" && e.type !== "assistant") {
+      const list = children.get(e.parentUuid) ?? []; list.push(e); children.set(e.parentUuid, list);
+    }
+    if ((e.type === "user" || e.type === "assistant") && !e.isSidechain && !e.teamName && !seen.has(e.uuid)) {
+      let parent = entries.get(e.parentUuid ?? "");
+      while (parent && !seen.has(parent.uuid) && !blocked.has(parent.uuid)) {
+        blocked.add(parent.uuid); parent = entries.get(parent.parentUuid ?? "");
+      }
+    }
+  }
+  const out: Entry[] = [];
+  const stack = [tail];
+  while (stack.length) {
+    const e = stack.pop()!;
+    if (e !== tail) {
+      if (seen.has(e.uuid)) continue;
+      seen.add(e.uuid);
+      if (e.queued && !blocked.has(e.uuid)) out.push(e);
+    }
+    const list = children.get(e.uuid) ?? [];
+    list.sort((a, b) => (a.timestamp ?? "").localeCompare(b.timestamp ?? ""));
+    for (let i = list.length - 1; i >= 0; i--) if (!seen.has(list[i]!.uuid)) stack.push(list[i]!);
+  }
+  return out;
+}
+
+/** Match the SDK reader: assistant blocks can be siblings rather than ancestors,
+ * and their results can point at another block of the same API message. */
+function completeAssistantMessages(entries: Map<string, Entry>, chain: Entry[], cutoff: number): Entry[] {
+  const assistants = chain.filter((e) => e.messageId);
+  if (!assistants.length) return chain;
+  const lastByMessage = new Map(assistants.map((e) => [e.messageId!, e]));
+  const groups = new Map<string, Entry[]>();
+  const toolOwners = new Map<string, Entry | null>();
+  const results: Entry[] = [];
+  for (const entry of entries.values()) {
+    if (entry.order > cutoff) continue;
+    if (entry.messageId) {
+      const group = groups.get(entry.messageId) ?? [];
+      group.push(entry); groups.set(entry.messageId, group);
+      for (const id of entry.tools ?? []) {
+        const owner = toolOwners.get(id);
+        toolOwners.set(id, owner === undefined || owner !== null && owner.messageId === entry.messageId ? entry : null);
+      }
+    } else if (entry.type === "user" && entry.parentUuid && entry.results?.length) results.push(entry);
+  }
+  const byAssistant = new Map<string, Map<string, Entry>>();
+  const associate = (id: string, result: Entry) => {
+    const list = byAssistant.get(id) ?? new Map<string, Entry>();
+    list.set(result.uuid, result); byAssistant.set(id, list);
+  };
+  const sameAgent = (a: Entry, b: Entry) => !!a.isSidechain === !!b.isSidechain && a.agentId === b.agentId;
+  for (const result of results) {
+    associate(result.parentUuid!, result);
+    const source = entries.get(result.sourceToolAssistantUUID ?? "");
+    if (source && sameAgent(source, result)) associate(source.uuid, result);
+    for (const id of result.results ?? []) {
+      const owner = toolOwners.get(id);
+      if (owner && sameAgent(owner, result)) associate(owner.uuid, result);
+    }
+  }
+  const seen = new Set(chain.map((e) => e.uuid));
+  const existingResults = new Set(chain.flatMap((e) => e.results ?? []));
+  const additions = new Map<string, Entry[]>();
+  const byTimestamp = (a: Entry, b: Entry) => (a.timestamp ?? "").localeCompare(b.timestamp ?? "");
+  for (const [messageId, last] of lastByMessage) {
+    const group = groups.get(messageId) ?? [last];
+    const groupIds = new Set(group.map((e) => e.uuid));
+    const siblings = group.filter((e) => !seen.has(e.uuid));
+    const direct: Entry[] = [];
+    const indirect: Entry[] = [];
+    const resultIds = new Set<string>();
+    for (const block of group) for (const result of byAssistant.get(block.uuid)?.values() ?? []) {
+      if (seen.has(result.uuid) || resultIds.has(result.uuid)) continue;
+      resultIds.add(result.uuid);
+      (groupIds.has(result.parentUuid!) ? direct : indirect).push(result);
+    }
+    // Global results are read-only membership checks. Each group stores only
+    // its own additions, avoiding a whole-branch Set copy per API message.
+    const included = new Set(direct.flatMap((e) => e.results ?? []));
+    indirect.sort((a, b) => a.order - b.order);
+    for (const result of indirect) {
+      if (!result.results?.some((id) => !existingResults.has(id) && !included.has(id) && groupIds.has(toolOwners.get(id)?.uuid ?? ""))) continue;
+      for (const id of result.results) included.add(id);
+      direct.push(result);
+    }
+    siblings.sort(byTimestamp); direct.sort(byTimestamp);
+    const extra = [...siblings, ...direct];
+    for (const entry of extra) seen.add(entry.uuid);
+    additions.set(last.uuid, extra);
+  }
+  return chain.flatMap((entry) => [entry, ...(additions.get(entry.uuid) ?? [])]);
+}
+
+async function read(handle: fs.FileHandle, entry: Entry): Promise<RecordLike> {
+  const buf = Buffer.allocUnsafe(entry.length);
+  let at = 0;
+  while (at < buf.length) {
+    const r = await handle.read(buf, at, buf.length - at, entry.offset + at);
+    if (!r.bytesRead) throw new HistoryError(409, "会话文件已变化，请重新加载");
+    at += r.bytesRead;
+  }
+  return JSON.parse(buf.toString("utf8"));
+}
+
+/** Control-state reader: same index, lock, UUID dedup and native branch as
+ * history, but retain effect attachments and never hydrate ordinary text/images. */
+export async function nativeGoalBranch(file: string | undefined, anchor?: string | null, legacyQuestion?: string | null): Promise<GoalRecord[]> {
+  return await withIndex(file, async (index, handle) => {
+    const { chain } = selectSessionBranch(index.entries, anchor, false, true);
+    const records: GoalRecord[] = [];
+    let foundQuestion = false;
+    for (const entry of chain) {
+      const record: GoalRecord = { type: entry.type, subtype: entry.subtype, uuid: entry.uuid, isMeta: entry.isMeta, localCommandCaveat: entry.localPrompt === "caveat", forkedFrom: entry.inherited || undefined, command: entry.goalCommand };
+      if (entry.attachmentType === "goal_status") record.attachment = (await read(handle, entry)).attachment;
+      else if (entry.queued) record.attachment = { type: "queued_command", source_uuid: entry.sourceUuid };
+      if (legacyQuestion && !foundQuestion && (entry.type === "user" || entry.queued)) {
+        const raw = await read(handle, entry);
+        if (recordText(raw as GoalRecord) === legacyQuestion) { record.message = { content: legacyQuestion }; foundQuestion = true; }
+      }
+      records.push(record);
+    }
+    return records;
+  }) ?? [];
+}
+
+function normalized(r: RecordLike, entry: Entry): SdkMessageLike {
+  if (r.attachment?.type === "queued_command") return { type: "user", uuid: entry.sourceUuid ?? r.uuid, isQueuedCommand: true, is_meta: r.attachment.isMeta === true || undefined, origin: r.attachment.origin, timestamp: r.timestamp, message: { role: "user", content: r.attachment.prompt }, parent_tool_use_id: null };
+  return { type: r.type, subtype: r.subtype, uuid: r.uuid, message: r.message, content: r.content, isCompactSummary: r.isCompactSummary,
+    isCompletedLocalCommand: entry.completedLocalCommand || undefined,
+    is_meta: r.isMeta === true || r.isCompactSummary === true || undefined, origin: r.origin, parent_tool_use_id: null, tool_use_result: r.toolUseResult ?? r.tool_use_result, timestamp: r.timestamp };
+}
+
+type Cursor = { g: string; size: number; mtime: number; id: string; direction: "older" | "newer" };
+const cursor = (index: Index, id: string, direction: Cursor["direction"]) => Buffer.from(JSON.stringify({ g: index.generation, size: index.fileSize, mtime: index.mtime, id, direction })).toString("base64url");
+export type PageOptions = { cursor?: string; before?: string; after?: string; anchor?: string | null; sidechain?: boolean };
+
+export async function historyPage(file: string | undefined, options: PageOptions = {}): Promise<HistoryPage> {
+  return await withIndex(file, async (index, handle) => {
+    const chain = branch(index, options.anchor, options.sidechain);
+    let direction: Cursor["direction"] = options.after ? "newer" : "older";
+    let id = options.before ?? options.after;
+    if (options.cursor) {
+      let c: Cursor;
+      try { c = JSON.parse(Buffer.from(options.cursor, "base64url").toString()); } catch { throw new HistoryError(400, "无效的历史游标"); }
+      if (c.g !== index.generation || index.fileSize < c.size || index.fileSize === c.size && index.mtime !== c.mtime) throw new HistoryError(409, "会话文件已变化，请重新加载");
+      if (!c.id || !["older", "newer"].includes(c.direction)) throw new HistoryError(400, "无效的历史游标");
+      direction = c.direction; id = c.id;
+    }
+    let boundary = id ? chain.findIndex((e) => e.uuid === id || e.sourceUuid === id) : chain.length;
+    if (boundary < 0) throw new HistoryError(409, "消息已不在当前分支，请重新加载");
+    const selected: { entry: Entry; message: SdkMessageLike }[] = [];
+    let bytes = 0;
+    for (let i = direction === "older" ? boundary - 1 : boundary + 1; i >= 0 && i < chain.length && selected.length < PAGE_LIMIT; i += direction === "older" ? -1 : 1) {
+      const entry = chain[i]!;
+      const message = displayMessage(normalized(await read(handle, entry), entry), entry.length * 2);
+      const size = Buffer.byteLength(JSON.stringify(message));
+      if (selected.length && bytes + size > PAGE_BYTES) break;
+      selected.push({ entry, message }); bytes += size;
+    }
+    if (direction === "older") selected.reverse();
+    const first = selected[0]?.entry;
+    const last = selected.at(-1)?.entry;
+    // Fetch only results belonging to visible tool calls, even when they lie on another page.
+    const wanted = new Set(selected.flatMap((e) => e.entry.tools ?? []));
+    if (wanted.size) {
+      for (const entry of chain) {
+        if (!entry.results?.some((id) => wanted.has(id))) continue;
+        const raw = await read(handle, entry);
+        const blocks = (raw.message as { content?: unknown[] })?.content;
+        for (const block of blocks ?? []) {
+          const b = block as { type: string; tool_use_id: string; content: unknown; is_error?: boolean };
+          if (b.type !== "tool_result" || !wanted.has(b.tool_use_id)) continue;
+          const owner = selected.find((e) => e.entry.tools?.includes(b.tool_use_id))!;
+          const results = (owner.message.linkedToolResults ??= {}) as Record<string, unknown>;
+          const resultUuids = (owner.message._toolResultUuids ??= {}) as Record<string, string>;
+          resultUuids[b.tool_use_id] = entry.uuid;
+          const result = { content: b.content, isError: !!b.is_error, structured: raw.toolUseResult ?? raw.tool_use_result };
+          const bodySize = Buffer.byteLength(JSON.stringify(result));
+          results[b.tool_use_id] = bodySize < 16 * 1024 && bytes + bodySize < PAGE_BYTES
+            ? result
+            : { content: "结果较大，请加载完整消息查看。", isError: !!b.is_error, deferredUuid: entry.uuid };
+          bytes += Math.min(bodySize, 16 * 1024);
+        }
+      }
+    }
+    const todoIds = new Map(chain.flatMap((e) => e.todoIds ?? []).map((r) => [r.id, r]));
+    const todos = deriveTodos(chain.flatMap((e) => e.todoItems ?? []).map((item) => {
+      const result = todoIds.get(item.id);
+      return result ? { ...item, result: { content: `Task #${result.taskId}`, isError: result.isError, structured: { task: { id: result.taskId } } } } : item;
+    }));
+    return { items: selected.map((s) => s.message), generation: index.generation, todos,
+      older: first && chain.indexOf(first) > 0 ? cursor(index, first.uuid, "older") : undefined,
+      newer: last && chain.indexOf(last) < chain.length - 1 ? cursor(index, last.uuid, "newer") : undefined };
+  }) ?? { items: [], generation: "empty" };
+}
+
+export async function historyMessage(file: string | undefined, uuid: string, anchor?: string | null, sidechain = false): Promise<SdkMessageLike> {
+  const found = await withIndex(file, async (index, handle) => {
+    const entry = branch(index, anchor, sidechain).find((e) => e.uuid === uuid || e.sourceUuid === uuid);
+    if (!entry) throw new HistoryError(404, "消息不存在");
+    if (entry.length * 2 > SESSION_BYTES / 2) throw new HistoryError(400, "这条消息超过缓存上限，请导出会话查看");
+    return normalized(await read(handle, entry), entry);
+  });
+  if (!found) throw new HistoryError(404, "消息不存在");
+  return found;
+}
+
+/** Resolve a Read from this visible transcript, never from a client-supplied path. */
+export async function historyReadPath(file: string | undefined, toolId: string, anchor?: string | null, sidechain = false): Promise<{ path: string; cwd?: string }> {
+  const found = await withIndex(file, async (index, handle) => {
+    const entry = branch(index, anchor, sidechain).find((e) => e.type === "assistant" && e.tools?.includes(toolId));
+    if (!entry || entry.length * 2 > SESSION_BYTES / 2) return;
+    const record = await read(handle, entry);
+    const content = (record.message as { content?: unknown[] } | undefined)?.content;
+    const call = content?.find((block) => {
+      const b = block as { type?: string; id?: string; name?: string } | null;
+      return b?.type === "tool_use" && b.id === toolId && b.name === "Read";
+    }) as { input?: { file_path?: unknown } } | undefined;
+    if (typeof call?.input?.file_path !== "string" || !call.input.file_path) return;
+    return { path: call.input.file_path, cwd: typeof record.cwd === "string" ? record.cwd : undefined };
+  });
+  if (!found) throw new HistoryError(404, "图片调用不存在");
+  return found;
+}