arisa 5.2.7 → 5.2.17

package/README.md

@@ -108,7 +108,7 @@ Per chat (`~/.arisa/chats/<chatId>/`):
 - chat-scoped daemon infrastructure lives in `state/tools/<tool>/daemon/`; persistent tool data stays beside it
 - ephemeral scratch lives under `tmp/`
 
-Managed daemons become ready only after their tool-defined health operation succeeds through the normal command queue. Arisa records heartbeats, successful jobs, errors, and standard lifecycle states, then retries recovery or recreates an unhealthy process with its persisted scope and startup context.
+Managed daemons become ready only after their tool-defined health operation succeeds through the normal command queue. Arisa records heartbeats, successful jobs, errors, and standard lifecycle states, then retries recovery or recreates an unhealthy process with its persisted scope and startup context. The supervisor automatically removes registrations and daemon runtime directories that no longer match an installed daemon tool. A live process is terminated only when its command line matches the registered entry and daemon invocation; unverifiable PIDs are left untouched and reported for attention.
 
 Daemon tools may opt into the `arisa-daemon-v1` local protocol for immediate
 multiplexed jobs and incremental NDJSON events over a capability-protected local
@@ -151,12 +151,31 @@ Automatic context compaction uses Pi's native implementation and can be tuned in
       "enabled": true,
       "reserveTokens": 120000,
       "keepRecentTokens": 20000
