@nklisch/pi-enhanced 0.1.0

package/node_modules/@juicesharp/rpiv-todo/package.json

@@ -0,0 +1,73 @@
+{
+	"name": "@juicesharp/rpiv-todo",
+	"version": "2.1.0",
+	"description": "Pi extension. A todo list for the model, rendered as a live overlay that survives /reload and conversation compaction.",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"rpiv",
+		"todo"
+	],
+	"type": "module",
+	"license": "MIT",
+	"author": "juicesharp",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/juicesharp/rpiv-mono.git",
+		"directory": "packages/rpiv-todo"
+	},
+	"homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme",
+	"bugs": {
+		"url": "https://github.com/juicesharp/rpiv-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "vitest run"
+	},
+	"files": [
+		"config.ts",
+		"index.ts",
+		"locales/",
+		"todo.ts",
+		"todo-overlay.ts",
+		"LICENSE",
+		"docs/",
+		"!docs/*.png",
+		"!docs/*.jpg",
+		"!docs/*.svg",
+		"README.md",
+		"state/invariants.ts",
+		"state/i18n-bridge.ts",
+		"state/replay.ts",
+		"state/selectors.ts",
+		"state/state-reducer.ts",
+		"state/state.ts",
+		"state/store.ts",
+		"state/task-graph.ts",
+		"tool/response-envelope.ts",
+		"tool/types.ts",
+		"view/format.ts"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@juicesharp/rpiv-i18n": "*",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"peerDependenciesMeta": {
+		"@juicesharp/rpiv-i18n": {
+			"optional": true
+		}
+	},
+	"dependencies": {
+		"@juicesharp/rpiv-config": "^2.1.0",
+		"typebox": "^1.1.24"
+	}
+}

package/node_modules/@juicesharp/rpiv-todo/state/i18n-bridge.ts

@@ -0,0 +1,64 @@
+/**
+ * i18n bridge for rpiv-todo — single thin import surface so every call site
+ * routes through one module. Backed by `@juicesharp/rpiv-i18n`'s SDK when
+ * available; degrades to canonical-English fallbacks when not.
+ *
+ * - `t(key, fallback)` is `scope("@juicesharp/rpiv-todo")` if the SDK is
+ *   installed (live `/languages` updates propagate). If the SDK is missing
+ *   (standalone install without rpiv-i18n), `t` is an identity passthrough
+ *   that returns the inline English fallback at every call site, so the
+ *   extension stays online with English UI.
+ * - `formatStatusLabel(status)` resolves a TaskStatus to its locale-aware
+ *   label via the canonical `status.*` namespace, with the English literal
+ *   as fallback so nothing renders blank if the namespace isn't registered.
+ *   This is the SINGLE point of localization for status words — overlay,
+ *   /todos header, /todos render-call all route through here.
+ *
+ * Strings are registered ONCE at extension load (see ../index.ts). Call sites
+ * MUST use this module at render time — never bake the result into a top-level
+ * `const X = formatStatusLabel(...)`.
+ */
+
+import type { TaskStatus } from "../tool/types.js";
+
+export const I18N_NAMESPACE = "@juicesharp/rpiv-todo";
+
+type ScopeFn = (key: string, fallback: string) => string;
+type I18nSDK = { scope: (namespace: string) => ScopeFn };
+
+// Prefer the live SDK if installed: closures it returns track the active
+// locale, so /languages picker propagates to our render call sites. If the
+// SDK isn't installed (standalone install of this extension without
+// rpiv-i18n), the dynamic import fails, every t(key, fallback) returns the
+// canonical English literal, and the extension stays online.
+//
+// Top-level await is required so a synchronous `t(...)` call from any
+// downstream module sees the resolved scope; ESM module loading awaits this
+// before evaluating any importer.
+let scopeImpl: ScopeFn;
+try {
+	const sdk = (await import("@juicesharp/rpiv-i18n")) as I18nSDK;
+	scopeImpl = sdk.scope(I18N_NAMESPACE);
+} catch {
+	scopeImpl = (_key, fallback) => fallback;
+}
+
+export const t: ScopeFn = scopeImpl;
+
+const STATUS_LABEL_PENDING = "pending";
+const STATUS_LABEL_IN_PROGRESS = "in progress";
+const STATUS_LABEL_COMPLETED = "completed";
+const STATUS_LABEL_DELETED = "deleted";
+
+export function formatStatusLabel(status: TaskStatus): string {
+	switch (status) {
+		case "pending":
+			return t("status.pending", STATUS_LABEL_PENDING);
+		case "in_progress":
+			return t("status.in_progress", STATUS_LABEL_IN_PROGRESS);
+		case "completed":
+			return t("status.completed", STATUS_LABEL_COMPLETED);
+		case "deleted":
+			return t("status.deleted", STATUS_LABEL_DELETED);
+	}
+}

