@hassangameryt/freeflow 0.7.1 → 0.7.3

package/pi-extension/src/runtime/runtime-context.ts

@@ -2,8 +2,8 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { resolveCognitiveRoutingState } from "../cognitive-routing/runtime.js";
-import { supportsCognitiveRoutingModelRegistry } from "../cognitive-routing/host.js";
+import { resolveCognitiveRoutingState } from "../cognitive-routing-v2/config.js";
+import { supportsCognitiveRoutingModelRegistry } from "../cognitive-routing-v2/config.js";
 
 export const WORKFLOW_COMMANDS = [
   { command: "discuss", skill: "discuss" },
@@ -47,7 +47,6 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "setup-freeflow",
   "launch-work",
   "simplify-code",
-  "tdd",
   "track-work",
   "verify-work",
   "workflow",
@@ -56,6 +55,13 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "write-spec",
 ];
 
+export const STABLE_FREEFLOW_SURFACE = Object.freeze({
+  enabled: true,
+  cognitiveRouting: { effective: true },
+  contextVirtualization: { effective: true },
+  conversationHistory: { effective: true },
+});
+
 export const FREEFLOW_CAPABILITY_SKILL_NAMES = ["cognitive-routing", "context-virtualization", "conversation-history"];
 
 export function freeflowSkillPath(skillName) {
@@ -87,7 +93,6 @@ type SessionCoreOverrides = Partial<Record<SessionCoreKey, boolean>>;
 const SESSION_OVERRIDES_ENTRY = "freeflow-session-overrides";
 const SESSION_CORE_KEYS = new Set<SessionCoreKey>(["enabled", "contextVirtualization", "conversationHistory"]);
 
-export const COGNITIVE_ROUTING_SWITCH_TOOL_NAME = "freeflow_switch_profile";
 export const FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-runtime-state";
 export const COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-cognitive-routing-runtime-state";
 export const WORKFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-workflow-bootstrap";
@@ -101,6 +106,33 @@ export function isPromptAvailable(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0;
 }
 
+// pi-subagents stamps child system prompts with this tag before binding extensions.
+// Keeping detection at the prompt boundary avoids a process-global child flag.
+export const SUBAGENT_AGENT_TAG = /<active_agent\s+name="[^"]+"\s*\/>/;
+export const FREEFLOW_SUBAGENT_CAPABILITIES_DISABLED_MARKER = "<!-- freeflow-subagent-capabilities: disabled -->";
+const SUBAGENT_OPTIONAL_CAPABILITIES_MESSAGE = "Optional Freeflow capabilities are disabled for subagents.";
+
+export function isSubagentContext(context: unknown): boolean {
+  try {
+    const systemPrompt = (context as { getSystemPrompt?: () => unknown })?.getSystemPrompt?.();
+    return (
+      typeof systemPrompt === "string" &&
+      (SUBAGENT_AGENT_TAG.test(systemPrompt) || systemPrompt.includes(FREEFLOW_SUBAGENT_CAPABILITIES_DISABLED_MARKER))
+    );
+  } catch {
+    return false;
+  }
+}
+
+function disableSubagentCapability(capability: any): any {
+  return {
+    ...capability,
+    enabled: false,
+    effective: false,
+    blockingReason: { code: "disabled", message: SUBAGENT_OPTIONAL_CAPABILITIES_MESSAGE },
+  };
+}
+
 export function hasUsableMandatoryPrompts(freeflowContext: any): boolean {
   return (
     isPromptAvailable(freeflowContext?.corePrompt) && isPromptAvailable(freeflowContext?.interactionContractPrompt)
@@ -432,7 +464,8 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
   const enabled = layers.configured && effectiveCore.config.enabled;
   const contextVirtualizationConfigEnabled = effectiveCore.config.contextVirtualization;
   const conversationHistoryConfigEnabled = effectiveCore.config.conversationHistory;
-  const hostSupportsCognitiveRouting = supportsCognitiveRoutingModelRegistry(host);
+  const subagentContext = isSubagentContext(host);
+  const hostSupportsCognitiveRouting = !subagentContext && supportsCognitiveRoutingModelRegistry(host);
   const configuredCognitiveRouting = await resolveCognitiveRoutingState(
     layers.repository.parsed,
     layers.local.parsed,
@@ -452,7 +485,7 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
         effective: false,
         blockingReason: disabledReason,
       };
-  return {
+  const capabilityState = {
     configured: layers.configured,
     repositoryConfigured: layers.repositoryConfigured,
     configExists: layers.repository.exists,
@@ -473,6 +506,14 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
     hostSupportsCognitiveRouting,
     cognitiveRouting,
   };
+  if (!subagentContext) return capabilityState;
+
+  return {
+    ...capabilityState,
+    contextVirtualization: disableSubagentCapability(capabilityState.contextVirtualization),
+    conversationHistory: disableSubagentCapability(capabilityState.conversationHistory),
+    cognitiveRouting: disableSubagentCapability(capabilityState.cognitiveRouting),
+  };
 }
 
 export const readRuntimeState = readCapabilityState;
@@ -525,11 +566,7 @@ export function setFreeflowStatus(
     active.push(`cognitive blocked · ${cognitiveRoutingRuntime?.runtimeReason ?? "runtime_blocked"}`);
   } else if (cognitiveRoutingActive) {
     const profile = cognitiveRoutingRuntime.activeProfile;
-    const control =
-      cognitiveRoutingRuntime.controlMode === "manual-standard" ||
-      cognitiveRoutingRuntime.controlMode === "manual-reasoning"
-        ? "manual hold"
-        : "automatic";
+    const control = String(cognitiveRoutingRuntime.controlMode).startsWith("manual-") ? "manual hold" : "automatic";
     active.push(`${profile} · ${control}`);
   } else if (cognitiveRouting?.enabled === true) {
     if (cognitiveRouting.blockingReason?.code === "runtime_disabled") {
@@ -542,8 +579,8 @@ export function setFreeflowStatus(
     ) {
       const startupProfile =
         cognitiveRouting.sessionStart?.control === "manual"
-          ? (cognitiveRouting.sessionStart.profile ?? "reasoning")
-          : "reasoning";
+          ? (cognitiveRouting.sessionStart.profile ?? "coordinator")
+          : "coordinator";
       active.push(`${startupProfile} · pending`);
     } else {
       const reason =
@@ -569,9 +606,12 @@ type CognitiveRoutingRuntimeSnapshot = {
   runtimeStatus?: "active" | "inactive" | "blocked";
   runtimeReason?: unknown;
   activeProfile?: unknown;
+  delegation?: unknown;
   controlMode?: unknown;
 };
 
+type CognitiveRoutingProjectionMode = "disabled" | "enabled" | "manual-bypass" | "blocked" | "unavailable" | "pending";
+
 type FreeflowContextMessage = {
   customType?: unknown;
   [key: string]: unknown;
@@ -579,13 +619,13 @@ type FreeflowContextMessage = {
 
 function publicCognitiveRoutingControl(controlMode) {
   if (controlMode === "automatic") return "automatic";
-  if (controlMode === "manual-standard" || controlMode === "manual-reasoning") return "manual";
+  if (["manual-helper", "manual-executor", "manual-coordinator"].includes(controlMode)) return "manual";
   return "unavailable";
 }
 
 function publicCognitiveRoutingProfile(activeProfile, effective) {
   if (effective !== true) return "unavailable";
-  return activeProfile === "standard" || activeProfile === "reasoning" ? activeProfile : "unavailable";
+  return ["helper", "executor", "coordinator"].includes(activeProfile) ? activeProfile : "unavailable";
 }
 
 function publicCapabilityStatus(capability) {
@@ -601,10 +641,25 @@ function publicCognitiveRoutingStatus(capability, runtime) {
   return publicCapabilityStatus(capability);
 }
 
+function publicCognitiveRoutingProjectionMode(
+  capability: any,
+  runtime: CognitiveRoutingRuntimeSnapshot | undefined,
+  projectionFailure?: string,
+): CognitiveRoutingProjectionMode {
+  if (capability?.projection !== true) return "disabled";
+  if (capability?.effective !== true) return "unavailable";
+  if (String(runtime?.controlMode).startsWith("manual-")) return "manual-bypass";
+  if (projectionFailure) return "blocked";
+  if (runtime?.runtimeStatus === "inactive" || runtime?.runtimeStatus === "blocked") return "unavailable";
+  if (runtime?.effective === true && runtime.controlMode === "automatic") return "enabled";
+  return "pending";
+}
+
 export function freeflowRuntimeStateMessage(
   capabilityState,
   cognitiveRoutingRuntime: CognitiveRoutingRuntimeSnapshot | undefined = undefined,
   freeflowContext = undefined,
+  options: { projectionFailure?: string } = {},
 ) {
   const cognitiveRoutingEffective = capabilityState?.cognitiveRouting?.effective === true;
   const profile = publicCognitiveRoutingProfile(
@@ -613,6 +668,11 @@ export function freeflowRuntimeStateMessage(
   );
   const control =
     profile === "unavailable" ? "unavailable" : publicCognitiveRoutingControl(cognitiveRoutingRuntime?.controlMode);
+  const projectionMode = publicCognitiveRoutingProjectionMode(
+    capabilityState?.cognitiveRouting,
+    cognitiveRoutingRuntime,
+    options.projectionFailure,
+  );
   const mandatoryPromptAvailable = capabilityState?.enabled !== true || hasUsableMandatoryPrompts(freeflowContext);
   const freeflowStatus = capabilityState?.configured
     ? capabilityState.enabled
@@ -642,6 +702,8 @@ export function freeflowRuntimeStateMessage(
       "Cognitive Routing:",
       `- Control: \`${control}\``,
       `- Profile: \`${profile}\``,
+      `- Delegation: \`${capabilityState?.cognitiveRouting?.delegation ?? "executor"}\``,
+      `- Projection: \`${projectionMode}\``,
     ].join("\n"),
     display: false,
     details: { source: "provider-request-runtime-state" },
@@ -677,10 +739,12 @@ export function withFreeflowRuntimeState(
   capabilityState,
   cognitiveRoutingRuntime: CognitiveRoutingRuntimeSnapshot | undefined = undefined,
   freeflowContext = undefined,
-  options: { force?: boolean } = {},
+  options: { force?: boolean; projectionFailure?: string } = {},
 ) {
   const source = Array.isArray(messages) ? messages : [];
-  const runtimeState = freeflowRuntimeStateMessage(capabilityState, cognitiveRoutingRuntime, freeflowContext);
+  const runtimeState = freeflowRuntimeStateMessage(capabilityState, cognitiveRoutingRuntime, freeflowContext, {
+    projectionFailure: options.projectionFailure,
+  });
   const runtimeStateMessages = source.filter(
     (message) =>
       message?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE ||
@@ -699,6 +763,25 @@ export function withFreeflowRuntimeState(
   return insertRuntimeStateBeforeLatestUser(withoutRuntimeState, runtimeState);
 }
 
+export function stableRuntimeContext(context) {
+  const sections = [
+    ["Freeflow core", context?.corePrompt],
+    ["Freeflow core", context?.interactionContractPrompt],
+    ["Cognitive Routing", context?.cognitiveRoutingPrompt],
+    ["Context Virtualization", context?.contextVirtualizationPrompt],
+    ["Conversation History", context?.conversationHistoryPrompt],
+  ];
+  return [
+    "# Freeflow availability contract",
+    "Freeflow keeps a fixed reference catalog of its instructions, skills, and tools to preserve prompt caching. Presence in this catalog does not mean a feature is active or an operation is permitted.",
+    "Apply the following guidance and Freeflow skills only when the latest extension-generated Freeflow Runtime State marks the corresponding feature active. When Freeflow is inactive, unavailable, or not configured, its core and capability guidance is dormant; do not bootstrap or follow it merely because it is listed. Explicit user instructions retain their normal authority.",
+    "For Cognitive Routing, follow the latest control/profile/responsibility snapshots on this branch. Earlier snapshots and notices are historical; they grant no current permission. Tool permissions are checked by the runtime, even though all definitions remain visible. Never call a disabled operation.",
+    ...sections
+      .filter(([, text]) => isPromptAvailable(text))
+      .map(([feature, text]) => `## Reference guidance: ${feature}\n\n${text.trim()}`),
+  ].join("\n\n");
+}
+
 export function runtimeContext(freeflowContext, capabilityState) {
   if (
     capabilityState?.configured !== true ||

package/pi-extension/src/session-sources/events.ts

@@ -0,0 +1,230 @@
+import { randomUUID } from "node:crypto";
+import { activeReadOnlySessionBranch, readOnlySessionSnapshot, ReadOnlySessionError } from "./read-only-session.js";
+import {
+  ROUTING_ENTRY,
+  RoutingError,
+  canonical,
+  eventKey,
+  eventValue,
+  requireCondition as check,
+  type EventData,
+  type NativeEntry,
+  type RoutingEvent,
+} from "../cognitive-routing-v2/types.js";
+import { parseRoutingEvent, reduce, replay } from "../cognitive-routing-v2/state.js";
+
+export interface SessionReader {
+  getSessionId(): string;
+  getSessionFile(): string | undefined;
+  getBranch(): readonly NativeEntry[];
+  getEntries(): readonly NativeEntry[];
+  getLeafId(): string | null;
+}
+export class EventStore {
+  private observed = new Map<string, { value: string; eventId: string; entryId: string }>();
+  private attempted = new Map<string, RoutingEvent>();
+  private fault?: string;
+  private ready = false;
+  private cachedEntries: readonly NativeEntry[] = [];
+  private cachedState = replay([]);
+  constructor(
+    private readonly pi: { appendEntry(type: string, data: unknown): void },
+    readonly reader: SessionReader,
+  ) {}
+  get blocked(): string | undefined {
+    return this.fault ?? (!this.ready ? "acknowledgment_unclassified" : undefined);
+  }
+  state() {
+    const entries = this.reader.getBranch();
+    const prefix =
+      this.cachedEntries.length <= entries.length && this.cachedEntries.every((entry, i) => entry === entries[i]);
+    if (!prefix) {
+      this.cachedState = replay(entries);
+    } else {
+      let state = this.cachedState;
+      for (const entry of entries.slice(this.cachedEntries.length))
+        if (entry.type === "custom" && entry.customType === ROUTING_ENTRY)
+          state = reduce(state, parseRoutingEvent(entry.data));
+      this.cachedState = state;
+    }
+    this.cachedEntries = [...entries];
+    return this.cachedState;
+  }
+  block(reason: string): void {
+    this.fault = reason;
+    this.ready = false;
+  }
+  make(data: EventData, operationId: string = randomUUID(), stepId: string = data.type): RoutingEvent {
+    return parseRoutingEvent({
+      version: 2,
+      eventId: randomUUID(),
+      operationId,
+      stepId,
+      recordedSessionId: this.reader.getSessionId(),
+      data,
+    });
+  }
+  async reconcile(): Promise<void> {
+    const acknowledged = this.ready && !this.fault;
+    this.ready = false;
+    const branch = this.reader.getBranch();
+    const live = branch.filter((e) => e.type === "custom" && e.customType === ROUTING_ENTRY);
+    try {
+      const ids = new Set<string>();
+      let parent: string | null = null;
+      for (const entry of branch) {
+        check(
+          typeof entry.id === "string" && !ids.has(entry.id) && entry.parentId === parent,
+          "invalid_native_ancestry",
+        );
+        ids.add(entry.id);
+        parent = entry.id;
+      }
+      check(parent === this.reader.getLeafId(), "invalid_native_ancestry");
+      if (
+        acknowledged &&
+        live.every((entry) => {
+          const event = parseRoutingEvent(entry.data);
+          const receipt = this.observed.get(eventKey(event));
+          return (
+            receipt?.entryId === entry.id && receipt.eventId === event.eventId && receipt.value === eventValue(event)
+          );
+        })
+      ) {
+        this.ready = true;
+        return;
+      }
+      if (!live.length && !this.attempted.size) {
+        this.observed.clear();
+        this.fault = undefined;
+        this.ready = true;
+        return;
+      }
+      // Pi defers creating a new session file until its first assistant message.
+      // Before that flush boundary, the complete in-memory native session is the
+      // only available source; uncertain appends still require persisted readback.
+      const preFlush =
+        !this.attempted.size &&
+        !this.reader.getEntries().some((entry) => entry.type === "message" && entry.message?.role === "assistant");
+      if (preFlush) {
+        replay(branch);
+        const known = new Map<string, { value: string; eventId: string; entryId: string }>();
+        for (const entry of branch) {
+          if (entry.type === "custom" && entry.customType === ROUTING_ENTRY) {
+            const event = parseRoutingEvent(entry.data);
+            known.set(eventKey(event), { value: eventValue(event), eventId: event.eventId, entryId: entry.id });
+          }
+        }
+        this.observed = known;
+        this.fault = undefined;
+        this.ready = true;
+        this.cachedEntries = [];
+        this.cachedState = replay([]);
+        return;
+      }
+      const path = this.reader.getSessionFile();
+      check(path, "persisted_snapshot_unavailable", "Existing or uncertain routing state needs a persisted snapshot.");
+      const snapshot = await readOnlySessionSnapshot(path);
+      check(snapshot.sessionId === this.reader.getSessionId(), "session_identity_changed");
+      const persistedBranch = activeReadOnlySessionBranch(snapshot, this.reader.getLeafId());
+      check(
+        persistedBranch.length === branch.length && persistedBranch.every((e, i) => e.id === branch[i].id),
+        "snapshot_ancestry_mismatch",
+        "Live branch is not the complete persisted ancestry for its claimed leaf.",
+      );
+      replay(persistedBranch as NativeEntry[]);
+      const disk = new Map(persistedBranch.map((e) => [e.id, e]));
+      const known = new Map<string, { value: string; eventId: string; entryId: string }>();
+      // Compare the live selected ancestry, not whichever branch was last written on disk.
+      for (const entry of branch) {
+        const captured = disk.get(entry.id);
+        check(
+          captured && canonical(captured) === canonical(entry),
+          "snapshot_divergence",
+          "Live ancestry is not fully established by the fresh persisted snapshot; reconcile the session before retrying.",
+        );
+        if (entry.type === "custom" && entry.customType === ROUTING_ENTRY) {
+          const event = parseRoutingEvent(entry.data);
+          known.set(eventKey(event), { value: eventValue(event), eventId: event.eventId, entryId: entry.id });
+        }
+      }
+      for (const [key, event] of this.attempted)
+        check(
+          known.get(key)?.value === eventValue(event) && known.get(key)?.eventId === event.eventId,
+          "append_acknowledgment_uncertain",
+          "The attempted routing event is not established by persisted readback.",
+        );
+      this.observed = known;
+      this.attempted.clear();
+      this.fault = undefined;
+      this.ready = true;
+      this.cachedEntries = [];
+      this.cachedState = replay([]);
+    } catch (error) {
+      this.block(
+        error instanceof RoutingError
+          ? error.code
+          : error instanceof ReadOnlySessionError
+            ? `${error.code}: ${error.message}`
+            : "snapshot_unavailable",
+      );
+      throw error;
+    }
+  }
+  append(event: RoutingEvent): RoutingEvent {
+    const value = parseRoutingEvent(event),
+      key = eventKey(value),
+      body = eventValue(value);
+    if (this.blocked) throw new RoutingError("acknowledgment_uncertain", this.blocked);
+    const prior = this.state().events.get(key);
+    if (prior) {
+      check(eventValue(prior) === body, "operation_conflict");
+      const occurrence = this.reader
+        .getBranch()
+        .find(
+          (entry) =>
+            entry.type === "custom" &&
+            entry.customType === ROUTING_ENTRY &&
+            (entry.data as any)?.eventId === prior.eventId,
+        );
+      if (
+        this.observed.get(key)?.value !== body ||
+        this.observed.get(key)?.eventId !== prior.eventId ||
+        this.observed.get(key)?.entryId !== occurrence?.id
+      ) {
+        this.block("prior_acknowledgment_unclassified");
+        throw new RoutingError("acknowledgment_uncertain", this.blocked!);
+      }
+      return prior;
+    }
+    // Validate the whole state transition before mutating Pi's session memory.
+    const candidate = reduce(this.state(), value);
+    const baseline = this.cachedEntries;
+    this.attempted.set(key, value);
+    try {
+      this.pi.appendEntry(ROUTING_ENTRY, value);
+      const found = this.reader
+        .getBranch()
+        .find(
+          (e) => e.type === "custom" && e.customType === ROUTING_ENTRY && (e.data as any)?.eventId === value.eventId,
+        );
+      check(found && eventValue(parseRoutingEvent(found.data)) === body, "append_not_observed");
+      this.observed.set(key, { value: body, eventId: value.eventId, entryId: found.id });
+      this.attempted.delete(key);
+      const branch = this.reader.getBranch();
+      const delta = branch.slice(baseline.length).filter((e) => e.type === "custom" && e.customType === ROUTING_ENTRY);
+      if (baseline.every((e, i) => branch[i] === e) && delta.length === 1 && delta[0].id === found!.id) {
+        // Publish the already validated candidate only after acknowledged native append.
+        this.cachedState = candidate;
+        this.cachedEntries = [...branch];
+      }
+      return value;
+    } catch (error) {
+      this.block("append_acknowledgment_uncertain");
+      throw new RoutingError(
+        "acknowledgment_uncertain",
+        error instanceof Error ? error.message : "Pi append/readback did not acknowledge the event.",
+      );
+    }
+  }
+}

package/pi-extension/src/session-sources/provenance.ts

@@ -0,0 +1,39 @@
+import { isWorkerProfile } from "../cognitive-routing-v2/types.js";
+import { isTaskEvidence, textRef, type Sources, type Source } from "./sources.js";
+
+export function annotateSources(
+  messages: any[],
+  renderedSources: Map<any, Source>,
+  full: Set<string>,
+  sources: Sources,
+  instance: string,
+): any[] {
+  const annotated: any[] = [];
+  for (let i = 0; i < messages.length;) {
+    const group = [messages[i++]];
+    while (i < messages.length && messages[i].role === "toolResult") group.push(messages[i++]);
+    const rows = group.flatMap((message) => {
+      const s = renderedSources.get(message);
+      if (!s) return [];
+      const representation = full.has(s.ref) ? "full" : "structural only; omitted result bodies are not evidence";
+      const selection =
+        isWorkerProfile(s.producer) && isTaskEvidence(s) && full.has(s.ref)
+          ? "task evidence; selection checks apply"
+          : "not offered for new evidence selection";
+      return [
+        `${s.ref} | producer: ${s.producer === "common" ? "unknown/common (no observed routing profile)" : s.producer} | ${s.original ? "assistant-text" : s.message.role}${s.message.toolName ? ` | ${s.message.toolName}` : ""}${s.assignmentId ? ` | assignment: ${s.assignmentId}` : ""} | ${representation} | ${selection}${!s.original && full.has(s.ref) && sources.byRef.has(textRef(s.ref)) ? ` | visible text: ${textRef(s.ref)}` : ""}`,
+      ];
+    });
+    annotated.push(...group);
+    if (rows.length)
+      annotated.push({
+        role: "custom",
+        customType: "freeflow-routing-v2-refs",
+        display: false,
+        content: `Source provenance for the preceding message/exchange:\n${rows.join("\n")}`,
+        details: { routingInstance: instance },
+        timestamp: 0,
+      });
+  }
+  return annotated;
+}

package/pi-extension/src/session-sources/read-only-session.ts

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import { open, stat } from "node:fs/promises";
+import { TextDecoder } from "node:util";
+
+export interface ReadOnlySessionEntry {
+  type: string;
+  id: string;
+  parentId?: string | null;
+  [key: string]: unknown;
+}
+export interface ReadOnlySessionSnapshot {
+  path: string;
+  sessionId: string;
+  version: number;
+  hash: string;
+  entries: readonly ReadOnlySessionEntry[];
+}
+export class ReadOnlySessionError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly line?: number,
+  ) {
+    super(message);
+    this.name = "ReadOnlySessionError";
+  }
+}
+
+export const SESSION_READ_LIMITS = {
+  maxBytes: 512 * 1024 * 1024,
+  maxEntryBytes: 128 * 1024 * 1024,
+  maxEntries: 250000,
+};
+function decodeEntry(text: string, line: number, seen: Set<string>): ReadOnlySessionEntry {
+  let value: any;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new ReadOnlySessionError("invalid_json", "Incomplete or invalid session JSON.", line);
+  }
+  if (!value || Array.isArray(value) || typeof value !== "object" || typeof value.type !== "string")
+    throw new ReadOnlySessionError("invalid_entry", "Invalid session entry.", line);
+  if (line === 1) {
+    if (
+      value.type !== "session" ||
+      typeof value.id !== "string" ||
+      !value.id ||
+      ![2, 3].includes(value.version) ||
+      typeof value.cwd !== "string"
+    )
+      throw new ReadOnlySessionError("invalid_header", "A supported native session header is required.", line);
+  } else {
+    if (value.type === "session" || typeof value.id !== "string" || !value.id || seen.has(value.id))
+      throw new ReadOnlySessionError("invalid_id", "Missing, duplicate, or misplaced session identity.", line);
+    if (value.parentId !== null && (typeof value.parentId !== "string" || !seen.has(value.parentId)))
+      throw new ReadOnlySessionError("invalid_parent", "Parent is absent or occurs after its child.", line);
+    seen.add(value.id);
+  }
+  return value;
+}
+export function parseReadOnlySessionText(text: string): readonly ReadOnlySessionEntry[] {
+  const lines = text.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  if (!lines.length || !lines[0]) throw new ReadOnlySessionError("empty", "Session snapshot is empty.");
+  const seen = new Set<string>();
+  return lines.map((line, i) => decodeEntry(line, i + 1, seen));
+}
+export async function readOnlySessionSnapshot(
+  path: string,
+  options: { maxBytes?: number; maxEntryBytes?: number; maxEntries?: number } = {},
+): Promise<ReadOnlySessionSnapshot> {
+  const limits = { ...SESSION_READ_LIMITS, ...options };
+  if (Object.values(limits).some((n) => !Number.isSafeInteger(n) || n <= 0))
+    throw new ReadOnlySessionError("invalid_limit", "Invalid snapshot limit.");
+  let file: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    file = await open(path, "r");
+    const before = await file.stat({ bigint: true });
+    if (!before.isFile()) throw new ReadOnlySessionError("read_limit", "Session is not a regular file.");
+    if (before.size > BigInt(limits.maxBytes))
+      throw new ReadOnlySessionError(
+        "read_limit",
+        `Session exceeds the supported ${limits.maxBytes} byte snapshot limit.`,
+      );
+    const hash = createHash("sha256"),
+      entries: ReadOnlySessionEntry[] = [],
+      seen = new Set<string>();
+    let total = 0,
+      lineBytes = 0,
+      parts: Buffer[] = [];
+    const append = (part: Buffer) => {
+      lineBytes += part.length;
+      if (lineBytes > limits.maxEntryBytes)
+        throw new ReadOnlySessionError(
+          "entry_limit",
+          `Session entry exceeds ${limits.maxEntryBytes} bytes.`,
+          entries.length + 1,
+        );
+      if (part.length) parts.push(part);
+    };
+    const decode = () => {
+      if (entries.length >= limits.maxEntries)
+        throw new ReadOnlySessionError("entry_count_limit", `Session exceeds ${limits.maxEntries} entries.`);
+      let text: string;
+      try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(parts, lineBytes));
+      } catch {
+        throw new ReadOnlySessionError("invalid_encoding", "Session is not complete UTF-8.", entries.length + 1);
+      }
+      entries.push(decodeEntry(text, entries.length + 1, seen));
+      parts = [];
+      lineBytes = 0;
+    };
+    for (;;) {
+      const buffer = Buffer.alloc(64 * 1024),
+        { bytesRead } = await file.read(buffer, 0, buffer.length, null);
+      if (!bytesRead) break;
+      total += bytesRead;
+      if (total > limits.maxBytes)
+        throw new ReadOnlySessionError("read_limit", "Session grew beyond the supported snapshot limit.");
+      const bytes = buffer.subarray(0, bytesRead);
+      hash.update(bytes);
+      let start = 0,
+        end: number;
+      while ((end = bytes.indexOf(10, start)) !== -1) {
+        append(bytes.subarray(start, end));
+        decode();
+        start = end + 1;
+      }
+      append(bytes.subarray(start));
+    }
+    if (lineBytes) decode();
+    if (!entries.length) throw new ReadOnlySessionError("empty", "Session snapshot is empty.");
+    const after = await file.stat({ bigint: true }),
+      current = await stat(path, { bigint: true });
+    const signature = (v: typeof before) => [v.dev, v.ino, v.size, v.mtimeNs, v.ctimeNs].join(":");
+    if (
+      signature(before) !== signature(after) ||
+      signature(after) !== signature(current) ||
+      after.size !== BigInt(total)
+    )
+      throw new ReadOnlySessionError("source_changed", "Session changed during snapshot capture.");
+    return { path, sessionId: entries[0].id, version: entries[0].version as number, hash: hash.digest("hex"), entries };
+  } catch (error) {
+    if (error instanceof ReadOnlySessionError) throw error;
+    throw new ReadOnlySessionError("read_failed", error instanceof Error ? error.message : String(error));
+  } finally {
+    await file?.close();
+  }
+}
+
+export function activeReadOnlySessionBranch(
+  snapshot: ReadOnlySessionSnapshot,
+  leafId: string | null,
+): readonly ReadOnlySessionEntry[] {
+  if (leafId === null) return [];
+  const byId = new Map(snapshot.entries.slice(1).map((entry) => [entry.id, entry]));
+  const path: ReadOnlySessionEntry[] = [];
+  const seen = new Set<string>();
+  let cursor: string | null = leafId;
+  while (cursor !== null) {
+    const entry = byId.get(cursor);
+    if (!entry || seen.has(cursor))
+      throw new ReadOnlySessionError("ancestry_unavailable", "Requested native ancestry is unavailable.");
+    seen.add(cursor);
+    path.push(entry);
+    cursor = entry.parentId as string | null;
+  }
+  return path.reverse();
+}