@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/session/tree/active-path.ts

@@ -0,0 +1,98 @@
+import type { MessageEntry, SessionEntry } from "../entries.js";
+
+/**
+ * Active-branch selection over a tree-shaped session entry list.
+ *
+ * current.jsonl is append-only: after a /tree switch to an earlier turn, new
+ * turns parent onto that turn and the abandoned sibling turns stay in the
+ * file. Replaying the file linearly resurrects those abandoned turns, so
+ * replay surfaces filter through this helper first.
+ *
+ * The filter traces the leaf's ancestry across message entries and keeps:
+ *   - message entries on the active path,
+ *   - sidecar entries anchored to a path turn (parentTurnId or targetTurnId),
+ *   - compaction summaries whose firstKeptTurnId or parent lands on the path,
+ *   - unanchored sidecars (parentTurnId null), which cannot be attributed to
+ *     a branch and keep their historical always-included behavior.
+ *
+ * A plain chain is returned unchanged unless a live caller explicitly pins an
+ * earlier leaf. That preserves historical linear replay (including old parent
+ * gaps) while making a backward /tree selection authoritative before the next
+ * append creates a structural sibling.
+ */
+export function filterEntriesToActivePath(entries: ReadonlyArray<SessionEntry>, leafTurnId?: string): SessionEntry[] {
+	const messages: MessageEntry[] = [];
+	const messagesById = new Map<string, MessageEntry>();
+	for (const entry of entries) {
+		if (entry.kind !== "message") continue;
+		messages.push(entry);
+		messagesById.set(entry.turnId, entry);
+	}
+	// Without a live-session pointer, offline readers fall back to the most
+	// recent message in file order. Current-session runtime paths must pass the
+	// explicit leaf because switchTurn() changes the next append point without
+	// appending a message to the ledger.
+	const latest = messages[messages.length - 1];
+	const pinnedLeaf = resolveLeafMessage(entries, messagesById, leafTurnId);
+	if (!hasBranch(messages) && (pinnedLeaf === undefined || pinnedLeaf.turnId === latest?.turnId)) return [...entries];
+	const leaf = pinnedLeaf ?? latest;
+	if (!leaf) return [...entries];
+
+	const pathIds = new Set<string>();
+	let current: MessageEntry | undefined = leaf;
+	while (current && !pathIds.has(current.turnId)) {
+		pathIds.add(current.turnId);
+		if (current.parentTurnId === null) break;
+		// A missing parent means an older rewrite dropped it; treat the break
+		// as the root rather than failing the whole replay.
+		current = messagesById.get(current.parentTurnId);
+	}
+	return entries.filter((entry) => entryOnActivePath(entry, pathIds));
+}
+
+/**
+ * Resolve the pinned leaf id to a message entry. A sidecar id pins the
+ * branch through the turn it is anchored to (targetTurnId, firstKeptTurnId,
+ * or parentTurnId), so callers may pass any entry's turnId. An id that
+ * resolves to nothing falls back to the caller's default leaf.
+ */
+function resolveLeafMessage(
+	entries: ReadonlyArray<SessionEntry>,
+	messagesById: ReadonlyMap<string, MessageEntry>,
+	leafTurnId: string | undefined,
+): MessageEntry | undefined {
+	if (leafTurnId === undefined) return undefined;
+	const direct = messagesById.get(leafTurnId);
+	if (direct) return direct;
+	const sidecar = entries.find((entry) => entry.turnId === leafTurnId);
+	if (!sidecar) return undefined;
+	const anchor = sidecarAnchorTurnId(sidecar);
+	return anchor === null ? undefined : messagesById.get(anchor);
+}
+
+function sidecarAnchorTurnId(entry: SessionEntry): string | null {
+	if (entry.kind === "label") return entry.targetTurnId;
+	if (entry.kind === "sessionInfo") return entry.targetTurnId ?? entry.parentTurnId;
+	if (entry.kind === "compactionSummary" && entry.firstKeptTurnId.length > 0) return entry.firstKeptTurnId;
+	return entry.parentTurnId;
+}
+
+function hasBranch(messages: ReadonlyArray<MessageEntry>): boolean {
+	const seenParents = new Set<string>();
+	for (const message of messages) {
+		if (message.parentTurnId === null) continue;
+		if (seenParents.has(message.parentTurnId)) return true;
+		seenParents.add(message.parentTurnId);
+	}
+	return false;
+}
+
+function entryOnActivePath(entry: SessionEntry, pathIds: ReadonlySet<string>): boolean {
+	if (entry.kind === "message") return pathIds.has(entry.turnId);
+	if (entry.kind === "label") return pathIds.has(entry.targetTurnId);
+	if (entry.kind === "sessionInfo") return entry.targetTurnId === undefined || pathIds.has(entry.targetTurnId);
+	if (entry.kind === "compactionSummary" && entry.firstKeptTurnId.length > 0 && pathIds.has(entry.firstKeptTurnId)) {
+		return true;
+	}
+	return entry.parentTurnId === null || pathIds.has(entry.parentTurnId);
+}