package/node_modules/@juicesharp/rpiv-todo/state/invariants.ts

@@ -0,0 +1,20 @@
+import type { TaskStatus } from "../tool/types.js";
+
+/**
+ * Allowed forward transitions per source status. `completed` is one-way to
+ * `deleted` (never back to `in_progress`); `deleted` is terminal.
+ *
+ * Idempotent same→same is checked separately in `isTransitionValid` so this
+ * table only enumerates actual transitions.
+ */
+export const VALID_TRANSITIONS: Record<TaskStatus, ReadonlySet<TaskStatus>> = {
+	pending: new Set(["in_progress", "completed", "deleted"]),
+	in_progress: new Set(["pending", "completed", "deleted"]),
+	completed: new Set(["deleted"]),
+	deleted: new Set(),
+};
+
+export function isTransitionValid(from: TaskStatus, to: TaskStatus): boolean {
+	if (from === to) return true;
+	return VALID_TRANSITIONS[from].has(to);
+}

package/node_modules/@juicesharp/rpiv-todo/state/replay.ts

@@ -0,0 +1,38 @@
+import type { TaskDetails } from "../tool/types.js";
+import { EMPTY_STATE, type TaskState } from "./state.js";
+
+/**
+ * Discriminator for `details` envelopes that match the persisted `TaskDetails`
+ * shape. Defensive — branch entries from older or corrupt sessions are
+ * skipped silently.
+ */
+export function isTaskDetails(value: unknown): value is TaskDetails {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	return Array.isArray(v.tasks) && typeof v.nextId === "number";
+}
+
+/**
+ * Walk the current branch in chronological order; the LAST `toolResult` whose
+ * `toolName === "todo"` and whose `details` shape matches `TaskDetails` wins
+ * (last-write-wins). When no matching entry exists, returns `EMPTY_STATE`.
+ *
+ * Pure of module state — `index.ts` writes the returned snapshot into the
+ * store after this returns. The function explicitly does NOT touch the store
+ * cell.
+ */
+export function replayFromBranch(ctx: { sessionManager: { getBranch(): Iterable<unknown> } }): TaskState {
+	let result: TaskState = { tasks: [...EMPTY_STATE.tasks], nextId: EMPTY_STATE.nextId };
+	for (const entry of ctx.sessionManager.getBranch()) {
+		const e = entry as { type?: string; message?: { role?: string; toolName?: string; details?: unknown } };
+		if (e.type !== "message") continue;
+		const msg = e.message;
+		if (msg?.role !== "toolResult" || msg.toolName !== "todo") continue;
+		if (!isTaskDetails(msg.details)) continue;
+		result = {
+			tasks: msg.details.tasks.map((t) => ({ ...t })),
+			nextId: msg.details.nextId,
+		};
+	}
+	return result;
+}

package/node_modules/@juicesharp/rpiv-todo/state/selectors.ts

