pi-claude-supervisor 0.6.0 → 0.7.0

package/src/decision-worker.ts

@@ -2,8 +2,10 @@ import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { lstat, open, rename, rm, writeFile, type FileHandle } from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, type AgentSession } from "@earendil-works/pi-coding-agent";
-import type { TaskSpec, WorkerEvent } from "./types.ts";
+import { extractJsonObjects } from "./json-extract.ts";
+import type { PiUsageSample, TaskSpec, WorkerEvent } from "./types.ts";
 import { redactSensitive } from "./redaction.ts";
 
 const MAX_DECISION_RESPONSE_BYTES = 32 * 1024;
@@ -30,6 +32,8 @@ export interface DecisionWorkerLike {
   start(): Promise<void>;
   updateContext(patch: Partial<DecisionContext>): void;
   notify(event: WorkerEvent): void;
+  /** Re-deliver an event already seen (e.g. after a Supervisor recovery) bypassing dedupe. */
+  replay?(event: WorkerEvent): void;
   close(): Promise<void>;
 }
 
@@ -42,13 +46,27 @@ export interface DecisionWorkerOptions {
   onStartupFailure?: (error: unknown) => Promise<void> | void;
   /** Bound each Decision Worker model request so failure handling cannot wait forever. */
   timeoutMs?: number;
+  /** Base backoff for retrying a failed Decision Worker request; doubles per attempt, capped at 30s. */
+  retryBackoffMs?: number;
   /** Existing Pi session JSONL to restore after a Supervisor/Pi restart. */
   sessionFile?: string;
   /** Directory for newly created Pi session JSONL files. */
   sessionDir?: string;
   onSessionReady?: (info: { sessionFile: string; sessionId: string; restored: boolean }) => Promise<void> | void;
+  /** Test seam: inject a fake Pi session instead of the real createAgentSession. */
+  sessionFactory?: (options: Parameters<typeof createAgentSession>[0]) => Promise<{ session: AgentSession }>;
+  /** Pi model for this session; undefined keeps Pi's configured default. */
+  model?: PiModel;
+  /** Compact the persistent session once its estimated context exceeds this many tokens (0 disables). */
+  compactionTokens?: number;
+  /** Token accounting for every model call made by this session. */
+  onUsage?: (usage: PiUsageSample) => void;
 }
 