package/src/domains/session/tree/fork.ts

@@ -0,0 +1,160 @@
+import { readSessionFileEntries, type SessionTreeNode, sessionPaths } from "../../../engine/session.js";
+import { collectSessionEntries } from "../compaction/session-entries.js";
+import type { SessionMeta } from "../contract.js";
+import { isSessionHeader, type SessionEntry } from "../entries.js";
+import { enrichForkMeta } from "../history.js";
+import { type SessionManagerState, startSession } from "../manager.js";
+
+/**
+ * Single-point fork-from-parent-turn orchestration. Closes the caller's
+ * prior state writer, starts a fresh session inheriting cwd/model/target
+ * from the parent meta, then stamps parent pointers atomically via
+ * enrichForkMeta. Returns the new SessionManagerState so the caller can
+ * install it as current.
+ *
+ * Used by SessionContract.fork (current session) and the /fork message
+ * picker path that lands in slice 12b-3. Kept out of extension.ts so the
+ * bundle wiring stays thin.
+ */
+export interface ForkInput {
+	/** The state we are forking from. Must carry a live writer. */
+	from: SessionManagerState;
+	/** Id of the parent turn (pinned via /fork message-picker). */
+	parentTurnId: string;
+	/** Optional cwd override; defaults to the parent session's cwd. */
+	cwd?: string;
+}
+
+export interface ForkResult {
+	next: SessionManagerState;
+	parentMeta: SessionMeta;
+	nodes: ReadonlyArray<SessionTreeNode>;
+}
+
+interface LinkedRecord {
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+	treeKind: SessionTreeNode["kind"] | null;
+	raw: SessionEntry;
+}
+
+function linkedRecordFromEntry(entry: SessionEntry): LinkedRecord {
+	return {
+		id: entry.turnId,
+		parentId: entry.parentTurnId,
+		timestamp: entry.timestamp,
+		treeKind: entry.kind === "message" ? entry.role : null,
+		raw: entry,
+	};
+}
+
+function traceAncestry(records: ReadonlyArray<LinkedRecord>, leafTurnId: string): LinkedRecord[] {
+	const byId = new Map<string, LinkedRecord>();
+	for (const record of records) byId.set(record.id, record);
+	const path: LinkedRecord[] = [];
+	let current = byId.get(leafTurnId);
+	if (!current) throw new Error(`session.fork: parent turn not found: ${leafTurnId}`);
+	const seen = new Set<string>();
+	while (current) {
+		if (seen.has(current.id)) throw new Error(`session.fork: cycle in parent chain at ${current.id}`);
+		seen.add(current.id);
+		path.unshift(current);
+		if (current.parentId === null) break;
+		const next = byId.get(current.parentId);
+		if (!next) throw new Error(`session.fork: broken parent chain at ${current.id}`);
+		current = next;
+	}
+	return path;
+}
+
+function treeFromLinearPath(path: ReadonlyArray<LinkedRecord>): SessionTreeNode[] {
+	return path
+		.filter((record): record is LinkedRecord & { treeKind: SessionTreeNode["kind"] } => record.treeKind !== null)
+		.map((record) => ({
+			id: record.id,
+			parentId: record.parentId,
+			at: record.timestamp,
+			kind: record.treeKind,
+		}));
+}
+
+/**
+ * Unanchored sidecars (parentTurnId null) carry no turn pointer, so file
+ * position is the only branch signal: anything written after the fork-point
+ * turn belongs to the timeline that diverged from it, not to the fork.
+ * `atOrBeforeForkPoint` is that positional verdict, computed by the caller.
+ */
+function sessionEntryBelongsToPath(
+	entry: SessionEntry,
+	pathIds: ReadonlySet<string>,
+	atOrBeforeForkPoint: boolean,
+): boolean {
+	if (entry.kind === "message") return pathIds.has(entry.turnId);
+	if (entry.kind === "label") return pathIds.has(entry.targetTurnId);
+	if (entry.kind === "sessionInfo") return entry.targetTurnId ? pathIds.has(entry.targetTurnId) : false;
+	if (entry.kind === "compactionSummary") {
+		// A summary describes history as of its write position. One written
+		// after the fork point did not exist when the forked timeline split,
+		// even when its firstKeptTurnId lands on the fork path; copying it
+		// would open the fork at the summary boundary and hide the transcript.
+		if (!atOrBeforeForkPoint) return false;
+		if (entry.firstKeptTurnId.length > 0 && pathIds.has(entry.firstKeptTurnId)) return true;
+	}
+	return entry.parentTurnId === null ? atOrBeforeForkPoint : pathIds.has(entry.parentTurnId);
+}
+
+function entryBelongsToPath(entry: SessionEntry, pathIds: ReadonlySet<string>, atOrBeforeForkPoint: boolean): boolean {
+	return sessionEntryBelongsToPath(entry, pathIds, atOrBeforeForkPoint);
+}
+
+function branchEntriesFromParent(
+	parentMeta: SessionMeta,
+	leafTurnId: string,
+): {
+	parentCurrentPath: string;
+	entries: unknown[];
+	tree: SessionTreeNode[];
+} {
+	const parentCurrentPath = sessionPaths(parentMeta).current;
+	const records = readSessionFileEntries(parentCurrentPath).filter((entry) => !isSessionHeader(entry));
+	const parsed = collectSessionEntries(records, parentCurrentPath);
+	const linked = parsed.map(linkedRecordFromEntry);
+	const path = traceAncestry(linked, leafTurnId);
+	const pathIds = new Set(path.map((record) => record.id));
+	const forkPointIndex = parsed.findIndex((entry) => linkedRecordFromEntry(entry).id === leafTurnId);
+	const entries = parsed.filter((entry, index) =>
+		entryBelongsToPath(entry, pathIds, forkPointIndex >= 0 && index <= forkPointIndex),
+	);
+	return {
+		parentCurrentPath,
+		entries,
+		tree: treeFromLinearPath(path),
+	};
+}
+
+/**
+ * Fork the given state into a new session. Closes the prior writer
+ * best-effort so the on-disk endedAt marker is written; the caller is
+ * responsible for replacing its own state pointer with `result.next`.
+ */
+export function forkFromState(input: ForkInput): ForkResult {
+	const parentMeta = input.from.meta;
+	// close() only performs synchronous filesystem work before resolving, so
+	// the following read sees a fully flushed parent transcript.
+	void input.from.writer.close();
+	const branch = branchEntriesFromParent(parentMeta, input.parentTurnId);
+
+	const cwd = input.cwd ?? parentMeta.cwd;
+	const next = startSession({
+		cwd,
+		model: parentMeta.model,
+		target: parentMeta.target,
+		initialEntries: branch.entries,
+		initialTree: branch.tree,
+		parentSession: branch.parentCurrentPath,
+		parentTurnId: input.parentTurnId,
+	});
+	enrichForkMeta(next.meta, parentMeta.id, input.parentTurnId);
+	return { next, parentMeta, nodes: branch.tree };
+}

