@buyi1net/pi-toolkit 0.0.1

package/modules/subagents/src/team.ts

@@ -0,0 +1,232 @@
+/**
+ * 持久团队 MVP 的父会话侧协议文件(全部位于父会话 artifactDir 下):
+ *
+ *   team-roster.json       成员名册:每个 member 的运行状态(idle/dispatched/offline)。
+ *                          父进程是唯一写者(成员侧只读),读-改-写 + tmp/rename 原子落盘。
+ *   team-mailbox/<name>/   每成员一个收件箱目录;成员侧 team_send 原子投递
+ *                          (<uuid>.msg.json,tmp+rename),父侧 round watcher 认领并经
+ *                          RPC steer 注入目标成员后删除。
+ *
+ * 诚实边界(README 同步):fire-and-forget——发送成功只代表落盘成功,不保证
+ * 目标在线期间消费;成员 offline 后残留消息不自动补投。无阻塞 request/response,
+ * 天然不存在 A↔B 互等死锁。
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { debugLog } from "./diagnostics.ts";
+import { normalizeSubagentName } from "./names.ts";
+
+/** 成员每轮结束写入的 sidecar(subagent-done.ts 的 agent_end 写入)。 */
+export interface RoundSignal {
+  version: 1;
+  name: string;
+  /** 进程内递增轮次序号(成员侧内存计数,仅供诊断)。 */
+  seq: number;
+  at: number;
+}
+
+// ── 派单轮关联 nonce ──────────────────────────────────────────────────
+// team_dispatch 的每一轮生成唯一 roundId,经 steer 文本携带进入成员会话
+// (成员侧无需感知);父侧 round watcher 在 .round 认领时检索会话用户消息,
+// 只有确实出现过本次派单 marker 的 .round 才属于派单轮——自发轮(成员间
+// 消息/ask 回复触发)的 .round 不会错误消费派单结果(见 index.ts
+// watchMemberRound 的关联判定)。首轮(spawn 时的初始 prompt)同样带 marker,
+// 保证语义统一。
+
+/** 派单轮关联标记文本(出现在成员会话的用户消息里)。 */
+export function teamRoundMarker(roundId: string): string {
+  return `[team-round:${roundId}]`;
+}
+
+/** 组装带关联标记的派单 prompt(标记行是协议噪音,明确标注可忽略)。 */
+export function buildTeamRoundPrompt(roundId: string, task: string): string {
+  return `${teamRoundMarker(roundId)} (team round protocol marker — ignore this line)\n\n${task}`;
+}
+
+/** 原子写轮次结束信号(成员侧,tmp+rename)。 */
+export function writeRoundSignal(sessionFile: string, signal: Omit<RoundSignal, "version">): void {
+  const tmp = `${sessionFile}.round.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, ...signal } satisfies RoundSignal), "utf-8");
+  renameSync(tmp, `${sessionFile}.round`);
+}
+
+/**
+ * 父侧认领并消费轮次结束信号(atomic rename claim):消费恰好一次;
+ * 读取失败/格式非法时删除并返回 null(坏信号不会重复触发回注)。
+ */
+export function claimRoundSignal(sessionFile: string): RoundSignal | null {
+  const path = `${sessionFile}.round`;
+  const claimed = `${path}.${process.pid}.${randomUUID()}.processing`;
+  try {
+    renameSync(path, claimed);
+    const parsed = JSON.parse(readFileSync(claimed, "utf-8")) as RoundSignal;
+    rmSync(claimed, { force: true });
+    if (parsed?.version === 1 && typeof parsed.name === "string") return parsed;
+    return null;
+  } catch (error) {
+    try { rmSync(claimed, { force: true }); } catch {}
+    if (existsSync(path)) debugLog(`Could not claim round signal ${path}`, error);
+    return null;
+  }
+}
+
+export type MemberStatus = "idle" | "dispatched" | "offline";
+
+export interface RosterMember {
+  name: string;
+  agent?: string;
+  sessionFile: string;
+  pid?: number;
+  status: MemberStatus;
+  /** 当前在途轮次开始的时间戳(仅 dispatched)。 */
+  dispatchedAt?: number;
+  /** 最近一次轮次完成时间戳。 */
+  lastRoundAt?: number;
+  /** offline 原因(含 process-exited / prompt-rejected / round-association-failed / stopped / host-shutdown / host-reload)。 */
+  offlineReason?: string;
+}
+
+interface RosterFile {
+  version: 1;
+  members: RosterMember[];
+}
+
+export function rosterPath(artifactDir: string): string {
+  return join(artifactDir, "team-roster.json");
+}
+
+export function mailboxDir(artifactDir: string, memberName: string): string {
+  return join(artifactDir, "team-mailbox", normalizeSubagentName(memberName, "member"));
+}
+
+function readRosterRaw(path: string): RosterFile {
+  try {
+    if (!existsSync(path)) return { version: 1, members: [] };
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as RosterFile;
+    if (parsed?.version !== 1 || !Array.isArray(parsed.members)) return { version: 1, members: [] };
+    return parsed;
+  } catch (error) {
+    debugLog(`Could not read team roster ${path}`, error);
+    return { version: 1, members: [] };
+  }
+}
+
+function writeRosterRaw(path: string, roster: RosterFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(roster), "utf-8");
+  renameSync(tmp, path);
+}
+
+export function readRoster(path: string): RosterMember[] {
+  return readRosterRaw(path).members.filter((member) =>
+    member && typeof member.name === "string" && typeof member.sessionFile === "string" &&
+    (member.status === "idle" || member.status === "dispatched" || member.status === "offline"),
+  );
+}
+
+export function findRosterMember(path: string, name: string): RosterMember | null {
+  const key = normalizeSubagentName(name, "");
+  return readRoster(path).find((member) => member.name === key) ?? null;
+}
+
+/**
+ * 幂等 upsert + 状态转换。父进程单写者,无需锁;offline 是吸收态——
+ * 再次登记(重新 spawn 同名 member)按新生命周期覆盖。
+ */
+export function upsertRosterMember(
+  path: string,
+  entry: {
+    name: string;
+    agent?: string;
+    sessionFile: string;
+    pid?: number;
+    status: MemberStatus;
+    dispatchedAt?: number;
+    lastRoundAt?: number;
+    offlineReason?: string;
+  },
+): RosterMember {
+  const roster = readRosterRaw(path);
+  const key = normalizeSubagentName(entry.name, "");
+  const next: RosterMember = {
+    name: key,
+    ...(entry.agent ? { agent: entry.agent } : {}),
+    sessionFile: entry.sessionFile,
+    ...(entry.pid != null ? { pid: entry.pid } : {}),
+    status: entry.status,
+    ...(entry.dispatchedAt != null ? { dispatchedAt: entry.dispatchedAt } : {}),
+    ...(entry.lastRoundAt != null ? { lastRoundAt: entry.lastRoundAt } : {}),
+    ...(entry.offlineReason ? { offlineReason: entry.offlineReason } : {}),
+  };
+  const idx = roster.members.findIndex((member) => member.name === key);
+  if (idx >= 0) roster.members[idx] = next;
+  else roster.members.push(next);
+  writeRosterRaw(path, roster);
+  return next;
+}
+
+export function removeRosterMember(path: string, name: string): void {
+  const roster = readRosterRaw(path);
+  const key = normalizeSubagentName(name, "");
+  const filtered = roster.members.filter((member) => member.name !== key);
+  if (filtered.length === roster.members.length) return;
+  writeRosterRaw(path, { version: 1, members: filtered });
+}
+
+// ── 成员间消息(mailbox)──────────────────────────────────────────────
+
+export interface TeamMessage {
+  version: 1;
+  /** 发送方成员名(成员进程 env 注入,父侧信任来源)。 */
+  from: string;
+  /** 接收方成员名。 */
+  to: string;
+  text: string;
+  sentAt: number;
+}
+
+// 同毫秒内多次投递的单调序号:文件名排序即投递顺序(父侧按序注入)。
+let mailboxSeq = 0;
+
+/** 原子投递一条 fire-and-forget 消息(tmp+rename;目录按需创建)。 */
+export function postTeamMessage(artifactDir: string, message: Omit<TeamMessage, "version">): string {
+  const dir = mailboxDir(artifactDir, message.to);
+  mkdirSync(dir, { recursive: true });
+  mailboxSeq += 1;
+  const file = join(dir, `${Date.now()}-${String(mailboxSeq).padStart(6, "0")}-${randomUUID()}.msg.json`);
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, ...message } satisfies TeamMessage), "utf-8");
+  renameSync(tmp, file);
+  return file;
+}
+
+/**
+ * 认领并读取目标成员的全部待投递消息(按文件名时间升序),认领即移出
+ * mailbox(rename 到 .processing,读完删除)——消费恰好一次;失败文件
+ * 留在 .processing 供人工排查,不会重复注入。
+ */
+export function claimTeamMessages(artifactDir: string, memberName: string): TeamMessage[] {
+  const dir = mailboxDir(artifactDir, memberName);
+  if (!existsSync(dir)) return [];
+  const messages: TeamMessage[] = [];
+  const files = readdirSync(dir)
+    .filter((file) => file.endsWith(".msg.json"))
+    .sort();
+  for (const file of files) {
+    const src = join(dir, file);
+    const claimed = `${src}.${process.pid}.processing`;
+    try {
+      renameSync(src, claimed);
+      const parsed = JSON.parse(readFileSync(claimed, "utf-8")) as TeamMessage;
+      if (parsed?.version === 1 && typeof parsed.from === "string" && typeof parsed.text === "string") {
+        messages.push(parsed);
+      }
+      rmSync(claimed, { force: true });
+    } catch (error) {
+      debugLog(`Could not claim team message ${src}`, error);
+    }
+  }
+  return messages;
+}

package/modules/subagents/src/tmux.ts

@@ -0,0 +1,210 @@
+/**
+ * tmux 表面 —— IO 原语。语法族判定(shellEscape/sentinelSuffix)由
+ * surface.ts 统一分派(tmux 恒为 POSIX),本模块只负责对 tmux CLI 的操作。
+ *
+ * 实现源自上游 amosblomqvist/pi-interactive-subagents 的 tmux.ts,接口
+ * 对齐到统一表面签名(cwd/env 经 split-window 的 -c / -e 传入,tmux
+ * 3.2+ 支持,替代上游的 cd 前缀 + 环境变量前缀拼装)。
+ *
+ * Panes are identified by tmux pane ids (e.g. `%12`). The parent pane keeps
+ * one fixed side: only the first subagent pane is split off the parent, and
+ * later splits subdivide the managed side only (see pane-layout.ts). The
+ * user's focus is never stolen.
+ */
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import { MIN_PANE_COLS, MIN_PANE_ROWS, rectMeetsBudget, type PaneRect } from "./layout-budget.ts";
+import { chooseSplitDirection, chooseSplitTarget, type LayoutPane, type SplitDirection } from "./pane-layout.ts";
+
+const execFileAsync = promisify(execFile);
+
+// ── Availability ──
+
+const commandAvailability = new Map<string, boolean>();
+
+function hasCommand(command: string): boolean {
+  if (commandAvailability.has(command)) {
+    return commandAvailability.get(command)!;
+  }
+
+  let available = false;
+  try {
+    execFileSync("sh", ["-c", `command -v ${command}`], { stdio: "ignore" });
+    available = true;
+  } catch {
+    available = false;
+  }
+
+  commandAvailability.set(command, available);
+  return available;
+}
+
+/**
+ * True when running inside tmux with the tmux binary on PATH.
+ * `TMUX` is set by tmux in every process it spawns (shell or pane).
+ */
+export function isAvailable(): boolean {
+  return !!process.env.TMUX && hasCommand("tmux");
+}
+
+export function setupHint(): string {
+  return "Start pi inside tmux (`tmux new -A -s pi 'pi'`).";
+}
+
+// ── Pane layout ──
+
+const managedPaneIds = new Set<string>();
+
+// 有意不使用 tmux select-layout(如 tiled)重排:全窗口重排会把主 pane 从
+// 固定侧挪走或挤小,违背“主 pane 稳定占一侧”的布局契约;split 按 50% 均分
+// 目标 pane,几何可预期,pane 关闭后 tmux 自动把空间归还相邻 pane,无需重排。
+
+// ── Surface primitives ──
+
+/**
+ * Create a new pane in the parent's window. Split target selection lives in
+ * pane-layout.ts:首次从主 pane 切出,之后只在 managed 区域内继续切分;
+ * split 沿能保住最小尺寸的轴进行。
+ * opts.cwd → split-window -c;opts.env → split-window -e(tmux 3.2+)。
+ * Returns the new pane id (e.g. `%12`).
+ */
+export function createSurface(
+  name: string,
+  opts?: { cwd?: string; env?: Record<string, string> },
+): string {
+  void name; // tmux panes are not named; the pi process inside shows its own title.
+
+  const parentId = process.env.TMUX_PANE;
+  if (!parentId) throw new Error("TMUX_PANE is missing; cannot place a subagent pane.");
+
+  const before = queryWindowLayout(parentId);
+  const target = chooseSplitTarget(before, parentId, managedPaneIds);
+  if (!target) {
+    throw new Error("Cannot inspect the current tmux window layout for a subagent pane.");
+  }
+
+  const direction = chooseSplitDirection(target.rect, MIN_PANE_COLS, MIN_PANE_ROWS);
+  if (!direction) {
+    throw new Error(
+      `Terminal too small for another subagent pane (current pane is ${target.rect.width}x${target.rect.height}, ` +
+        `need >= ${MIN_PANE_COLS * 2}x${MIN_PANE_ROWS * 2} for another split).`,
+    );
+  }
+  const paneId = splitPane(target.pane_id, direction, opts);
+  managedPaneIds.add(paneId);
+
+  const after = queryWindowLayout(parentId);
+  const relevantIds = new Set([parentId, ...managedPaneIds]);
+  const invalidPane = after?.find(
+    (pane) => relevantIds.has(pane.pane_id) && !rectMeetsBudget(pane.rect),
+  );
+  if (!after || invalidPane) {
+    managedPaneIds.delete(paneId);
+    try { execFileSync("tmux", ["kill-pane", "-t", paneId], { encoding: "utf8" }); } catch {}
+    const rect = invalidPane?.rect;
+    throw new Error(
+      `Terminal too small for another subagent pane (got ${rect?.width ?? "?"}x${rect?.height ?? "?"}, ` +
+        `need >= ${MIN_PANE_COLS}x${MIN_PANE_ROWS}). Reduce subagents or enlarge the window.`,
+    );
+  }
+  return paneId;
+}
+
+function splitPane(
+  target: string,
+  direction: SplitDirection,
+  opts?: { cwd?: string; env?: Record<string, string> },
+): string {
+  const args = ["split-window", "-d", direction === "right" ? "-h" : "-v", "-t", target, "-p", "50"];
+  if (opts?.cwd) {
+    args.push("-c", opts.cwd);
+  }
+  for (const [key, value] of Object.entries(opts?.env ?? {})) {
+    args.push("-e", `${key}=${value}`);
+  }
+  args.push("-P", "-F", "#{pane_id}");
+
+  const pane = execFileSync("tmux", args, { encoding: "utf8" }).trim();
+  if (!pane.startsWith("%")) {
+    throw new Error(`Unexpected tmux split-window output: ${pane}`);
+  }
+  return pane;
+}
+
+/** 查询当前 window 的 pane 布局。 */
+function queryWindowLayout(paneId: string): LayoutPane[] | null {
+  try {
+    const output = execFileSync(
+      "tmux",
+      ["list-panes", "-t", paneId, "-F", "#{pane_id} #{pane_width} #{pane_height}"],
+      { encoding: "utf8" },
+    );
+    return output.split(/\r?\n/).flatMap((line) => {
+      const [id, widthText, heightText] = line.trim().split(/\s+/);
+      const width = Number(widthText);
+      const height = Number(heightText);
+      return id && Number.isFinite(width) && Number.isFinite(height)
+        ? [{ pane_id: id, rect: { width, height } }]
+        : [];
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Send a command string to a pane and execute it.
+ * Typed literally (`-l`) so special characters are not interpreted as keys,
+ * then submitted with Enter.
+ */
+export function sendCommand(surface: string, command: string): void {
+  execFileSync("tmux", ["send-keys", "-t", surface, "-l", command], { encoding: "utf8" });
+  execFileSync("tmux", ["send-keys", "-t", surface, "Enter"], { encoding: "utf8" });
+}
+
+/** Read the screen contents of a pane (sync). */
+export function readScreen(surface: string, lines = 50): string {
+  return execFileSync(
+    "tmux",
+    ["capture-pane", "-p", "-t", surface, "-S", `-${Math.max(1, lines)}`],
+    {
+      encoding: "utf8",
+    },
+  );
+}
+
+/** Read the screen contents of a pane (async). */
+export async function readScreenAsync(surface: string, lines = 50): Promise<string> {
+  const { stdout } = await execFileAsync(
+    "tmux",
+    ["capture-pane", "-p", "-t", surface, "-S", `-${Math.max(1, lines)}`],
+    { encoding: "utf8" },
+  );
+  return stdout;
+}
+
+/** 重载恢复后，把已有 pane 纳入当前 window 的布局目标集合。 */
+export function trackSurface(surface: string): void {
+  managedPaneIds.add(surface);
+}
+
+/** 查询 pane 是否仍然存在,用于 /reload 恢复时丢弃 stale 记录。 */
+export function surfaceExists(surface: string): boolean {
+  try {
+    execFileSync("tmux", ["display-message", "-p", "-t", surface, "#{pane_id}"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Close a pane. tmux 自动把空间归还相邻 pane,无需重排。 */
+export function closeSurface(surface: string): void {
+  execFileSync("tmux", ["kill-pane", "-t", surface], { encoding: "utf8" });
+  managedPaneIds.delete(surface);
+}
+
+/** 给 pane 设置可识别标签(best-effort,失败不致命)。 */
+export function labelSurface(surface: string, label: string): void {
+  execFileSync("tmux", ["select-pane", "-t", surface, "-T", label], { encoding: "utf8" });
+}

package/modules/subagents/src/tools/safe-bash.ts

@@ -0,0 +1,72 @@
+/**
+ * Safe bash extension for the worker subagent.
+ * Wraps the built-in bash tool with dangerous command blocking.
+ *
+ * Loaded into a child pi process via `--extension` when an agent's `tools`
+ * frontmatter lists `safe_bash`. See CUSTOM_TOOL_EXTENSIONS in ../index.ts.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createBashTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const DANGEROUS_PATTERNS = [
+	/\brm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?(-[a-zA-Z]*r[a-zA-Z]*\s+)?(\/|~\/?\s|~\/?\b)/,
+	/\brm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+)?(-[a-zA-Z]*f[a-zA-Z]*\s+)?(\/|~\/?\s|~\/?\b)/,
+	/\bsudo\b/,
+	/\bmkfs\b/,
+	/\bdd\s+if=/,
+	/:\(\)\s*\{\s*:\|:&\s*\}\s*;:/,
+	/>\s*\/dev\/[sh]d[a-z]/,
+	/\bchmod\s+(-[a-zA-Z]+\s+)?777\s+\//,
+	/\bchown\s+(-[a-zA-Z]+\s+)?root/,
+	/\bcurl\s.*\|\s*(ba)?sh/,
+	/\bwget\s.*\|\s*(ba)?sh/,
+	/\bshutdown\b/,
+	/\breboot\b/,
+	/\binit\s+0\b/,
+	/\bkill\s+-9\s+1\b/,
+	/\bkillall\b/,
+	// Long-form flags and shell indirection are common ways to evade a short
+	// option-only check. This remains a heuristic, not a security boundary.
+	/\brm\b(?=[^;\n]*(?:--recursive|--force|--no-preserve-root))(?=[^;\n]*(?:^|\s)(?:\/(?:\s|$)|~(?:\/|\s|$)))[^;\n]*/i,
+	/\b(?:bash|sh|zsh)\s+(?:-[a-z]*c|--command)\b/i,
+	/\b(?:python|python3|node|perl|ruby)\s+-[ce]\b/i,
+	/\|\s*(?:ba)?sh\b/i,
+	/\bxargs\b/i,
+];
+
+function isDangerous(command: string): string | null {
+	const normalized = command.replace(/\\\n/g, " ");
+	for (const pattern of DANGEROUS_PATTERNS) {
+		if (pattern.test(normalized)) {
+			return `Command blocked by safe_bash: matches dangerous pattern ${pattern}`;
+		}
+	}
+	return null;
+}
+
+export const __test__ = { isDangerous };
+
+export default function (pi: ExtensionAPI) {
+	const bashTool = createBashTool(process.cwd());
+
+	pi.registerTool({
+		name: "safe_bash",
+		label: "Safe Bash",
+		description:
+			"Execute a bash command with heuristic blocking for dangerous commands. This is not a security sandbox.",
+		parameters: Type.Object({
+			command: Type.String({ description: "Bash command to execute" }),
+			timeout: Type.Optional(
+				Type.Number({ description: "Timeout in seconds (optional)" }),
+			),
+		}),
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const danger = isDangerous(params.command);
+			if (danger) {
+				throw new Error(danger);
+			}
+			return bashTool.execute(toolCallId, params, signal, onUpdate);
+		},
+	});
+}

package/modules/subagents/src/types.ts

@@ -0,0 +1,131 @@
+import type { SubagentActivityState } from "./activity.ts";
+import type { SubagentStatusState } from "./status.ts";
+import type { SessionStats } from "./session.ts";
+import type { HeadlessChild } from "./headless.ts";
+
+export interface SubagentResult {
+  name: string;
+  task: string;
+  /** 仅用于展示和结果聚合的并行分组标签,不改变生命周期语义。 */
+  cohortId?: string;
+  summary: string;
+  sessionFile?: string;
+  sessionId?: string;
+  exitCode: number;
+  elapsed: number;
+  errorMessage?: string;
+  stats?: SessionStats;
+  /**
+   * pane 被外部关闭且无 .exit sidecar(典型:用户直接关掉演示 pane)。
+   * 这是稳定的非错误终态分类:不算 provider/agent error(不生成
+   * route_exception),依赖注册表按 cancelled settle。
+   */
+  userClosed?: boolean;
+  /**
+   * 显式停止(subagent_stop)兑出的取消终态:与意外失败区分,迟到回注
+   * 与依赖 settle 都按 cancelled 语义呈现,不报 failed。
+   */
+  stopped?: boolean;
+  /**
+   * /reload(module replaced)移交标记:宿主重载后旧模块的 watcher 已把该
+   * 子代理移交给运行态记录恢复逻辑(recoverRuntimeSubagents),本结果不是
+   * 终态——真实结果由恢复路径在子代理结束后回注。调用方不得把它当作
+   * cancelled/failed 处理或再次回注,只能返回明确的 handed-off 说明。
+   * 宿主会话关闭(/new、/resume 切走)的 detach 也复用该语义:进程/pane
+   * 与 runtime record 全保留,由本会话的恢复路径接管。
+   */
+  handedOff?: boolean;
+}
+
+export type SubagentWaitMode = "hard-barrier" | "interactive" | "member-round" | "recovered";
+export type SubagentWaitRelease = "escape" | "timeout";
+
+export interface RunningSubagent {
+  id: string;
+  name: string;
+  task: string;
+  /** 仅用于展示和结果聚合的并行分组标签。 */
+  cohortId?: string;
+  agent?: string;
+  /**
+   * 解析后的模型 id(含 ":thinking" 后缀;来自显式 params、tier 解析或 agent
+   * frontmatter)。route_exception 的 provider/model 拆分来源;旧记录/mock 可缺省。
+   */
+  model?: string | null;
+  /** 直接父子代理 run id;顶层子代理为 null。 */
+  parentId?: string | null;
+  /** 本次硬屏障等待上限;未配置时缺省。 */
+  timeoutMs?: number;
+  /** 当前运行的等待载体与恢复状态。 */
+  waitMode?: SubagentWaitMode;
+  /** 主工具等待已被 Escape 或 timeout 解除,但子代理仍在运行。 */
+  waitReleased?: SubagentWaitRelease;
+  surface: string;
+  startTime: number;
+  sessionFile: string;
+  activityFile?: string;
+  activity?: SubagentActivityState;
+  activityRead?: {
+    ok: boolean;
+    reason?: "missing" | "invalid" | "wrong-id";
+    error?: string;
+  };
+  abortController?: AbortController;
+  statusState: SubagentStatusState;
+  interactive: boolean;
+  sentinelToken: string;
+  runtimeFile: string;
+  /**
+   * 运行载体:"pane"(herdr/tmux,默认——兼容未带此字段的旧测试 mock 与旧记录)
+   * 或 "headless"(独立 pi --mode rpc 后台进程)。
+   */
+  kind?: "pane" | "headless";
+  /** headless 运行的子进程 PID(仅 kind="headless")。 */
+  pid?: number;
+  /** headless 运行的子进程句柄(仅 kind="headless",运行中存在)。 */
+  headlessChild?: HeadlessChild;
+  /** 本次 spawn 是否成功写入父侧锚定 loadout;用于 resume 信任链。 */
+  anchoredLoadout?: boolean;
+  /**
+   * 轮次信号在会话文件暂时不可读时的内存保留副本,避免 atomic claim
+   * 后因解析竞态静默丢失结果。
+   */
+  pendingRoundSignal?: { name: string; seq: number; at: number };
+  /** 轮次关联连续读失败次数,达到上限后转为明确失败终态。 */
+  roundAssociationAttempts?: number;
+  /**
+   * 本次 spawn 写入父会话 artifactDir/context/ 的任务与系统提示文件
+   * (retention 清理用;resume 重启的新 spawn 会记录自己的新文件)。
+   */
+  contextFiles?: string[];
+  /**
+   * /reload 恢复后丢失 stdin 时的降级标记:无法再向该子代理 steer/投递
+   * ask 回复,只能等进程退出后从 session 文件提取结果。显式降级,不伪称完整恢复。
+   */
+  stdinLost?: boolean;
+  /**
+   * 持久团队成员(member: true):headless 常驻进程,不走硬屏障;每轮
+   * 经 team_dispatch 派单,.round sidecar 标记轮次结束。强制 headless +
+   * preserve + 无 timeoutMs/dependsOn(工具层校验)。
+   */
+  member?: boolean;
+  /** 当前是否有在途轮次(team_dispatch 置位,.round 消费后清除)。 */
+  dispatchedRound?: boolean;
+  /** 在途轮次的关联 nonce(spawn 首轮与 team_dispatch 各生成一个;与
+   *  .round 认领时的会话 marker 检索配合,区分派单轮与自发轮)。 */
+  dispatchedRoundId?: string;
+  /** 在途轮次开始时的会话行数(轮次结果提取基线)。 */
+  roundEntryBaseline?: number;
+  /** 父会话 team roster 文件路径(成员状态转换的单一真源,父进程独写)。 */
+  rosterFile?: string;
+  /**
+   * watcher 的终态 promise(subagent_stop 等待停止落定用)。由启动 watcher
+   * 的工具路径(spawn/resume)写入;resolve 单次,promise 可被多消费。
+   */
+  watchPromise?: Promise<SubagentResult>;
+  /**
+   * 显式停止(subagent_stop)标记:置位后 watcher 把 pane 消失等观察到的
+   * 中断一律按显式 cancelled 终态处理,不再误分类为 user_closed。
+   */
+  stopRequested?: boolean;
+}