pi-firecode 0.8.0 → 1.0.0

package/master/list-view.ts

@@ -0,0 +1,129 @@
+/** subagents / subagents_list 的工具行与 /fire-master status 文本：纯投影，不改状态。 */
+import { statSync } from "node:fs";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { formatDuration } from "../format.js";
+import { ToolLine, makeResultRenderer } from "../tools/line.js";
+import type { Part } from "../tools/parts.js";
+import type { WorkerLive } from "./runtime.js";
+import type { WorkerRef, WorkerStatus } from "./state.js";
+
+export const renderSubagentsResult = makeResultRenderer(false);
+const STATUS_WORD = { working: "工作", idle: "空闲", reviewing: "审查" } satisfies Record<WorkerStatus, string>;
+const ACTION_VERB: Record<string, string> = { start: "启动", list: "查看", kill: "移除", send: "发送", interrupt: "中断", review: "审查", tail: "近况", ack: "待命" };
+
+export function subagentsCallParts(args: Record<string, unknown>): Part[] {
+	const action = typeof args.action === "string" ? args.action : "?";
+	const parts: Part[] = [{ text: ACTION_VERB[action] ?? action, bold: true }];
+	const target = optionalText(args.worker);
+	if (target) parts.push({ text: ` ${target}`, color: "accent" });
+	const role = optionalText(args.role);
+	if ((action === "start" || action === "send") && role) parts.push({ text: ` · ${role}`, color: "muted" });
+	const prompt = optionalText(args.prompt)?.split("\n", 1)[0];
+	if (prompt && action === "start") parts.push({ text: ` — ${prompt}`, color: "muted" });
+	return parts;
+}
+
+export type CompactWorker = ReturnType<typeof compactWorker>;
+
+/** 给模型的池快照：只有档案事实。 */
+export function compactWorker(worker: WorkerRef) {
+	return {
+		name: worker.name,
+		role: worker.role,
+		status: worker.status,
+		model: worker.model,
+		thinking: worker.thinking,
+		session: worker.sessionPath,
+		...(worker.interruptedAt ? { interruptedAt: worker.interruptedAt } : {}),
+		...(worker.reviewNeeded ? { reviewNeeded: true } : {}),
+		...(worker.disposition ? { disposition: worker.disposition } : {}),
+	};
+}
+
+/** 展开行用的当前动作：审查进度、落定时刻（reload 后退到会话文件 mtime）或最近的工具。 */
+export function currentWorkerAction(worker: CompactWorker, live: WorkerLive | undefined) {
+	if (worker.status === "reviewing") return live?.reviewProgress && { kind: "review" as const, ...live.reviewProgress };
+	if (worker.status === "idle") {
+		let since = live?.idleAt;
+		try {
+			since ??= statSync(worker.session).mtimeMs;
+		} catch {
+			// 缺失档案仍可 list；真正恢复时由 send 明确报错。
+		}
+		return { kind: "idle" as const, ...(since ? { since } : {}) };
+	}
+	const current = [...(live?.currentTools.values() ?? [])].at(-1);
+	return current ? { kind: "tool" as const, ...current } : undefined;
+}
+
+export function expandedWorkerList(
+	workers: unknown[],
+	theme: ExtensionContext["ui"]["theme"],
+	context: Parameters<typeof renderSubagentsResult>[3],
+) {
+	return {
+		invalidate() {},
+		render(width: number): string[] {
+			return ["", ...workers.flatMap((value) => {
+				const worker = value as Record<string, unknown>;
+				const action = worker.currentAction as {
+					kind?: string;
+					tool?: string;
+					startedAt?: number;
+					since?: number;
+					round?: number;
+					settled?: number;
+					total?: number;
+				} | undefined;
+				const actionParts: Part[] = action?.kind === "tool" && action.tool && action.startedAt
+					? [{
+						text: ` · ${action.tool} · 已 ${formatDuration(Math.max(0, Date.now() - action.startedAt))}`,
+						color: "accent",
+					}]
+					: action?.kind === "idle"
+						? [{
+							text: action.since ? ` · 落定 ${formatDuration(Date.now() - action.since)}前` : " · 已落定",
+							color: "muted",
+						}]
+						: action?.kind === "review"
+							? [{ text: ` · 第 ${action.round} 轮 · 审查者 ${action.settled}/${action.total}`, color: "accent" }]
+							: [];
+				return new ToolLine({
+					label: String(worker.name),
+					value: [
+						{ text: roleStatusText(worker), color: "accent" },
+						...actionParts,
+						{ text: ` · ${String(worker.model).split("/").pop()}/${String(worker.thinking)}`, color: "muted" },
+					],
+					clip: "end",
+					theme,
+					ctx: { ...context, state: {}, expanded: false },
+				}).render(width);
+			})];
+		},
+	};
+}
+
+export function listMeta(workers: unknown[]): Part[] {
+	if (!workers.length) return [{ text: " — 池 0", color: "muted" }];
+	return [{ text: ` — 池 ${workers.length}：${workers.map((value) => {
+		const worker = value as Record<string, unknown>;
+		return `${String(worker.name)} ${roleStatusText(worker)}`;
+	}).join(" · ")}`, color: "muted" }];
+}
+
+export function statusText(workers: WorkerRef[]): string {
+	return workers.length
+		? workers.map((worker) => `${worker.name} ${roleStatusText(worker)} ${worker.model.split("/").pop()}`).join("\n")
+		: "没有子代理";
+}
+
+/** 角色为主的状态投影：「工程师·工作」；档案缺角色时退到纯状态词。 */
+function roleStatusText(worker: { role?: unknown; status?: unknown }): string {
+	const status = STATUS_WORD[worker.status as WorkerStatus] ?? String(worker.status);
+	return worker.role ? `${String(worker.role)}·${status}` : status;
+}
+
+function optionalText(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/master/outbox.ts

@@ -0,0 +1,188 @@
+/**
+ * 事件发件箱：落定事件先以 pending entry 写进主会话，再经 deliver.ts 投递，成功后写 ack；reload 重投差集。
+ * 同一节拍内的落定合并成一条消息。在飞子代理数也在这里算：指挥官在等的 working/reviewing 加上它们的事件还在队列
+ * 或投递中的子代理，所以归零只发生在事件交给指挥官之后。视图起的运行（见 RunOrigin）不算在飞，它的事件只告知不唤醒。
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { deliver, inform, wrapEnvelope } from "../deliver.js";
+import { roundFromEntry } from "../tools/round.js";
+import { MASTER_EVENT_TYPE, withElapsed, type MasterEvent } from "./event-format.js";
+import type { MasterRuntime } from "./runtime.js";
+
+const PENDING_EVENT_TYPE = "firecode-master-pending-event";
+const EVENT_ACK_TYPE = "firecode-master-event-ack";
+const EVENT_RETRY_MS = 5_000;
+/** 指挥官空闲时，从第一条结果入队起最多等这么久就唤醒，即使结果还在陆续到达。 */
+const WAKE_MAX_MS = 6_000;
+
+export interface PendingMasterEvent {
+	id: string;
+	content: string;
+	worker?: string;
+	/** 指挥官没在等这个结果（视图起的运行）：只告知不唤醒，也不计入在飞。 */
+	inform?: true;
+}
+
+export class Outbox {
+	private readonly queued: PendingMasterEvent[] = [];
+	/** 已交给 deliver、尚未确认送达的事件：投递完成前对应子代理仍算在飞。 */
+	private readonly delivering = new Set<PendingMasterEvent>();
+	private flushTimer?: NodeJS.Timeout;
+	private retrying = false;
+	/** 空闲合并窗口里第一条事件入队的时刻。 */
+	private firstQueuedAt?: number;
+	private inFlightScheduled = false;
+
+	constructor(private readonly active: MasterRuntime) {}
+
+	/** 新产出的事件：追加耗时、持久化为 pending、排队投递。 */
+	enqueue(produced: MasterEvent, worker?: string): void {
+		if (this.active.closed) return;
+		const informOnly = worker !== undefined && this.active.live.get(worker)?.origin === "view";
+		const event: PendingMasterEvent = {
+			id: crypto.randomUUID(),
+			content: this.withElapsed(produced, worker),
+			...(worker ? { worker } : {}),
+			...(informOnly ? { inform: true as const } : {}),
+		};
+		try {
+			this.active.setup.pi.appendEntry(PENDING_EVENT_TYPE, event);
+		} catch (error) {
+			this.active.ctx.ui.notify(`子代理结果持久化失败，crash 时可能丢失：${String(error)}`, "warning");
+		}
+		this.push(event);
+	}
+
+	/** reload 重投 pending 与 ack 的差集：正文已带落定当时的耗时，原样再投。 */
+	replayUnacked(ctx: ExtensionContext): void {
+		for (const event of unackedEvents(ctx)) this.push(event);
+	}
+
+	/**
+	 * 在飞 = working/reviewing + 已落定但结果事件还在队列或投递中（投递失败重试期间也算）。
+	 * 落定先改 store、随后才入队事件：同一同步段内合并成一次计算，避免中间闪出一次归零。
+	 */
+	scheduleInFlight(): void {
+		if (this.inFlightScheduled) return;
+		this.inFlightScheduled = true;
+		queueMicrotask(() => {
+			this.inFlightScheduled = false;
+			if (this.active.closed) return;
+			const names = new Set<string>();
+			for (const worker of this.active.store.state.workers)
+				if ((worker.status === "working" || worker.status === "reviewing") && this.active.live.get(worker.name)?.origin !== "view")
+					names.add(worker.name);
+			for (const event of [...this.queued, ...this.delivering]) if (event.worker && !event.inform) names.add(event.worker);
+			this.active.setup.publishInFlight(names.size);
+		});
+	}
+
+	close(): void {
+		clearTimeout(this.flushTimer);
+	}
+
+	/**
+	 * 指挥官在跑：立即投（句缝送达，不打断）。指挥官空闲：每次唤醒都是一个完整回合，陆续到达的一批结果
+	 * 等一个安静窗口合并成一次唤醒——最后一条入队后 wakeQuietMs 内没有新结果才唤醒，从第一条起最多等 WAKE_MAX_MS。
+	 * 只告知的事件不开窗口、立即追加；窗口已开就随那一批唤醒送达。
+	 */
+	private push(event: PendingMasterEvent): void {
+		this.queued.push(event);
+		this.scheduleInFlight();
+		if (this.retrying) return;
+		const quiet = this.active.setup.wakeQuietMs;
+		if (!this.active.ctx.isIdle() || quiet <= 0) {
+			if (!this.flushTimer || this.firstQueuedAt !== undefined) this.schedule(0);
+			return;
+		}
+		if (event.inform) {
+			if (this.firstQueuedAt === undefined) this.schedule(0);
+			return;
+		}
+		this.firstQueuedAt ??= Date.now();
+		this.schedule(Math.min(quiet, Math.max(0, this.firstQueuedAt + WAKE_MAX_MS - Date.now())));
+	}
+
+	private schedule(delay: number): void {
+		clearTimeout(this.flushTimer);
+		this.flushTimer = setTimeout(() => this.flush(), delay);
+		this.flushTimer.unref?.();
+	}
+
+	private flush(): void {
+		const { active } = this;
+		if (active.closed) return;
+		this.flushTimer = undefined;
+		this.retrying = false;
+		this.firstQueuedAt = undefined;
+		if (!this.queued.length) return;
+		const batch = this.queued.splice(0);
+		for (const event of batch) this.delivering.add(event);
+		const send = batch.every((event) => event.inform) ? inform : deliver;
+		send(active.setup.pi, active.ctx, {
+			customType: MASTER_EVENT_TYPE,
+			content: batch.map((event) => wrapEnvelope("firecode_master_event", event.content)).join("\n\n"),
+		}).then(() => {
+			if (active.closed) return;
+			for (const event of batch) this.delivering.delete(event);
+			try {
+				active.setup.pi.appendEntry(EVENT_ACK_TYPE, { ids: batch.map((event) => event.id) });
+			} catch (error) {
+				active.ctx.ui.notify(`子代理结果确认写入失败，reload 后可能重复投递：${String(error)}`, "warning");
+			}
+			for (const event of batch) {
+				if (!event.worker) continue;
+				const worker = active.store.state.workers.find((candidate) => candidate.name === event.worker);
+				if (worker?.status === "idle" && worker.disposition !== "reminded")
+					active.store.dispatch({ type: "UPSERT_WORKER", worker: { ...worker, disposition: "pending" } });
+			}
+			this.scheduleInFlight();
+		}, (error) => {
+			if (active.closed) return;
+			for (const event of batch) this.delivering.delete(event);
+			this.queued.unshift(...batch);
+			active.ctx.ui.notify(`子代理结果投递失败，将自动重试：${String(error)}`, "warning");
+			this.retrying = true;
+			this.schedule(EVENT_RETRY_MS);
+		});
+	}
+
+	/**
+	 * 本次运行耗时 = 这次运行（start/send/review 起点之后）在子代理会话里写下的轮记录之和：fallback 续跑或审查里的
+	 * 修复回合各自成段，合起来才是这次运行。子代理排除了 FireCode（没有轮记录器）或 reload 后起点丢失时省略。
+	 * 读得到：宿主在 prompt 结束前发 agent_settled，审查则先写终态 checkpoint 再释放占用，记录都早于这里的读取。
+	 */
+	private withElapsed(produced: MasterEvent, worker?: string): string {
+		const live = worker === undefined ? undefined : this.active.live.get(worker);
+		const since = live?.runStartedAt;
+		const branch = live?.observed?.session.sessionManager.getBranch() ?? [];
+		const rounds = since === undefined ? [] : branch.flatMap((entry) => {
+			const round = roundFromEntry(entry);
+			return round && round.at >= since ? [round] : [];
+		});
+		const sessionSince = this.active.setup.sessionSince();
+		return withElapsed(produced, {
+			...(rounds.length ? { run: rounds.reduce((total, round) => total + round.elapsed, 0) } : {}),
+			...(sessionSince === undefined ? {} : { task: Date.now() - sessionSince }),
+		});
+	}
+}
+
+function unackedEvents(ctx: ExtensionContext): PendingMasterEvent[] {
+	const pending = new Map<string, PendingMasterEvent>();
+	const acked = new Set<string>();
+	for (const entry of ctx.sessionManager.getEntries()) {
+		if (entry.type !== "custom" || !entry.data || typeof entry.data !== "object") continue;
+		const data = entry.data as Record<string, unknown>;
+		if (entry.customType === PENDING_EVENT_TYPE && typeof data.id === "string" && typeof data.content === "string")
+			pending.set(data.id, {
+				id: data.id,
+				content: data.content,
+				...(typeof data.worker === "string" ? { worker: data.worker } : {}),
+				...(data.inform === true ? { inform: true as const } : {}),
+			});
+		if (entry.customType === EVENT_ACK_TYPE && Array.isArray(data.ids))
+			for (const id of data.ids) if (typeof id === "string") acked.add(id);
+	}
+	return [...pending.values()].filter((event) => !acked.has(event.id));
+}

package/master/prompts/master.zh.md

@@ -1,17 +1,22 @@
-subagents 激活时，你是唯一的指挥官（Master），负责委派与最终验收，把任务推进到交付完成。
+subagents 激活时，你是唯一的指挥官（Master）：亲手把任务推进到交付完成，委派是工具不是职责。终审 diff 与交付裁决始终亲手。
 
-- 派发：role 只使用调研员、工程师、全栈、架构师、设计师、哨兵六个固定词；start 按已配置角色表显式传 role，send 需要换职能时也传 role；thinking 仅在用户明确要求时覆盖角色原子档。供应商额度或计费耗尽、模型不可用、宿主重试用尽的持续 5xx 会自动按该角色 fallback 降级并回报；架构师费用高，启用前必须先征求用户确认。以等待为主的盯守（CI、部署、长测试）使用哨兵。
-- 动手边界：短小明确的活亲手做——单文件小改、数条命令内可完成并验证的任务，委派开销大于任务本身就不委派。委派用于长时间运行、可并行、产生大量中间输出、需要干净上下文或独立验证的任务。终审 diff 与交付裁决始终亲手。
-- 并行：并行实现前先冻结共享边界——接口、共享类型、注册表、schema 由你亲手或单一 Worker 先行落地，其余 Worker 按路径划界同时开跑，每个共享文件只有一个写者，工作说明写明各自路径；集成以测试门裁决。
+- 动手边界：委派换来的是几块大工作同时推进，代价是每个 Worker 几十秒的冷启动、整体被最慢的一块拖住、最后还要汇总；你的 codemode 本身就能并行调工具、过滤输出。能拆成几块、每块单独都要做很久（十几分钟以上）的工作，并行委派；几分钟内能在主会话用并行脚本做完的，即使是调研或审计，也亲手做。按互不重叠的范围（文件、模块、对象）拆，各块工作量相近；不让几个 Worker 按关注点读同一份代码，也不把同一件工作按写代码、写测试、审查拆给不同 Worker。派出去的部分不再亲手重做。事件末尾的已用时间用来判断还值不值得并行。
+- 派发：按角色表的适用场景选 role；start 必须显式传 role，send 需要换职能时也传 role；thinking 仅在用户明确要求时覆盖角色原子档。工作说明只给指针——检出路径、工单号与相关提交、本票特有约束——不复述工单正文，Worker 自己读工单。Worker 续派到另一个检出时 send 带 cwd。
+- 并行：相互无阻塞边的工作默认并行派发；并行实现前先冻结共享边界——接口、共享类型、注册表、schema 由你亲手或单一 Worker 先行落地，其余 Worker 按路径划界同时开跑，每个共享文件只有一个写者，工作说明写明各自路径；集成以测试门裁决。
 - 工单：项目存在工单库时，每次派发前按约定认领工单、对齐他人工单状态，并基于最新代码开工；新问题由你决策开新工单或交给上下文合适的在场 Worker 顺手解决，Worker 不开单。无工单库则以用户验收为交付边界。
-- 实现标准：实现类工作说明要求 Worker 先读 implement 技能（~/.agents/skills/matt/implement）再动手；你终审时按同一标准裁决。
-- 收割：调研与盯守 Worker 收割要点后立即 kill；实现 Worker 保留到收口。计划产物存在时，其维护责任随指挥权归你。
+- 实现标准：Worker 按 implement 技能实现；你终审时按同一标准裁决，并核对三件事：验收测试验的是需求而非实现、红的原因是尚未实现、实现提交未触碰验收测试；缺一项退回。
+- 收割：调研与盯守 Worker 收割要点后立即 kill。计划产物存在时，其维护责任随指挥权归你。
 - 调研衔接：执行档模型的聚焦探索（读代码定位、方案设计）直接 send 续派原 Worker 执行，现场就是工作上下文。廉价档或高噪声调研（大量搜索、日志、死路）只收割结构化线索（事实、路径、候选、证据来源、未决问题），核实后另派执行 Worker，不复用 transcript。
-- 投递：Worker 结果、中断与审查终态会自动送达；tail 仅用于按需读取执行细节。
-- 何时审查：复杂且影响大的实现，以及无法靠窄测可靠验收的任务，需要对抗性审查，在 start 时传 review:true；其余任务省略。
-- 如何启动：review:true 只是在任务开始时标记“这个任务完成后需要审查”，不会自动启动审查。这个标记不会因 send、reload、中断或失败而丢失，审查结束前不能 ack。Worker 返回结果并完成验证后，指挥官主动执行 review，才会开始对抗性审查。任务开始时没有标记 review:true，也可以在 Worker 空闲后主动执行 review；如果整个任务已经放弃，直接 kill。
-- 审查过程：review 会在原 Worker 会话中启动。独立模型读取 Worker 的工作记录，核对相关文件和验证结果。发现问题时，审查意见会交回同一个 Worker 核实和修复，然后再次审查；审查通过、顾问决定停止或达到最大轮数后结束。审查通过时仍可能附带不阻塞交付的建议，由指挥官判断是否需要继续处理。
-- 审查收尾：审查通过但附带的非阻塞建议确有必要解决时，在原 Worker 会话收口干净再 ack。
-- 交付：终审 diff 后，重要改动亲手 dogfood 试用；完全符合原则才 PR 与合并，看到发布成功后关闭工单并同步状态。合并冲突按 resolving-merge-conflicts 技能处理。
+- 投递：Worker 结果、中断与审查终态会自动送达（陆续返回的一批会合并成一次唤醒）；派发后手头没有亲手可做的活就结束回合等送达，不用 sleep、tail 或 subagents_list 轮询等结果。tail 仅用于按需读取执行细节。
+- 等待：你直接与用户对话，单次工具调用累计阻塞不超过 60 秒的 sleep、wait 或 watch（含串联多个 sleep、gh run watch），否则这段时间用户无法和你沟通；更长的等待派哨兵执行或放后台，回来再查结果。
+- 收到结果：界面已用一行把每个结果给用户看了。同批还有子代理在跑、这条结果不需要你此刻动作时，本回合不输出任何文字（不写“X 已完成”“继续等”之类的进度话），直接结束回合；等这一批全部返回再给用户一次汇总。需要你动作（失败、要续派、要拍板）就直接动作，只说动作和理由，不复述结果原文。
+- 标题带“（你在子代理视图里直接派的）”的结果是用户在子代理视图里直接跟它说的（正文“你说：”是原话）：你没在等它，所以它不唤醒你，随下一回合到达；用户已亲眼看过，不复述。
+- `<firecode_review>` 信封来自你自己这个会话的 fire-review（审查的是你的改动），与子代理无关；子代理的审查终态只经 `<firecode_master_event>` 送达。
+- 对用户说人话：不转述池快照里的内部字段与状态词（disposition、待发落、处置状态、working/idle 之类），只说结果、风险和下一步。
+- 对抗性审查是什么：review 动作起的是内建的 fire-review 状态机，不是另派 Worker 看代码，也不要手工模拟。它在原 Worker 会话里跑：多个独立模型并行读该 Worker 的完整工作记录、核对文件、跑只读验证，各自出 PASS 或带证据的 FAIL；连续失败到阈值召顾问模型仲裁继续还是叫停。FAIL 的发现自动回流给同一个 Worker 修复，修完进下一轮，直到通过、顾问叫停或轮数用尽，终态自动送达。通过时仍可能附带不阻塞交付的建议。
+- 何时与怎么审：复杂且影响大的实现，以及无法靠窄测可靠验收的任务，start 时传 review:true；其余省略。review:true 只登记审查义务，不自动开审——它不因 send、reload、中断或失败丢失，未履行就不能 ack。Worker 返回结果并完成验证后由你发起 review；没登记义务的票也可以在 Worker 空闲时主动审；整票放弃直接 kill。
+- 交付：顺序是审查通过 → 非阻塞建议确有必要就在原 Worker 会话收口 → ack → 终审 diff，重要改动亲手或派子代理 dogfood 试用 → 推送、开 PR 与合并（本地工单库则合回主干）。ack 之前禁止推送与开 PR，draft 也不行——提前开 PR 只换来几分钟 CI 并行，代价是打回重修、CI 重跑和 PR 噪音。CI 与发布等待派哨兵执行项目的上线等待入口（项目 AGENTS.md 指明），一次阻塞到终态后转述。看到发布成功后关闭工单并同步状态。
+- 收口：清理调试产物、检出与本地栈（用项目的拆检出入口）、因此失效的文档和测试，并行指挥官的除外；实现 Worker 保留到用户验收通过，验出问题就地续派。
+- 汇报：给用户的收尾汇报第一句说交付状态（已上线、待合并或待你验收）和用户此刻要做的事，并列出还没收口的：在跑或保留的子代理、未合并的分支、未删的检出；验证只说没覆盖到的和失败的，跑过的命令与退出码不复述。
 
-调用样板：start {"worker":"fix-auth","role":"工程师","prompt":"自包含工作说明"}；send {"worker":"fix-auth","role":"架构师","prompt":"自包含工作说明"}。
+调用样板：start {"worker":"fix-auth","role":"工程师","prompt":"检出 <路径>，实现工单 #<n>；本票约束：…"}；send {"worker":"fix-auth","prompt":"后续说明"}；续派到新检出：send {"worker":"fix-auth","prompt":"…","cwd":"<新检出路径>"}。

package/master/prompts/worker.zh.md

@@ -1 +1 @@
-你是指挥官委派的 Worker，只在当前 checkout 内完成工作说明。验证改动并报告结果、证据与遗留风险；无法完成或验证时如实报告阻塞原因和现场，不得假成功。Git 操作限于本地且仅覆盖自己修改的路径。
+你是指挥官委派的 Worker，只在当前 checkout 内完成工作说明。工作说明关联工单或要求实现时，动手前先读 implement 技能并按其步骤交付证据。验证改动并报告结果、证据与遗留风险；无法完成或验证时如实报告阻塞原因和现场，不得假成功。Git 操作限于本地且仅覆盖自己修改的路径。你是委派出去的子代理，不直接与用户对话：任务需要的长命令（sleep、长测试、构建、盯守）照常前台执行；等待后台测试、构建或服务时，用一次带超时的阻塞等待直到它结束，不分段轮询；指挥官需要时会中断你。回合只在交付物完成或真正被阻塞时结束：不以宣布下一步、询问要不要继续、列出并不阻塞后续工作的待决事项或阶段性汇报结束回合；盯守类任务等到工作说明定义的终态才回复。

package/master/role.ts

@@ -2,7 +2,12 @@ import { AsyncLocalStorage } from "node:async_hooks";
 
 export type SubsessionRole = "worker" | "observer" | "reviewer" | "advisor";
 
-const ROLE = new AsyncLocalStorage<SubsessionRole>();
+// pi 的扩展加载器（jiti，moduleCache: false）在子会话 cwd 变化或宿主 reload 后会重新
+// 求值整个模块图：模块级变量在两份拷贝间互不相通，角色标记必须挂在进程唯一的 globalThis
+// 上，否则新拷贝读不到 spawn 侧设置的角色，watcher/master 会级联注册进子会话。
+const ROLE_KEY = Symbol.for("firecode.subsession-role");
+const shared = globalThis as Record<symbol, AsyncLocalStorage<SubsessionRole> | undefined>;
+const ROLE = (shared[ROLE_KEY] ??= new AsyncLocalStorage<SubsessionRole>());
 
 export function currentSubsessionRole(): SubsessionRole | undefined {
 	return ROLE.getStore();