package/src/domains/session/tree/manager.ts

@@ -0,0 +1,128 @@
+import { existsSync, renameSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+	appendSessionFileEntry,
+	openSession,
+	readSessionMeta,
+	type SessionTreeNode,
+	sessionPaths,
+} from "../../../engine/session.js";
+import { collectSessionEntries } from "../compaction/session-entries.js";
+import type { SessionMeta } from "../contract.js";
+import type { SessionEntry, SessionInfoEntry } from "../entries.js";
+
+/**
+ * Domain-level tree-file helpers. Operates directly on the on-disk artifacts
+ * the engine writer owns (`tree.json`, `current.jsonl`, `meta.json`) for the
+ * non-current session cases that the higher-level SessionContract methods
+ * need: /tree rendering for arbitrary sessions, editLabel on another session,
+ * deleteSession tombstoning.
+ *
+ * For the *current* session, writes flow through `SessionManagerState.writer`
+ * (via manager.appendEntry / checkpoint). This module only handles the
+ * off-loaded paths.
+ */
+
+export interface ResolvedLabel {
+	label: string;
+	timestamp: string;
+}
+
+export interface SessionTreeFileBundle {
+	sessionId: string;
+	meta: SessionMeta;
+	nodes: SessionTreeNode[];
+	entries: SessionEntry[];
+	labels: Map<string, ResolvedLabel>;
+}
+
+/**
+ * Load the `tree.json` for an arbitrary session plus the resolved labels.
+ * Uses the engine reader (openSession) so we do not re-implement its
+ * session-directory lookup.
+ */
+export function readTreeBundle(sessionId: string): SessionTreeFileBundle {
+	const reader = openSession(sessionId);
+	const meta = reader.meta() as SessionMeta;
+	const paths = sessionPaths(meta);
+	const nodes = [...reader.tree()];
+	const entries = collectSessionEntries(reader.turns(), paths.current);
+	const labels = resolveLabelMap(entries);
+	return { sessionId, meta, nodes, entries, labels };
+}
+
+/**
+ * Scan rich entries for SessionInfoEntry label markers. Last-wins by
+ * timestamp (ISO8601 strings sort lexicographically for same-format inputs).
+ * Empty-string label acts as a tombstone: it is stored with its timestamp
+ * so that subsequent older-timestamp label sets do not resurrect the label.
+ * Consumers treat `label === ""` as "no label".
+ *
+ * Exported for unit tests via the manager module path. Intentionally kept
+ * off the domain index barrel.
+ */
+export function resolveLabelMap(entries: ReadonlyArray<SessionEntry>): Map<string, ResolvedLabel> {
+	const out = new Map<string, ResolvedLabel>();
+	for (const entry of entries) {
+		const info = labelFields(entry);
+		if (!info) continue;
+		const existing = out.get(info.targetTurnId);
+		if (existing && existing.timestamp > info.timestamp) continue;
+		if (info.label === undefined || info.label === "") {
+			out.set(info.targetTurnId, { label: "", timestamp: info.timestamp });
+			continue;
+		}
+		out.set(info.targetTurnId, { label: info.label, timestamp: info.timestamp });
+	}
+	return out;
+}
+
+function labelFields(entry: SessionEntry): { targetTurnId: string; timestamp: string; label?: string } | null {
+	if (entry.kind === "label") return entry;
+	if (entry.kind !== "sessionInfo") return null;
+	const info = entry as SessionInfoEntry;
+	if (!info.targetTurnId) return null;
+	const out: { targetTurnId: string; timestamp: string; label?: string } = {
+		targetTurnId: info.targetTurnId,
+		timestamp: info.timestamp,
+	};
+	if (info.label !== undefined) out.label = info.label;
+	return out;
+}
+
+/**
+ * Append a single SessionEntry line to an arbitrary session's
+ * `current.jsonl`. Intended for the not-current session case in editLabel;
+ * the current-session case goes through the engine writer.
+ */
+export function appendEntryToSessionFile(sessionId: string, entry: SessionEntry): void {
+	const meta = readSessionMeta(sessionId);
+	const paths = sessionPaths(meta);
+	appendSessionFileEntry(paths.current, entry);
+}
+
+/**
+ * Destructively remove the entire session directory (current.jsonl,
+ * tree.json, meta.json, plus any sidecars the engine adds in future).
+ * Used by deleteSession when `keepFiles` is not requested.
+ */
+export function removeSessionDirectory(sessionId: string): void {
+	const meta = readSessionMeta(sessionId);
+	const paths = sessionPaths(meta);
+	const dir = dirname(paths.meta);
+	rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Tombstone variant: rename `meta.json` to `meta.deleted.json` so
+ * `listSessionsForCwd` (which filters on existence of meta.json) drops
+ * the session from history without touching the transcript files.
+ * Resume can still target the session id directly via manual recovery.
+ */
+export function tombstoneSession(sessionId: string): void {
+	const meta = readSessionMeta(sessionId);
+	const paths = sessionPaths(meta);
+	if (!existsSync(paths.meta)) return;
+	const tombstone = join(dirname(paths.meta), "meta.deleted.json");
+	renameSync(paths.meta, tombstone);
+}

package/src/domains/session/tree/navigator.ts

@@ -0,0 +1,177 @@
+import type { SessionTreeNode } from "../../../engine/session.js";
+import type { SessionMeta } from "../contract.js";
+import type { ResolvedLabel } from "./manager.js";
+
+/**
+ * Purely functional tree-walk helpers. Given the raw SessionTreeNode[] that
+ * the engine persists plus a label map and a leaf pointer, produce a
+ * render-friendly snapshot. No I/O. Used by SessionContract.tree() to
+ * deliver a serializable structure to overlay renderers in slice 12b-2.
+ */
+
+/**
+ * Node kinds the navigator renders. `tree.json` stores turn kinds only, so the
+ * two structural events a session can carry, a compaction and a returned-from
+ * branch, live in the ledger as `compactionSummary` / `branchSummary` entries.
+ * They are the two moments a reader most needs to see in the tree, so the
+ * snapshot admits them as node kinds and the builder links them by their
+ * recorded parent turn.
+ */
+export type TreeNodeKind = SessionTreeNode["kind"] | "compaction" | "branch";
+
+/** A tree node the snapshot builder accepts: a persisted turn node or a ledger-derived structural node. */
+export interface TreeInputNode {
+	id: string;
+	parentId: string | null;
+	at: string;
+	kind: TreeNodeKind;
+}
+
+export interface TreeSnapshotNode {
+	id: string;
+	parentId: string | null;
+	at: string;
+	kind: TreeNodeKind;
+	label?: string;
+	/**
+	 * Single-line, ANSI/sentinel-stripped synopsis of the underlying turn
+	 * payload. Populated when the snapshot builder is given a previews map
+	 * keyed by turnId; absent for snapshots built without payload access
+	 * (e.g. unit tests that exercise tree shape only).
+	 */
+	preview?: string;
+	/** Child ids in oldest-first order. */
+	children: string[];
+}
+
+export interface TreeSnapshot {
+	sessionId: string;
+	/**
+	 * SessionMeta slice suitable for overlay rendering. Keep the shape
+	 * stable so the /tree overlay does not need to re-type it.
+	 */
+	meta: {
+		id: string;
+		cwd: string;
+		createdAt: string;
+		endedAt: string | null;
+		model: string | null;
+		target: string | null;
+		parentSessionId?: string | null;
+		parentTurnId?: string | null;
+	};
+	/** Id of the active turn the session will append under next. */
+	leafId: string | null;
+	/** Flat node map keyed by id. */
+	nodesById: Record<string, TreeSnapshotNode>;
+	/** Root node ids in oldest-first order. A well-formed session has one. */
+	rootIds: string[];
+}
+
+function pickMeta(meta: SessionMeta): TreeSnapshot["meta"] {
+	const out: TreeSnapshot["meta"] = {
+		id: meta.id,
+		cwd: meta.cwd,
+		createdAt: meta.createdAt,
+		endedAt: meta.endedAt,
+		model: meta.model,
+		target: meta.target,
+	};
+	if (meta.parentSessionId !== undefined) out.parentSessionId = meta.parentSessionId;
+	if (meta.parentTurnId !== undefined) out.parentTurnId = meta.parentTurnId;
+	return out;
+}
+
+/**
+ * Compute the natural leaf of a tree: the most recent node with no children.
+ * Timestamp ties break toward the later node in append order, since nodes
+ * append in creation order and ISO timestamps only carry millisecond
+ * precision; a branch switch and re-append inside one millisecond must still
+ * resolve to the newest branch. Returns null for an empty tree. Used by
+ * tree() when the caller has not explicitly tracked a current-branch
+ * pointer yet.
+ */
+export function computeLeafId(nodes: ReadonlyArray<TreeInputNode>): string | null {
+	if (nodes.length === 0) return null;
+	const hasChild = new Set<string>();
+	for (const node of nodes) {
+		if (node.parentId) hasChild.add(node.parentId);
+	}
+	let leaf: TreeInputNode | null = null;
+	for (const node of nodes) {
+		if (hasChild.has(node.id)) continue;
+		if (!leaf || node.at >= leaf.at) leaf = node;
+	}
+	return leaf?.id ?? null;
+}
+
+/**
+ * Build a serializable snapshot from raw tree nodes + labels + meta. Pure:
+ * no fs, no time. Sorts child lists by timestamp ascending so the overlay
+ * renders consistently across platforms.
+ */
+export function buildTreeSnapshot(input: {
+	meta: SessionMeta;
+	nodes: ReadonlyArray<TreeInputNode>;
+	labels: ReadonlyMap<string, ResolvedLabel>;
+	leafId?: string | null;
+	/**
+	 * Optional turnId → preview map. When supplied, each TreeSnapshotNode
+	 * carries the matching preview so /tree overlay rows can render a
+	 * distinguishing synopsis. Domain callers populate this from the engine
+	 * reader's turns; unit tests that only care about tree shape may omit it.
+	 */
+	previews?: ReadonlyMap<string, string>;
+}): TreeSnapshot {
+	const nodesById: Record<string, TreeSnapshotNode> = {};
+	for (const node of input.nodes) {
+		const entry: TreeSnapshotNode = {
+			id: node.id,
+			parentId: node.parentId,
+			at: node.at,
+			kind: node.kind,
+			children: [],
+		};
+		const resolved = input.labels.get(node.id);
+		// Empty-string label is a tombstone produced by resolveLabelMap; treat
+		// it as "no label" so tombstone entries do not surface as blank chips.
+		if (resolved && resolved.label !== "") entry.label = resolved.label;
+		const preview = input.previews?.get(node.id);
+		if (preview !== undefined && preview.length > 0) entry.preview = preview;
+		nodesById[node.id] = entry;
+	}
+
+	const rootIds: string[] = [];
+	for (const node of input.nodes) {
+		const parent = node.parentId ? nodesById[node.parentId] : undefined;
+		if (!parent) {
+			rootIds.push(node.id);
+		} else {
+			parent.children.push(node.id);
+		}
+	}
+
+	// Oldest-first for stable rendering. Unknown timestamps sort by id.
+	const byTime = (a: string, b: string) => {
+		const na = nodesById[a];
+		const nb = nodesById[b];
+		if (!na || !nb) return a < b ? -1 : a > b ? 1 : 0;
+		if (na.at === nb.at) return na.id < nb.id ? -1 : na.id > nb.id ? 1 : 0;
+		return na.at < nb.at ? -1 : 1;
+	};
+	rootIds.sort(byTime);
+	for (const key of Object.keys(nodesById)) {
+		const entry = nodesById[key];
+		if (entry) entry.children.sort(byTime);
+	}
+
+	const leafId = input.leafId !== undefined ? input.leafId : computeLeafId(input.nodes);
+
+	return {
+		sessionId: input.meta.id,
+		meta: pickMeta(input.meta),
+		leafId,
+		nodesById,
+		rootIds,
+	};
+}