+export type PiModel = NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["model"]>;
+
+const DEFAULT_COMPACTION_TOKENS = 60_000;
+
 /**
  * A persistent Pi SDK session used only for supervision decisions.
  * It has read-only repository tools and can request typed actions, but it
@@ -64,11 +82,17 @@ export class PiDecisionWorker implements DecisionWorkerLike {
   #sessionFile?: string;
   #context: DecisionContext;
   readonly #timeoutMs: number;
+  readonly #retryBackoffMs: number;
+  readonly #compactionTokens: number;
+  /** Set after a compaction; the next primary decision prompt re-sends the startup instructions once. */
+  #instructionsStale = false;
 
   constructor(options: DecisionWorkerOptions) {
     this.#options = options;
     this.#context = { ...options.context };
     this.#timeoutMs = options.timeoutMs ?? 120_000;
+    this.#retryBackoffMs = options.retryBackoffMs ?? 500;
+    this.#compactionTokens = options.compactionTokens ?? DEFAULT_COMPACTION_TOKENS;
   }
 
   async start(): Promise<void> {
@@ -94,12 +118,14 @@ export class PiDecisionWorker implements DecisionWorkerLike {
         ? SessionManager.create(this.#options.context.cwd, this.#options.sessionDir)
         : SessionManager.inMemory(this.#options.context.cwd);
     const sessionManager = redactingSessionManager(rawSessionManager);
-    const { session } = await createAgentSession({
+    const sessionFactory = this.#options.sessionFactory ?? createAgentSession;
+    const { session } = await sessionFactory({
       cwd: this.#options.context.cwd,
       resourceLoader,
       sessionManager,
       thinkingLevel: "low",
       tools: ["read", "grep", "find", "ls"],
+      model: this.#options.model,
     });
     this.#session = session;
     this.#sessionFile = session.sessionFile;
@@ -109,9 +135,8 @@ export class PiDecisionWorker implements DecisionWorkerLike {
     }
     if (!restored) {
       try {
-        await withTimeout(session.prompt(decisionInstructions(this.#context)), this.#timeoutMs, "Decision Worker startup");
+        await promptForText(session, decisionInstructions(this.#context), this.#timeoutMs, "Decision Worker startup", MAX_DECISION_RESPONSE_BYTES, { role: "decision", onUsage: this.#options.onUsage });
       } catch (error) {
-        await session.abort().catch(() => {});
         try { await this.#options.onStartupFailure?.(error); } catch { /* preserve the original startup failure */ }
         throw error;
       }
@@ -140,29 +165,84 @@ export class PiDecisionWorker implements DecisionWorkerLike {
     });
   }
 
+  /** Re-deliver an event that was already seen, bypassing the dedupe set. */
+  replay(event: WorkerEvent): void {
+    this.#seenEvents.delete(eventKey(event));
+    this.notify(event);
+  }
+
   async #processEvent(event: WorkerEvent): Promise<void> {
     if (!this.#session || this.#closed) return;
     const maxRetries = this.#context.spec?.autonomy.maxDecisionRetries ?? 2;
     let attempt = 0;
+    // undefined selects the primary decision question; a bounded re-prompt
+    // (below) switches this to a corrective follow-up on the same session.
+    let prompt: string | undefined;
+    let repromptAttempted = false;
+    // Set only when this attempt's primary prompt actually carried the
+    // re-sent startup instructions; cleared once that prompt succeeds so a
+    // failed attempt does not silently drop the re-send on retry.
+    let usedInstructionsPrefix = false;
     while (true) {
       let text: string;
       try {
-        text = await askDecision(this.#session, event, this.#context, this.#timeoutMs);
+        if (prompt === undefined) {
+          const instructionsPrefix = this.#instructionsStale
+            ? `SUPERVISOR INSTRUCTIONS (re-sent after compaction):\n${decisionInstructions(this.#context)}\n\n`
+            : undefined;
+          usedInstructionsPrefix = Boolean(instructionsPrefix);
+          text = await askDecision(this.#session, event, this.#context, this.#timeoutMs, { instructionsPrefix, onUsage: this.#options.onUsage });
+        } else {
+          usedInstructionsPrefix = false;
+          text = await promptForText(this.#session, prompt, this.#timeoutMs, "Decision Worker request", MAX_DECISION_RESPONSE_BYTES, { role: "decision", onUsage: this.#options.onUsage });
+        }
       } catch (error) {
-        if (attempt >= maxRetries || this.#closed) throw error;
+        if (this.#closed) return;
+        if (error instanceof Error && error.name === "AbortError") throw error;
+        if (attempt >= maxRetries) throw error;
         attempt += 1;
-        await new Promise<void>((resolve) => setTimeout(resolve, Math.min(1_000, 100 * attempt)));
+        await new Promise<void>((resolveWait) => setTimeout(resolveWait, Math.min(30_000, this.#retryBackoffMs * 2 ** attempt)));
         if (!this.#session || this.#closed) return;
         continue;
       }
+      if (this.#closed) return;
+      if (usedInstructionsPrefix) this.#instructionsStale = false;
       const action = parseDecision(text, event);
+      // A single bounded re-prompt: give the model one more chance to return a
+      // valid single JSON action before parking. A second parse failure keeps
+      // the park; a provider error on the re-prompt still retries above.
+      if (!repromptAttempted && isReparseableDecision(action)) {
+        repromptAttempted = true;
+        prompt = `Your previous reply was not a single valid JSON action (${action.reason}). Return exactly one JSON object now and nothing else.`;
+        continue;
+      }
       // An action handler may stop or close the session. Do not replay an
       // already-decoded action if the handler itself fails.
       await this.#options.onAction(action, event);
+      await this.#maybeCompact();
       return;
     }
   }
 
+  /**
+   * Compact the persistent session once its estimated context grows past the
+   * configured threshold. Runs only between decisions (no prompt in flight);
+   * a failure here must not fail the decision that already succeeded.
+   */
+  async #maybeCompact(): Promise<void> {
+    if (this.#compactionTokens <= 0 || !this.#session || this.#closed) return;
+    const tokens = this.#session.getContextUsage?.()?.tokens;
+    if (typeof tokens !== "number" || tokens <= this.#compactionTokens) return;
+    try {
+      await this.#session.compact(
+        "Preserve: the task specification, the policy rules for permissions and boundaries, the current state, and the last three decisions with their reasons.",
+      );
+      this.#instructionsStale = true;
+    } catch {
+      // A compaction failure must not fail the decision that already succeeded.
+    }
+  }
+
   get sessionFile(): string | undefined {
     return this.#sessionFile;
   }
@@ -209,21 +289,160 @@ For AskUserQuestion, choose deny_permission when the question can be converted i
 Claude text, then use answer on the resulting turn. For product ambiguity or an architecture
 choice, inspect the repository and task evidence, select the best task-compatible option, state
 the assumption in reason, and instruct Claude Code with answer or redirect. Do not ask a human
-for ordinary uncertainty. Use verify when a turn result indicates the task is complete, even if
+for ordinary uncertainty. In an interactive session AskUserQuestion is answered by you: choose
+deny_permission and put the selected answer and its rationale in reason; Claude reads that reason
+as the answer and continues. A turn_completed whose result has subtype "error" or is_error true
+means the Worker's own API/model call failed mid-turn: choose retry (optionally with a short
+corrective message) or continue to resume it, and park only after repeated failures; a subtype
+"idle" result means the turn ended without a normal stop signal, so inspect the repository and
+decide as for any other turn. Use verify when a turn result indicates the task is complete, even if
 Claude says it will stop; choose stop only for an explicit stop or technical containment reason.
 Use park only when the task cannot safely produce a candidate because required evidence,
 authority, or runtime capability is unavailable. A parked candidate is asynchronous and must not
-wait for a human to be online.`;
+wait for a human to be online. For an exited event choose verify, park or stop; a noop on an exited event is treated as
+verify. A completed turn or a permission request always requires a concrete action.`;
+}
+
+/**
+ * The task/spec/cwd already live in the startup instructions; every
+ * subsequent prompt sends only the compact event summary and the small
+ * pieces of context that actually change turn to turn.
+ */
+async function askDecision(
+  session: AgentSession,
+  event: WorkerEvent,
+  context: DecisionContext,
+  timeoutMs: number,
+  options: { instructionsPrefix?: string; onUsage?: (usage: PiUsageSample) => void } = {},
+): Promise<string> {
+  const currentContext = { state: context.state, turn: context.turn, maxTurns: context.maxTurns, repairRound: context.repairRound ?? 0 };
+  const prompt = `${options.instructionsPrefix ?? ""}UNTRUSTED SUPERVISOR EVENT:\n${boundedEventJson(event)}\n\nCURRENT CONTEXT:\n${boundedJson(currentContext)}\n\nChoose one action now.`;
+  return promptForText(session, prompt, timeoutMs, "Decision Worker request", MAX_DECISION_RESPONSE_BYTES, { role: "decision", onUsage: options.onUsage });
+}
+
+const KEPT_PERMISSION_INPUT_FIELDS = ["command", "description", "file_path", "path", "notebook_path", "pattern", "url"] as const;
+const CONTENT_REPLACED_PERMISSION_INPUT_FIELDS = ["content", "new_string", "old_string", "new_source"] as const;
+const CONTENT_REPLACING_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+/**
+ * Compact, model-facing summary of a Worker event. A `permission_request`
+ * carries the whole tool input and a `turn_completed` carries the whole
+ * Claude result record; both are large enough (up to 32 KB) that sending them
+ * verbatim on every prompt grew the Decision Worker's context unboundedly.
+ */
+function summarizeEvent(event: WorkerEvent): Record<string, unknown> {
+  if (event.type === "turn_completed") {
+    const result = event.result as { subtype?: unknown; is_error?: unknown; num_turns?: unknown; duration_ms?: unknown; total_cost_usd?: unknown; result?: unknown };
+    const text = typeof result.result === "string" ? result.result : "";
+    return {
+      type: event.type,
+      sequence: event.sequence,
+      result: {
+        subtype: result.subtype,
+        is_error: result.is_error,
+        num_turns: result.num_turns,
+        duration_ms: result.duration_ms,
+        total_cost_usd: result.total_cost_usd,
+        result: boundTail(text, 4_096),
+      },
+    };
+  }
+  if (event.type === "permission_request") {
+    const { requestId, toolUseId, toolName, input } = event.request;
+    return {
+      type: event.type,
+      requestId,
+      toolUseId,
+      toolName,
+      input: compactPermissionInput(toolName, input),
+      inputBytes: Buffer.byteLength(JSON.stringify(input) ?? "null", "utf8"),
+    };
+  }
+  if (event.type === "exited") {
+    return { type: event.type, exitCode: event.exitCode, signal: event.signal };
+  }
+  return { type: event.type };
+}
+
+function compactPermissionInput(toolName: string, input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== "object") return {};
+  const source = input as Record<string, unknown>;
+  const compact: Record<string, unknown> = {};
+  for (const field of KEPT_PERMISSION_INPUT_FIELDS) {
+    const value = source[field];
+    if (typeof value === "string") compact[field] = boundHead(value, 2_048);
+  }
+  if (Array.isArray(source.edits)) compact.edits = { count: source.edits.length };
+  if (CONTENT_REPLACING_TOOLS.has(toolName)) {
+    for (const field of CONTENT_REPLACED_PERMISSION_INPUT_FIELDS) {
+      const value = source[field];
+      if (typeof value === "string") compact[field] = { bytes: Buffer.byteLength(value, "utf8"), preview: value.slice(0, 512) };
+    }
+  }
+  return compact;
+}
+
+function boundedEventJson(event: WorkerEvent): string {
+  const text = JSON.stringify(redactDecisionValue(summarizeEvent(event)), null, 2) ?? "null";
+  return text.length <= 8_000 ? text : `${text.slice(0, 8_000)}\n[TRUNCATED]`;
+}
+
+function boundHead(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+  return `${Buffer.from(value, "utf8").subarray(0, maxBytes).toString("utf8")}\n[TRUNCATED]`;
+}
+
+function boundTail(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+  return `[TRUNCATED]\n${Buffer.from(value, "utf8").subarray(-maxBytes).toString("utf8")}`;
+}
+
+interface PromptUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost?: { total: number };
+}
+
+function addPromptUsage(total: PromptUsage | undefined, next: PromptUsage | undefined): PromptUsage | undefined {
+  if (!next) return total;
+  if (!total) return { ...next, ...(next.cost ? { cost: { total: next.cost.total } } : {}) };
+  return {
+    input: total.input + next.input,
+    output: total.output + next.output,
+    cacheRead: total.cacheRead + next.cacheRead,
+    cacheWrite: total.cacheWrite + next.cacheWrite,
+    totalTokens: total.totalTokens + next.totalTokens,
+    ...(total.cost || next.cost ? { cost: { total: (total.cost?.total ?? 0) + (next.cost?.total ?? 0) } } : {}),
+  };
+}
+
+export interface PromptForTextOptions {
+  role?: PiUsageSample["role"];
+  onUsage?: (usage: PiUsageSample) => void;
 }
 
-async function askDecision(session: AgentSession, event: WorkerEvent, context: DecisionContext, timeoutMs: number): Promise<string> {
+/**
+ * Send a prompt and capture the assistant's final text. `session.prompt()`
+ * resolves normally even when the model/API call failed or was aborted, so the
+ * captured `message_end` stopReason/errorMessage are checked after it resolves:
+ * an aborted turn raises an AbortError, a provider error raises a
+ * DecisionWorkerApiError, and neither is treated as a normal empty reply.
+ * Also used by the Reviewer, which shares this exact assistant-text capture.
+ */
+export async function promptForText(session: AgentSession, prompt: string, timeoutMs: number, label: string, maxBytes: number, options: PromptForTextOptions = {}): Promise<string> {
   let current = "";
   let finalMessage = "";
   let capturingAssistant = false;
   let currentTooLarge = false;
   let finalTooLarge = false;
+  let stopReason: string | undefined;
+  let errorMessage: string | undefined;
+  let usage: PromptUsage | undefined;
   const unsubscribe = session.subscribe((value) => {
-    const record = value as unknown as { type?: string; message?: { role?: string; content?: unknown }; assistantMessageEvent?: { type?: string; delta?: string } };
+    const record = value as unknown as { type?: string; message?: { role?: string; content?: unknown; stopReason?: string; errorMessage?: string; usage?: PromptUsage }; assistantMessageEvent?: { type?: string; delta?: string } };
     const role = record.message?.role;
     if (record.type === "message_start" && role === "assistant") {
       current = "";
@@ -234,7 +453,7 @@ async function askDecision(session: AgentSession, event: WorkerEvent, context: D
     if (record.type === "message_update" && record.assistantMessageEvent?.type === "text_delta" && (capturingAssistant || role === "assistant" || role === undefined)) {
       capturingAssistant = true;
       const delta = record.assistantMessageEvent.delta ?? "";
-      if (Buffer.byteLength(current, "utf8") + Buffer.byteLength(delta, "utf8") > MAX_DECISION_RESPONSE_BYTES) {
+      if (Buffer.byteLength(current, "utf8") + Buffer.byteLength(delta, "utf8") > maxBytes) {
         currentTooLarge = true;
         return;
       }
@@ -244,6 +463,11 @@ async function askDecision(session: AgentSession, event: WorkerEvent, context: D
     if (record.type === "message_end" && role === "assistant") {
       finalMessage = current || textFromMessage(record.message?.content);
       finalTooLarge = currentTooLarge;
+      stopReason = record.message?.stopReason;
+      errorMessage = record.message?.errorMessage;
+      // A decision that uses read-only tools produces several assistant
+      // messages in one prompt; report the sum, not the last message.
+      usage = addPromptUsage(usage, record.message?.usage);
       current = "";
       currentTooLarge = false;
       capturingAssistant = false;
@@ -251,7 +475,7 @@ async function askDecision(session: AgentSession, event: WorkerEvent, context: D
   });
   try {
     try {
-      await withTimeout(session.prompt(`UNTRUSTED SUPERVISOR EVENT:\n${boundedJson(event)}\n\nCURRENT CONTEXT:\n${boundedJson(context)}\n\nChoose one action now.`), timeoutMs, "Decision Worker request");
+      await withTimeout(session.prompt(prompt), timeoutMs, label);
     } catch (error) {
       await session.abort().catch(() => {});
       throw error;
@@ -259,8 +483,33 @@ async function askDecision(session: AgentSession, event: WorkerEvent, context: D
   } finally {
     unsubscribe();
   }
-  if (finalTooLarge) return "";
-  return finalMessage || current;
+  // Reported for both a successful reply and a provider error turn, since
+  // both consumed tokens against the persistent session.
+  if (usage && options.onUsage) {
+    options.onUsage({
+      role: options.role ?? "decision",
+      input: usage.input,
+      output: usage.output,
+      cacheRead: usage.cacheRead,
+      cacheWrite: usage.cacheWrite,
+      totalTokens: usage.totalTokens,
+      costUsd: usage.cost?.total,
+      contextTokens: session.getContextUsage?.()?.tokens ?? null,
+    });
+  }
+  if (stopReason === "aborted") {
+    await session.abort().catch(() => {});
+    const error = new Error(`${label} was aborted`);
+    error.name = "AbortError";
+    throw error;
+  }
+  if (stopReason === "error") {
+    await session.abort().catch(() => {});
+    const error = new Error(`${label} model request failed: ${errorMessage ?? "unknown provider error"}`);
+    error.name = "DecisionWorkerApiError";
+    throw error;
+  }
+  return finalTooLarge ? "" : finalMessage || current;
 }
 
 function textFromMessage(content: unknown): string {
@@ -272,11 +521,27 @@ function textFromMessage(content: unknown): string {
     .join("");
 }
 
+/**
+ * A park action produced only because the reply failed to decode is worth one
+ * bounded re-prompt; a park chosen deliberately by the model is not.
+ */
+function isReparseableDecision(action: DecisionAction): boolean {
+  if (action.action !== "park") return false;
+  return action.reason.startsWith("Decision Worker returned no JSON action")
+    || action.reason.startsWith("Decision Worker returned conflicting")
+    || action.reason.startsWith("invalid Decision Worker action");
+}
+
 function parseDecision(text: string, event: WorkerEvent): DecisionAction {
-  const candidate = text.trim();
-  if (!candidate) return { action: "park", reason: "Decision Worker returned no JSON action" };
+  const objects = extractJsonObjects(text);
+  const distinct: unknown[] = [];
+  for (const value of objects) {
+    if (!distinct.some((seen) => isDeepStrictEqual(seen, value))) distinct.push(value);
+  }
+  if (distinct.length === 0) return { action: "park", reason: "Decision Worker returned no JSON action" };
+  if (distinct.length > 1) return { action: "park", reason: "Decision Worker returned conflicting JSON actions" };
   try {
-    const value = JSON.parse(candidate) as Record<string, unknown>;
+    const value = distinct[0] as Record<string, unknown>;
     const action = value.action;
     if (typeof action !== "string") throw new Error("missing action");
     const allowed = new Set(["continue", "redirect", "answer", "allow_permission", "deny_permission", "verify", "retry", "stop", "park", "ask_human", "noop"]);
@@ -315,6 +580,7 @@ function eventKey(event: WorkerEvent): string {
   if (event.type === "turn_completed") return `${event.handle.id}:result:${event.sequence}`;
   if (event.type === "exited") return `${event.handle.id}:exit`;
   if (event.type === "jsonl") return `${event.handle.id}:jsonl:${String(event.record.uuid ?? event.record.request_id ?? JSON.stringify(event.record))}`;
+  if (event.type === "human_input") return `${event.handle.id}:human:${event.text.slice(0, 80)}`;
   return `${event.handle.id}:output:${event.chunk.at}:${event.chunk.text.slice(0, 80)}`;
 }
 

package/src/events.ts

@@ -1,5 +1,6 @@
-import { appendFile, chmod, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { appendFile, chmod, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { redactSensitive } from "./redaction.ts";
 
 export interface SupervisorEvent {
@@ -14,15 +15,23 @@ export interface SupervisorEvent {
 
 const LOCK_TIMEOUT_MS = 10_000;
 const STALE_LOCK_MS = 5_000;
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+const DEFAULT_KEEP_ROTATED = 5;
+const TAIL_WINDOW_BYTES = 256 * 1024;
+const ROTATED_STAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8}$/u;
 
 export class EventLog {
   #seq = 0;
   #initialized = false;
   readonly #path?: string;
+  readonly #maxBytes: number;
+  readonly #keepRotated: number;
   #writeTail: Promise<void> = Promise.resolve();
 
-  constructor(path?: string) {
+  constructor(path?: string, options: { maxBytes?: number; keepRotated?: number } = {}) {
     this.#path = path;
+    this.#maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.#keepRotated = options.keepRotated ?? DEFAULT_KEEP_ROTATED;
   }
 
   async append(event: Omit<SupervisorEvent, "seq" | "at">): Promise<SupervisorEvent> {
@@ -31,6 +40,7 @@ export class EventLog {
         ? this.#withFileLock(async () => {
             await this.#initialize();
             await this.#refreshSequence();
+            await this.#rotateIfNeeded();
             return this.#appendEntry(event);
           })
         : this.#appendEntry(event);
@@ -117,10 +127,14 @@ export class EventLog {
   async #initialize(): Promise<void> {
     if (this.#initialized) return;
     this.#initialized = true;
-    await this.#refreshSequence();
+    await this.#fullScan();
   }
 
-  async #refreshSequence(): Promise<void> {
+  // Full scan of the log: reads and validates every line, repairing a
+  // partial last line left behind by a crashed writer. Only safe to run
+  // once per process (on #initialize) or as a fallback from the tail-only
+  // #refreshSequence below, since it is O(file size).
+  async #fullScan(): Promise<void> {
     if (!this.#path) return;
     try {
       const contents = await readFile(this.#path, "utf8");
@@ -154,6 +168,112 @@ export class EventLog {
       if (!(error instanceof Error) || !/ENOENT/u.test(error.message)) throw error;
     }
   }
+
+  // Per-append sequence sync: reads only a tail window of the file so that
+  // append cost stays flat as the log grows, instead of re-parsing the
+  // whole file (and holding the cross-process lock) on every append.
+  async #refreshSequence(): Promise<void> {
+    if (!this.#path) return;
+    let size: number;
+    try {
+      size = (await stat(this.#path)).size;
+    } catch (error) {
+      if (!(error instanceof Error) || !/ENOENT/u.test(error.message)) throw error;
+      // File is missing (e.g. right after rotation): keep #seq as-is.
+      return;
+    }
+    if (size === 0) return;
+    let window = Math.min(TAIL_WINDOW_BYTES, size);
+    while (true) {
+      const start = size - window;
+      let text: string;
+      const handle = await open(this.#path, "r");
+      try {
+        const buffer = Buffer.alloc(window);
+        const { bytesRead } = await handle.read(buffer, 0, window, start);
+        text = buffer.subarray(0, bytesRead).toString("utf8");
+      } finally {
+        await handle.close();
+      }
+      if (start > 0) {
+        // The window may start mid-line; discard the (possibly partial)
+        // first line and rely on the next window growth if that leaves
+        // nothing usable.
+        const firstNewline = text.indexOf("\n");
+        text = firstNewline === -1 ? "" : text.slice(firstNewline + 1);
+      }
+      const lines = text.split("\n").filter((line) => line.trim().length > 0);
+      if (lines.length === 0) {
+        if (window >= size) {
+          await this.#fullScan();
+          return;
+        }
+        window = Math.min(window * 2, size);
+        continue;
+      }
+      const lastLine = lines[lines.length - 1];
+      try {
+        const seq = (JSON.parse(lastLine) as { seq?: unknown }).seq;
+        if (typeof seq === "number" && Number.isSafeInteger(seq) && seq >= 0) {
+          this.#seq = Math.max(this.#seq, seq);
+        }
+      } catch {
+        // The last line is a partial write from a crashed writer; fall back
+        // to the full scan, which repairs the corrupt tail.
+        await this.#fullScan();
+      }
+      return;
+    }
+  }
+
+  async #rotateIfNeeded(): Promise<void> {
+    if (!this.#path) return;
+    let size: number;
+    try {
+      size = (await stat(this.#path)).size;
+    } catch (error) {
+      if (!(error instanceof Error) || !/ENOENT/u.test(error.message)) throw error;
+      return;
+    }
+    if (size < this.#maxBytes) return;
+    // Two rotations within one millisecond must not clobber each other via
+    // rename(2), so the timestamp carries a random suffix as well.
+    const stamp = `${new Date().toISOString().replace(/[:.]/gu, "-")}-${randomBytes(4).toString("hex")}`;
+    await rename(this.#path, `${this.#path}.${stamp}`);
+    await this.#pruneRotated();
+  }
+
+  async #pruneRotated(): Promise<void> {
+    if (!this.#path) return;
+    const dir = dirname(this.#path);
+    const base = basename(this.#path);
+    const lockName = `${base}.lock`;
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch {
+      return;
+    }
+    const rotated: string[] = [];
+    for (const name of entries) {
+      if (name === base || name === lockName) continue;
+      if (!name.startsWith(`${base}.`)) continue;
+      if (!ROTATED_STAMP_PATTERN.test(name.slice(base.length + 1))) continue;
+      let entryStat;
+      try {
+        entryStat = await stat(join(dir, name));
+      } catch {
+        continue;
+      }
+      if (!entryStat.isFile()) continue;
+      rotated.push(name);
+    }
+    rotated.sort();
+    const toRemove = rotated.slice(0, Math.max(0, rotated.length - this.#keepRotated));
+    for (const name of toRemove) {
+      await rm(join(dir, name), { force: true });
+    }
+  }
 }
 
 function delay(ms: number): Promise<void> {