@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/session/extension.ts

@@ -0,0 +1,403 @@
+import {
+	BusChannels,
+	type SessionParkReason as ParkReason,
+	type SessionResumeVia as ResumeVia,
+} from "../../core/bus-events.js";
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import { performCheckpoint } from "./checkpoint.js";
+import type { DeleteSessionOptions, SessionContract, SessionEntryInput, SessionMeta, TurnInput } from "./contract.js";
+import type { LabelEntry, SessionEntry, SessionInfoEntry } from "./entries.js";
+import { listSessionsForCwd } from "./history.js";
+import {
+	appendEntry,
+	appendTurn,
+	newTurnId,
+	persistSessionMeta,
+	replaceEntries,
+	resumeSessionState,
+	type SessionManagerState,
+	startSession,
+} from "./manager.js";
+import { forkFromState } from "./tree/fork.js";
+import { appendEntryToSessionFile, readTreeBundle, removeSessionDirectory, tombstoneSession } from "./tree/manager.js";
+import { buildTreeSnapshot, computeLeafId, type TreeInputNode, type TreeSnapshot } from "./tree/navigator.js";
+import { buildTurnPreview } from "./tree/preview.js";
+import { probeWorkspace } from "./workspace/index.js";
+
+/**
+ * Session domain wire-up. Owns a single current SessionManagerState and
+ * funnels create/append/checkpoint/resume/fork/close through the engine
+ * session writer. The CLI drives lifecycle; the extension only enforces the
+ * shutdown contract (final checkpoint + close) on domain stop.
+ *
+ * Lifecycle transitions fan onto the shared bus so the safety audit
+ * subscriber can persist `session_park` and `session_resume` rows without
+ * pulling in the session contract directly. Park fires whenever the current
+ * session is replaced or closed; resume fires when an existing session is
+ * reopened via resume() or switchBranch().
+ */
+export function createSessionBundle(context: DomainContext): DomainBundle<SessionContract> {
+	let state: SessionManagerState | null = null;
+	let currentTurnId: string | null = null;
+
+	function emitPark(sessionId: string, reason: ParkReason): void {
+		context.bus.emit(BusChannels.SessionParked, { sessionId, reason, at: Date.now() });
+	}
+
+	function emitResume(sessionId: string, via: ResumeVia): void {
+		context.bus.emit(BusChannels.SessionResumed, { sessionId, via, at: Date.now() });
+	}
+
+	function emitTurnSwitched(sessionId: string, turnId: string): void {
+		context.bus.emit(BusChannels.SessionTurnSwitched, { sessionId, turnId, at: Date.now() });
+	}
+
+	/**
+	 * The leaf to resume onto: the persisted `/tree` pin when it still names a
+	 * real turn in this session's tree, otherwise the inferred newest-node leaf.
+	 * A pin surviving here is what makes a `/tree` switch made without a
+	 * follow-up message survive quit + resume instead of silently reverting to
+	 * the abandoned tip (issue #94).
+	 */
+	function resolveLeafOnOpen(resumed: {
+		state: SessionManagerState;
+		nodes: ReadonlyArray<TreeInputNode>;
+	}): string | null {
+		const pinned = resumed.state.meta.pinnedLeafTurnId;
+		if (pinned && resumed.nodes.some((node) => node.id === pinned)) return pinned;
+		return computeLeafId(resumed.nodes);
+	}
+
+	async function closeCurrent(reason: ParkReason = "close"): Promise<void> {
+		if (!state) return;
+		const s = state;
+		emitPark(s.meta.id, reason);
+		state = null;
+		currentTurnId = null;
+		await s.writer.close();
+	}
+
+	async function flushIfCurrent(sessionId: string): Promise<void> {
+		if (state?.meta.id === sessionId) {
+			// tree.json lives on disk; the writer holds the canonical in-memory
+			// copy. Flush before a tree() read so the domain-level navigator
+			// observes every append since the last checkpoint.
+			await state.writer.persistTree();
+		}
+	}
+
+	/**
+	 * Structural nodes the turn tree cannot hold. `tree.json` records message
+	 * turns; a compaction and a returned-from branch are ledger entries with
+	 * their own turn ids and parent pointers, and /tree showed neither, so a
+	 * session that had been compacted looked exactly like one that had not.
+	 * Their previews carry the facts already on the entry.
+	 */
+	function structuralTreeNodes(entries: ReadonlyArray<SessionEntry>, previews: Map<string, string>): TreeInputNode[] {
+		const nodes: TreeInputNode[] = [];
+		for (const entry of entries) {
+			if (entry.kind === "compactionSummary") {
+				nodes.push({ id: entry.turnId, parentId: entry.parentTurnId, at: entry.timestamp, kind: "compaction" });
+				const summarized = entry.messagesSummarized === undefined ? "history" : `${entry.messagesSummarized} entries`;
+				const after = entry.tokensAfter === undefined ? "" : ` -> ~${entry.tokensAfter}`;
+				previews.set(entry.turnId, `${summarized} summarized, ~${entry.tokensBefore}${after} tokens`);
+				continue;
+			}
+			if (entry.kind === "branchSummary") {
+				nodes.push({ id: entry.turnId, parentId: entry.parentTurnId, at: entry.timestamp, kind: "branch" });
+				const text = entry.summary.split("\n", 1)[0] ?? "";
+				previews.set(
+					entry.turnId,
+					text.length > 0 ? `returned from ${entry.fromTurnId}: ${text}` : `returned from ${entry.fromTurnId}`,
+				);
+			}
+		}
+		return nodes;
+	}
+
+	function snapshotFor(sessionId: string): TreeSnapshot {
+		const bundle = readTreeBundle(sessionId);
+		// Prefer the live in-memory meta when we are looking at the current
+		// session so checkpoint/fork pointers are fresh; otherwise fall back
+		// to the on-disk read.
+		const meta: SessionMeta = state?.meta.id === sessionId ? state.meta : bundle.meta;
+		// Build a turnId → preview map so /tree rows show distinguishing
+		// payload slices. Reading turns is cheap (single jsonl scan) and
+		// happens only when the overlay opens.
+		const previews = new Map<string, string>();
+		let structural: TreeInputNode[] = [];
+		try {
+			for (const entry of bundle.entries) {
+				if (entry.kind !== "message") continue;
+				const text = buildTurnPreview({ kind: entry.role, payload: entry.payload });
+				if (text.length > 0) previews.set(entry.turnId, text);
+			}
+			structural = structuralTreeNodes(bundle.entries, previews);
+		} catch {
+			// Best-effort: if the on-disk transcript cannot be read, fall back
+			// to a previewless snapshot. The overlay handles missing previews
+			// gracefully via its kind-label fallback.
+		}
+		const persistedLeaf =
+			bundle.meta.pinnedLeafTurnId && bundle.nodes.some((node) => node.id === bundle.meta.pinnedLeafTurnId)
+				? bundle.meta.pinnedLeafTurnId
+				: computeLeafId(bundle.nodes);
+		return buildTreeSnapshot({
+			meta,
+			nodes: [...bundle.nodes, ...structural],
+			labels: bundle.labels,
+			previews,
+			// The leaf is the next append point, so it is computed over turn nodes
+			// only: a structural node marks a moment in the timeline, never a place
+			// the session continues from.
+			leafId: state?.meta.id === sessionId ? currentTurnId : persistedLeaf,
+		});
+	}
+
+	const contract: SessionContract = {
+		current: () => state?.meta ?? null,
+		create(input) {
+			const cwd = input?.cwd ?? process.cwd();
+			const startInput: { cwd: string; model?: string | null; target?: string | null } = { cwd };
+			if (input?.model !== undefined) startInput.model = input.model;
+			if (input?.target !== undefined) startInput.target = input.target;
+			// Close any prior writer first so tree.json + meta.json get the
+			// endedAt + final-tree flush. Without this, the old session leaks
+			// its in-memory tree to disk and /tree on a resume would miss
+			// every append since the last checkpoint.
+			if (state) {
+				const prior = state;
+				emitPark(prior.meta.id, "create_new");
+				state = null;
+				void prior.writer.close();
+			}
+			const next = startSession(startInput);
+			next.meta.workspace = probeWorkspace(cwd);
+			persistSessionMeta(next);
+			state = next;
+			currentTurnId = null;
+			return next.meta;
+		},
+		append(turn: TurnInput) {
+			if (!state) throw new Error("session.append: no current session");
+			// Invariant: a turn can only extend this session's own current leaf.
+			// The interactive layer tracks its own copy of "the last turn id"
+			// (turn-persistence.ts) and normally keeps it in lockstep with
+			// currentTurnId via chat.resetForSession after every switch; when a
+			// failed resume/fork/switchBranch left that copy pointing at a turn
+			// from a session that was never actually opened here, this is the
+			// one place that catches it before a foreign parent id reaches disk.
+			if (turn.parentId !== currentTurnId) {
+				throw new Error(
+					`session.append: turn parentId ${turn.parentId ?? "null"} is not this session's current leaf (expected ${currentTurnId ?? "null"}); refusing to parent a turn onto another session's turn`,
+				);
+			}
+			const record = appendTurn(state, turn);
+			currentTurnId = record.id;
+			// A fresh append moves the leaf past whatever /tree pinned earlier
+			// (or this append could not have been made: see the invariant above),
+			// so the persisted pin is stale and must not outlive it. Once cleared,
+			// resolveLeafOnOpen's timestamp inference is trustworthy again.
+			if (state.meta.pinnedLeafTurnId !== undefined && state.meta.pinnedLeafTurnId !== null) {
+				state.meta.pinnedLeafTurnId = null;
+				persistSessionMeta(state);
+			}
+			return record;
+		},
+		appendEntry(entry: SessionEntryInput) {
+			if (!state) throw new Error("session.appendEntry: no current session");
+			return appendEntry(state, entry);
+		},
+		replaceEntries(entries) {
+			if (!state) throw new Error("session.replaceEntries: no current session");
+			replaceEntries(state, entries);
+		},
+		recordSkillActivation(activation) {
+			if (!state) throw new Error("session.recordSkillActivation: no current session");
+			appendEntry(state, {
+				kind: "skillActivation",
+				parentTurnId: activation.turnId ?? null,
+				activation,
+			});
+			const existing = state.meta.skillActivations ?? [];
+			state.meta.skillActivations = [...existing, activation];
+			persistSessionMeta(state);
+			return activation;
+		},
+		async checkpoint(reason) {
+			if (!state) throw new Error("session.checkpoint: no current session");
+			await performCheckpoint(state, reason);
+		},
+		flushAppends() {
+			if (!state) throw new Error("session.flushAppends: no current session");
+			state.writer.flushAppends();
+		},
+		resume(sessionId) {
+			if (state && state.meta.id === sessionId) return state.meta;
+			// Open the target before touching the current session: resumeSessionState
+			// reads and migrates the target's meta.json and can throw (unsupported
+			// format version, unreadable entries, missing files). Closing or nulling
+			// the prior session ahead of that risk is how a failed switch used to
+			// orphan the operator with no current session (issue #93); on success,
+			// the prior is parked and closed only now that the successor is known good.
+			const resumed = resumeSessionState(sessionId);
+			if (state) {
+				const prior = state;
+				emitPark(prior.meta.id, "resume_other");
+				void prior.writer.close();
+			}
+			state = resumed.state;
+			currentTurnId = resolveLeafOnOpen(resumed);
+			emitResume(resumed.state.meta.id, "resume");
+			return resumed.state.meta;
+		},
+		fork(parentTurnId, input) {
+			if (!state) throw new Error("session.fork: no current session to fork from");
+			const prior = state;
+			// forkFromState reads and validates the parent's own ancestry chain
+			// and can throw (unknown or broken parent turn) before it ever creates
+			// the child session; it closes `prior.writer` itself, and only once the
+			// child is known good (see tree/fork.ts). Do not null or park `state`
+			// until forkFromState returns, for the same reason as resume() above.
+			const { next, nodes } = forkFromState({
+				from: prior,
+				parentTurnId,
+				...(input?.cwd !== undefined ? { cwd: input.cwd } : {}),
+			});
+			emitPark(prior.meta.id, "fork");
+			state = next;
+			currentTurnId = computeLeafId(nodes);
+			return next.meta;
+		},
+		tree(sessionId) {
+			const id = sessionId ?? state?.meta.id;
+			if (!id) throw new Error("session.tree: no sessionId provided and no current session");
+			// Current-session reads must see every append the in-memory writer
+			// has absorbed since the last checkpoint. persistTree runs
+			// atomicWrite synchronously in-body before yielding its Promise,
+			// so the file on disk is up to date by the time snapshotFor opens
+			// it below. The void-discarded Promise is settled on the next
+			// microtask and carries no return value we care about.
+			if (state?.meta.id === id) void flushIfCurrent(id);
+			return snapshotFor(id);
+		},
+		switchBranch(sessionId) {
+			// /tree-driven branch switch currently delegates to resume. Kept as a
+			// distinct contract method so later slices can layer telemetry or
+			// chat-loop rewiring without changing resume's semantics. Same
+			// open-before-close ordering as resume() above and for the same reason.
+			if (state?.meta.id === sessionId) return state.meta;
+			const resumed = resumeSessionState(sessionId);
+			if (state) {
+				const prior = state;
+				emitPark(prior.meta.id, "switch_branch");
+				void prior.writer.close();
+			}
+			state = resumed.state;
+			currentTurnId = resolveLeafOnOpen(resumed);
+			emitResume(resumed.state.meta.id, "switch_branch");
+			return resumed.state.meta;
+		},
+		switchTurn(turnId) {
+			if (!state) throw new Error("session.switchTurn: no current session");
+			void flushIfCurrent(state.meta.id);
+			const nodes = readTreeBundle(state.meta.id).nodes;
+			if (!nodes.some((node) => node.id === turnId)) {
+				throw new Error(`session.switchTurn: turn not found: ${turnId}`);
+			}
+			currentTurnId = turnId;
+			// Persist the pin immediately, not just in memory: without this, a
+			// switch made without a follow-up message was silently lost on quit
+			// because resume() had nothing but timestamp inference to fall back
+			// on and always landed back on the abandoned tip (issue #94).
+			state.meta.pinnedLeafTurnId = turnId;
+			persistSessionMeta(state);
+			emitTurnSwitched(state.meta.id, turnId);
+			return state.meta;
+		},
+		editLabel(turnId, label, sessionId) {
+			const targetId = sessionId ?? state?.meta.id;
+			if (!targetId) throw new Error("session.editLabel: no sessionId provided and no current session");
+			// Label entries are side-car metadata; they do not project into
+			// tree.json (engine `appendEntry` path leaves non-message entries
+			// off the tree), so parentTurnId is left null.
+			if (state && state.meta.id === targetId) {
+				appendEntry(state, {
+					kind: "label",
+					parentTurnId: null,
+					targetTurnId: turnId,
+					label,
+				} as SessionEntryInput);
+				return;
+			}
+			const entry: LabelEntry = {
+				kind: "label",
+				turnId: newTurnId(),
+				parentTurnId: null,
+				timestamp: new Date().toISOString(),
+				targetTurnId: turnId,
+				label,
+			};
+			appendEntryToSessionFile(targetId, entry);
+		},
+		setName(name, sessionId) {
+			const targetId = sessionId ?? state?.meta.id;
+			if (!targetId) throw new Error("session.setName: no sessionId provided and no current session");
+			// A name is session-wide metadata rather than a turn label. Keep it
+			// unanchored and let history's last-wins SessionInfoEntry fold resolve it.
+			if (state && state.meta.id === targetId) {
+				appendEntry(state, {
+					kind: "sessionInfo",
+					parentTurnId: null,
+					name,
+				} as SessionEntryInput);
+				return;
+			}
+			const entry: SessionInfoEntry = {
+				kind: "sessionInfo",
+				turnId: newTurnId(),
+				parentTurnId: null,
+				timestamp: new Date().toISOString(),
+				name,
+			};
+			appendEntryToSessionFile(targetId, entry);
+		},
+		deleteSession(id, opts) {
+			if (state?.meta.id === id) {
+				throw new Error("session.deleteSession: refusing to delete the currently open session; close() first");
+			}
+			const options: DeleteSessionOptions = opts ?? {};
+			if (options.keepFiles) {
+				tombstoneSession(id);
+			} else {
+				removeSessionDirectory(id);
+			}
+		},
+		history(): ReadonlyArray<SessionMeta> {
+			const cwd = state?.meta.cwd ?? process.cwd();
+			return listSessionsForCwd(cwd);
+		},
+		async close() {
+			await closeCurrent();
+		},
+	};
+
+	const extension: DomainExtension = {
+		async start() {
+			// Sessions are created lazily by the CLI; nothing to do on boot.
+		},
+		async stop() {
+			if (!state) return;
+			try {
+				await performCheckpoint(state, "shutdown");
+			} catch (err) {
+				process.stderr.write(
+					`[clio:session] shutdown checkpoint failed: ${err instanceof Error ? err.message : String(err)}\n`,
+				);
+			}
+			await closeCurrent("shutdown");
+		},
+	};
+
+	return { extension, contract };
+}

