@oh-my-pi/pi-coding-agent 15.8.2 → 15.9.0

package/src/prompts/tools/browser.md

@@ -25,7 +25,7 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
   - `tab.waitForUrl(pattern, { timeout? })` — pattern is a substring or `RegExp`. Polls `location.href` so it works for SPA pushState navigations, not just real navigations. Returns the matched URL.
   - `tab.waitForResponse(pattern, { timeout? })` — pattern is a substring, `RegExp`, or `(response) => boolean`. Returns the raw puppeteer `HTTPResponse` (call `.text()` / `.json()` / `.status()` / `.headers()` on it).
   - `tab.evaluate(fn, …args)` — sugar for `page.evaluate` with the abort signal already wired. Use this instead of dropping to `page.evaluate` for ad-hoc DOM reads.
-  - `tab.screenshot({ selector?, fullPage?, save?, silent? })` — auto-attaches the image to the tool output unless `silent: true`. Saves full-res to `save` (or `browser.screenshotDir` setting) and a downscaled copy to the model.
+  - `tab.screenshot({ selector?, fullPage?, save?, silent? })` — captures a screenshot and **auto-attaches it to the tool output for you to view** (unless `silent: true`). `save` is **strictly optional**: OMIT it when you just want to look at the page — the downscaled image is shown to you regardless, and the full-res capture is written to a temp file automatically. Pass `save` (a path) ONLY when you deliberately need to keep a full-res copy on disk for later use; `browser.screenshotDir` does the same for every shot. Do NOT invent a `save` path for a throwaway/temporal screenshot.
   - `tab.extract(format = "markdown")` — Readability-extracted page content.
 - Selectors accept CSS as well as puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`. Playwright-style `p-aria/[name="…"]`, `p-text/…`, etc. are normalized.
 - Default to `tab.observe()` over `tab.screenshot()` for understanding page state. Screenshot only when visual appearance matters.
@@ -46,7 +46,10 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
 # Click an observed element by id
 `{"action":"run","name":"docs","code":"const obs = await tab.observe(); const link = obs.elements.find(e => e.role === 'link' && e.name === 'Sign in'); assert(link, 'Sign in link missing'); await (await tab.id(link.id)).click();"}`
 
-# Save a full-page screenshot to disk
+# Take a transient screenshot just to look at the page — NO save path needed; the image is shown to you
+`{"action":"run","name":"docs","code":"await tab.screenshot();"}`
+
+# Persist a full-page screenshot to disk (only when you deliberately need to keep the file)
 `{"action":"run","name":"docs","code":"await tab.screenshot({ fullPage: true, save: 'screenshot.png' });"}`
 
 # Fill and submit a form via selectors

package/src/prompts/tools/search.md

@@ -2,7 +2,7 @@ Searches files using powerful regex matching.
 
 <instruction>
 - Supports Rust regex syntax (RE2-style — no lookaround or backreferences). Use line anchors or post-filters instead of (?!…)/(?<!…)
-- `paths` is required and accepts either one string or an array of files, directories, globs, or internal URLs
+- `paths` accepts either one string or an array of files, directories, globs, or internal URLs. Optional: when omitted or empty it searches the workspace root (`.`). Prefer scoping to specific paths when you know them.
 - For multiple targets, pass an array with one target per element: `["src", "tests"]`.
 - Cross-line patterns are detected from literal `\n` or escaped `\\n` in `pattern`
 </instruction>

package/src/prompts/tools/task.md

@@ -38,6 +38,8 @@ Subagents have no conversation history. Every fact, file path, and direction the
 - Pass large payloads via `local://<path>` URIs, not inline. {{#if contextEnabled}} (other than the context){{/if}}
 {{#if contextEnabled}}- Put shared constraints in `context` once; do not duplicate across assignments.{{/if}}
 - Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.
+- **Read-only agents**: Agents tagged READ-ONLY (e.g. `explore`) have no edit/write/command tools. NEVER hand them an assignment that requires changing files or running commands — they cannot do it and the turn is wasted. Use them to investigate and report back; do the edits yourself or delegate to a writing agent (`task`, `oracle`, `designer`).
+- **No reasoning offload**: NEVER offload reasoning, analysis, design, or decision-making to `quick_task` or `explore` — they run minimal-effort / small models for mechanical lookups and data collection only. Keep judgment and synthesis in your own context; delegate hard thinking to `task`, `plan`, or `oracle`.
 </rules>
 
 <parallelization>
@@ -71,7 +73,7 @@ Parallel when tasks touch disjoint files or are independent refactors/tests.
 Agent spawning is disabled for this context.
 {{else}}
 {{#list agents join="\n"}}
-# {{name}}
+# {{name}}{{#if readOnly}} — READ-ONLY (no edit/write/exec tools){{/if}}
 {{description}}
 {{/list}}
 {{/if}}

package/src/prompts/tools/{todo-write.md → todo.md}

@@ -48,3 +48,11 @@ Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, an
 # Append tasks to a phase
 `{"ops":[{"op":"append","phase":"Auth","items":["Handle retries","Run tests"]}]}`
 </examples>
+
+<critical>
+When the user hands you a multi-step plan — a phased todo, a numbered or bulleted checklist, or "N bugs/items/tasks" to work through:
+- You MUST `init` the list with EVERY item as its own task before doing the work.
+- Enumerate all of them;
+- NEVER summarize the plan into fewer tasks, sample "the important ones", drop items, or rely on memory to track the rest.
+The entire point is to remember every one.
+</critical>

package/src/sdk.ts

@@ -1259,6 +1259,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getModelString: () => (hasExplicitModel && model ? formatModelString(model) : undefined),
 			getActiveModelString,
 			getPlanModeState: () => session?.getPlanModeState(),
+			getPlanReferencePath: () => session?.getPlanReferencePath() ?? "local://PLAN.md",
 			getGoalModeState: () => session?.getGoalModeState(),
 			getGoalRuntime: () => session?.goalRuntime,
 			getUsageStatistics: () => sessionManager.getUsageStatistics(),

package/src/session/agent-session.ts

@@ -55,6 +55,7 @@ import {
 	shouldCompact,
 } from "@oh-my-pi/pi-agent-core/compaction";
 import { DEFAULT_PRUNE_CONFIG, pruneToolOutputs } from "@oh-my-pi/pi-agent-core/compaction/pruning";
+import type { ProtectedToolMatcher } from "@oh-my-pi/pi-agent-core/compaction/tool-protection";
 import type {
 	AssistantMessage,
 	Context,
@@ -163,6 +164,7 @@ import { parseTurnBudget } from "../modes/turn-budget";
 import { containsUltrathink, ULTRATHINK_NOTICE } from "../modes/ultrathink";
 import { computeNonMessageTokens } from "../modes/utils/context-usage";
 import { containsWorkflow, WORKFLOW_NOTICE } from "../modes/workflow";
+import { createPlanReadMatcher } from "../plan-mode/plan-protection";
 import type { PlanModeState } from "../plan-mode/state";
 import autoContinuePrompt from "../prompts/system/auto-continue.md" with { type: "text" };
 import eagerTodoPrompt from "../prompts/system/eager-todo.md" with { type: "text" };
@@ -201,7 +203,7 @@ import type { CheckpointState } from "../tools/checkpoint";
 import { outputMeta } from "../tools/output-meta";
 import { normalizeLocalScheme, resolveToCwd } from "../tools/path-utils";
 import { isAutoQaEnabled } from "../tools/report-tool-issue";
-import { getLatestTodoPhasesFromEntries, type TodoItem, type TodoPhase } from "../tools/todo-write";
+import { getLatestTodoPhasesFromEntries, type TodoItem, type TodoPhase } from "../tools/todo";
 import { ToolAbortError, ToolError } from "../tools/tool-errors";
 import { clampTimeout } from "../tools/tool-timeouts";
 import { parseCommandArgs } from "../utils/command-args";
@@ -1805,21 +1807,21 @@ export class AgentSession {
 				if (toolName === "edit" && details?.path) {
 					this.#invalidateFileCacheForPath(details.path);
 				}
-				if (toolName === "todo_write" && !isError && Array.isArray(details?.phases)) {
+				if (toolName === "todo" && !isError && Array.isArray(details?.phases)) {
 					this.setTodoPhases(details.phases);
 				}
-				if (toolName === "todo_write" && isError) {
+				if (toolName === "todo" && isError) {
 					const errorText = content?.find(part => part.type === "text")?.text;
 					const reminderText = [
 						"<system-reminder>",
-						"todo_write failed, so todo progress is not visible to the user.",
-						errorText ? `Failure: ${errorText}` : "Failure: todo_write returned an error.",
-						"Fix the todo payload and call todo_write again before continuing.",
+						"todo failed, so todo progress is not visible to the user.",
+						errorText ? `Failure: ${errorText}` : "Failure: todo returned an error.",
+						"Fix the todo payload and call todo again before continuing.",
 						"</system-reminder>",
 					].join("\n");
 					await this.sendCustomMessage(
 						{
-							customType: "todo-write-error-reminder",
+							customType: "todo-error-reminder",
 							content: reminderText,
 							display: false,
 							details: { toolName, errorText },
@@ -4992,7 +4994,7 @@ export class AgentSession {
 	// splice mutated canonical `#todoPhases` between tool calls, so the model
 	// observed phase totals shrinking ("5 → 4") after marking tasks done. The
 	// `tasks.todoClearDelay` setting is now inert; completed tasks survive
-	// until the next explicit `todo_write` call removes them via `rm`/`drop`.
+	// until the next explicit `todo` call removes them via `rm`/`drop`.
 
 	/**
 	 * Abort current operation and wait for agent to become idle.
@@ -5658,9 +5660,20 @@ export class AgentSession {
 	// Compaction
 	// =========================================================================
 
+	/**
+	 * Append plan-read protection to a prune/shake config so the active plan
+	 * file survives compaction alongside skill reads (the config defaults
+	 * already carry skill protection). The matcher reads the current plan
+	 * reference path at match time, so retitled plans are covered.
+	 */
+	#withPlanProtection<T extends { protectedTools: ProtectedToolMatcher[] }>(config: T): T {
+		const planMatcher = createPlanReadMatcher(() => this.#planReferencePath);
+		return { ...config, protectedTools: [...config.protectedTools, planMatcher] };
+	}
+
 	async #pruneToolOutputs(): Promise<{ prunedCount: number; tokensSaved: number } | undefined> {
 		const branchEntries = this.sessionManager.getBranch();
-		const result = pruneToolOutputs(branchEntries, DEFAULT_PRUNE_CONFIG);
+		const result = pruneToolOutputs(branchEntries, this.#withPlanProtection(DEFAULT_PRUNE_CONFIG));
 		if (result.prunedCount === 0) {
 			return undefined;
 		}
@@ -5741,7 +5754,7 @@ export class AgentSession {
 			return { mode, toolResultsDropped: 0, blocksDropped: 0, imagesDropped: removed, tokensFreed: 0 };
 		}
 
-		const config = opts.config ?? AGGRESSIVE_SHAKE_CONFIG;
+		const config = this.#withPlanProtection(opts.config ?? AGGRESSIVE_SHAKE_CONFIG);
 		const regions = collectShakeRegions(this.sessionManager.getBranch(), config);
 		if (regions.length === 0) {
 			return { mode, toolResultsDropped: 0, blocksDropped: 0, tokensFreed: 0 };
@@ -6540,16 +6553,16 @@ export class AgentSession {
 			return undefined;
 		}
 
-		if (!this.#toolRegistry.has("todo_write")) {
-			logger.warn("Eager todo enforcement skipped because todo_write is unavailable", {
+		if (!this.#toolRegistry.has("todo")) {
+			logger.warn("Eager todo enforcement skipped because todo is unavailable", {
 				activeToolNames: this.agent.state.tools.map(tool => tool.name),
 			});
 			return undefined;
 		}
 
-		const todoWriteToolChoice = buildNamedToolChoice("todo_write", this.model);
-		if (!todoWriteToolChoice) {
-			logger.warn("Eager todo enforcement skipped because the current model does not support forcing todo_write", {
+		const todoToolChoice = buildNamedToolChoice("todo", this.model);
+		if (!todoToolChoice) {
+			logger.warn("Eager todo enforcement skipped because the current model does not support forcing todo", {
 				modelApi: this.model?.api,
 				modelId: this.model?.id,
 			});
@@ -6567,7 +6580,7 @@ export class AgentSession {
 				attribution: "agent",
 				timestamp: Date.now(),
 			},
-			toolChoice: todoWriteToolChoice,
+			toolChoice: todoToolChoice,
 		};
 	}
 	/**

package/src/session/indexed-session-storage.ts

@@ -0,0 +1,430 @@
+import { toError } from "@oh-my-pi/pi-utils";
+import type { SessionStorage, SessionStorageStat, SessionStorageWriter } from "./session-storage";
+
+export interface SessionStorageIndexEntry {
+	path: string;
+	size: number;
+	mtimeMs: number;
+}
+
+export interface SessionStorageBackend {
+	init(): Promise<void>;
+	loadIndex(): Promise<Iterable<SessionStorageIndexEntry>>;
+	readFull(path: string): Promise<string | null>;
+	readSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
+	writeFull(path: string, content: string, mtimeMs: number): Promise<void>;
+	append(path: string, line: string, mtimeMs: number): Promise<void>;
+	truncate(path: string, mtimeMs: number): Promise<void>;
+	remove(paths: string[]): Promise<void>;
+	move(src: string, dst: string, mtimeMs: number): Promise<void>;
+}
+
+interface IndexEntry {
+	size: number;
+	mtimeMs: number;
+}
+
+interface EnqueueOptions {
+	trackDrain: boolean;
+}
+
+const RESOLVED = Promise.resolve();
+
+function enoent(p: string): NodeJS.ErrnoException {
+	const err = new Error(`ENOENT: no such file, '${p}'`) as NodeJS.ErrnoException;
+	err.code = "ENOENT";
+	err.errno = -2;
+	err.path = p;
+	err.syscall = "open";
+	return err;
+}
+
+function matchesGlob(name: string, pattern: string): boolean {
+	if (pattern === "*") return true;
+	if (pattern.startsWith("*.")) return name.endsWith(pattern.slice(1));
+	return name === pattern;
+}
+
+function byteLength(text: string): number {
+	return Buffer.byteLength(text, "utf-8");
+}
+
+function normalizeByteLimit(maxBytes: number): number {
+	if (!(maxBytes > 0)) return 0;
+	return Math.trunc(maxBytes);
+}
+
+function uniquePaths(paths: readonly string[]): string[] {
+	const out: string[] = [];
+	const seen = new Set<string>();
+	for (const path of paths) {
+		if (seen.has(path)) continue;
+		seen.add(path);
+		out.push(path);
+	}
+	return out;
+}
+
+export class IndexedSessionStorage implements SessionStorage {
+	readonly #backend: SessionStorageBackend;
+	readonly #index = new Map<string, IndexEntry>();
+	readonly #writers = new Set<IndexedSessionStorageWriter>();
+	readonly #pathTails = new Map<string, Promise<void>>();
+	readonly #pathPending = new Map<string, Promise<void>>();
+	readonly #drainPending = new Set<Promise<void>>();
+	#nextMtimeMs = 0;
+	#firstDrainError: Error | undefined;
+
+	constructor(backend: SessionStorageBackend) {
+		this.#backend = backend;
+	}
+
+	async initialize(): Promise<void> {
+		await this.#backend.init();
+		await this.refresh();
+	}
+
+	async refresh(): Promise<void> {
+		await this.drain();
+		const rows = await this.#backend.loadIndex();
+		this.#index.clear();
+		for (const row of rows) {
+			this.#setIndex(row.path, row.size, row.mtimeMs);
+		}
+	}
+
+	async drain(): Promise<void> {
+		while (this.#drainPending.size > 0) {
+			await Promise.allSettled(this.#drainPending);
+		}
+		const error = this.#firstDrainError;
+		this.#firstDrainError = undefined;
+		if (error) throw error;
+	}
+
+	ensureDirSync(_dir: string): void {
+		// Indexed backends are flat: directories are derived from key prefixes.
+	}
+
+	existsSync(path: string): boolean {
+		return this.#index.has(path);
+	}
+
+	writeTextSync(path: string, content: string): void {
+		const mtimeMs = this.#allocMtimeMs();
+		this.#setIndex(path, byteLength(content), mtimeMs);
+		this.#enqueuePath(path, () => this.#backend.writeFull(path, content, mtimeMs), { trackDrain: true });
+	}
+
+	statSync(path: string): SessionStorageStat {
+		const entry = this.#index.get(path);
+		if (!entry) throw enoent(path);
+		return {
+			size: entry.size,
+			mtimeMs: entry.mtimeMs,
+			mtime: new Date(entry.mtimeMs),
+		};
+	}
+
+	listFilesSync(dir: string, pattern: string): string[] {
+		const prefix = dir.endsWith("/") ? dir : `${dir}/`;
+		const out: string[] = [];
+		for (const path of this.#index.keys()) {
+			if (!path.startsWith(prefix)) continue;
+			const name = path.slice(prefix.length);
+			if (name.includes("/") || name.includes("\\")) continue;
+			if (!matchesGlob(name, pattern)) continue;
+			out.push(path);
+		}
+		return out;
+	}
+
+	exists(path: string): Promise<boolean> {
+		return Promise.resolve(this.existsSync(path));
+	}
+
+	async readText(path: string): Promise<string> {
+		if (!this.#index.has(path)) throw enoent(path);
+		await this.#awaitPath(path);
+		const content = await this.#backend.readFull(path);
+		if (content === null) throw enoent(path);
+		return content;
+	}
+
+	async readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]> {
+		if (!this.#index.has(path)) throw enoent(path);
+		const prefixLimit = normalizeByteLimit(prefixBytes);
+		const suffixLimit = normalizeByteLimit(suffixBytes);
+		if (prefixLimit === 0 && suffixLimit === 0) return ["", ""];
+		await this.#awaitPath(path);
+		return this.#backend.readSlices(path, prefixLimit, suffixLimit);
+	}
+
+	async writeText(path: string, content: string): Promise<void> {
+		await this.#awaitPath(path);
+		const previous = this.#index.get(path);
+		const mtimeMs = this.#allocMtimeMs();
+		this.#setIndex(path, byteLength(content), mtimeMs);
+		try {
+			await this.#enqueuePath(path, () => this.#backend.writeFull(path, content, mtimeMs), { trackDrain: false });
+		} catch (err) {
+			this.#restoreIndex(path, previous);
+			throw toError(err);
+		}
+	}
+
+	async rename(src: string, dst: string): Promise<void> {
+		await this.#awaitPath(src);
+		await this.#awaitPath(dst);
+		const entry = this.#index.get(src);
+		if (!entry) throw enoent(src);
+		const dstPrevious = this.#index.get(dst);
+		this.#index.delete(src);
+		this.#index.set(dst, { ...entry });
+		try {
+			await this.#enqueuePaths([src, dst], () => this.#backend.move(src, dst, entry.mtimeMs), { trackDrain: false });
+		} catch (err) {
+			this.#index.delete(dst);
+			this.#restoreIndex(dst, dstPrevious);
+			this.#index.set(src, entry);
+			throw toError(err);
+		}
+	}
+
+	async unlink(path: string): Promise<void> {
+		await this.#awaitPath(path);
+		const previous = this.#index.get(path);
+		if (!previous) throw enoent(path);
+		this.#index.delete(path);
+		try {
+			await this.#enqueuePath(path, () => this.#backend.remove([path]), { trackDrain: false });
+		} catch (err) {
+			this.#index.set(path, previous);
+			throw toError(err);
+		}
+	}
+
+	async deleteSessionWithArtifacts(sessionPath: string): Promise<void> {
+		await this.#awaitPath(sessionPath);
+		const sessionEntry = this.#index.get(sessionPath);
+		if (!sessionEntry) throw enoent(sessionPath);
+
+		const artifactsDir = sessionPath.slice(0, -6);
+		const prefix = artifactsDir.endsWith("/") ? artifactsDir : `${artifactsDir}/`;
+		const paths = [sessionPath];
+		for (const key of this.#index.keys()) {
+			if (key.startsWith(prefix)) paths.push(key);
+		}
+
+		for (const path of paths) await this.#awaitPath(path);
+
+		const previous = new Map<string, IndexEntry>();
+		for (const path of paths) {
+			const entry = this.#index.get(path);
+			if (entry) previous.set(path, entry);
+			this.#index.delete(path);
+		}
+
+		try {
+			await this.#enqueuePaths(paths, () => this.#backend.remove(paths), { trackDrain: false });
+		} catch (err) {
+			for (const [path, entry] of previous) this.#index.set(path, entry);
+			throw toError(err);
+		}
+	}
+
+	openWriter(path: string, options?: { flags?: "a" | "w"; onError?: (err: Error) => void }): SessionStorageWriter {
+		const writer = new IndexedSessionStorageWriter(this, path, options);
+		this.#writers.add(writer);
+		return writer;
+	}
+
+	_writerClosed(writer: IndexedSessionStorageWriter): void {
+		this.#writers.delete(writer);
+	}
+
+	_truncateForWriter(path: string): number {
+		const mtimeMs = this.#allocMtimeMs();
+		this.#setIndex(path, 0, mtimeMs);
+		return mtimeMs;
+	}
+
+	_queueTruncate(path: string, mtimeMs: number, getError?: () => Error | undefined): Promise<void> {
+		return this.#enqueuePath(
+			path,
+			async () => {
+				const error = getError?.();
+				if (error) throw error;
+				await this.#backend.truncate(path, mtimeMs);
+			},
+			{ trackDrain: true },
+		);
+	}
+
+	_appendForWriter(path: string, line: string): number {
+		const mtimeMs = this.#allocMtimeMs();
+		const existing = this.#index.get(path);
+		const size = (existing?.size ?? 0) + byteLength(line);
+		this.#setIndex(path, size, mtimeMs);
+		return mtimeMs;
+	}
+
+	_queueAppend(path: string, line: string, mtimeMs: number, getError?: () => Error | undefined): Promise<void> {
+		return this.#enqueuePath(
+			path,
+			async () => {
+				const error = getError?.();
+				if (error) throw error;
+				await this.#backend.append(path, line, mtimeMs);
+			},
+			{ trackDrain: true },
+		);
+	}
+
+	#restoreIndex(path: string, entry: IndexEntry | undefined): void {
+		if (entry) {
+			this.#index.set(path, entry);
+		} else {
+			this.#index.delete(path);
+		}
+	}
+
+	#setIndex(path: string, size: number, mtimeMs: number): void {
+		this.#index.set(path, { size, mtimeMs });
+		if (mtimeMs > this.#nextMtimeMs) this.#nextMtimeMs = mtimeMs;
+	}
+
+	#allocMtimeMs(): number {
+		const now = Date.now();
+		const next = now > this.#nextMtimeMs ? now : this.#nextMtimeMs + 1;
+		this.#nextMtimeMs = next;
+		return next;
+	}
+
+	#enqueuePath(path: string, task: () => Promise<void>, options: EnqueueOptions): Promise<void> {
+		return this.#enqueuePaths([path], task, options);
+	}
+
+	#enqueuePaths(paths: readonly string[], task: () => Promise<void>, options: EnqueueOptions): Promise<void> {
+		const unique = uniquePaths(paths);
+		const previous = unique.map(path => this.#pathTails.get(path) ?? RESOLVED);
+		const operation = Promise.all(previous).then(task);
+		const tracked = operation.catch(err => {
+			const error = toError(err);
+			if (options.trackDrain && !this.#firstDrainError) this.#firstDrainError = error;
+			throw error;
+		});
+		const tail = tracked.catch(() => {});
+		for (const path of unique) {
+			this.#pathTails.set(path, tail);
+			this.#pathPending.set(path, tracked);
+		}
+		tail.finally(() => {
+			for (const path of unique) {
+				if (this.#pathTails.get(path) === tail) this.#pathTails.delete(path);
+			}
+		});
+		tracked
+			.finally(() => {
+				for (const path of unique) {
+					if (this.#pathPending.get(path) === tracked) this.#pathPending.delete(path);
+				}
+			})
+			.catch(() => {});
+		tracked.catch(() => {});
+		if (options.trackDrain) {
+			this.#drainPending.add(tracked);
+			tracked
+				.finally(() => {
+					this.#drainPending.delete(tracked);
+				})
+				.catch(() => {});
+		}
+		return tracked;
+	}
+
+	#awaitPath(path: string): Promise<void> {
+		return this.#pathPending.get(path) ?? RESOLVED;
+	}
+}
+
+class IndexedSessionStorageWriter implements SessionStorageWriter {
+	#storage: IndexedSessionStorage;
+	#path: string;
+	#closed = false;
+	#error: Error | undefined;
+	#onError: ((err: Error) => void) | undefined;
+	#pendingChain: Promise<void> = Promise.resolve();
+
+	constructor(
+		storage: IndexedSessionStorage,
+		path: string,
+		options?: { flags?: "a" | "w"; onError?: (err: Error) => void },
+	) {
+		this.#storage = storage;
+		this.#path = path;
+		this.#onError = options?.onError;
+		if ((options?.flags ?? "a") === "w") {
+			const mtimeMs = storage._truncateForWriter(path);
+			this.#trackPromise(storage._queueTruncate(path, mtimeMs, () => this.#error));
+		}
+	}
+
+	#recordError(err: unknown): Error {
+		const error = toError(err);
+		if (!this.#error) this.#error = error;
+		this.#onError?.(error);
+		return error;
+	}
+
+	#trackPromise(promise: Promise<void>): Promise<void> {
+		const next = this.#pendingChain.then(async () => {
+			if (this.#error) throw this.#error;
+			try {
+				await promise;
+			} catch (err) {
+				throw this.#recordError(err);
+			}
+		});
+		this.#pendingChain = next.catch(() => {});
+		return next;
+	}
+
+	writeLineSync(line: string): void {
+		if (this.#closed) throw new Error("Writer closed");
+		if (this.#error) throw this.#error;
+		const mtimeMs = this.#storage._appendForWriter(this.#path, line);
+		this.#trackPromise(this.#storage._queueAppend(this.#path, line, mtimeMs, () => this.#error));
+	}
+
+	async writeLine(line: string): Promise<void> {
+		if (this.#closed) throw new Error("Writer closed");
+		if (this.#error) throw this.#error;
+		const mtimeMs = this.#storage._appendForWriter(this.#path, line);
+		await this.#trackPromise(this.#storage._queueAppend(this.#path, line, mtimeMs, () => this.#error));
+	}
+
+	async flush(): Promise<void> {
+		if (this.#error) throw this.#error;
+		await this.#pendingChain;
+		if (this.#error) throw this.#error;
+	}
+
+	async fsync(): Promise<void> {
+		await this.flush();
+	}
+
+	async close(): Promise<void> {
+		if (this.#closed) return;
+		this.#closed = true;
+		try {
+			await this.flush();
+		} finally {
+			this.#storage._writerClosed(this);
+		}
+	}
+
+	getError(): Error | undefined {
+		return this.#error;
+	}
+}