+    },
+    "sessionRotation": {
+      "enabled": true,
+      "compactAtPersistedBytes": 25165824,
+      "maxPersistedBytes": 33554432
+    },
+    "toolFanout": {
+      "enabled": true,
+      "maxConcurrent": 2,
+      "pressureConcurrent": 1,
+      "serializePercent": 60
+    },
+    "turnCoordinator": {
+      "enabled": true,
+      "backgroundQueueTtlMs": 600000,
+      "interactiveQueueTtlMs": 0,
+      "maxQueued": 100
     }
   }
 }
 ```
 
-Pi compacts when the context exceeds the model's context window minus `reserveTokens`. The default keeps a large reserve so compaction occurs before Arisa Doctor's context warning on the default model. Set a smaller reserve when using models with substantially smaller context windows. Arisa does not add Telegram commands or compaction notifications.
+Pi compacts when the context exceeds the model's context window minus `reserveTokens`. Arisa also requests compaction when persisted history exceeds `compactAtPersistedBytes`, then rotates to a fresh JSONL using the latest summary and retained active context. Before Pi loads a recent session above `maxPersistedBytes`, Arisa discovers the last valid active-branch compaction by streaming, atomically creates a compact child with `parentSession`, and leaves the historical JSONL intact. An unsafe oversized session is rejected rather than loaded into an OOM-prone worker. Same-turn `run_tool` fan-out is capped at two, becomes sequential when heap usage reaches `serializePercent`, and uses the heap circuit breaker before every admission. Across chats and topics, `turnCoordinator` admits only one Pi turn or headless poll at a time, prioritizes interactive messages and events over queued background work, and safely expires stale background admissions before execution. Set a smaller token reserve when using models with substantially smaller context windows. Arisa adds no Telegram commands or compaction notifications.
+
+Browser and checkout tools report lifecycle states separately: profile connection is not a session share, a session share is not target validation, wallet enrollment is not checkout submission, and only explicit target or merchant evidence can confirm the final objective.
 
 ## Install globally
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "5.2.7",
+  "version": "5.2.17",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",

package/src/core/agent/agent-manager.js

@@ -14,6 +14,9 @@ import { createPiCapabilityTools } from "./pi-capability-tools.js";
 import { ToolResourceNoteStore } from "../tools/tool-resource-note-store.js";
 import { materializeToolOutput } from "../tools/tool-output-materializer.js";
 import { WorkerHeapCircuitBreaker } from "./worker-heap-circuit-breaker.js";
+import { WorkerToolFanoutController } from "./worker-tool-fanout.js";
+import { compactionRotationRequest, normalizeSessionRotationPolicy } from "./session-rotation.js";
+import { AgentTurnCoordinator } from "./agent-turn-coordinator.js";
 
 const piValidationTimeoutMs = 60_000;
 const arisaToolNames = [
@@ -156,13 +159,23 @@ export class AgentManager {
     this.sessionLifecycle = new AgentSessionLifecycle({
       logger,
       summarizeContext: summarizeRetainedContext,
-      cachePolicy: config.pi.sessionCache
+      cachePolicy: config.pi.sessionCache,
+      sessionRotationPolicy: config.pi.sessionRotation
     });
     this.heapCircuitBreaker = new WorkerHeapCircuitBreaker({
       lifecycle: this.sessionLifecycle,
       logger,
       config: config.pi.heapCircuitBreaker
     });
+    this.toolFanout = new WorkerToolFanoutController({
+      heapCircuitBreaker: this.heapCircuitBreaker,
+      logger,
+      config: config.pi.toolFanout
+    });
+    this.turnCoordinator = new AgentTurnCoordinator({
+      logger,
+      config: config.pi.turnCoordinator
+    });
     this.sessions = this.sessionLifecycle.sessions;
     this.pendingNewSessions = this.sessionLifecycle.pendingNewSessions;
     this.pendingSessionHandoffs = this.sessionLifecycle.pendingSessionHandoffs;
@@ -196,7 +209,10 @@ export class AgentManager {
   setConfig(config) {
     this.sessionLifecycle.resetConfigState();
     this.sessionLifecycle.setCachePolicy(config.pi.sessionCache);
+    this.sessionLifecycle.setSessionRotationPolicy(config.pi.sessionRotation);
     this.heapCircuitBreaker.setConfig(config.pi.heapCircuitBreaker);
+    this.toolFanout.setConfig(config.pi.toolFanout);
+    this.turnCoordinator.setConfig(config.pi.turnCoordinator);
     this.config = config;
   }
 
@@ -222,7 +238,9 @@ export class AgentManager {
     const diagnostic = await this.sessionLifecycle.getDiagnostic();
     return {
       ...diagnostic,
-      heapCircuitBreaker: this.heapCircuitBreaker.getDiagnostic()
+      heapCircuitBreaker: this.heapCircuitBreaker.getDiagnostic(),
+      toolFanout: this.toolFanout.getDiagnostic(),
+      turnCoordinator: this.turnCoordinator.diagnostic()
     };
   }
 
@@ -249,13 +267,60 @@ export class AgentManager {
     return context;
   }
 
+  async compactPersistedSessionIfNeeded(sessionKey, context, persistedBytes) {
+    const policy = normalizeSessionRotationPolicy(this.config.pi.sessionRotation);
+    if (!policy.enabled
+      || persistedBytes <= policy.compactAtPersistedBytes
+      || context.rotationRequest
+      || typeof context.session?.compact !== "function") return;
+    try {
+      this.logger?.log("agent", `compacting ${Math.ceil(persistedBytes / 1024 / 1024)} MiB Pi session for chat ${sessionKey} before rotation`);
+      await context.session.compact();
+      await context.rotationCheckPromise;
+    } catch (error) {
+      this.logger?.error?.("agent", `persisted-size compaction failed for chat ${sessionKey}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
   async releaseSessionContext(sessionKey, context) {
     if (this.sessions.get(String(sessionKey)) !== context) return;
+    await context.rotationCheckPromise;
     const persistedBytes = await this.estimatePersistedSessionBytes(context.session);
+    if ((context.activeUsers || 0) <= 1) {
+      await this.compactPersistedSessionIfNeeded(sessionKey, context, persistedBytes);
+    }
     this.sessionLifecycle.releaseCached(sessionKey, persistedBytes);
+    if ((context.activeUsers || 0) === 0 && context.rotationRequest) {
+      const request = context.rotationRequest;
+      const parentSession = context.session.sessionFile || "";
+      this.logger?.log("agent", `rotating ${Math.ceil(request.persistedBytes / 1024 / 1024)} MiB Pi session for chat ${sessionKey} after compaction`);
+      this.sessionLifecycle.resetSession(sessionKey, {
+        handoff: request.handoff,
+        parentSession,
+        source: "compaction-rotation"
+      });
+      await this.sessionLifecycle.waitForClose(sessionKey);
+      return;
+    }
     await this.sessionLifecycle.enforceCachePolicy();
   }
 
