pi-firecode 0.8.1 → 1.0.0

package/master/run.ts

@@ -0,0 +1,315 @@
+/**
+ * 回合编排：打开 Worker 会话、跑一个回合、按终态落定（成功/失败/中断/fallback 续跑）、审查监视与中断续跑提醒。
+ * 所有 await 之后的写回经 runtime.current/commit 重读档案：kill 赢过迟到的异步写回。
+ */
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { MasterRole, ModelAtom } from "../config.js";
+import { wrapEnvelope } from "../deliver.js";
+import { clip, firstSentence, textOf } from "../format.js";
+import { outcomeOfEntry, readReviewOutcome, reviewProgressOf, type ReviewOutcome } from "../review/outcome.js";
+import { masterEvent, type MasterEvent } from "./event-format.js";
+import { assembleWorkerPrompt } from "./prompt.js";
+import type { MasterRuntime, WorkerLive } from "./runtime.js";
+import type { WorkerRef } from "./state.js";
+
+export const WORKER_TOOLS = ["read", "bash", "edit", "write"];
+/** Worker 跟随指挥官是否启用 codemode；on/only 由 Worker 会话读到的同一份 settings 决定，不另传。 */
+const CODEMODE_TOOL = "codemode";
+const FAULT_SUMMARY_WIDTH = 80;
+/** 算作“有输出”的子会话事件：模型 token 流与工具执行；活动列表据此判卡住。 */
+const OUTPUT_EVENTS = new Set(["message_update", "tool_execution_start", "tool_execution_update", "tool_execution_end"]);
+
+interface WorkerTerminal {
+	text: string;
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+/** 新建（start）或恢复（send/review 冷启动）Worker 会话；会话路径是档案身份的唯一事实源。 */
+export async function spawnWorker(active: MasterRuntime, worker: WorkerRef, resume: boolean): Promise<AgentSession> {
+	const { pool, exclusions } = active.setup;
+	const model = await pool.resolveModel(worker.model);
+	active.assertOpen();
+	const spawned = await pool.spawn({
+		cwd: worker.cwd ?? process.cwd(),
+		role: "worker",
+		model,
+		thinking: worker.thinking,
+		tools: active.setup.pi.getActiveTools().includes(CODEMODE_TOOL) ? [...WORKER_TOOLS, CODEMODE_TOOL] : WORKER_TOOLS,
+		excludeExtensions: exclusions,
+		systemPrompt: { mode: "append", text: assembleWorkerPrompt(active.setup.workerPrompt(), worker.name) },
+		contextFiles: true,
+		persistence: { type: "file", sessionPath: worker.sessionPath, ...(resume ? { resume: true } : {}) },
+	});
+	if (active.closed) {
+		await spawned.dispose();
+		active.assertOpen();
+	}
+	return spawned.session;
+}
+
+export async function openWorkerSession(active: MasterRuntime, worker: WorkerRef): Promise<AgentSession> {
+	active.assertOpen();
+	return active.setup.pool.getSession(worker.sessionPath) ?? spawnWorker(active, worker, true);
+}
+
+/** 投影当前动作、卡住判定与审查进度的唯一订阅。 */
+export function observeWorker(active: MasterRuntime, worker: WorkerRef, session: AgentSession): void {
+	active.observe(worker, session, (live, event) => {
+		if (OUTPUT_EVENTS.has(event.type)) live.lastOutputAt = Date.now();
+		if (event.type === "tool_execution_start")
+			live.currentTools.set(event.toolCallId, { tool: event.toolName, args: event.args, startedAt: Date.now() });
+		if (event.type === "tool_execution_end") live.currentTools.delete(event.toolCallId);
+		if (event.type === "entry_appended") live.reviewProgress = reviewProgressOf(event.entry) ?? live.reviewProgress;
+	});
+}
+
+/** resolve 即回合已在飞：宿主 prompt 的前置阶段仍报空闲，期间 abort 会被丢弃，interrupt 必须晚于 preflight。 */
+export async function runWorker(active: MasterRuntime, worker: WorkerRef, session: AgentSession, prompt: string): Promise<void> {
+	// 启动回合的路径都经这里：准备期间被 kill 的不调模型、不留热会话。
+	active.current(worker);
+	observeWorker(active, worker, session);
+	const live = active.liveOf(worker.name);
+	const run = Symbol(worker.name);
+	live.run = run;
+	const mine = () => !active.closed && active.live.get(worker.name) === live && live.run === run;
+	let terminal: WorkerTerminal | undefined;
+	const unsubscribeTerminal = session.subscribe((event) => {
+		if (mine() && event.type === "agent_end") terminal = captureWorkerTerminal(event.messages);
+	});
+	const settled = async (error?: unknown) => {
+		unsubscribeTerminal();
+		if (!mine()) return;
+		const stranded = session.clearQueue().steering;
+		if (stranded.length) active.outbox.enqueue(masterEvent.stranded(worker.name, stranded), worker.name);
+		live.run = undefined;
+		if (live.interruptedRun === run) {
+			live.interruptedRun = undefined;
+			settleInterrupted(active, worker);
+			return;
+		}
+		if (terminal?.stopReason === "error" && error === undefined) {
+			await resumeWithFallback(active, worker, session, terminal, faultSummary(terminal));
+			return;
+		}
+		settleWorker(active, worker, terminal, error);
+	};
+	const inflight = Promise.withResolvers<void>();
+	void session.prompt(prompt, { preflightResult: () => inflight.resolve() })
+		.then(() => settled(), settled)
+		.finally(() => inflight.resolve());
+	await inflight.promise;
+}
+
+function settleInterrupted(active: MasterRuntime, identity: WorkerRef): void {
+	const current = active.find(identity);
+	if (!current) return;
+	const interrupted: WorkerRef = { ...current, status: "idle", interruptedAt: Date.now() };
+	active.store.dispatch({ type: "UPSERT_WORKER", worker: interrupted });
+	active.markIdle(interrupted, { kind: "interrupted" }, interrupted.interruptedAt);
+	active.outbox.enqueue(masterEvent.interrupted(identity.name, current.reviewNeeded === true, takeViewPrompts(active, identity)), identity.name);
+}
+
+/**
+ * 会话重载打断的回合：恢复后满时限仍未续派就提醒指挥官；按档案里的中断时刻补算剩余时间。指挥官自己 interrupt 的不提醒。
+ * 只提醒、不代发“继续”：工作说明归指挥官，插件盲续会复活它已作废的任务。
+ */
+export function armInterruptReminder(active: MasterRuntime, worker: WorkerRef): void {
+	if (active.closed) return;
+	const live = active.liveOf(worker.name);
+	clearTimeout(live.interruptTimer);
+	const delay = Math.max(0, (worker.interruptedAt ?? Date.now()) + active.setup.interruptResumeMs - Date.now());
+	live.interruptTimer = setTimeout(() => {
+		if (active.closed || active.live.get(worker.name) !== live) return;
+		live.interruptTimer = undefined;
+		const current = active.find(worker);
+		if (!current?.interruptedAt || current.interruptedAt !== worker.interruptedAt) return;
+		active.store.dispatch({ type: "UPSERT_WORKER", worker: { ...current, disposition: "reminded" } });
+		active.outbox.enqueue(masterEvent.resumeReminder(worker.name), worker.name);
+	}, delay);
+	live.interruptTimer.unref?.();
+}
+
+/**
+ * 任何 error 终态都沿角色链切换，不按关键词分类故障：供应商措辞多变，关键词白名单实测一次未命中，分类也不改变决策。
+ * 瞬时限流与 Claude 令牌换发在 error 之前已由宿主重试和 claude-sub 自愈处理。由插件而非宿主做：宿主不知道角色与档案。
+ */
+async function resumeWithFallback(
+	active: MasterRuntime,
+	identity: WorkerRef,
+	session: AgentSession,
+	terminal: WorkerTerminal,
+	reason: string,
+): Promise<void> {
+	const current = active.current(identity);
+	const configuredRole = active.setup.roster.find((entry) => entry.role === current.role);
+	if (!configuredRole)
+		return settleWorker(active, current, terminal, new Error(`${terminalFailure(terminal)}\n角色 ${current.role} 已不在角色表，无法 fallback`));
+	const fallback = nextFallback(configuredRole, current);
+	if (!fallback)
+		return settleWorker(active, current, terminal, new Error(`${terminalFailure(terminal)}\n角色 ${current.role} 的 fallback 链已用尽`));
+	try {
+		const model = await active.setup.pool.resolveModel(fallback.model);
+		active.assertOpen();
+		await session.setModel(model);
+		active.assertOpen();
+		session.setThinkingLevel(fallback.thinking);
+		const switched = active.commit(current, (latest) => ({ ...latest, ...fallback, status: "working" }));
+		const from = modelAtomText(current);
+		const to = modelAtomText(fallback);
+		active.outbox.enqueue(masterEvent.modelSwitched(current.name, from, to, reason), current.name);
+		await runWorker(active, switched, session, fallbackResumePrompt(from, to, reason));
+	} catch (error) {
+		const failure = `${terminalFailure(terminal)}\nfallback 切换失败：${error instanceof Error ? error.message : String(error)}`;
+		settleWorker(active, current, terminal, new Error(failure));
+	}
+}
+
+function settleWorker(active: MasterRuntime, identity: WorkerRef, terminal: WorkerTerminal | undefined, error?: unknown): void {
+	const current = active.find(identity);
+	if (!current) return;
+	const failure = error instanceof Error ? error.message : error === undefined ? terminalFailure(terminal) : String(error);
+	const idle: WorkerRef = { ...current, status: "idle" };
+	active.store.dispatch({ type: "UPSERT_WORKER", worker: idle });
+	// 活动列表展开行显示结果首句（失败是错误首句），不是千篇一律的“已返回”。
+	active.markIdle(idle, failure ? { kind: "failed", note: firstSentence(failure) } : { kind: "done", note: firstSentence(terminal!.text) });
+	const obligation = current.reviewNeeded === true;
+	const event: MasterEvent = failure
+		? masterEvent.failed(identity.name, failure, obligation, takeViewPrompts(active, identity))
+		: masterEvent.returned(identity.name, terminal!.text, obligation, takeViewPrompts(active, identity));
+	active.outbox.enqueue(event, identity.name);
+}
+
+/** 起审：在原 Worker 会话里跑 /fire-review，终态经 review/outcome.ts 读取后落定并投递。 */
+export function monitorAndSettleReview(active: MasterRuntime, target: WorkerRef, session: AgentSession, previousRunId: string | undefined): void {
+	const live = active.liveOf(target.name);
+	const reviewing = () => {
+		const current = active.closed || active.live.get(target.name) !== live ? undefined : active.find(target);
+		return current?.status === "reviewing" ? current : undefined;
+	};
+	void monitorReview(session, target.sessionPath, previousRunId).then(
+		(outcome) => {
+			const current = reviewing();
+			if (!current) return;
+			const { reviewNeeded: _needed, ...fulfilled } = current;
+			const idle: WorkerRef = { ...(outcome.status === "passed" || outcome.status === "stopped" ? fulfilled : current), status: "idle" };
+			active.store.dispatch({ type: "UPSERT_WORKER", worker: idle });
+			active.markIdle(idle, reviewOutcomeRow(outcome));
+			active.outbox.enqueue(masterEvent.review(target.name, outcome, latestAssistantText(session.messages)), target.name);
+		},
+		(error) => {
+			const current = reviewing();
+			if (!current) return;
+			const idle: WorkerRef = { ...current, status: "idle" };
+			active.store.dispatch({ type: "UPSERT_WORKER", worker: idle });
+			active.markIdle(idle, { kind: "failed", note: "审查未完成" });
+			active.outbox.enqueue(masterEvent.reviewIncomplete(target.name, String(error)), target.name);
+		},
+	);
+}
+
+/** 这次运行里视图说过的话交给落定事件后清空：下一次运行另算。 */
+function takeViewPrompts(active: MasterRuntime, worker: WorkerRef): string[] {
+	const live = active.liveOf(worker.name);
+	const prompts = live.viewPrompts;
+	live.viewPrompts = [];
+	return prompts;
+}
+
+export function reviewRunId(outcome: ReviewOutcome): string | undefined {
+	return "runId" in outcome ? outcome.runId : undefined;
+}
+
+function monitorReview(session: AgentSession, sessionPath: string, previousRunId: string | undefined): Promise<ReviewOutcome> {
+	return new Promise((resolve, reject) => {
+		let done = false;
+		let unsubscribe = () => {};
+		const fail = (error: unknown) => {
+			if (done) return;
+			done = true;
+			unsubscribe();
+			reject(error);
+		};
+		const finish = (outcome: ReviewOutcome) => {
+			if (done) return;
+			const runId = reviewRunId(outcome);
+			if (outcome.status !== "error"
+				&& (!runId || runId === previousRunId || outcome.status === "in_progress" || outcome.status === "none")) return;
+			done = true;
+			unsubscribe();
+			resolve(outcome);
+		};
+		// 只看刚追加的那条记录，不每条都重读整份 JSONL；回合结束时再读一次文件兜底。
+		unsubscribe = session.subscribe((event) => {
+			const outcome = event.type === "entry_appended" ? outcomeOfEntry(event.entry) : undefined;
+			if (outcome) finish(outcome);
+		});
+		void session.prompt("/fire-review").then(
+			() => {
+				const outcome = readReviewOutcome(sessionPath);
+				const runId = reviewRunId(outcome);
+				if (outcome.status === "error") return finish(outcome);
+				if (!runId || runId === previousRunId) return fail(new Error("fire-review 审查未启动"));
+				finish(outcome);
+			},
+			fail,
+		);
+	});
+}
+
+/** 审查落定在活动列表上的结局：只有通过算完成，停止与未完成都是要指挥官看的失败行。 */
+function reviewOutcomeRow(outcome: ReviewOutcome): WorkerLive["outcome"] {
+	if (outcome.status === "passed") return { kind: "done", note: "审查通过" };
+	return { kind: "failed", note: outcome.status === "stopped" ? "审查停止" : "审查未完成" };
+}
+
+function captureWorkerTerminal(
+	messages: Array<{ role: string; content?: unknown; stopReason?: string; errorMessage?: string }>,
+): WorkerTerminal | undefined {
+	const message = messages.findLast((candidate) => candidate.role === "assistant");
+	if (!message) return undefined;
+	return {
+		text: textOf(message.content),
+		...(message.stopReason ? { stopReason: message.stopReason } : {}),
+		...(message.errorMessage ? { errorMessage: message.errorMessage } : {}),
+	};
+}
+
+function terminalFailure(terminal: WorkerTerminal | undefined): string | undefined {
+	if (!terminal) return "回合结束但未产生 assistant 终态";
+	if (terminal.stopReason === "error") return terminal.errorMessage || "供应商返回未知错误";
+	if (terminal.stopReason === "aborted") return `回合意外中止：${terminal.errorMessage || "供应商未提供原因"}`;
+	if (!terminal.text) return "回合结束但未产生回复";
+	return undefined;
+}
+
+function faultSummary(terminal: WorkerTerminal): string {
+	const message = terminal.errorMessage?.trim();
+	if (!message) return "供应商返回未知错误";
+	const [first = message] = message.split(/(?<=[.。!！?？])\s|\n/u);
+	return clip(first.trim(), FAULT_SUMMARY_WIDTH);
+}
+
+function latestAssistantText(messages: Array<{ role: string; content?: unknown }>): string {
+	return textOf(messages.findLast((candidate) => candidate.role === "assistant")?.content);
+}
+
+function nextFallback(role: MasterRole, worker: WorkerRef): ModelAtom | undefined {
+	const chain: ModelAtom[] = [role, ...role.fallback];
+	let index = chain.findIndex((atom) => atom.model === worker.model && atom.thinking === worker.thinking);
+	if (index < 0) index = chain.findIndex((atom) => atom.model === worker.model);
+	return chain[index + 1];
+}
+
+export function modelAtomText(atom: Pick<ModelAtom, "model" | "thinking">): string {
+	return `${atom.model}/${atom.thinking}`;
+}
+
+/** 首次续派前置的现场核对提示。 */
+export function resumeCheckPrompt(): string {
+	return wrapEnvelope("firecode_master_event", "上次被外部中断，先核对 git status 与现场再继续，避免重复执行已经发生的副作用。");
+}
+
+function fallbackResumePrompt(from: string, to: string, reason: string): string {
+	return wrapEnvelope("firecode_master_event", `供应商故障，已切换 ${from}→${to}（${reason}）。沿用当前会话与原工作说明，从中断处继续，不要重复已经完成的副作用。`);
+}

package/master/runtime.ts

@@ -0,0 +1,259 @@
+/**
+ * 一个指挥官会话的运行时：持久化档案（store）、按名字索引的 Worker 运行时事实（live）、事件发件箱与活动列表。
+ * 运行时事实只在进程内；档案与 JSONL 才是身份与续派的事实源。会话关闭后 closed 置位，迟到的异步续延一律作废。
+ */
+import { getAgentDir, type AgentSession, type AgentSessionEvent, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MasterRole } from "../config.js";
+import { HEAT_COLORS, paint } from "../flame.js";
+import type { ReviewProgress } from "../review/outcome.js";
+import { ActivityList, visibleRows, type ActivityFacts, type SettledFact } from "./activity-list.js";
+import { Outbox } from "./outbox.js";
+import { openWorkerView } from "./worker-view.js";
+import type { InProcessSessionPool } from "./spawn.js";
+import { MasterStore, masterStatePath, type MasterState, type WorkerRef } from "./state.js";
+
+/** 注册时定下、跨会话不变的配置与依赖。 */
+export interface MasterSetup {
+	pi: ExtensionAPI;
+	pool: InProcessSessionPool;
+	roster: MasterRole[];
+	exclusions: string[];
+	/** Worker 系统提示；提示词文件坏了时抛错。 */
+	workerPrompt(): string;
+	/** fire-review 不可用的原因；可用时为 undefined。 */
+	reviewGate?: string;
+	interruptResumeMs: number;
+	/** 指挥官空闲时合并唤醒的安静窗口（见 outbox.ts）。 */
+	wakeQuietMs: number;
+	/** 在飞子代理数的唯一发布口（跨会话保持上次发布值以便配对）。 */
+	publishInFlight(count: number): void;
+	/** 本段会话进行中的起点（busy.ts 的 since，与上边框计时同一事实）；歇下时为 undefined。 */
+	sessionSince(): number | undefined;
+}
+
+export interface CurrentTool {
+	tool: string;
+	args: unknown;
+	startedAt: number;
+}
+
+/**
+ * 这次运行是谁派的。在飞数的定义是“指挥官在等结果的运行”：用户在全过程视图里直接派的运行指挥官并不在等，
+ * 不计入在飞数（主会话不因它进入进行中、不产生主会话轮记录），落定事件只告知不唤醒；
+ * 指挥官在这次运行中途又 send 给它时转为指挥官的（它从此在等）。
+ */
+export type RunOrigin = "master" | "view";
+
+/** 一个 Worker 名下的全部运行时事实；kill 时整条删除。 */
+export interface WorkerLive {
+	/** start 已占名但档案尚未落盘。 */
+	starting?: true;
+	/** send/review 的准备过程单飞。 */
+	transitioning?: true;
+	/** 当前回合的令牌；落定回调只认自己的令牌。 */
+	run?: symbol;
+	/** interrupt 标记的回合：它落定时按中断处理。 */
+	interruptedRun?: symbol;
+	interruptTimer?: NodeJS.Timeout;
+	/** 本次运行（start/send/review 投递）的起点：活动列表的实时耗时，以及从子代理会话里挑出属于这次运行的轮记录。 */
+	runStartedAt?: number;
+	/** 这次运行里用户在子代理全过程视图直接说的话；落定事件据此注明来源。 */
+	viewPrompts: string[];
+	origin: RunOrigin;
+	/** 最近一次输出（模型 token 或工具事件），活动列表据此判卡住。 */
+	lastOutputAt?: number;
+	currentTools: Map<string, CurrentTool>;
+	reviewProgress?: ReviewProgress;
+	/** 最近一次落定的时刻：池起释放计时、列表“落定 X 前”与活动列表冻结耗时共用这一份。 */
+	idleAt?: number;
+	/** 活动列表上的落定结局；ack 清掉失败与被中断，完成留到 kill。 */
+	outcome?: Omit<SettledFact, "at">;
+	observed?: { session: AgentSession; sessionPath: string; unsubscribe: () => void };
+}
+
+const LIST_WIDGET_KEY = "firecode-master-list";
+/** 边框身份：纯文字，子代理状态由输入框上方的活动列表承担。 */
+const MASTER_IDENTITY = paint(HEAT_COLORS.orange, "指挥官");
+
+export class MasterRuntime {
+	readonly store: MasterStore;
+	readonly outbox: Outbox;
+	readonly live = new Map<string, WorkerLive>();
+	/** 最近取出的启动序；接着档案里已有的最大值，恢复后新 start 仍排在后面。 */
+	private launchSeq: number;
+	private list?: ActivityList;
+	private closedValue = false;
+	private readonly stopReleaseWatch: () => void;
+	/** 子代理会话被接上订阅（冷启动或重开）时通知：全过程视图据此在第一条事件之前接上自己的订阅。 */
+	private readonly sessionListeners = new Set<(name: string) => void>();
+	/** 子代理被移除（kill 或启动失败撤票）时通知：全过程视图据此显示已移除。 */
+	private readonly removedListeners = new Set<(name: string) => void>();
+
+	constructor(readonly setup: MasterSetup, public ctx: ExtensionContext, restored?: MasterState) {
+		this.outbox = new Outbox(this);
+		this.store = new MasterStore(masterStatePath(getAgentDir(), ctx.sessionManager.getSessionId()), restored, () => this.render());
+		this.launchSeq = Math.max(0, ...this.store.state.workers.map((worker) => worker.launch));
+		// 池空闲释放热会话后放掉订阅：不再持有已关闭的会话。
+		this.stopReleaseWatch = setup.pool.onRelease((sessionPath) => {
+			for (const live of this.live.values())
+				if (live.observed?.sessionPath === sessionPath) this.unobserve(live);
+		});
+		ctx.ui.setWidget(LIST_WIDGET_KEY, (tui, theme) => {
+			this.list = new ActivityList(tui, theme, () => this.activityFacts(),
+				() => visibleRows(tui.terminal?.rows), (name) => void openWorkerView(this, name));
+			return this.list;
+		}, { placement: "aboveEditor" });
+	}
+
+	get closed(): boolean {
+		return this.closedValue;
+	}
+
+	assertOpen(): void {
+		if (this.closedValue) throw new Error("Master 会话已替换，取消旧会话动作");
+	}
+
+	/** 事实变化后的唯一重绘入口：在飞数、边框身份与活动列表。 */
+	render(): void {
+		if (this.closedValue) return;
+		this.outbox.scheduleInFlight();
+		this.ctx.ui.setStatus("master", MASTER_IDENTITY);
+		this.list?.sync();
+	}
+
+	/** 新的一轮（人类输入）开始：活动列表的展开收起。 */
+	collapseList(): void {
+		this.list?.collapse();
+	}
+
+	liveOf(name: string): WorkerLive {
+		let live = this.live.get(name);
+		if (!live) this.live.set(name, live = { currentTools: new Map(), viewPrompts: [], origin: "master" });
+		return live;
+	}
+
+	/** start 同步段占名并取启动序（并发 start 越过后续 await 的先后不定，序号必须在此取）。 */
+	reserve(name: string): { live: WorkerLive; launch: number } {
+		const live: WorkerLive = { currentTools: new Map(), viewPrompts: [], origin: "master", starting: true };
+		this.live.set(name, live);
+		return { live, launch: ++this.launchSeq };
+	}
+
+	/**
+	 * 移除子代理的唯一入口：删名下全部运行时事实与档案，档案确有这一票时通知订阅方。
+	 * 运行时事实只删属于 expected 的那一条（kill 后同名重开的新票不受影响）。
+	 */
+	remove(name: string, expected = this.live.get(name)): void {
+		const live = this.live.get(name);
+		if (live && live === expected) {
+			clearTimeout(live.interruptTimer);
+			if (live.observed) this.unobserve(live);
+			this.live.delete(name);
+		}
+		const before = this.store.state;
+		if (this.store.dispatch({ type: "REMOVE_WORKER", name }) === before) return;
+		for (const notify of this.removedListeners) notify(name);
+	}
+
+	/** await 之后的唯一重读点：档案已被 kill（或同名换票）就释放热会话并放弃本次动作。 */
+	current(identity: Pick<WorkerRef, "name" | "sessionPath">): WorkerRef {
+		this.assertOpen();
+		const current = this.store.state.workers.find((worker) => worker.name === identity.name);
+		if (current?.sessionPath === identity.sessionPath) return current;
+		void this.setup.pool.dispose(identity.sessionPath);
+		throw new Error(`${identity.name} 已被 kill，取消本次动作`);
+	}
+
+	/** await 之后的写回只经这里：基于重读的最新档案做函数式更新，不拿 await 前的快照覆盖。 */
+	commit(identity: Pick<WorkerRef, "name" | "sessionPath">, update: (current: WorkerRef) => WorkerRef): WorkerRef {
+		const next = update(this.current(identity));
+		this.store.dispatch({ type: "UPSERT_WORKER", worker: next });
+		return next;
+	}
+
+	/** 同步读：档案仍是这一票时返回，否则 undefined（落定回调用，不抛）。 */
+	find(identity: Pick<WorkerRef, "name" | "sessionPath">): WorkerRef | undefined {
+		const current = this.store.state.workers.find((worker) => worker.name === identity.name);
+		return current?.sessionPath === identity.sessionPath ? current : undefined;
+	}
+
+	/** Worker 闲下来的唯一登记点：记落定时刻与结局，池据此起释放计时。 */
+	markIdle(worker: WorkerRef, outcome: WorkerLive["outcome"], at = Date.now()): void {
+		const live = this.liveOf(worker.name);
+		live.idleAt = at;
+		live.outcome = outcome;
+		live.currentTools.clear();
+		live.reviewProgress = undefined;
+		this.setup.pool.markIdle(worker.sessionPath);
+	}
+
+	/** 开始一次运行（start/send/review）：起点与来源归这一次，旧的中断提醒作废。 */
+	beginRun(name: string, origin: RunOrigin = "master"): void {
+		const live = this.liveOf(name);
+		clearTimeout(live.interruptTimer);
+		live.interruptTimer = undefined;
+		live.runStartedAt = Date.now();
+		live.viewPrompts = [];
+		live.origin = origin;
+	}
+
+	/** 每个 Worker 只挂一个会话订阅；换了会话（释放后重开）才重挂。 */
+	observe(worker: WorkerRef, session: AgentSession, listener: (live: WorkerLive, event: AgentSessionEvent) => void): void {
+		this.assertOpen();
+		const live = this.liveOf(worker.name);
+		if (live.observed?.session === session) return;
+		if (live.observed) this.unobserve(live);
+		const unsubscribe = session.subscribe((event) => {
+			if (!this.closedValue && this.live.get(worker.name) === live) listener(live, event);
+		});
+		live.observed = { session, sessionPath: worker.sessionPath, unsubscribe };
+		for (const notify of this.sessionListeners) notify(worker.name);
+	}
+
+	onWorkerSession(listener: (name: string) => void): () => void {
+		this.sessionListeners.add(listener);
+		return () => this.sessionListeners.delete(listener);
+	}
+
+	onWorkerRemoved(listener: (name: string) => void): () => void {
+		this.removedListeners.add(listener);
+		return () => this.removedListeners.delete(listener);
+	}
+
+	close(): void {
+		this.closedValue = true;
+		this.stopReleaseWatch();
+		for (const live of this.live.values()) {
+			clearTimeout(live.interruptTimer);
+			if (live.observed) this.unobserve(live);
+		}
+		this.live.clear();
+		this.outbox.close();
+		this.list?.dispose();
+		this.ctx.ui.setWidget(LIST_WIDGET_KEY, undefined);
+		this.ctx.ui.setStatus("master", undefined);
+	}
+
+	private unobserve(live: WorkerLive): void {
+		live.observed?.unsubscribe();
+		live.observed = undefined;
+	}
+
+	/** 活动列表的输入：档案加运行时事实的一次投影（全过程视图按同一顺序换子代理）。 */
+	activityFacts(): ActivityFacts {
+		const workers = this.store.state.workers;
+		const byPath = <T>(pick: (live: WorkerLive) => T | undefined) => new Map(workers.flatMap((worker) => {
+			const live = this.live.get(worker.name);
+			const value = live && pick(live);
+			return value === undefined ? [] : [[worker.sessionPath, value] as const];
+		}));
+		return {
+			workers,
+			currentTools: byPath((live) => (live.currentTools.size ? live.currentTools : undefined)),
+			reviewProgress: byPath((live) => live.reviewProgress),
+			runStartedAt: byPath((live) => live.runStartedAt),
+			lastOutputAt: byPath((live) => live.lastOutputAt),
+			settled: byPath((live) => (live.outcome && live.idleAt !== undefined ? { ...live.outcome, at: live.idleAt } : undefined)),
+		};
+	}
+}