package/src/domains/session/history.ts

@@ -0,0 +1,172 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { clioStateDir } from "../../core/xdg.js";
+import { atomicWrite, cwdHash, readSessionFileEntries, sessionPaths } from "../../engine/session.js";
+import { collectSessionEntries } from "./compaction/session-entries.js";
+import type { SessionMeta } from "./contract.js";
+import { isSessionHeader, type LabelEntry, type SessionInfoEntry } from "./entries.js";
+
+/**
+ * Walks `clioStateDir()/sessions/<cwdHash>/` and returns every session meta
+ * for the given cwd, sorted by last-activity descending (newest activity
+ * first). Falls back to createdAt when no entries carry timestamps.
+ */
+export function listSessionsForCwd(cwd: string): SessionMeta[] {
+	const hash = cwdHash(cwd);
+	const dir = join(clioStateDir(), "sessions", hash);
+	if (!existsSync(dir)) return [];
+	const metas: SessionMeta[] = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const sessionDir = join(dir, entry.name);
+		const metaPath = join(sessionDir, "meta.json");
+		if (!existsSync(metaPath)) continue;
+		let meta: SessionMeta;
+		try {
+			if (!statSync(metaPath).isFile()) continue;
+			const raw = readFileSync(metaPath, "utf8");
+			meta = JSON.parse(raw) as SessionMeta;
+		} catch {
+			// Skip unreadable or malformed metadata files.
+			continue;
+		}
+		enrichMetaForListing(meta, join(sessionDir, "current.jsonl"));
+		metas.push(meta);
+	}
+	metas.sort((a, b) => {
+		const aKey = a.lastActivityAt ?? a.createdAt ?? "";
+		const bKey = b.lastActivityAt ?? b.createdAt ?? "";
+		return aKey === bKey ? 0 : aKey > bKey ? -1 : 1;
+	});
+	return metas;
+}
+
+const PREVIEW_MAX_CHARS = 240;
+
+function collapseWhitespace(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Pull the first non-empty piece of user-authored text out of a payload.
+ * Structured message payloads may contain a bare string, a text property,
+ * or pi-ai content blocks.
+ */
+function extractUserText(payload: unknown): string | null {
+	if (typeof payload === "string") {
+		const collapsed = collapseWhitespace(payload);
+		return collapsed.length > 0 ? collapsed : null;
+	}
+	if (!payload || typeof payload !== "object") return null;
+	const obj = payload as Record<string, unknown>;
+	if (typeof obj.text === "string") {
+		const collapsed = collapseWhitespace(obj.text);
+		if (collapsed.length > 0) return collapsed;
+	}
+	if (Array.isArray(obj.content)) {
+		const parts: string[] = [];
+		for (const part of obj.content) {
+			if (
+				part &&
+				typeof part === "object" &&
+				(part as { type?: unknown }).type === "text" &&
+				typeof (part as { text?: unknown }).text === "string"
+			) {
+				parts.push((part as { text: string }).text);
+			}
+		}
+		const joined = collapseWhitespace(parts.join(" "));
+		if (joined.length > 0) return joined;
+	}
+	return null;
+}
+
+interface ScanResult {
+	firstUserMessage: string | null;
+	messageCount: number;
+	lastTimestamp: string | null;
+	name: string | null;
+	labels: Map<string, { label: string; timestamp: string }>;
+}
+
+function scanCurrentJsonl(currentPath: string): ScanResult {
+	const result: ScanResult = {
+		firstUserMessage: null,
+		messageCount: 0,
+		lastTimestamp: null,
+		name: null,
+		labels: new Map(),
+	};
+	if (!existsSync(currentPath)) return result;
+	const records = readSessionFileEntries(currentPath).filter((entry) => !isSessionHeader(entry));
+	for (const parsed of collectSessionEntries(records, currentPath)) {
+		if (result.lastTimestamp === null || parsed.timestamp > result.lastTimestamp) {
+			result.lastTimestamp = parsed.timestamp;
+		}
+		if (parsed.kind === "message" && parsed.role === "user") {
+			result.messageCount += 1;
+			if (result.firstUserMessage === null) {
+				const text = extractUserText(parsed.payload);
+				if (text !== null) result.firstUserMessage = text;
+			}
+		}
+		if (parsed.kind === "sessionInfo") {
+			const info = parsed as SessionInfoEntry;
+			if (info.name !== undefined) {
+				const trimmed = info.name.trim();
+				result.name = trimmed.length > 0 ? trimmed : null;
+			}
+			if (info.targetTurnId && info.label !== undefined) {
+				const existing = result.labels.get(info.targetTurnId);
+				if (!existing || existing.timestamp <= info.timestamp) {
+					result.labels.set(info.targetTurnId, { label: info.label, timestamp: info.timestamp });
+				}
+			}
+		}
+		if (parsed.kind === "label") {
+			const label = parsed as LabelEntry;
+			const existing = result.labels.get(label.targetTurnId);
+			if (!existing || existing.timestamp <= label.timestamp) {
+				result.labels.set(label.targetTurnId, { label: label.label ?? "", timestamp: label.timestamp });
+			}
+		}
+	}
+	return result;
+}
+
+function enrichMetaForListing(meta: SessionMeta, currentPath: string): void {
+	const scan = scanCurrentJsonl(currentPath);
+	if (scan.name) meta.name = scan.name;
+	const labelValues = [...scan.labels.values()].map((entry) => entry.label.trim()).filter((label) => label.length > 0);
+	if (labelValues.length > 0) meta.labels = labelValues;
+	if (scan.firstUserMessage) {
+		meta.firstMessagePreview =
+			scan.firstUserMessage.length > PREVIEW_MAX_CHARS
+				? `${scan.firstUserMessage.slice(0, PREVIEW_MAX_CHARS - 1)}…`
+				: scan.firstUserMessage;
+	}
+	if (scan.messageCount > 0) meta.messageCount = scan.messageCount;
+	const fallbackMtime = readMtimeIso(currentPath);
+	const activity = scan.lastTimestamp ?? fallbackMtime ?? meta.endedAt ?? meta.createdAt ?? null;
+	if (activity) meta.lastActivityAt = activity;
+}
+
+function readMtimeIso(path: string): string | null {
+	try {
+		return statSync(path).mtime.toISOString();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Applies fork pointers to a freshly-created session's meta. Mutates the meta
+ * object in place so the engine writer's `close()` (which spreads `...meta`
+ * when rewriting meta.json with endedAt) preserves the parent pointers, then
+ * atomically rewrites meta.json so the marker survives crashes before close.
+ */
+export function enrichForkMeta(meta: SessionMeta, parentSessionId: string, parentTurnId: string): void {
+	Object.assign(meta, { parentSessionId, parentTurnId });
+	const paths = sessionPaths(meta);
+	atomicWrite(paths.meta, JSON.stringify(meta, null, 2));
+}

package/src/domains/session/index.ts

@@ -0,0 +1,84 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import { createSessionBundle } from "./extension.js";
+import { SessionManifest } from "./manifest.js";
+
+export const SessionDomainModule: DomainModule = {
+	manifest: SessionManifest,
+	createExtension: createSessionBundle,
+};
+
+export type {
+	AuditJsonRow,
+	AuditReadResult,
+	SessionLedgerRef,
+	SessionReadResult,
+} from "./archive-readers.js";
+export {
+	listSessionLedgerRefs,
+	parseSessionEntries,
+	readAuditRows,
+	readSessionEntriesForId,
+} from "./archive-readers.js";
+export type {
+	ClioSessionMetaExtension,
+	DeleteSessionOptions,
+	SessionContract,
+	SessionEntryInput,
+	SessionMeta,
+	TurnInput,
+} from "./contract.js";
+export type {
+	BaseSessionEntry,
+	BashExecutionEntry,
+	BranchSummaryEntry,
+	CompactionSummaryEntry,
+	CustomEntry,
+	FileEntryEntry,
+	LabelEntry,
+	MessageEntry,
+	MessageRole,
+	ModelChangeEntry,
+	ProtectedArtifactEntry,
+	ProtectedArtifactEntryArtifact,
+	ProtectedArtifactEntrySource,
+	SessionEntry,
+	SessionEntryKind,
+	SessionFileEntry,
+	SessionHeader,
+	SessionInfoEntry,
+	SkillActivationEntry,
+	TaskLedgerEntry,
+	TaskLedgerEvidenceStatus,
+	TaskLedgerGoal,
+	TaskLedgerStatus,
+	TaskLedgerValidationEvidence,
+	ThinkingLevelChangeEntry,
+	WorkerRunEntry,
+	WorkerRunOrigin,
+	WorkerRunRuntime,
+	WorkerRunRuntimeKind,
+} from "./entries.js";
+export { isSessionEntry, isSessionHeader, SESSION_ENTRY_KINDS } from "./entries.js";
+export { SessionManifest } from "./manifest.js";
+export { CURRENT_SESSION_FORMAT_VERSION, runMigrations } from "./migrations/index.js";
+export {
+	protectedArtifactEntryFromArtifact,
+	protectedArtifactFromSessionEntry,
+	protectedArtifactStateFromSessionEntries,
+} from "./protected-artifacts.js";
+export type {
+	TaskBoardCounts,
+	TaskBoardMutation,
+	TaskBoardMutationResult,
+	TaskBoardSnapshot,
+	TaskBoardStore,
+	TaskBoardStoreDeps,
+	TaskBoardTask,
+} from "./task-board.js";
+export { createTaskBoardStore, foldTaskBoard, taskBoardCounts, toTaskLedgerEntryFields } from "./task-board.js";
+// The tree/ module is a domain-internal building block. Only the
+// overlay-facing types surface here; callers that need deeper helpers import
+// from the concrete submodules directly (session domain only).
+export type { TreeSnapshot, TreeSnapshotNode } from "./tree/navigator.js";
+export type { LedgerUsageCall, SessionUsageDefaults } from "./usage.js";
+export { ledgerUsageCalls } from "./usage.js";