+  scheduleCompactionRotationCheck(sessionKey, context, event) {
+    if (event?.type !== "compaction_end") return;
+    const previous = context.rotationCheckPromise || Promise.resolve();
+    context.rotationCheckPromise = previous
+      .catch(() => {})
+      .then(async () => {
+        if (this.sessions.get(String(sessionKey)) !== context) return;
+        const persistedBytes = await this.estimatePersistedSessionBytes(context.session);
+        const request = compactionRotationRequest(event, persistedBytes, this.config.pi.sessionRotation);
+        if (request) context.rotationRequest = request;
+      })
+      .catch((error) => {
+        this.logger?.error?.("agent", `session rotation check failed for chat ${sessionKey}: ${error instanceof Error ? error.message : String(error)}`);
+      });
+  }
+
   async validatePiAgent(config = this.config) {
     this.logger?.log("agent", "validating Pi session");
     const { authStorage, modelRegistry } = createPiRuntime({
@@ -402,8 +467,11 @@ export class AgentManager {
       modelKey: effectiveModelKey,
       speedController,
       telegramTarget,
-      accessGuardTarget
+      accessGuardTarget,
+      rotationCheckPromise: Promise.resolve(),
+      rotationRequest: null
     };
+    session.subscribe((event) => this.scheduleCompactionRotationCheck(sessionKey, ctx, event));
     this.sessions.set(sessionKey, ctx);
     if (isNewSession) this.sessionLifecycle.completeNewSession(sessionKey);
     return this.acquireSessionContext(sessionKey, ctx);
@@ -424,9 +492,15 @@ export class AgentManager {
   }
 
   async close() {
+    this.turnCoordinator.close();
     await this.sessionLifecycle.closeAll();
   }
 
+  async runTurn(options, work) {
+    if (typeof work !== "function") throw new Error("Agent turn work is required");
+    return this.turnCoordinator.run(options, work);
+  }
+
   async runTool({ name, request, chatId, taskContext = null }) {
     await this.toolRegistry.load();
     this.logger?.log("agent", `run_tool ${name}`);
@@ -453,7 +527,8 @@ export class AgentManager {
       telegram,
       chatId,
       policy,
-      logger: this.logger
+      logger: this.logger,
+      toolFanout: this.toolFanout
     });
   }
 

package/src/core/agent/agent-session-lifecycle.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { getChatPiSessionsDir, sessionStartOperationalNotesFile } from "../../platform/paths.js";
 import { arisaInstallDir } from "./runtime-context.js";
+import { migrateRecentSessionBeforeLoad } from "./session-preload-migration.js";
 
 const operationalNoteMaxChars = 220;
 
@@ -26,7 +27,7 @@ export function loadSessionStartOperationalNotes() {
   }
 }
 
-function formatSessionStartOperationalNotes(notes) {
+export function formatSessionStartOperationalNotes(notes) {
   if (!notes.length) return "";
   return [
     "Durable operating notes for this Arisa session:",
@@ -41,7 +42,7 @@ function closeAgentSession(session) {
 }
 
 export class AgentSessionLifecycle {
-  constructor({ logger, summarizeContext, cachePolicy = {} }) {
+  constructor({ logger, summarizeContext, cachePolicy = {}, sessionRotationPolicy = {} }) {
     this.logger = logger;
     this.summarizeContext = summarizeContext;
     this.sessions = new Map();
@@ -49,6 +50,7 @@ export class AgentSessionLifecycle {
     this.pendingSessionHandoffs = new Map();
     this.sessionClosePromises = new Map();
     this.setCachePolicy(cachePolicy);
+    this.setSessionRotationPolicy(sessionRotationPolicy);
   }
 
   setCachePolicy(cachePolicy = {}) {
@@ -58,6 +60,10 @@ export class AgentSessionLifecycle {
     };
   }
 
+  setSessionRotationPolicy(policy = {}) {
+    this.sessionRotationPolicy = { ...policy };
+  }
+
   acquireCached(sessionKey, persistedBytes = 0) {
     const context = this.sessions.get(String(sessionKey));
     if (!context) return;
@@ -161,14 +167,19 @@ export class AgentSessionLifecycle {
     this.pendingSessionHandoffs.clear();
   }
 
-  resetSession(chatId, { handoff = "", parentSession = "" } = {}) {
+  resetSession(chatId, { handoff = "", parentSession = "", source = "" } = {}) {
     const sessionKey = String(chatId);
     this.closeCached(sessionKey);
     this.pendingNewSessions.add(sessionKey);
     const text = String(handoff || "").trim();
     const parent = String(parentSession || "").trim();
+    const handoffSource = String(source || "").trim();
     if (text || parent) {
-      this.pendingSessionHandoffs.set(sessionKey, { text, parentSession: parent });
+      this.pendingSessionHandoffs.set(sessionKey, {
+        text,
+        parentSession: parent,
+        ...(handoffSource ? { source: handoffSource } : {})
+      });
     } else {
       this.pendingSessionHandoffs.delete(sessionKey);
     }
@@ -177,6 +188,7 @@ export class AgentSessionLifecycle {
   createSessionManager(chatId, workspaceDir = arisaInstallDir, sessionRevision = 0) {
     const sessionKey = String(chatId);
     const sessionDir = getChatPiSessionsDir(sessionKey, sessionRevision);
+    const operationalNotes = formatSessionStartOperationalNotes(loadSessionStartOperationalNotes());
     if (this.pendingNewSessions.has(sessionKey)) {
       this.logger?.log("agent", `starting new persisted session for chat ${sessionKey}`);
       const handoff = this.pendingSessionHandoffs.get(sessionKey);
@@ -185,7 +197,6 @@ export class AgentSessionLifecycle {
         sessionDir,
         handoff?.parentSession ? { parentSession: handoff.parentSession } : undefined
       );
-      const operationalNotes = formatSessionStartOperationalNotes(loadSessionStartOperationalNotes());
       if (operationalNotes) {
         sessionManager.appendCustomMessageEntry(
           "arisa-operational-notes",
@@ -199,11 +210,23 @@ export class AgentSessionLifecycle {
           "arisa-session-handoff",
           handoff.text,
           false,
-          { source: "telegram-new" }
+          { source: handoff.source || "telegram-new" }
         );
       }
       return { sessionManager, isNewSession: true };
     }
+    const migration = migrateRecentSessionBeforeLoad({
+      sessionDir,
+      cwd: workspaceDir,
+      policy: this.sessionRotationPolicy,
+      operationalNotes
+    });
+    if (migration) {
+      this.logger?.log(
+        "agent",
+        `migrated oversized Pi session for chat ${sessionKey} before loading (${Math.ceil(migration.sourceBytes / 1024 / 1024)} MiB -> ${Math.ceil(migration.targetBytes / 1024 / 1024)} MiB)`
+      );
+    }
     this.logger?.log("agent", `recovering persisted session for chat ${sessionKey}`);
     return {
       sessionManager: SessionManager.continueRecent(workspaceDir, sessionDir),

package/src/core/agent/agent-turn-coordinator.js

@@ -0,0 +1,143 @@
+function normalizedPriority(value) {
+  if (value === "interactive") return 10;
+  if (value === "background") return 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.max(-100, Math.min(100, parsed)) : 0;
+}
+
+function positiveInteger(value, fallback, max) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.min(max, parsed) : fallback;
+}
+
+function queueExpiredError(label) {
+  const error = new Error(`${label || "Agent turn"} expired while waiting for exclusive execution.`);
+  error.code = "AGENT_TURN_QUEUE_EXPIRED";
+  error.retryable = true;
+  error.outcomeUncertain = false;
+  return error;
+}
+
+export class AgentTurnCoordinator {
+  constructor({ config = {}, logger = null, now = Date.now } = {}) {
+    this.logger = logger;
+    this.now = now;
+    this.queue = [];
+    this.active = null;
+    this.sequence = 0;
+    this.closed = false;
+    this.completed = 0;
+    this.expired = 0;
+    this.maxObservedQueue = 0;
+    this.totalWaitMs = 0;
+    this.setConfig(config);
+  }
+
+  setConfig(config = {}) {
+    this.config = {
+      enabled: config.enabled !== false,
+      backgroundQueueTtlMs: positiveInteger(config.backgroundQueueTtlMs, 10 * 60_000, 60 * 60_000),
+      interactiveQueueTtlMs: positiveInteger(config.interactiveQueueTtlMs, 0, 60 * 60_000),
+      maxQueued: Math.max(1, positiveInteger(config.maxQueued, 100, 1_000))
+    };
+  }
+
+  queueTtlMs(priority, override) {
+    if (override != null) return positiveInteger(override, 0, 60 * 60_000);
+    return priority === "interactive" ? this.config.interactiveQueueTtlMs : this.config.backgroundQueueTtlMs;
+  }
+
+  describeActive(entry) {
+    if (!entry) return null;
+    return { label: entry.label, priority: entry.priorityName, startedAt: entry.startedAt };
+  }
+
+  diagnostic() {
+    return {
+      enabled: this.config.enabled,
+      active: this.describeActive(this.active),
+      queued: this.queue.length,
+      maxObservedQueue: this.maxObservedQueue,
+      completed: this.completed,
+      expired: this.expired,
+      averageWaitMs: this.completed ? Math.round(this.totalWaitMs / this.completed) : 0
+    };
+  }
+
+  remove(entry) {
+    const index = this.queue.indexOf(entry);
+    if (index >= 0) this.queue.splice(index, 1);
+  }
+
+  next() {
+    if (this.active || this.closed || !this.queue.length) return;
+    this.queue.sort((left, right) => right.priority - left.priority || left.sequence - right.sequence);
+    const entry = this.queue.shift();
+    if (entry.timer) clearTimeout(entry.timer);
+    entry.startedAt = new Date(this.now()).toISOString();
+    this.active = entry;
+    const waitMs = Math.max(0, this.now() - entry.queuedAt);
+    this.totalWaitMs += waitMs;
+    if (waitMs > 0) this.logger?.log("agent", `${entry.label} waited ${waitMs}ms for exclusive agent execution`);
+    let released = false;
+    entry.resolve(() => {
+      if (released) return;
+      released = true;
+      if (this.active === entry) this.active = null;
+      this.completed += 1;
+      queueMicrotask(() => this.next());
+    });
+  }
+
+  acquire({ priority: priorityName = "background", label = "Agent turn", queueTtlMs } = {}) {
+    if (!this.config.enabled) return Promise.resolve(() => {});
+    if (this.closed) return Promise.reject(Object.assign(new Error("Agent turn coordinator is closed."), { retryable: true }));
+    if (this.queue.length >= this.config.maxQueued) {
+      return Promise.reject(Object.assign(new Error("Agent turn queue is full."), { code: "AGENT_TURN_QUEUE_FULL", retryable: true }));
+    }
+    const priority = normalizedPriority(priorityName);
+    const ttlMs = this.queueTtlMs(priorityName, queueTtlMs);
+    return new Promise((resolve, reject) => {
+      const entry = {
+        label: String(label || "Agent turn").slice(0, 160),
+        priorityName: priorityName === "interactive" ? "interactive" : "background",
+        priority,
+        sequence: this.sequence += 1,
+        queuedAt: this.now(),
+        startedAt: null,
+        resolve,
+        reject,
+        timer: null
+      };
+      if (ttlMs > 0) {
+        entry.timer = setTimeout(() => {
+          if (this.active === entry) return;
+          this.remove(entry);
+          this.expired += 1;
+          reject(queueExpiredError(entry.label));
+        }, ttlMs);
+        entry.timer.unref?.();
+      }
+      this.queue.push(entry);
+      this.maxObservedQueue = Math.max(this.maxObservedQueue, this.queue.length);
+      this.next();
+    });
+  }
+
+  async run(options, work) {
+    const release = await this.acquire(options);
+    try {
+      return await work();
+    } finally {
+      release();
+    }
+  }
+
+  close() {
+    this.closed = true;
+    for (const entry of this.queue.splice(0)) {
+      if (entry.timer) clearTimeout(entry.timer);
+      entry.reject(Object.assign(new Error("Agent turn coordinator closed before execution."), { retryable: true }));
+    }
+  }
+}

package/src/core/agent/pi-capability-tools.js

@@ -18,7 +18,7 @@ function nativeTools(policy) {
   }];
 }
 
-export function createPiCapabilityTools({ capabilityService, telegram, chatId, policy, logger }) {
+export function createPiCapabilityTools({ capabilityService, telegram, chatId, policy, logger, toolFanout }) {
   if (!capabilityService?.execute) throw new Error("Pi capability tools require CapabilityService");
 
   const baseContext = {
@@ -38,6 +38,7 @@ export function createPiCapabilityTools({ capabilityService, telegram, chatId, p
     }
   };
 
+  const runWithFanout = (work) => toolFanout?.run ? toolFanout.run(work) : work();
   const execute = (actorToolName, method, params = {}, context = {}) => capabilityService.execute({
     method,
     actorToolName,
@@ -113,12 +114,14 @@ export function createPiCapabilityTools({ capabilityService, telegram, chatId, p
         args: Type.Optional(Type.Record(Type.String(), Type.String())),
         deliver: Type.Optional(Type.Boolean())
       }),
-      execute: async (_id, params) => jsonResult(await execute("run_tool", "tools.run", params))
+      execute: async (_id, params) => jsonResult(await runWithFanout(
+        () => execute("run_tool", "tools.run", params)
+      ))
     }),
     defineTool({
       name: "list_scheduled_tasks",
       label: "List scheduled tasks",
-      description: "List scheduled async tasks for the current Telegram chat. Results default to 50 tasks, always include pending/running tasks, and accept an optional limit up to 100.",
+      description: "List scheduled async tasks for the current Telegram chat. Results default to 50 tasks, always include pending, running, and authentication-blocked tasks, and accept an optional limit up to 100.",
       parameters: Type.Object({
         status: Type.Optional(Type.String()),
         limit: Type.Optional(Type.Integer({ minimum: 1, maximum: maxScheduledTaskListLimit }))
@@ -135,7 +138,7 @@ export function createPiCapabilityTools({ capabilityService, telegram, chatId, p
     defineTool({
       name: "cancel_all_scheduled_tasks",
       label: "Cancel all scheduled tasks",
-      description: "Cancel all pending or running async tasks for the current Telegram chat.",
+      description: "Cancel all active async tasks, including authentication-blocked tasks, for the current Telegram chat.",
       parameters: Type.Object({}),
       execute: async () => jsonResult(await execute("cancel_all_scheduled_tasks", "tasks.cancelAll"))
     }),

package/src/core/agent/session-history-reader.js

@@ -0,0 +1,168 @@
+import { closeSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+const readBufferBytes = 1024 * 1024;
+const supportedSessionVersion = 3;
+
+function parseEntry(line) {
+  if (!line.trim()) return null;
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function readSessionHeader(filePath) {
+  const descriptor = openSync(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(4096);
+    const bytesRead = readSync(descriptor, buffer, 0, buffer.length, 0);
+    const line = buffer.toString("utf8", 0, bytesRead).split("\n", 1)[0];
+    const header = parseEntry(line);
+    return header?.type === "session" ? header : null;
+  } catch {
+    return null;
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function findMostRecentSessionFile(sessionDir, cwd) {
+  const expectedCwd = path.resolve(cwd);
+  try {
+    return readdirSync(sessionDir)
+      .filter((name) => name.endsWith(".jsonl"))
+      .map((name) => path.join(sessionDir, name))
+      .map((filePath) => ({ filePath, header: readSessionHeader(filePath) }))
+      .filter(({ header }) => header && typeof header.cwd === "string" && path.resolve(header.cwd) === expectedCwd)
+      .map(({ filePath }) => ({ filePath, mtimeMs: statSync(filePath).mtimeMs }))
+      .sort((left, right) => right.mtimeMs - left.mtimeMs)[0]?.filePath || null;
+  } catch {
+    return null;
+  }
+}
+
+export function streamSessionEntries(filePath, visit) {
+  const descriptor = openSync(filePath, "r");
+  try {
+    const decoder = new StringDecoder("utf8");
+    const buffer = Buffer.allocUnsafe(readBufferBytes);
+    let pending = "";
+    while (true) {
+      const bytesRead = readSync(descriptor, buffer, 0, buffer.length, null);
+      if (!bytesRead) break;
+      pending += decoder.write(buffer.subarray(0, bytesRead));
+      let newline = pending.indexOf("\n");
+      while (newline !== -1) {
+        const entry = parseEntry(pending.slice(0, newline));
+        if (entry) visit(entry);
+        pending = pending.slice(newline + 1);
+        newline = pending.indexOf("\n");
+      }
+    }
+    pending += decoder.end();
+    const entry = parseEntry(pending);
+    if (entry) visit(entry);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function traceActivePath(entries, leafId) {
+  const reversed = [];
+  const seen = new Set();
+  let currentId = leafId;
+  while (currentId) {
+    if (seen.has(currentId)) return null;
+    seen.add(currentId);
+    const entry = entries.get(currentId);
+    if (!entry) return null;
+    reversed.push(entry);
+    currentId = entry.parentId || null;
+  }
+  return reversed.reverse();
+}
+
+function findLatestValidCompaction(path) {
+  const pathIndex = new Map(path.map((entry, index) => [entry.id, index]));
+  for (let index = path.length - 1; index >= 0; index -= 1) {
+    const entry = path[index];
+    if (entry.type !== "compaction" || !entry.hasSummary) continue;
+    if (!entry.firstKeptEntryId) return { entry, index, firstKeptIndex: index };
+    const firstKeptIndex = pathIndex.get(entry.firstKeptEntryId);
+    if (firstKeptIndex !== undefined && firstKeptIndex < index) {
+      return { entry, index, firstKeptIndex };
+    }
+  }
+  return null;
+}
+
+function inspectSessionGraph(filePath) {
+  let header = null;
+  let firstEntry = true;
+  let invalidHeader = false;
+  let leafId = null;
+  let duplicateId = false;
+  const entries = new Map();
+  streamSessionEntries(filePath, (entry) => {
+    if (firstEntry) {
+      firstEntry = false;
+      header = entry.type === "session" ? entry : null;
+      invalidHeader = !header;
+      return;
+    }
+    if (invalidHeader) return;
+    if (!entry.id || entry.type === "session") return;
+    if (entries.has(entry.id)) duplicateId = true;
+    entries.set(entry.id, {
+      id: entry.id,
+      parentId: entry.parentId || null,
+      type: entry.type,
+      firstKeptEntryId: entry.type === "compaction" ? entry.firstKeptEntryId || null : null,
+      hasSummary: entry.type === "compaction" && Boolean(String(entry.summary || "").trim())
+    });
+    leafId = entry.id;
+  });
+  if (invalidHeader || !header || header.version !== supportedSessionVersion || duplicateId || !leafId) return null;
+  const path = traceActivePath(entries, leafId);
+  if (!path) return null;
+  const compaction = findLatestValidCompaction(path);
+  if (!compaction) return null;
+  return { header, path, compaction };
+}
+
+function loadMigrationPayload(filePath, path, compaction) {
+  const before = path.slice(compaction.firstKeptIndex, compaction.index);
+  const after = path.slice(compaction.index + 1);
+  const contextIds = [...before, ...after].map((entry) => entry.id);
+  const wanted = new Set(contextIds);
+  const loaded = new Map();
+  let summary = "";
+  streamSessionEntries(filePath, (entry) => {
+    if (entry.id === compaction.entry.id) summary = String(entry.summary || "").trim();
+    if (wanted.has(entry.id)) loaded.set(entry.id, entry);
+  });
+  if (!summary || loaded.size !== wanted.size) return null;
+  return {
+    summary,
+    contextEntries: contextIds.map((id) => loaded.get(id))
+  };
+}
+
+export function inspectSessionForPreloadMigration(filePath, maxPersistedBytes) {
+  const sourceBytes = statSync(filePath).size;
+  if (sourceBytes <= Math.max(1, Number(maxPersistedBytes) || 1)) return null;
+  const graph = inspectSessionGraph(filePath);
+  if (!graph) return null;
+  const payload = loadMigrationPayload(filePath, graph.path, graph.compaction);
+  if (!payload) return null;
+  return {
+    sourceFile: filePath,
+    sourceBytes,
+    header: graph.header,
+    compactionId: graph.compaction.entry.id,
+    ...payload
+  };
+}