@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/engine/session.ts

@@ -0,0 +1,834 @@
+/**
+ * Clio session JSONL writer + reader (Phase 3 slice 1).
+ *
+ * On-disk layout under `clioStateDir()`:
+ *   sessions/<cwdHash>/<sessionId>/
+ *     meta.json      ClioSessionMeta
+ *     current.jsonl  append-only structured session entries
+ *     tree.json      [{id, parentId, at, kind}, ...]
+ *
+ * Atomicity:
+ *   - Appends go to an O_APPEND fd held for the writer's lifetime; each line
+ *     is one write(2). fsync is debounced after appends and forced on
+ *     checkpoint (`persistTree`) and `close`. A torn last line from a crash
+ *     is tolerated by the reader (skipped with a warning).
+ *   - `replaceEntries` rewrites current.jsonl via `writeJsonlFileAtomic`
+ *     (`.tmp` + fsync + rename) and reopens the append fd afterwards.
+ *   - tree.json and meta.json are written via `atomicWrite` (tmp + fsync + rename).
+ *
+ * This module sits in `src/engine/` because it is the engine's artifact
+ * contract with the session domain, but it imports no pi-mono packages.
+ * It is pure node: fs, path, crypto.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import {
+	closeSync,
+	existsSync,
+	constants as fsConstants,
+	fstatSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readdirSync,
+	readFileSync,
+	readSync,
+	renameSync,
+	statSync,
+	writeSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { readClioVersion, readPiMonoVersion } from "../core/package-root.js";
+import { assertSafeId } from "../core/safe-id.js";
+import { fsyncDirectory, safeResourceWrite } from "../core/safe-resource-write.js";
+import { clioStateDir, stateRootRemoved } from "../core/xdg.js";
+
+export interface ClioSessionMeta {
+	id: string;
+	cwd: string;
+	cwdHash: string;
+	createdAt: string;
+	endedAt: string | null;
+	model: string | null;
+	target: string | null;
+	clioVersion: string;
+	piMonoVersion: string;
+	platform: string;
+	nodeVersion: string;
+	/**
+	 * Version 3 on every new session. Readers reject earlier versions and
+	 * sessions that omit this field.
+	 */
+	sessionFormatVersion?: number;
+}
+
+export const CURRENT_SESSION_FORMAT_VERSION = 3;
+
+export interface ClioSessionJsonlHeader {
+	type: "session";
+	version: number;
+	id: string;
+	timestamp: string;
+	cwd: string;
+	parentSession?: string;
+	parentTurnId?: string;
+}
+
+export interface ClioTurnRecord {
+	id: string;
+	parentId: string | null;
+	at: string;
+	kind: "user" | "assistant" | "tool_call" | "tool_result" | "system" | "checkpoint";
+	payload: unknown;
+}
+
+export interface SessionTreeNode {
+	id: string;
+	parentId: string | null;
+	at: string;
+	kind: ClioTurnRecord["kind"];
+}
+
+export interface ClioSessionFile {
+	current: string;
+	tree: string;
+	meta: string;
+}
+
+export interface ClioSessionWriter {
+	/** Write an ordinary turn as a structured message entry and add its tree node. */
+	append(turn: ClioTurnRecord): void;
+	/**
+	 * Write a pre-composed structured session entry as a JSON line. Callers
+	 * supply `treeNode` when the entry must project into the turn tree.
+	 */
+	appendEntry(entry: unknown, opts?: { treeNode?: SessionTreeNode }): void;
+	/** Atomically replace current.jsonl entries while preserving the session header. */
+	replaceEntries(entries: ReadonlyArray<unknown>): void;
+	persistTree(): Promise<void>;
+	/** Synchronously fsync append-only transcript bytes without rewriting tree/meta. */
+	flushAppends(): void;
+	close(): Promise<void>;
+}
+
+export interface ClioSessionReader {
+	meta(): ClioSessionMeta;
+	turns(): ReadonlyArray<unknown>;
+	fileEntries(): ReadonlyArray<unknown>;
+	header(): ClioSessionJsonlHeader | null;
+	tree(): ReadonlyArray<SessionTreeNode>;
+}
+
+export function cwdHash(cwd: string): string {
+	const normalized = resolve(cwd);
+	return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}
+
+export function sessionPaths(meta: ClioSessionMeta): ClioSessionFile {
+	const dir = join(clioStateDir(), "sessions", meta.cwdHash, meta.id);
+	mkdirSync(dir, { recursive: true });
+	return {
+		current: join(dir, "current.jsonl"),
+		tree: join(dir, "tree.json"),
+		meta: join(dir, "meta.json"),
+	};
+}
+
+// meta.json and tree.json rewrites delegate to the canonical writer. Neither
+// file is recovered from a leftover temp, so the randomized hidden temp name is
+// safe here (unlike current.jsonl, which promotes a deterministic `.tmp`).
+export function atomicWrite(targetPath: string, contents: string | Uint8Array): void {
+	safeResourceWrite(targetPath, contents);
+}
+
+export interface SessionJsonlWarning {
+	path: string;
+	line: number;
+	message: string;
+}
+
+export type SessionJsonlWarningSink = (warning: SessionJsonlWarning) => void;
+
+export interface SessionJsonlReadOptions {
+	onWarning?: SessionJsonlWarningSink;
+}
+
+export interface SessionJsonlWriteOptions {
+	beforeRename?: (tmpPath: string, targetPath: string) => void;
+}
+
+/**
+ * One damaged line, one message. A single ledger is read several times per
+ * command by callers that do not know about each other (resume, the turn tree,
+ * history), and each read re-reported every unparseable line, so one torn tail
+ * printed the identical skip line three times and read as three problems. The
+ * key is the exact warning, so a second defect in the same file is still said.
+ */
+const reportedSessionJsonlWarnings = new Set<string>();
+// A long-lived process sweeping a large store must not grow this without
+// bound. Forgetting everything at the cap at worst repeats a warning once.
+const REPORTED_SESSION_JSONL_WARNING_LIMIT = 1000;
+
+function defaultSessionJsonlWarning(warning: SessionJsonlWarning): void {
+	const key = `${warning.path}:${warning.line}:${warning.message}`;
+	if (reportedSessionJsonlWarnings.has(key)) return;
+	if (reportedSessionJsonlWarnings.size >= REPORTED_SESSION_JSONL_WARNING_LIMIT) reportedSessionJsonlWarnings.clear();
+	reportedSessionJsonlWarnings.add(key);
+	process.stderr.write(`[clio:session] ${warning.path}:${warning.line}: ${warning.message}\n`);
+}
+
+function serializeJsonl(entries: ReadonlyArray<unknown>): string {
+	if (entries.length === 0) return "";
+	const lines = entries.map((entry, index) => {
+		const serialized = JSON.stringify(entry);
+		if (serialized === undefined) {
+			throw new Error(`session JSONL entry ${index + 1} is not serializable`);
+		}
+		return serialized;
+	});
+	return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Rewrite a JSONL file through `<target>.tmp` and rename over the target.
+ * A crash or interruption before the rename leaves the original target
+ * untouched; when no target exists yet, recovery readers can promote the tmp.
+ */
+export function writeJsonlFileAtomic(
+	targetPath: string,
+	entries: ReadonlyArray<unknown>,
+	options: SessionJsonlWriteOptions = {},
+): void {
+	const dir = dirname(targetPath);
+	mkdirSync(dir, { recursive: true });
+	const body = serializeJsonl(entries);
+	const tmp = `${targetPath}.tmp`;
+	const fd = openSync(tmp, "w");
+	try {
+		writeSync(fd, body);
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	options.beforeRename?.(tmp, targetPath);
+	renameSync(tmp, targetPath);
+	fsyncDirectory(dir);
+}
+
+function recoverJsonlTargetIfMissing(targetPath: string): string | null {
+	if (existsSync(targetPath)) return targetPath;
+	const tmp = `${targetPath}.tmp`;
+	try {
+		if (!statSync(tmp).isFile()) return null;
+		renameSync(tmp, targetPath);
+		fsyncDirectory(dirname(targetPath));
+		return targetPath;
+	} catch {
+		return existsSync(targetPath) ? targetPath : existsSync(tmp) ? tmp : null;
+	}
+}
+
+const SESSION_JSONL_READ_CHUNK_BYTES = 64 * 1024;
+
+function parseSessionJsonlLine(
+	line: string,
+	lineNumber: number,
+	readPath: string,
+	entries: unknown[],
+	warn: SessionJsonlWarningSink,
+): void {
+	if (line.trim().length === 0) return;
+	try {
+		entries.push(JSON.parse(line) as unknown);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		warn({ path: readPath, line: lineNumber, message: `invalid JSON skipped: ${message}` });
+	}
+}
+
+export function readSessionFileEntries(path: string, options: SessionJsonlReadOptions = {}): unknown[] {
+	const readPath = recoverJsonlTargetIfMissing(path);
+	if (readPath === null) return [];
+	const entries: unknown[] = [];
+	const warn = options.onWarning ?? defaultSessionJsonlWarning;
+	const fd = openSync(readPath, "r");
+	const buffer = Buffer.allocUnsafe(SESSION_JSONL_READ_CHUNK_BYTES);
+	const decoder = new StringDecoder("utf8");
+	let pending = "";
+	let lineNumber = 0;
+	try {
+		for (;;) {
+			const bytesRead = readSync(fd, buffer, 0, buffer.length, null);
+			if (bytesRead === 0) break;
+			pending += decoder.write(buffer.subarray(0, bytesRead));
+			for (;;) {
+				const newlineIndex = pending.indexOf("\n");
+				if (newlineIndex < 0) break;
+				const line = pending.slice(0, newlineIndex);
+				pending = pending.slice(newlineIndex + 1);
+				lineNumber += 1;
+				parseSessionJsonlLine(line, lineNumber, readPath, entries, warn);
+			}
+		}
+		pending += decoder.end();
+		if (pending.length > 0) {
+			lineNumber += 1;
+			parseSessionJsonlLine(pending, lineNumber, readPath, entries, warn);
+		}
+	} finally {
+		closeSync(fd);
+	}
+	return entries;
+}
+
+export interface SessionTailReadResult {
+	/** Parsed tail entries in file order (header included only if BOF was reached). */
+	entries: unknown[];
+	/** Non-empty JSONL lines parsed — the bounded-work signal (≈ maxEntries, not file size). */
+	linesParsed: number;
+	/** True when the read consumed the whole file from its start (small files). */
+	reachedStart: boolean;
+}
+
+/** Read exactly `length` bytes at `position`, looping over short reads. */
+function readExactAt(fd: number, buffer: Buffer, position: number, length: number): void {
+	let read = 0;
+	while (read < length) {
+		const got = readSync(fd, buffer, read, length - read, position + read);
+		if (got === 0) break; // truncated under us; parse what we have
+		read += got;
+	}
+}
+
+/**
+ * Read only the last `maxEntries` non-empty JSONL lines of a session ledger by
+ * scanning backward from EOF, instead of parsing the whole file. Cost is bounded
+ * by `maxEntries` and the trailing bytes those lines occupy, not by session
+ * length. The trailing window starts at one chunk and doubles until it holds
+ * enough complete lines or reaches the file start; the first line of a non-BOF
+ * window is dropped as a partial line (its start lies before the window), which
+ * at worst discards one extra oldest line — never one of the last `maxEntries`.
+ *
+ * Behaviour matches `readSessionFileEntries` line-for-line over the tail it
+ * returns: same `parseSessionJsonlLine` (torn-tail tolerant), same warning sink.
+ */
+export function readSessionFileTailEntries(
+	path: string,
+	maxEntries: number,
+	options: SessionJsonlReadOptions & { chunkBytes?: number } = {},
+): SessionTailReadResult {
+	const readPath = recoverJsonlTargetIfMissing(path);
+	if (readPath === null) return { entries: [], linesParsed: 0, reachedStart: true };
+	const warn = options.onWarning ?? defaultSessionJsonlWarning;
+	const bound = Number.isFinite(maxEntries) && maxEntries > 0 ? Math.floor(maxEntries) : 1;
+	const chunkBytes =
+		options.chunkBytes !== undefined && options.chunkBytes > 0
+			? Math.floor(options.chunkBytes)
+			: SESSION_JSONL_READ_CHUNK_BYTES;
+	const fd = openSync(readPath, "r");
+	try {
+		const size = fstatSync(fd).size;
+		if (size === 0) return { entries: [], linesParsed: 0, reachedStart: true };
+		let windowBytes = Math.min(size, chunkBytes);
+		for (;;) {
+			const offset = Math.max(0, size - windowBytes);
+			const length = size - offset;
+			const buffer = Buffer.allocUnsafe(length);
+			readExactAt(fd, buffer, offset, length);
+			const decoder = new StringDecoder("utf8");
+			const text = decoder.write(buffer) + decoder.end();
+			const reachedStart = offset === 0;
+			// A non-BOF window's first line is partial (it began before `offset`).
+			const lines = text.split("\n");
+			const candidate = reachedStart ? lines : lines.slice(1);
+			const nonEmpty = candidate.filter((line) => line.trim().length > 0);
+			if (nonEmpty.length >= bound || reachedStart) {
+				const tail = nonEmpty.slice(Math.max(0, nonEmpty.length - bound));
+				const entries: unknown[] = [];
+				let lineNumber = 0;
+				for (const line of tail) {
+					lineNumber += 1;
+					parseSessionJsonlLine(line, lineNumber, readPath, entries, warn);
+				}
+				return { entries, linesParsed: tail.length, reachedStart };
+			}
+			if (windowBytes >= size) return { entries: [], linesParsed: 0, reachedStart: true };
+			windowBytes = Math.min(size, windowBytes * 2);
+		}
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/**
+ * Tail-scoped counterpart to `openSession(id).turns()`: the last `maxTurns`
+ * non-header entries of the session ledger, in file order. Reads one extra line
+ * so a header consuming a slot in a wholly-read small file never shrinks the
+ * turn count below `maxTurns`.
+ */
+export function readSessionTailTurns(id: string, maxTurns: number): SessionTailReadResult {
+	const currentPath = sessionCurrentPath(id);
+	const result = readSessionFileTailEntries(currentPath, maxTurns + 1);
+	const turns = result.entries.filter((entry) => !isSessionJsonlHeader(entry));
+	return {
+		entries: turns.slice(Math.max(0, turns.length - maxTurns)),
+		linesParsed: result.linesParsed,
+		reachedStart: result.reachedStart,
+	};
+}
+
+function isPositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function isOptionalString(value: unknown): boolean {
+	return value === undefined || typeof value === "string";
+}
+
+function isSessionJsonlHeader(value: unknown): value is ClioSessionJsonlHeader {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	return (
+		v.type === "session" &&
+		isPositiveInteger(v.version) &&
+		typeof v.id === "string" &&
+		typeof v.timestamp === "string" &&
+		typeof v.cwd === "string" &&
+		isOptionalString(v.parentSession) &&
+		isOptionalString(v.parentTurnId)
+	);
+}
+
+function sessionHeaderFromMeta(
+	meta: ClioSessionMeta,
+	options: { parentSession?: string; parentTurnId?: string } = {},
+): ClioSessionJsonlHeader {
+	const header: ClioSessionJsonlHeader = {
+		type: "session",
+		version: CURRENT_SESSION_FORMAT_VERSION,
+		id: meta.id,
+		timestamp: meta.createdAt,
+		cwd: meta.cwd,
+	};
+	if (options.parentSession !== undefined) header.parentSession = options.parentSession;
+	if (options.parentTurnId !== undefined) header.parentTurnId = options.parentTurnId;
+	return header;
+}
+
+function ensureSessionHeader(
+	meta: ClioSessionMeta,
+	entries: ReadonlyArray<unknown>,
+	options: { parentSession?: string; parentTurnId?: string } = {},
+): unknown[] {
+	const first = entries[0];
+	if (isSessionJsonlHeader(first)) return [...entries];
+	return [sessionHeaderFromMeta(meta, options), ...entries];
+}
+
+function recordFromTurn(turn: ClioTurnRecord): unknown {
+	const entry: Record<string, unknown> = {
+		kind: "message",
+		turnId: turn.id,
+		parentTurnId: turn.parentId,
+		timestamp: turn.at,
+		role: turn.kind,
+		payload: turn.payload,
+	};
+	return entry;
+}
+
+function newTurnId(): string {
+	const n = BigInt(`0x${randomBytes(8).toString("hex")}`);
+	const raw = n.toString(36);
+	if (raw.length >= 12) return raw.slice(0, 12);
+	return raw.padStart(12, "0");
+}
+
+function buildMeta(input: { cwd: string; model?: string | null; target?: string | null }): ClioSessionMeta {
+	const resolvedCwd = resolve(input.cwd);
+	return {
+		id: newTurnId(),
+		cwd: resolvedCwd,
+		cwdHash: cwdHash(resolvedCwd),
+		createdAt: new Date().toISOString(),
+		endedAt: null,
+		model: input.model ?? null,
+		target: input.target ?? null,
+		clioVersion: readClioVersion(),
+		piMonoVersion: readPiMonoVersion(),
+		platform: process.platform,
+		nodeVersion: process.version,
+		sessionFormatVersion: CURRENT_SESSION_FORMAT_VERSION,
+	};
+}
+
+function readMetaFile(path: string): ClioSessionMeta {
+	const raw = readFileSync(path, "utf8");
+	return JSON.parse(raw) as ClioSessionMeta;
+}
+
+const TURN_KINDS: readonly ClioTurnRecord["kind"][] = [
+	"user",
+	"assistant",
+	"tool_call",
+	"tool_result",
+	"system",
+	"checkpoint",
+];
+
+function isTurnKind(value: unknown): value is ClioTurnRecord["kind"] {
+	return typeof value === "string" && (TURN_KINDS as readonly string[]).includes(value);
+}
+
+function nullableString(value: unknown): value is string | null {
+	return value === null || typeof value === "string";
+}
+
+function isSessionTreeNode(value: unknown): value is SessionTreeNode {
+	if (!value || typeof value !== "object") return false;
+	const node = value as Record<string, unknown>;
+	return (
+		typeof node.id === "string" && nullableString(node.parentId) && typeof node.at === "string" && isTurnKind(node.kind)
+	);
+}
+
+function readTreeFile(path: string): SessionTreeNode[] {
+	if (!existsSync(path)) return [];
+	try {
+		const raw = readFileSync(path, "utf8");
+		if (raw.trim().length === 0) return [];
+		const parsed = JSON.parse(raw) as unknown;
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter(isSessionTreeNode);
+	} catch {
+		return [];
+	}
+}
+
+function treeNodeFromFileEntry(entry: unknown): SessionTreeNode | null {
+	if (!entry || typeof entry !== "object" || isSessionJsonlHeader(entry)) return null;
+	const value = entry as Record<string, unknown>;
+	if (
+		value.kind === "message" &&
+		typeof value.turnId === "string" &&
+		nullableString(value.parentTurnId) &&
+		typeof value.timestamp === "string" &&
+		isTurnKind(value.role) &&
+		Object.hasOwn(value, "payload")
+	) {
+		return { id: value.turnId, parentId: value.parentTurnId, at: value.timestamp, kind: value.role };
+	}
+	return null;
+}
+
+function treeFromFileEntries(fileEntries: ReadonlyArray<unknown>): SessionTreeNode[] {
+	const nodes: SessionTreeNode[] = [];
+	for (const entry of fileEntries) {
+		const node = treeNodeFromFileEntry(entry);
+		if (node) nodes.push(node);
+	}
+	return nodes;
+}
+
+function sameTreeNode(a: SessionTreeNode | undefined, b: SessionTreeNode): boolean {
+	return !!a && a.id === b.id && a.parentId === b.parentId && a.at === b.at && a.kind === b.kind;
+}
+
+function sameTree(a: ReadonlyArray<SessionTreeNode>, b: ReadonlyArray<SessionTreeNode>): boolean {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i += 1) {
+		const left = a[i];
+		const right = b[i];
+		if (!left || !right || !sameTreeNode(left, right)) return false;
+	}
+	return true;
+}
+
+function recoverTreeFromJsonl(diskTree: SessionTreeNode[], fileEntries: ReadonlyArray<unknown>): SessionTreeNode[] {
+	const recovered = treeFromFileEntries(fileEntries);
+	if (recovered.length === 0) return diskTree;
+	return sameTree(diskTree, recovered) ? diskTree : recovered;
+}
+
+export function sessionCurrentPath(id: string): string {
+	return join(findSessionDir(id), "current.jsonl");
+}
+
+function findSessionDir(id: string): string {
+	// Session ids are identifiers, not paths. Reject a traversal id before any
+	// filesystem read so it can never resolve a directory outside the sessions
+	// root (`join(sessionsRoot, entry, id)` would otherwise escape).
+	assertSafeId(id, "session");
+	const sessionsRoot = join(clioStateDir(), "sessions");
+	if (!existsSync(sessionsRoot)) {
+		throw new Error(`session not found: ${id}`);
+	}
+	for (const entry of readdirSync(sessionsRoot, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const candidate = join(sessionsRoot, entry.name, id);
+		if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+			return candidate;
+		}
+	}
+	throw new Error(`session not found: ${id}`);
+}
+
+/** Read only meta.json for callers that do not need to parse the transcript. */
+export function readSessionMeta(id: string): ClioSessionMeta {
+	return readMetaFile(join(findSessionDir(id), "meta.json"));
+}
+
+const APPEND_FSYNC_DEBOUNCE_MS = 500;
+
+/**
+ * True when the file's last byte is a newline (or the file is empty or
+ * missing). A false result means a crash left a torn partial line that an
+ * O_APPEND writer must terminate before writing, or the next record would
+ * fuse onto the fragment and corrupt itself too.
+ */
+function endsWithNewline(path: string): boolean {
+	let size: number;
+	try {
+		size = statSync(path).size;
+	} catch {
+		return true;
+	}
+	if (size === 0) return true;
+	const fd = openSync(path, "r");
+	try {
+		const buf = Buffer.alloc(1);
+		readSync(fd, buf, 0, 1, size - 1);
+		return buf[0] === 0x0a;
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/**
+ * Durably append one entry to an existing session JSONL file without reading
+ * or replacing its prior contents. This is the off-current counterpart to the
+ * long-lived writer: a torn final fragment is terminated and left visible to
+ * the tolerant reader, then the new record is written through O_APPEND and
+ * fsynced before returning.
+ */
+export function appendSessionFileEntry(targetPath: string, entry: unknown): void {
+	const appendPath = recoverJsonlTargetIfMissing(targetPath);
+	if (appendPath === null) throw new Error(`session JSONL file not found: ${targetPath}`);
+	const serialized = JSON.stringify(entry);
+	if (serialized === undefined) throw new Error("session JSONL entry is not serializable");
+	const line = Buffer.from(`${endsWithNewline(appendPath) ? "" : "\n"}${serialized}\n`, "utf8");
+	const fd = openSync(appendPath, fsConstants.O_WRONLY | fsConstants.O_APPEND);
+	try {
+		const written = writeSync(fd, line);
+		if (written !== line.length) {
+			throw new Error(`short session JSONL append: wrote ${written} of ${line.length} bytes`);
+		}
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+}
+
+function createWriter(
+	meta: ClioSessionMeta,
+	initialTree: SessionTreeNode[],
+	initialFileEntries: ReadonlyArray<unknown>,
+	headerOptions: { parentSession?: string; parentTurnId?: string } = {},
+): ClioSessionWriter {
+	const paths = sessionPaths(meta);
+	const tree: SessionTreeNode[] = [...initialTree];
+	const fileEntries = ensureSessionHeader(meta, initialFileEntries, headerOptions);
+	let closed = false;
+	let appendFd: number | null = null;
+	let fsyncTimer: NodeJS.Timeout | null = null;
+
+	// One-time normalization for resumes of pre-header files: rewrite once so
+	// fd-appended lines land after a header. Disk and memory match from here on.
+	if (!isSessionJsonlHeader(initialFileEntries[0])) {
+		writeJsonlFileAtomic(paths.current, fileEntries);
+	}
+
+	function openAppendFd(): number {
+		if (appendFd !== null) return appendFd;
+		const tornTail = !endsWithNewline(paths.current);
+		appendFd = openSync(paths.current, "a");
+		// Terminating the fragment keeps the reader's torn-tail behavior:
+		// it skips exactly one invalid line with a warning.
+		if (tornTail) writeSync(appendFd, "\n");
+		return appendFd;
+	}
+
+	function scheduleFsync(): void {
+		if (fsyncTimer !== null) return;
+		fsyncTimer = setTimeout(() => {
+			fsyncTimer = null;
+			if (appendFd === null) return;
+			try {
+				fsyncSync(appendFd);
+			} catch {
+				// A concurrent close already flushed and released the fd.
+			}
+		}, APPEND_FSYNC_DEBOUNCE_MS);
+		fsyncTimer.unref?.();
+	}
+
+	function closeAppendFd(opts: { flush: boolean }): void {
+		if (fsyncTimer !== null) {
+			clearTimeout(fsyncTimer);
+			fsyncTimer = null;
+		}
+		if (appendFd === null) return;
+		try {
+			if (opts.flush) fsyncSync(appendFd);
+		} finally {
+			closeSync(appendFd);
+			appendFd = null;
+		}
+	}
+
+	function appendLine(entry: unknown): void {
+		const serialized = JSON.stringify(entry);
+		if (serialized === undefined) {
+			throw new Error("session JSONL entry is not serializable");
+		}
+		writeSync(openAppendFd(), `${serialized}\n`);
+		scheduleFsync();
+	}
+
+	return {
+		append(turn: ClioTurnRecord): void {
+			if (closed) throw new Error("session writer closed");
+			const record = recordFromTurn(turn);
+			appendLine(record);
+			fileEntries.push(record);
+			tree.push({
+				id: turn.id,
+				parentId: turn.parentId,
+				at: turn.at,
+				kind: turn.kind,
+			});
+		},
+		appendEntry(entry: unknown, opts?: { treeNode?: SessionTreeNode }): void {
+			if (closed) throw new Error("session writer closed");
+			appendLine(entry);
+			fileEntries.push(entry);
+			if (opts?.treeNode) tree.push(opts.treeNode);
+		},
+		replaceEntries(entries: ReadonlyArray<unknown>): void {
+			if (closed) throw new Error("session writer closed");
+			// The rename below replaces the inode; the held fd would keep
+			// appending to the orphaned old file. Drop it, reopen lazily.
+			closeAppendFd({ flush: false });
+			const existingHeader = fileEntries.find(isSessionJsonlHeader);
+			const body = entries.filter((entry) => !isSessionJsonlHeader(entry));
+			const nextEntries = existingHeader ? [existingHeader, ...body] : ensureSessionHeader(meta, body, headerOptions);
+			writeJsonlFileAtomic(paths.current, nextEntries);
+			fileEntries.length = 0;
+			fileEntries.push(...nextEntries);
+			const recoveredTree = treeFromFileEntries(nextEntries);
+			if (recoveredTree.length > 0) {
+				tree.length = 0;
+				tree.push(...recoveredTree);
+			}
+		},
+		async persistTree(): Promise<void> {
+			// Checkpoint: make appended lines durable alongside the tree.
+			if (appendFd !== null) fsyncSync(appendFd);
+			// `paths` was resolved at construction, but atomicWrite mkdirs the
+			// session directory again, so an uninstall that has already removed the
+			// state root would be undone here. Fsyncing the held fd first is safe
+			// either way: it writes into an unlinked inode and creates nothing.
+			if (stateRootRemoved()) return;
+			atomicWrite(paths.tree, JSON.stringify(tree, null, 2));
+		},
+		flushAppends(): void {
+			if (appendFd !== null) fsyncSync(appendFd);
+		},
+		async close(): Promise<void> {
+			if (closed) return;
+			closeAppendFd({ flush: true });
+			// Closed regardless: the writer is done either way, and a removed state
+			// root must not get tree.json and meta.json written back into it.
+			closed = true;
+			if (stateRootRemoved()) return;
+			atomicWrite(paths.tree, JSON.stringify(tree, null, 2));
+			const ended: ClioSessionMeta = { ...meta, endedAt: new Date().toISOString() };
+			atomicWrite(paths.meta, JSON.stringify(ended, null, 2));
+			meta.endedAt = ended.endedAt;
+		},
+	};
+}
+
+export function createSession(input: {
+	cwd: string;
+	model?: string | null;
+	target?: string | null;
+	initialEntries?: ReadonlyArray<unknown>;
+	initialTree?: ReadonlyArray<SessionTreeNode>;
+	parentSession?: string;
+	parentTurnId?: string;
+}): {
+	meta: ClioSessionMeta;
+	writer: ClioSessionWriter;
+} {
+	const meta = buildMeta(input);
+	const paths = sessionPaths(meta);
+	atomicWrite(paths.meta, JSON.stringify(meta, null, 2));
+	const headerOptions: { parentSession?: string; parentTurnId?: string } = {};
+	if (input.parentSession !== undefined) headerOptions.parentSession = input.parentSession;
+	if (input.parentTurnId !== undefined) headerOptions.parentTurnId = input.parentTurnId;
+	const initialEntries = ensureSessionHeader(meta, input.initialEntries ?? [], headerOptions);
+	const initialTree = [...(input.initialTree ?? [])];
+	writeJsonlFileAtomic(paths.current, initialEntries);
+	atomicWrite(paths.tree, JSON.stringify(initialTree, null, 2));
+	const writer = createWriter(meta, initialTree, initialEntries, headerOptions);
+	return { meta, writer };
+}
+
+export function openSession(id: string): ClioSessionReader {
+	const dir = findSessionDir(id);
+	const metaPath = join(dir, "meta.json");
+	const meta = readMetaFile(metaPath);
+	const currentPath = join(dir, "current.jsonl");
+	const fileEntries = readSessionFileEntries(currentPath);
+	const turns = fileEntries.filter((entry) => !isSessionJsonlHeader(entry));
+	const header = fileEntries.find(isSessionJsonlHeader) ?? null;
+	const tree = recoverTreeFromJsonl(readTreeFile(join(dir, "tree.json")), fileEntries);
+	return {
+		meta(): ClioSessionMeta {
+			return meta;
+		},
+		turns(): ReadonlyArray<unknown> {
+			return turns;
+		},
+		fileEntries(): ReadonlyArray<unknown> {
+			return fileEntries;
+		},
+		header(): ClioSessionJsonlHeader | null {
+			return header;
+		},
+		tree(): ReadonlyArray<SessionTreeNode> {
+			return tree;
+		},
+	};
+}
+
+export function resumeSession(id: string): {
+	meta: ClioSessionMeta;
+	writer: ClioSessionWriter;
+	tree: ReadonlyArray<SessionTreeNode>;
+} {
+	const dir = findSessionDir(id);
+	const metaPath = join(dir, "meta.json");
+	const meta = readMetaFile(metaPath);
+	// resume reopens an active session; clear endedAt if it was set by a prior close
+	if (meta.endedAt !== null) {
+		meta.endedAt = null;
+		atomicWrite(metaPath, JSON.stringify(meta, null, 2));
+	}
+	const existingFileEntries = readSessionFileEntries(join(dir, "current.jsonl"));
+	const existingTree = recoverTreeFromJsonl(readTreeFile(join(dir, "tree.json")), existingFileEntries);
+	const writer = createWriter(meta, existingTree, existingFileEntries);
+	return { meta, writer, tree: existingTree };
+}