@@ -0,0 +1,107 @@
+import type { Task, TaskStatus } from "../tool/types.js";
+import type { TaskState } from "./state.js";
+
+/** Tasks excluding deleted tombstones — the canonical "what's visible". */
+export function selectVisibleTasks(state: TaskState): readonly Task[] {
+	return state.tasks.filter((t) => t.status !== "deleted");
+}
+
+/**
+ * Group visible tasks by status. Iteration order at the call site uses
+ * (`completed`, `inProgress`, `pending`) to match the `/todos` header part
+ * order pinned by `todo.command.test.ts`.
+ */
+export interface TasksByStatus {
+	pending: readonly Task[];
+	inProgress: readonly Task[];
+	completed: readonly Task[];
+}
+export function selectTasksByStatus(state: TaskState): TasksByStatus {
+	const visible = selectVisibleTasks(state);
+	return {
+		pending: visible.filter((t) => t.status === "pending"),
+		inProgress: visible.filter((t) => t.status === "in_progress"),
+		completed: visible.filter((t) => t.status === "completed"),
+	};
+}
+
+/** Total counts for the overlay heading (`Todos (n/m)`) and `/todos` header. */
+export interface TodoCounts {
+	total: number;
+	pending: number;
+	inProgress: number;
+	completed: number;
+}
+export function selectTodoCounts(state: TaskState): TodoCounts {
+	const groups = selectTasksByStatus(state);
+	return {
+		total: groups.pending.length + groups.inProgress.length + groups.completed.length,
+		pending: groups.pending.length,
+		inProgress: groups.inProgress.length,
+		completed: groups.completed.length,
+	};
+}
+
+/**
+ * Whether any visible task carries a `blockedBy` reference. The overlay uses
+ * this to gate the `#id` prefix on per-task rows — without at least one
+ * `⛓ #N` suffix, the per-row id has no anchor.
+ */
+export function selectShowTaskIds(state: TaskState): boolean {
+	return selectVisibleTasks(state).some((t) => t.blockedBy && t.blockedBy.length > 0);
+}
+
+/**
+ * Resolve a task's subject by id from the live state for renderCall's
+ * accent label. `undefined` when the id is unknown — caller falls back to
+ * `#id` plain rendering.
+ */
+export function selectTaskSubjectById(state: TaskState, id: number): string | undefined {
+	return state.tasks.find((t) => t.id === id)?.subject;
+}
+
+/**
+ * Overlay layout decision. Encapsulates the "drop completed first, then
+ * truncate non-completed tail" rule pre-refactor lived in
+ * `todo-overlay.ts:144-188`. `budget` is the body-slot count (caller passes
+ * `getMaxWidgetLines() - 1` to reserve the heading row); on overflow the
+ * selector reserves one more slot internally for the summary row. Returns
+ * the visible task slice plus the overflow summary parts.
+ */
+export interface OverlayLayout {
+	visible: readonly Task[];
+	hiddenCompleted: number;
+	truncatedTail: number;
+}
+export function selectOverlayLayout(state: TaskState, budget: number): OverlayLayout {
+	const all = selectVisibleTasks(state);
+	if (all.length <= budget) {
+		return { visible: all, hiddenCompleted: 0, truncatedTail: 0 };
+	}
+	const innerBudget = budget - 1;
+	const nonCompleted = all.filter((t) => t.status !== "completed");
+	const totalCompleted = all.length - nonCompleted.length;
+	if (nonCompleted.length <= innerBudget) {
+		const kept = new Set<Task>(nonCompleted);
+		for (const t of all) {
+			if (kept.size >= innerBudget) break;
+			if (t.status === "completed") kept.add(t);
+		}
+		const visible = all.filter((t) => kept.has(t));
+		const shownCompleted = visible.filter((t) => t.status === "completed").length;
+		return { visible, hiddenCompleted: totalCompleted - shownCompleted, truncatedTail: 0 };
+	}
+	const visible = nonCompleted.slice(0, innerBudget);
+	const truncatedTail = nonCompleted.length - innerBudget;
+	return { visible, hiddenCompleted: totalCompleted, truncatedTail };
+}
+
+/**
+ * Helper: whether any visible task is `pending` or `in_progress`. The overlay
+ * uses this to pick the heading icon (`accent`+`●` vs `dim`+`○`).
+ */
+export function selectHasActive(state: TaskState): boolean {
+	return selectVisibleTasks(state).some((t) => t.status === "in_progress" || t.status === "pending");
+}
+
+export const ACTIVE_STATUSES: ReadonlySet<TaskStatus> = new Set(["pending", "in_progress"]);

