ytdb-slate 0.1.0

package/extension/prompt-docs.ts

@@ -0,0 +1,49 @@
+/**
+ * Role-guideline prompt docs (config: orchestratorPromptDocs / workerPromptDocs).
+ *
+ * Projects may split role-specific guidance into per-role markdown docs
+ * that get injected into the matching role's system prompt only —
+ * orchestrator docs while orchestrator mode is on (mode.ts), worker docs
+ * into every worker session (worker.ts). Each role's always-loaded surface
+ * then carries only what that role needs (context-as-RAM discipline, P10).
+ * Both lists default to EMPTY, and callers gate the reads behind project
+ * trust — an untrusted project never gets its files injected into prompts.
+ * Missing/unreadable files and malformed config entries are skipped
+ * silently, so a configured setup works before the docs exist.
+ */
+
+import { readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+
+/**
+ * Read each doc (relative paths resolved against cwd) and return one
+ * formatted prompt block per file that exists; missing/unreadable/empty
+ * files and non-string entries are skipped without error. Blocks carry NO
+ * separators — each caller joins/prefixes for its own prompt shape.
+ */
+export function loadPromptDocs(cwd: string, paths: string[]): string[] {
+	// The declared type is a runtime lie: callers pass values straight from
+	// user-edited slate.json, so a whole-value shape error (e.g.
+	// orchestratorPromptDocs: 42, or a string — which for...of would iterate
+	// char by char) reaches this loop unchecked. Malformed config must never
+	// break prompt assembly, so bail out to "no docs" instead of throwing.
+	if (!Array.isArray(paths)) return [];
+	const blocks: string[] = [];
+	for (const path of paths) {
+		// The whole per-entry body is guarded: paths come from user-edited
+		// slate.json, and a throw escaping here (e.g. resolve() on a
+		// non-string entry) would abort the caller's prompt hook — on the
+		// orchestrator path that drops the ENTIRE systemPrompt modification
+		// for the turn, doctrine included.
+		try {
+			if (typeof path !== "string") continue;
+			const file = resolve(cwd, path);
+			const content = readFileSync(file, "utf8").trim();
+			if (!content) continue;
+			blocks.push(`# Role guidelines (injected from ${relative(cwd, file)})\n\n${content}`);
+		} catch {
+			/* missing/unreadable doc → skip */
+		}
+	}
+	return blocks;
+}

package/extension/render.ts

@@ -0,0 +1,138 @@
+/**
+ * TUI rendering for the `thread` tool (ExecPlan M3).
+ *
+ * Collapsed: one-line header (status icon, thread, task preview), streaming
+ * progress lines while running, Key Findings digest + usage when done.
+ * Expanded (Ctrl+O): full episode markdown + usage stats.
+ */
+
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { UsageStats } from "./threads.ts";
+
+// Minimal structural theme type (avoids depending on exact Theme export).
+type ThemeLike = {
+	fg: (color: string, text: string) => string;
+	bold: (text: string) => string;
+};
+
+interface ThreadCallArgs {
+	thread?: string;
+	name?: string;
+	task?: string;
+	context?: string[];
+	model?: string;
+}
+
+interface ThreadDetails {
+	threadId?: string;
+	threadName?: string;
+	episodeId?: string;
+	status?: "ok" | "failed";
+	lines?: string[];
+	usage?: UsageStats;
+	done?: boolean;
+}
+
+function formatTokens(n: number): string {
+	if (n < 1000) return String(n);
+	if (n < 1_000_000) return `${Math.round(n / 1000)}k`;
+	return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+function formatUsage(u: UsageStats | undefined): string {
+	if (!u) return "";
+	const parts: string[] = [];
+	if (u.turns) parts.push(`${u.turns} turn${u.turns > 1 ? "s" : ""}`);
+	if (u.input) parts.push(`↑${formatTokens(u.input)}`);
+	if (u.output) parts.push(`↓${formatTokens(u.output)}`);
+	if (u.cost) parts.push(`$${u.cost.toFixed(4)}`);
+	if (u.contextTokens) parts.push(`ctx:${formatTokens(u.contextTokens)}`);
+	return parts.join(" ");
+}
+
+function contentText(result: { content?: Array<{ type: string; text?: string }> }): string {
+	return (result.content ?? [])
+		.filter((c) => c.type === "text")
+		.map((c) => c.text ?? "")
+		.join("\n");
+}
+
+/** Extract one `## Section` body from episode markdown. */
+function extractSection(episode: string, section: string): string {
+	const re = new RegExp(`^## ${section}\\s*$`, "m");
+	const m = re.exec(episode);
+	if (!m) return "";
+	const rest = episode.slice(m.index + m[0].length);
+	const next = rest.search(/^## /m);
+	return (next >= 0 ? rest.slice(0, next) : rest).trim();
+}
+
+export function renderThreadCall(args: ThreadCallArgs, theme: ThemeLike) {
+	let text = theme.fg("toolTitle", theme.bold("thread "));
+	text += theme.fg("accent", args.thread ?? (args.name ? `new:"${args.name}"` : "new"));
+	if (args.model) text += theme.fg("muted", ` [${args.model}]`);
+	if (args.context && args.context.length > 0) text += theme.fg("muted", ` ⇐ ${args.context.join(", ")}`);
+	const task = (args.task ?? "").replace(/\s+/g, " ");
+	text += `\n  ${theme.fg("dim", task.length > 100 ? `${task.slice(0, 100)}...` : task)}`;
+	return new Text(text, 0, 0);
+}
+
+export function renderThreadResult(
+	result: { content?: Array<{ type: string; text?: string }>; details?: unknown },
+	options: { expanded: boolean; isPartial?: boolean },
+	theme: ThemeLike,
+) {
+	const details = (result.details ?? {}) as ThreadDetails;
+	const name = details.threadName ?? details.threadId ?? "thread";
+
+	// Streaming: show live progress lines.
+	if (options.isPartial || !details.done) {
+		const lines = (details.lines ?? []).slice(-6);
+		let text = `${theme.fg("warning", "⏳")} ${theme.fg("toolTitle", theme.bold(name))} ${theme.fg("muted", "running")}`;
+		for (const line of lines) {
+			text += `\n  ${theme.fg("dim", line.length > 110 ? `${line.slice(0, 110)}...` : line)}`;
+		}
+		return new Text(text, 0, 0);
+	}
+
+	const failed = details.status === "failed";
+	const icon = failed ? theme.fg("error", "✗") : theme.fg("success", "✓");
+	const episodeLabel = `${details.episodeId ?? "episode"}${failed ? " FAILED" : ""}`;
+	const usageStr = formatUsage(details.usage);
+	const full = contentText(result);
+
+	if (options.expanded) {
+		const container = new Container();
+		container.addChild(
+			new Text(
+				`${icon} ${theme.fg("toolTitle", theme.bold(name))} ${theme.fg(failed ? "error" : "accent", episodeLabel)}`,
+				0,
+				0,
+			),
+		);
+		container.addChild(new Spacer(1));
+		container.addChild(new Markdown(full.trim(), 0, 0, getMarkdownTheme()));
+		if (usageStr) {
+			container.addChild(new Spacer(1));
+			container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+		}
+		return container;
+	}
+
+	// Collapsed: headline + Key Findings digest (or Open Issues when failed).
+	let text = `${icon} ${theme.fg("toolTitle", theme.bold(name))} ${theme.fg(failed ? "error" : "accent", episodeLabel)}`;
+	const digestSection = failed ? "Open Issues" : "Key Findings";
+	const digest = extractSection(full, digestSection);
+	if (digest) {
+		const digestLines = digest.split("\n").slice(0, 8);
+		text += `\n${theme.fg("muted", `— ${digestSection}:`)}`;
+		for (const line of digestLines) {
+			text += `\n  ${theme.fg("toolOutput", line.length > 110 ? `${line.slice(0, 110)}...` : line)}`;
+		}
+		if (digest.split("\n").length > 8) text += `\n  ${theme.fg("muted", "…")}`;
+	}
+	if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
+	text += `\n${theme.fg("muted", `(${keyHint("app.tools.expand", "to expand")})`)}`;
+	return new Text(text, 0, 0);
+}

package/extension/state.ts

@@ -0,0 +1,191 @@
+/**
+ * Slate state: thread/episode records, session-scoped persistence.
+ *
+ * Persistence model (ExecPlan D9): every mutation appends a full snapshot as a
+ * custom session entry ("slate-state") via pi.appendEntry. On session_start the
+ * store rebuilds from the LAST such entry on the current branch, so state
+ * follows pi's session tree across restart/resume/fork. Thread session files
+ * and episode files live on disk under <config dir>/slate/ and are validated
+ * on restore.
+ */
+
+import { existsSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export interface ThreadRecord {
+	id: string; // "t1", "t2", ...
+	name: string;
+	sessionFile: string; // absolute path to worker .jsonl ("" until first dispatch completes session creation)
+	status: "idle" | "running";
+	model?: string; // "provider/id" when overridden at creation
+	episodeIds: string[];
+	episodeSeq: number; // monotonic per-thread episode counter
+	createdAt: number;
+	updatedAt: number;
+}
+
+export interface EpisodeRecord {
+	id: string; // "t1.e2"
+	threadId: string;
+	task: string;
+	status: "ok" | "failed";
+	file: string; // absolute path to episode .md
+	createdAt: number;
+}
+
+export interface SlateSnapshot {
+	threads: ThreadRecord[];
+	episodes: EpisodeRecord[];
+	orchestratorMode: boolean;
+	paused: boolean;
+	workerCostUsd: number;
+	carriedCostUsd: number; // orchestrator spend banked from ancestor sessions at handoff
+}
+
+export interface SlateConfig {
+	episodeModel?: string; // "provider/id" for the episode compressor (D5)
+	workerTools?: string[];
+	maxConcurrent?: number;
+	pauseThresholdPercent?: number; // orchestrator context budget for auto-pause (default 40)
+	orchestratorModeDefault?: boolean; // seed orchestrator mode ON for fresh interactive sessions (unsaved until first real mutation)
+	orchestratorPromptDocs?: string[]; // role-guideline docs appended to the orchestrator prompt (cwd-relative paths, default none)
+	workerPromptDocs?: string[]; // role-guideline docs appended to worker system prompts (cwd-relative paths, default none)
+	workflow?: { draftPRs?: boolean }; // draftPRs: umbrella draft PRs are part of the pre-implementation gates (default false)
+	doctrineExtraPath?: string; // cwd-relative markdown appended to the orchestrator doctrine (project-doctrine section)
+	reviewPerspectivesPath?: string; // cwd-relative markdown with additional project-specific review perspectives
+}
+
+export class SlateStore {
+	threads = new Map<string, ThreadRecord>();
+	episodes = new Map<string, EpisodeRecord>();
+	orchestratorMode = false;
+	/** When true (context budget exceeded) ThreadManager rejects NEW dispatches. */
+	paused = false;
+	/**
+	 * Cumulative USD spend of worker threads this session. Includes the episode
+	 * compressor's LLM calls, so the "workers" figure shown in the widget covers
+	 * compression spend too.
+	 */
+	workerCostUsd = 0;
+	/** Orchestrator spend inherited from ancestor sessions across handoffs. */
+	carriedCostUsd = 0;
+	/** Invoked after every save/restore; used by mode.ts to refresh the widget. */
+	onDidChange?: () => void;
+
+	constructor(private pi: ExtensionAPI) {}
+
+	nextThreadId(): string {
+		let max = 0;
+		for (const id of this.threads.keys()) {
+			const m = /^t(\d+)$/.exec(id);
+			if (m) max = Math.max(max, Number(m[1]));
+		}
+		return `t${max + 1}`;
+	}
+
+	snapshot(): SlateSnapshot {
+		return {
+			threads: [...this.threads.values()].map((t) => ({ ...t, status: "idle" as const })),
+			episodes: [...this.episodes.values()],
+			orchestratorMode: this.orchestratorMode,
+			paused: this.paused,
+			workerCostUsd: this.workerCostUsd,
+			carriedCostUsd: this.carriedCostUsd,
+		};
+	}
+
+	save(): void {
+		this.pi.appendEntry("slate-state", this.snapshot() as unknown as Record<string, unknown>);
+		this.onDidChange?.();
+	}
+
+	/** Rebuild from the last slate-state entry on the current branch. */
+	restore(ctx: ExtensionContext): void {
+		let latest: SlateSnapshot | undefined;
+		for (const entry of ctx.sessionManager.getBranch()) {
+			const e = entry as { type: string; customType?: string; data?: unknown };
+			if (e.type === "custom" && e.customType === "slate-state" && e.data) {
+				latest = e.data as SlateSnapshot;
+			}
+		}
+		this.adoptSnapshot(latest, ctx);
+		// Cost counters are NOT branch-scoped like the records above: money never
+		// un-spends, and dispatches on now-abandoned branches were still billed.
+		// Take the MAX over ALL slate-state entries (both counters are monotonic
+		// within a session file) so a branch switch cannot roll them back.
+		for (const entry of ctx.sessionManager.getEntries()) {
+			const e = entry as {
+				type: string;
+				customType?: string;
+				data?: { workerCostUsd?: number; carriedCostUsd?: number };
+			};
+			if (e.type !== "custom" || e.customType !== "slate-state") continue;
+			this.workerCostUsd = Math.max(this.workerCostUsd, e.data?.workerCostUsd ?? 0);
+			this.carriedCostUsd = Math.max(this.carriedCostUsd, e.data?.carriedCostUsd ?? 0);
+		}
+	}
+
+	/**
+	 * Replace all state with a snapshot (undefined clears), dropping records
+	 * whose files vanished. Shared by restore() and the cross-session handoff
+	 * adoption in handoff.ts.
+	 */
+	adoptSnapshot(latest: SlateSnapshot | undefined, ctx: ExtensionContext): void {
+		this.threads.clear();
+		this.episodes.clear();
+		this.orchestratorMode = false;
+		this.paused = false;
+		this.workerCostUsd = 0;
+		this.carriedCostUsd = 0;
+		if (!latest) return;
+
+		this.orchestratorMode = latest.orchestratorMode ?? false;
+		this.paused = latest.paused ?? false;
+		// ?? 0: old snapshots lack the cost fields.
+		this.workerCostUsd = latest.workerCostUsd ?? 0;
+		this.carriedCostUsd = latest.carriedCostUsd ?? 0;
+		const dropped: string[] = [];
+		for (const t of latest.threads ?? []) {
+			if (t.sessionFile && !existsSync(t.sessionFile)) {
+				dropped.push(`thread ${t.id} (${t.name}): missing ${t.sessionFile}`);
+				continue;
+			}
+			this.threads.set(t.id, { ...t, status: "idle" });
+		}
+		for (const e of latest.episodes ?? []) {
+			if (!existsSync(e.file)) {
+				dropped.push(`episode ${e.id}: missing ${e.file}`);
+				continue;
+			}
+			if (!this.threads.has(e.threadId)) continue;
+			this.episodes.set(e.id, e);
+		}
+		// Prune episode ids that did not survive.
+		for (const t of this.threads.values()) {
+			t.episodeIds = t.episodeIds.filter((id) => this.episodes.has(id));
+		}
+		if (dropped.length > 0 && ctx.hasUI) {
+			ctx.ui.notify(`slate: dropped stale records:\n${dropped.join("\n")}`, "warning");
+		}
+		this.onDidChange?.();
+	}
+}
+
+/**
+ * Orchestrator spend recorded in the session file: billed LINEAGE spend —
+ * summed over ALL entries including abandoned branches (forked/cloned sessions
+ * thus inherit parent-file spend as their own). EXCLUDES pi-internal LLM calls
+ * stored as non-message entries (compaction, branch summarization).
+ * Shared by the widget (mode.ts) and handoff carry (handoff.ts).
+ */
+export function orchestratorCostUsd(ctx: ExtensionContext): number {
+	let cost = 0;
+	for (const entry of ctx.sessionManager.getEntries()) {
+		// Loose cast + optional chaining: tolerate malformed/legacy entries.
+		const e = entry as { type: string; message?: { role?: string; usage?: { cost?: { total?: number } } } };
+		if (e.type === "message" && e.message?.role === "assistant") {
+			cost += e.message.usage?.cost?.total ?? 0;
+		}
+	}
+	return cost;
+}

package/extension/threads.ts

@@ -0,0 +1,311 @@
+/**
+ * ThreadManager: dispatch lifecycle (ExecPlan M1).
+ *
+ * One dispatch = one bounded action on one thread:
+ *   resolve/create thread → per-thread FIFO queue → global semaphore →
+ *   open/reuse worker session → inject context episodes → prompt →
+ *   compress the new messages into an episode (ok or FAILED) → update store.
+ *
+ * Parallelism happens ACROSS threads (pi runs sibling tool calls
+ * concurrently); a single thread is a serial work stream (D9).
+ */
+
+import { readFileSync } from "node:fs";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { compressEpisode } from "./episodes.ts";
+import type { EpisodeRecord, SlateConfig, SlateStore, ThreadRecord } from "./state.ts";
+import { openWorkerSession, type WorkerSession } from "./worker.ts";
+
+export interface DispatchOptions {
+	threadId?: string;
+	name?: string;
+	task: string;
+	contextEpisodeIds?: string[];
+	model?: string;
+	tools?: string[];
+}
+
+export interface UsageStats {
+	turns: number;
+	input: number;
+	output: number;
+	cost: number;
+	contextTokens: number;
+}
+
+export interface DispatchProgress {
+	threadId: string;
+	threadName: string;
+	lines: string[];
+	usage: UsageStats;
+	done: boolean;
+	status?: "ok" | "failed";
+}
+
+export interface DispatchResult {
+	episodeText: string;
+	episode: EpisodeRecord;
+	thread: ThreadRecord;
+	usage: UsageStats;
+}
+
+class Semaphore {
+	private waiters: Array<() => void> = [];
+	private active = 0;
+	constructor(private limit: number) {}
+	async acquire(): Promise<void> {
+		if (this.active < this.limit) {
+			this.active++;
+			return;
+		}
+		// Wait for a slot transferred directly by release(); do NOT increment
+		// here — the releasing side keeps `active` unchanged when handing over.
+		await new Promise<void>((r) => this.waiters.push(r));
+	}
+	release(): void {
+		const next = this.waiters.shift();
+		if (next) {
+			// Transfer the slot to the next waiter without decrementing:
+			// the slot never becomes observable as free.
+			next();
+		} else {
+			this.active--;
+		}
+	}
+}
+
+export class ThreadManager {
+	private live = new Map<string, WorkerSession>();
+	private queues = new Map<string, Promise<unknown>>();
+	private semaphore: Semaphore;
+
+	constructor(
+		private store: SlateStore,
+		private config: SlateConfig,
+	) {
+		this.semaphore = new Semaphore(config.maxConcurrent ?? 4);
+	}
+
+	getConfig(): SlateConfig {
+		return this.config;
+	}
+
+	async dispatch(
+		opts: DispatchOptions,
+		ctx: ExtensionContext,
+		signal: AbortSignal | undefined,
+		onProgress?: (p: DispatchProgress) => void,
+	): Promise<DispatchResult> {
+		// Pause blocks only NEW dispatches — in-flight ones already hold their
+		// queue slot and are allowed to finish (their episodes still get written).
+		if (this.store.paused) {
+			throw new Error(
+				"Slate is paused for handoff: the context budget was exceeded and new dispatches are rejected. " +
+					"Reply to the user with a handoff brief (overall goal, per-thread state with episode ids, immediate next actions) " +
+					"and ask them to run /slate handoff [focus] to continue in a fresh session.",
+			);
+		}
+		const thread = this.resolveThread(opts);
+
+		// Per-thread FIFO: chain onto the previous dispatch for this thread.
+		const prev = this.queues.get(thread.id) ?? Promise.resolve();
+		const run = prev
+			.catch(() => undefined) // a failed predecessor must not poison the queue
+			.then(() => this.runDispatch(thread, opts, ctx, signal, onProgress));
+		this.queues.set(thread.id, run);
+		return run;
+	}
+
+	private resolveThread(opts: DispatchOptions): ThreadRecord {
+		if (opts.threadId) {
+			const existing = this.store.threads.get(opts.threadId);
+			if (!existing) {
+				const known = [...this.store.threads.keys()].join(", ") || "none";
+				throw new Error(`Unknown thread "${opts.threadId}". Known threads: ${known}. Omit "thread" to create a new one.`);
+			}
+			return existing;
+		}
+		const id = this.store.nextThreadId();
+		const record: ThreadRecord = {
+			id,
+			name: opts.name?.trim() || id,
+			sessionFile: "",
+			status: "idle",
+			model: opts.model,
+			episodeIds: [],
+			episodeSeq: 0,
+			createdAt: Date.now(),
+			updatedAt: Date.now(),
+		};
+		this.store.threads.set(id, record);
+		this.store.save();
+		return record;
+	}
+
+	private buildPrompt(opts: DispatchOptions): string {
+		const contextIds = opts.contextEpisodeIds ?? [];
+		if (contextIds.length === 0) return opts.task;
+		const parts: string[] = ["## Context from prior episodes (injected by the orchestrator)", ""];
+		for (const id of contextIds) {
+			const episode = this.store.episodes.get(id);
+			if (!episode) throw new Error(`Unknown episode "${id}". Known: ${[...this.store.episodes.keys()].join(", ") || "none"}`);
+			parts.push(readFileSync(episode.file, "utf8").trim(), "");
+		}
+		parts.push("## Action", "", opts.task);
+		return parts.join("\n");
+	}
+
+	private async runDispatch(
+		thread: ThreadRecord,
+		opts: DispatchOptions,
+		ctx: ExtensionContext,
+		signal: AbortSignal | undefined,
+		onProgress?: (p: DispatchProgress) => void,
+	): Promise<DispatchResult> {
+		const prompt = this.buildPrompt(opts); // may throw on unknown episode ids (before any state change)
+		await this.semaphore.acquire();
+		try {
+			return await this.runDispatchInner(thread, opts, prompt, ctx, signal, onProgress);
+		} finally {
+			this.semaphore.release();
+		}
+	}
+
+	private async runDispatchInner(
+		thread: ThreadRecord,
+		opts: DispatchOptions,
+		prompt: string,
+		ctx: ExtensionContext,
+		signal: AbortSignal | undefined,
+		onProgress?: (p: DispatchProgress) => void,
+	): Promise<DispatchResult> {
+		const usage: UsageStats = { turns: 0, input: 0, output: 0, cost: 0, contextTokens: 0 };
+		const lines: string[] = [];
+		const emit = (done: boolean, status?: "ok" | "failed") =>
+			onProgress?.({ threadId: thread.id, threadName: thread.name, lines, usage, done, status });
+
+		let session: WorkerSession | undefined;
+		let unsubscribe: (() => void) | undefined;
+		let onAbort: (() => void) | undefined;
+		let messagesBefore = 0;
+		let status: "ok" | "failed" = "ok";
+		let diagnostics: string | undefined;
+
+		try {
+			thread.status = "running";
+			thread.updatedAt = Date.now();
+			this.store.save();
+			emit(false);
+
+			session = this.live.get(thread.id);
+			if (!session) {
+				session = await openWorkerSession({
+					ctx,
+					sessionFile: thread.sessionFile || undefined,
+					model: thread.model,
+					tools: opts.tools ?? this.config.workerTools,
+					promptDocs: this.config.workerPromptDocs,
+				});
+				this.live.set(thread.id, session);
+				if (!thread.sessionFile && session.sessionFile) {
+					thread.sessionFile = session.sessionFile;
+					this.store.save();
+				}
+			}
+
+			messagesBefore = session.messages.length;
+
+			unsubscribe = session.subscribe((event: { type: string; [k: string]: unknown }) => {
+				if (event.type === "tool_execution_start") {
+					lines.push(`→ ${(event as unknown as { toolName: string }).toolName}`);
+					emit(false);
+				} else if (event.type === "message_end") {
+					const msg = (event as unknown as { message: { role: string; content?: Array<{ type: string; text?: string }>; usage?: { input?: number; output?: number; totalTokens?: number; cost?: { total?: number } }; stopReason?: string; errorMessage?: string } }).message;
+					if (msg.role !== "assistant") return;
+					usage.turns++;
+					usage.input += msg.usage?.input ?? 0;
+					usage.output += msg.usage?.output ?? 0;
+					usage.cost += msg.usage?.cost?.total ?? 0;
+					usage.contextTokens = msg.usage?.totalTokens ?? usage.contextTokens;
+					const text = (msg.content ?? [])
+						.filter((c) => c.type === "text")
+						.map((c) => c.text ?? "")
+						.join(" ")
+						.trim();
+					if (text) lines.push(text.length > 120 ? `${text.slice(0, 120)}...` : text);
+					if (msg.stopReason === "error" || msg.stopReason === "aborted") {
+						status = "failed";
+						diagnostics = msg.errorMessage ?? `worker stopReason: ${msg.stopReason}`;
+					}
+					emit(false);
+				}
+			});
+
+			if (signal?.aborted) throw new Error("aborted before worker start");
+			onAbort = () => void session?.abort();
+			signal?.addEventListener("abort", onAbort, { once: true });
+
+			await session.prompt(prompt);
+
+			if (signal?.aborted) {
+				status = "failed";
+				diagnostics = diagnostics ?? "aborted by orchestrator";
+			}
+		} catch (error) {
+			status = "failed";
+			diagnostics = error instanceof Error ? error.message : String(error);
+		} finally {
+			unsubscribe?.();
+			if (onAbort) signal?.removeEventListener("abort", onAbort);
+		}
+
+		const actionMessages = session ? session.messages.slice(messagesBefore) : [];
+
+		const episodeId = `${thread.id}.e${++thread.episodeSeq}`;
+		const compressed = await compressEpisode({
+			ctx,
+			episodeId,
+			threadId: thread.id,
+			threadName: thread.name,
+			task: opts.task,
+			status,
+			diagnostics,
+			messages: actionMessages as unknown[],
+			workerModel: session?.model ? { provider: session.model.provider, id: session.model.id } : undefined,
+			configuredModel: this.config.episodeModel,
+			signal: signal?.aborted ? undefined : signal,
+		});
+
+		const episode: EpisodeRecord = {
+			id: episodeId,
+			threadId: thread.id,
+			task: opts.task,
+			status,
+			file: compressed.file,
+			createdAt: Date.now(),
+		};
+		this.store.episodes.set(episodeId, episode);
+		thread.episodeIds.push(episodeId);
+		thread.status = "idle";
+		thread.updatedAt = Date.now();
+		// Accumulate session-wide worker spend (worker turns + episode compressor)
+		// BEFORE save so it persists with the snapshot.
+		this.store.workerCostUsd += usage.cost + compressed.costUsd;
+		this.store.save();
+
+		emit(true, status);
+
+		return { episodeText: compressed.text, episode, thread, usage };
+	}
+
+	disposeAll(): void {
+		for (const session of this.live.values()) {
+			try {
+				session.dispose();
+			} catch {
+				/* ignore */
+			}
+		}
+		this.live.clear();
+	}
+}