package/node_modules/@juicesharp/rpiv-todo/state/state-reducer.ts

@@ -0,0 +1,227 @@
+import type { Task, TaskAction, TaskMutationParams, TaskStatus } from "../tool/types.js";
+import { isTransitionValid } from "./invariants.js";
+import type { TaskState } from "./state.js";
+import { detectCycle } from "./task-graph.js";
+
+/**
+ * Reducer outcome. Closed tagged union — adding a new action requires extending
+ * this union AND the response-envelope's `formatContent` switch (compiler-
+ * enforced exhaustive). Mirrors the `Effect` pattern in
+ * `packages/rpiv-ask-user-question/state/state-reducer.ts:14-30`.
+ *
+ * `error` carries the message in-band so callers can pattern-match on
+ * `op.kind === "error"` without a side-channel boolean.
+ */
+export type Op =
+	| { kind: "create"; taskId: number }
+	| { kind: "update"; id: number; fromStatus: TaskStatus; toStatus: TaskStatus; changed: boolean }
+	| { kind: "delete"; id: number; subject: string }
+	| { kind: "list"; statusFilter?: TaskStatus; includeDeleted: boolean }
+	| { kind: "get"; task: Task }
+	| { kind: "clear"; count: number }
+	| { kind: "error"; message: string };
+
+export interface ApplyResult {
+	state: TaskState;
+	op: Op;
+}
+
+function errorResult(state: TaskState, message: string): ApplyResult {
+	return { state, op: { kind: "error", message } };
+}
+
+function sameNumberList(a: number[] | undefined, b: number[] | undefined): boolean {
+	const x = a ?? [];
+	const y = b ?? [];
+	return x.length === y.length && x.every((v, i) => v === y[i]);
+}
+
+function sameRecord(a: Record<string, unknown> | undefined, b: Record<string, unknown> | undefined): boolean {
+	return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+
+/**
+ * Did this `update` change anything? Compares the task before/after the params
+ * are applied. A no-effect update — `status` set to its current value, or any
+ * field re-sent unchanged — returns false, letting the response envelope say
+ * "No change" instead of "Updated #N". Without this, a no-op update is
+ * indistinguishable from a real mutation, which can drive a model to re-issue
+ * the same call in a loop.
+ *
+ * blockedBy is order-sensitive (the reducer preserves insertion order);
+ * metadata round-trips through JSON persistence, so JSON-equality is the
+ * operative notion of "changed".
+ */
+function taskChanged(before: Task, after: Task): boolean {
+	return (
+		before.subject !== after.subject ||
+		before.status !== after.status ||
+		before.description !== after.description ||
+		before.activeForm !== after.activeForm ||
+		before.owner !== after.owner ||
+		!sameNumberList(before.blockedBy, after.blockedBy) ||
+		!sameRecord(before.metadata, after.metadata)
+	);
+}
+
+/**
+ * Pure reducer: (state, action, params) → (state, op). Mirrors the
+ * `applyTaskMutation` of pre-refactor `todo.ts` minus content/details
+ * formatting; the response envelope (`tool/response-envelope.ts`) owns
+ * formatting, the store (`state/store.ts`) owns commit.
+ *
+ * Validation is in-line: structural guards (`subject required`, `id required`,
+ * `at least one mutable field`) plus state-aware checks (transition legality,
+ * dangling/deleted blockedBy, self-block, cycles). Decision: validation stays
+ * in-reducer — see Plan §Decisions §Decision 2.
+ */
+export function applyTaskMutation(state: TaskState, action: TaskAction, params: TaskMutationParams): ApplyResult {
+	switch (action) {
+		case "create": {
+			if (!params.subject?.trim()) {
+				return errorResult(state, "subject required for create");
+			}
+			if (params.blockedBy?.length) {
+				for (const dep of params.blockedBy) {
+					const depTask = state.tasks.find((t) => t.id === dep);
+					if (!depTask) return errorResult(state, `blockedBy: #${dep} not found`);
+					if (depTask.status === "deleted") return errorResult(state, `blockedBy: #${dep} is deleted`);
+				}
+			}
+			const newTask: Task = {
+				id: state.nextId,
+				subject: params.subject,
+				status: "pending",
+			};
+			if (params.description) newTask.description = params.description;
+			if (params.activeForm) newTask.activeForm = params.activeForm;
+			if (params.blockedBy?.length) newTask.blockedBy = [...params.blockedBy];
+			if (params.owner) newTask.owner = params.owner;
+			if (params.metadata) newTask.metadata = { ...params.metadata };
+
+			const newTasks = [...state.tasks, newTask];
+			return {
+				state: { tasks: newTasks, nextId: state.nextId + 1 },
+				op: { kind: "create", taskId: newTask.id },
+			};
+		}
+
+		case "update": {
+			if (params.id === undefined) return errorResult(state, "id required for update");
+			const idx = state.tasks.findIndex((t) => t.id === params.id);
+			if (idx === -1) return errorResult(state, `#${params.id} not found`);
+			const current = state.tasks[idx];
+
+			const hasMutation =
+				params.subject !== undefined ||
+				params.description !== undefined ||
+				params.activeForm !== undefined ||
+				params.status !== undefined ||
+				params.owner !== undefined ||
+				params.metadata !== undefined ||
+				(params.addBlockedBy && params.addBlockedBy.length > 0) ||
+				(params.removeBlockedBy && params.removeBlockedBy.length > 0);
+			if (!hasMutation) return errorResult(state, "update requires at least one mutable field");
+
+			let newStatus = current.status;
+			if (params.status !== undefined) {
+				if (!isTransitionValid(current.status, params.status)) {
+					return errorResult(state, `illegal transition ${current.status} → ${params.status}`);
+				}
+				newStatus = params.status;
+			}
+
+			let newBlockedBy = current.blockedBy ? [...current.blockedBy] : [];
+			if (params.removeBlockedBy?.length) {
+				const toRemove = new Set(params.removeBlockedBy);
+				newBlockedBy = newBlockedBy.filter((dep) => !toRemove.has(dep));
+			}
+			if (params.addBlockedBy?.length) {
+				for (const dep of params.addBlockedBy) {
+					if (dep === current.id) return errorResult(state, `cannot block #${current.id} on itself`);
+					const depTask = state.tasks.find((t) => t.id === dep);
+					if (!depTask) return errorResult(state, `addBlockedBy: #${dep} not found`);
+					if (depTask.status === "deleted") return errorResult(state, `addBlockedBy: #${dep} is deleted`);
+					if (!newBlockedBy.includes(dep)) newBlockedBy.push(dep);
+				}
+				if (detectCycle(state.tasks, current.id, newBlockedBy)) {
+					return errorResult(state, "addBlockedBy would create a cycle in the blockedBy graph");
+				}
+			}
+
+			let newMetadata = current.metadata;
+			if (params.metadata !== undefined) {
+				const merged: Record<string, unknown> = { ...(current.metadata ?? {}) };
+				for (const [k, v] of Object.entries(params.metadata)) {
+					if (v === null) delete merged[k];
+					else merged[k] = v;
+				}
+				newMetadata = Object.keys(merged).length ? merged : undefined;
+			}
+
+			const updated: Task = { ...current, status: newStatus };
+			if (params.subject !== undefined) updated.subject = params.subject;
+			if (params.description !== undefined) updated.description = params.description;
+			if (params.activeForm !== undefined) updated.activeForm = params.activeForm;
+			if (params.owner !== undefined) updated.owner = params.owner;
+			if (newBlockedBy.length) updated.blockedBy = newBlockedBy;
+			else delete updated.blockedBy;
+			if (newMetadata === undefined) delete updated.metadata;
+			else updated.metadata = newMetadata;
+
+			const newTasks = [...state.tasks];
+			newTasks[idx] = updated;
+			return {
+				state: { tasks: newTasks, nextId: state.nextId },
+				op: {
+					kind: "update",
+					id: updated.id,
+					fromStatus: current.status,
+					toStatus: newStatus,
+					changed: taskChanged(current, updated),
+				},
+			};
+		}
+
+		case "list": {
+			return {
+				state,
+				op: {
+					kind: "list",
+					includeDeleted: params.includeDeleted === true,
+					...(params.status !== undefined ? { statusFilter: params.status } : {}),
+				},
+			};
+		}
+
+		case "get": {
+			if (params.id === undefined) return errorResult(state, "id required for get");
+			const task = state.tasks.find((t) => t.id === params.id);
+			if (!task) return errorResult(state, `#${params.id} not found`);
+			return { state, op: { kind: "get", task } };
+		}
+
+		case "delete": {
+			if (params.id === undefined) return errorResult(state, "id required for delete");
+			const idx = state.tasks.findIndex((t) => t.id === params.id);
+			if (idx === -1) return errorResult(state, `#${params.id} not found`);
+			const current = state.tasks[idx];
+			if (current.status === "deleted") return errorResult(state, `#${current.id} is already deleted`);
+			const updated: Task = { ...current, status: "deleted" };
+			const newTasks = [...state.tasks];
+			newTasks[idx] = updated;
+			return {
+				state: { tasks: newTasks, nextId: state.nextId },
+				op: { kind: "delete", id: updated.id, subject: updated.subject },
+			};
+		}
+
+		case "clear": {
+			const count = state.tasks.length;
+			return {
+				state: { tasks: [], nextId: 1 },
+				op: { kind: "clear", count },
+			};
+		}
+	}
+}

package/node_modules/@juicesharp/rpiv-todo/state/state.ts

@@ -0,0 +1,18 @@
+import type { Task } from "../tool/types.js";
+
+/**
+ * Canonical state for the todo tool. Single source of truth — both the reducer
+ * (`state/state-reducer.ts`) and the live store cell (`state/store.ts`) read
+ * this shape. Replay (`state/replay.ts`) returns a fresh `TaskState`; the
+ * lifecycle handlers in `index.ts` write it via `replaceState`.
+ *
+ * The shape is intentionally minimal — no derived caches or runtime cells.
+ * Selectors in `state/selectors.ts` are pure of `TaskState` and own all
+ * derivations (visible/grouped/counted/etc).
+ */
+export interface TaskState {
+	tasks: Task[];
+	nextId: number;
+}
+
+export const EMPTY_STATE: TaskState = { tasks: [], nextId: 1 };

package/node_modules/@juicesharp/rpiv-todo/state/store.ts

@@ -0,0 +1,126 @@
+import type { Task } from "../tool/types.js";
+import { EMPTY_STATE, type TaskState } from "./state.js";
+
+/**
+ * Per-session live state. Pre-refactor this was a single scalar `let state`
+ * cell; it is now a Map partitioned by session id so a detached/child session
+ * (distinct sid) can never read or clobber another session's tasks.
+ *
+ * The Map is the single mutation seam — only `commitState` / `replaceState` /
+ * `evictSession` write it; the reducer (`state/state-reducer.ts`) stays pure.
+ */
+const sessions = new Map<string, TaskState>();
+
+/**
+ * Ctx-less render pointer: which slot do the ctx-free readers (the overlay's
+ * `getSnapshot()`, the tool's `renderCall()`) render? Set once at overlay
+ * creation by the session that first built the overlay (creator-ownership —
+ * see `index.ts`). A *distinct* concept from the three task-state mutation
+ * seams; it is not a 4th writer of task state.
+ */
+let activeRenderSession = "";
+
+/**
+ * Session-id extractor. Structural ctx type (no Pi-runtime import) —
+ * mirrors `replay.ts`'s ctx shape so `state/` stays Pi-import-free. Returns
+ * `… ?? ""` so an unknown/empty session resolves to "" rather than undefined
+ * (keeps the key a plain string for callers and the Phase 2 sid-gate).
+ */
+export function sid(ctx: { sessionManager: { getSessionId(): string } }): string {
+	return ctx.sessionManager.getSessionId() ?? "";
+}
+
+/** Fresh, non-aliasing EMPTY_STATE copy (never returns `EMPTY_STATE.tasks`). */
+function freshState(): TaskState {
+	return { tasks: [...EMPTY_STATE.tasks], nextId: EMPTY_STATE.nextId };
+}
+
+/** Get-or-read a session's slot: the committed slot by identity, or a fresh
+ * EMPTY_STATE copy (not stored) when the slot is absent. */
+function slotFor(sessionId: string): TaskState {
+	return sessions.get(sessionId) ?? freshState();
+}
+
+/**
+ * Live tasks accessor for a session. Returned `readonly Task[]` so callers
+ * (overlay render hook, `/todos` command, `renderCall` subject lookup) cannot
+ * mutate the live slot. Consumers must not cast back.
+ */
+export function getTodos(sessionId: string): readonly Task[] {
+	return slotFor(sessionId).tasks;
+}
+
+export function getNextId(sessionId: string): number {
+	return slotFor(sessionId).nextId;
+}
+
+/** Snapshot accessor used by reducer callers to pass canonical state in. */
+export function getState(sessionId: string): TaskState {
+	return slotFor(sessionId);
+}
+
+/**
+ * Replay seam. Lifecycle handlers in `index.ts` call this on
+ * `session_start` / `session_compact` / `session_tree` after
+ * `replayFromBranch` decodes the latest snapshot, keyed to the session.
+ */
+export function replaceState(sessionId: string, next: TaskState): void {
+	sessions.set(sessionId, next);
+}
+
+/**
+ * Post-reducer commit seam. Tool `execute()` calls this with the reducer's
+ * `state` output to publish the new canonical state to live readers (overlay,
+ * `/todos`, `renderCall`), keyed to the calling session.
+ */
+export function commitState(sessionId: string, next: TaskState): void {
+	sessions.set(sessionId, next);
+}
+
+/** Drop a session's slot on `session_shutdown`. No-op if the slot is absent. */
+export function evictSession(sessionId: string): void {
+	sessions.delete(sessionId);
+}
+
+/**
+ * Ctx-less render reader: the slot the overlay / `renderCall` render.
+ * Resolves to the `activeRenderSession` slot, or a fresh EMPTY_STATE copy when
+ * no foreground has been set yet.
+ */
+export function getRenderState(): TaskState {
+	return slotFor(activeRenderSession);
+}
+
+/** Set the ctx-less render pointer (called at overlay creation in `index.ts`). */
+export function setActiveRenderSession(sessionId: string): void {
+	activeRenderSession = sessionId;
+}
+
+/**
+ * Reads the foreground render pointer — the sid the `index.ts` sid-gate compares
+ * against, and the slot `getRenderState()` resolves to. Distinct from
+ * `setActiveRenderSession` (the writer): Slice 1 only ever *set* the pointer;
+ * Slice 2's gate must also *read* it, and foreground teardown must *clear* it.
+ */
+export function getActiveRenderSession(): string {
+	return activeRenderSession;
+}
+
+/**
+ * Foreground teardown (session_shutdown of the foreground session). Resets the
+ * pointer to "" so the next `hasUI` session_start reclaims the foreground.
+ */
+export function clearActiveRenderSession(): void {
+	activeRenderSession = "";
+}
+
+/**
+ * Test-setup reset. Wired into the global `test/setup.ts` `beforeEach` via
+ * the existing `__resetState` import path. Signature unchanged ⇒ no
+ * `test/setup.ts` edit needed. Clears BOTH the session Map and the render
+ * pointer so filesystem/detect resets start from a clean state.
+ */
+export function __resetState(): void {
+	sessions.clear();
+	activeRenderSession = "";
+}