@buyi1net/pi-toolkit 0.0.1

package/modules/subagents/src/names.ts

@@ -0,0 +1,17 @@
+const MAX_NAME_LENGTH = 72;
+
+/** 统一 pane、widget 和 registry 使用的显示名，避免不可寻址的空白字符。 */
+export function normalizeSubagentName(name: string, fallback = "subagent"): string {
+  const normalized = name.replace(/\s+/g, " ").trim() || fallback;
+  return normalized.slice(0, MAX_NAME_LENGTH);
+}
+
+export function sanitizeSubagentFileName(name: string, fallback = "subagent"): string {
+  const sanitized = name
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return sanitized || fallback;
+}

package/modules/subagents/src/pane-layout.ts

@@ -0,0 +1,49 @@
+import type { PaneRect } from "./layout-budget.ts";
+
+export type SplitDirection = "right" | "down";
+
+export interface LayoutPane {
+  pane_id: string;
+  rect: PaneRect;
+}
+
+/**
+ * 选择下一次分屏的目标 pane。
+ *
+ * 布局契约:主 pane(parentId)稳定占据一侧。已有本扩展管理的 pane 时,
+ * 只在 managed 区域内选面积最大的继续切分——无论 parent 面积多大都不再切
+ * parent,避免主 pane 被后续分屏挤成小窗;当前布局中已无任何 managed pane
+ * (尚未创建过,或均已被外部关闭)时,才首次/重新从 parent 切出。
+ * managedPaneIds 里已失效的 id(pane 已不存在)会被当前布局自然过滤,
+ * 不影响上述判断。
+ */
+export function chooseSplitTarget(
+  layout: LayoutPane[] | null,
+  parentId: string,
+  managedPaneIds: Set<string>,
+): LayoutPane | null {
+  if (!layout) return null;
+  const managed = layout.filter((pane) => managedPaneIds.has(pane.pane_id));
+  if (managed.length === 0) {
+    return layout.find((pane) => pane.pane_id === parentId) ?? null;
+  }
+  return managed.reduce<LayoutPane | null>(
+    (largest, pane) =>
+      !largest || pane.rect.width * pane.rect.height > largest.rect.width * largest.rect.height ? pane : largest,
+    null,
+  );
+}
+
+/** 优先沿仍能满足最小尺寸的方向切分;两边都可用时沿较长轴切分。 */
+export function chooseSplitDirection(
+  rect: PaneRect,
+  minCols: number,
+  minRows: number,
+): SplitDirection | null {
+  const canSplitRight = rect.width >= minCols * 2;
+  const canSplitDown = rect.height >= minRows * 2;
+  if (canSplitRight && canSplitDown) return rect.width >= rect.height ? "right" : "down";
+  if (canSplitRight) return "right";
+  if (canSplitDown) return "down";
+  return null;
+}

package/modules/subagents/src/params.ts

@@ -0,0 +1,145 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+export const MAX_COHORT_ID_LENGTH = 128;
+
+export function normalizeCohortId(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim();
+  return normalized || undefined;
+}
+
+export function validateCohortId(value: unknown): string | null {
+  if (value == null) return null;
+  if (typeof value !== "string") {
+    return `Invalid cohortId: must be a string when provided; got ${String(value)}.`;
+  }
+  const normalized = value.trim();
+  if (!normalized) return "Invalid cohortId: must be non-empty after trimming.";
+  if (/[\u0000-\u001f\u007f]/.test(normalized)) {
+    return "Invalid cohortId: must not contain control characters.";
+  }
+  if (normalized.length > MAX_COHORT_ID_LENGTH) {
+    return `Invalid cohortId: must be at most ${MAX_COHORT_ID_LENGTH} characters.`;
+  }
+  return null;
+}
+
+export const SubagentParams = Type.Object({
+  agent: Type.String({
+    description:
+      "Which agent to spawn (e.g. 'worker', 'scout', 'researcher'). This loads the agent's " +
+      "fixed profile — its model, tool loadout, and system prompt. Must be one of the available agents.",
+  }),
+  task: Type.String({ description: "Task/prompt for the sub-agent" }),
+  name: Type.Optional(
+    Type.String({
+      description:
+        "Optional cosmetic label for the subagent's pane and widget row. Defaults to the agent name. " +
+        "Has no effect on which agent runs — use `agent` for that.",
+    }),
+  ),
+  cohortId: Type.Optional(
+    Type.String({
+      minLength: 1,
+      maxLength: MAX_COHORT_ID_LENGTH,
+      pattern: "^[^\\u0000-\\u001F\\u007F]+$",
+      description:
+        "Optional opaque group label for displaying and aggregating results from parallel subagents. " +
+        "It has no scheduling, dependency, ownership, retention, or cleanup semantics; resume keeps the original label.",
+    }),
+  ),
+  model: Type.Optional(Type.String({ description: "Model override (overrides agent default and takes precedence over `tier`). Supports 'provider/id' and optional ':<thinking>' suffix" })),
+  tier: Type.Optional(
+    Type.String({
+      description:
+        "Model tier preset: 'fast', 'balanced', or 'deep' (aliases quick/balance|standard/strong accepted). " +
+        "Resolved from the pi-subagents config (models.fast/balanced/deep). An explicit `model` always wins over `tier`. " +
+        "A tier without a configured model fails with a clear error — models are never silently swapped.",
+    }),
+  ),
+  thinking: Type.Optional(
+    Type.String({
+      description:
+        "Thinking level override for this spawn: off, minimal, low, medium, high, xhigh, or max. " +
+        "Takes precedence over the agent's frontmatter thinking and over any ':<thinking>' suffix on the model parameter.",
+    }),
+  ),
+  cwd: Type.Optional(
+    Type.String({
+      description:
+        "Working directory for the sub-agent. The agent starts in this folder and picks up its local .pi/ config, CLAUDE.md, skills, and extensions. Use for role-specific subfolders.",
+    }),
+  ),
+  dependsOn: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Names of same-session subagents that MUST reach a terminal state BEFORE this call launches. " +
+        "Also works for sibling subagent calls issued in the SAME assistant message: the dependent call waits on the upstream completion promise instead of launching in parallel; independent siblings still run in parallel. " +
+        "When every dependency completed, a short upstream-results context block is appended to `task` (real extracted summaries, never fabricated). " +
+        "If any dependency failed or was cancelled, this call does NOT launch and returns a structured `dependencyException` in the tool result details — no pane/process is created. " +
+        "Rejected without launching: depending on this call's own name, on unknown names (not running, not announced in this message, and not in the session registry), and on interactive demo-pane subagents (they have no waitable terminal state). " +
+        "Dependencies that already finished in an earlier turn are resolved from the session's name registry / session files.",
+    }),
+  ),
+  surface: Type.Optional(
+    Type.Union(
+      [
+        Type.Literal("auto"),
+        Type.Literal("background"),
+        Type.Literal("pane"),
+      ],
+      {
+        description:
+          "Where the sub-agent runs. 'auto' (default): autonomous agents run headless as an independent background pi process " +
+          '(no pane/tab is created); demo/interactive agents run in a visible pane the user can operate. ' +
+          "'background': force headless (refused for interactive agents — they need a visible pane). 'pane': force a visible pane. " +
+          "Headless sub-agents are NOT visible and cannot be operated by the user.",
+      },
+    ),
+  ),
+  retention: Type.Optional(
+    Type.Union(
+      [
+        Type.Literal("auto"),
+        Type.Literal("preserve"),
+        Type.Literal("discard"),
+      ],
+      {
+        description:
+          "Session retention for headless autonomous sub-agents after this call settles. 'auto' (default): delete this sub-agent's " +
+          "session JSONL, .loadout.json, context task/system-prompt files and activity/runtime registration after a SUCCESSFUL terminal state; " +
+          "failed, cancelled or handed-off runs are preserved so you can resume them with subagent_message. 'preserve': always keep everything. " +
+          "'discard': always delete after a terminal state (including failure/cancellation) — use when you know you will never resume. " +
+          "Visible pane / demo sub-agents are ALWAYS preserved regardless of this parameter. Deletion happens only after the result has been " +
+          "extracted and returned — it never affects the tool result.",
+      },
+    ),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      minimum: 1000,
+      description:
+        "Optional wait timeout in milliseconds (>= 1000) for THIS tool call's hard-barrier wait on an AUTONOMOUS sub-agent. " +
+        "Omit it to wait indefinitely (existing behavior). When the timeout fires the call returns a structured non-terminal `timed-out` result: " +
+        "the sub-agent itself is NOT killed, NOT cancelled, nothing is cleaned up and no summary is fabricated — it keeps running exactly like an " +
+        "Escape-detached wait, and its real result is delivered later as a single steer message (lateDelivery). DependsOn consumers keep waiting " +
+        "for the real terminal state. The timeout covers the post-launch run wait only; it does not shorten the pre-launch dependsOn wait. " +
+        "Refused for interactive (demo) agents — their spawn returns immediately and has no wait to bound. " +
+        "Siblings in the same message return their own tool results independently; a timed-out call is not a batch summary.",
+    }),
+  ),
+  member: Type.Optional(
+    Type.Boolean({
+      description:
+        "Spawn this sub-agent as a persistent TEAM MEMBER instead of a one-shot task. The call returns an immediate ack (no hard barrier): " +
+        "the member runs as a long-lived headless process, stays alive after each round, and receives follow-up rounds via team_dispatch. " +
+        "Each round's result is delivered once as a steer message when it ends. Members may message each other (fire-and-forget team_send) only " +
+        "along ACL edges declared in the agent profile's `peer-send`. Constraints (violations are refused): headless only (surface may not be " +
+        "'pane'), retention is forced to 'preserve' (may not be 'discard'), no timeoutMs, no dependsOn, and interactive (demo) agents cannot be " +
+        "members. Members cannot be dependsOn targets (no process-level terminal state). Stopping a member requires subagent_stop; host session " +
+        "shutdown or /reload terminates members and marks them offline (session preserved for explicit resume).",
+    }),
+  ),
+});
+
+export type SubagentParams = Static<typeof SubagentParams>;

package/modules/subagents/src/renderers.ts

@@ -0,0 +1,181 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import { Box, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import type { SessionStats } from "./session.ts";
+import { contextWindowFor, formatContextUsage, formatElapsed, formatUsageSegments } from "./display.ts";
+
+export function registerSubagentRenderers(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer("subagent_result", (message, options, theme) => {
+    const details = message.details as any;
+    if (!details) return undefined;
+
+    return {
+      invalidate() {},
+      render(width: number): string[] {
+        const name = details.name ?? "subagent";
+        const exitCode = details.exitCode ?? 0;
+        const errorMessage = typeof details.errorMessage === "string" ? details.errorMessage : "";
+        const userClosed = details.userClosed === true;
+        const late = details.lateDelivery === "detached";
+        const failed = !userClosed && (exitCode !== 0 || !!errorMessage);
+        const elapsed = details.elapsed != null ? formatElapsed(details.elapsed) : "?";
+        const bgFn = userClosed
+          ? (text: string) => theme.bg("customMessageBg", text)
+          : failed
+            ? (text: string) => theme.bg("toolErrorBg", text)
+            : (text: string) => theme.bg("toolSuccessBg", text);
+        const stats = (details.stats ?? null) as SessionStats | null;
+        const icon = userClosed ? theme.fg("warning", "✕") : failed ? theme.fg("error", "✗") : theme.fg("success", "✓");
+        const agentTag = details.agent ? theme.fg("dim", ` (${details.agent})`) : "";
+        const modelTag = stats?.model ? theme.fg("dim", ` (${stats.model})`) : "";
+        const lateTag = late ? theme.fg("accent", " (late delivery after detached wait)") : "";
+        const title = `${icon} ${theme.fg("toolTitle", theme.bold(name))}${agentTag}${modelTag} ${theme.fg("dim", "—")} `;
+
+        let header: string;
+        if (userClosed) {
+          // 用户直接关闭 pane:稳定分类,不是 provider/agent 错误。
+          header = `${title}${theme.fg("warning", "closed by user")} ${theme.fg("dim", `· ${elapsed}`)}${lateTag}`;
+        } else if (failed) {
+          const reason = errorMessage ? "failed (provider/agent error)" : `failed (exit ${exitCode})`;
+          header = `${title}${theme.fg("error", reason)} ${theme.fg("dim", `· ${elapsed}`)}${lateTag}`;
+        } else {
+          const toolPart = stats ? `${stats.toolCount} tools · ${elapsed}` : elapsed;
+          header = `${title}${theme.fg("dim", toolPart)}${lateTag}`;
+        }
+
+        let usageLine: string | null = null;
+        if (stats) {
+          const segments = formatUsageSegments(stats).map((segment) => theme.fg("dim", segment));
+          if (stats.contextTokens > 0) {
+            const window = contextWindowFor(stats.model);
+            const context = formatContextUsage(stats.contextTokens, window);
+            const percent = window ? (stats.contextTokens / window) * 100 : 0;
+            segments.push(percent > 90 ? theme.fg("error", context) : percent > 70 ? theme.fg("warning", context) : theme.fg("dim", context));
+          }
+          if (segments.length > 0) usageLine = segments.join(theme.fg("dim", " "));
+        }
+
+        const rawContent = typeof message.content === "string" ? message.content : "";
+        const summary = rawContent
+          .replace(/\n\nFollow up with subagent_message[\s\S]+$/, "")
+          .replace(`Sub-agent "${name}" completed (${elapsed}).\n\n`, "")
+          .replace(`Sub-agent "${name}" failed (exit code ${exitCode}).\n\n`, "")
+          .replace(new RegExp(`^Sub-agent "${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}" failed after ${elapsed} \\(provider/agent error — auto-retry exhausted\\)\\.\\n\\n`), "");
+
+        const contentLines = [header];
+        if (usageLine) contentLines.push(usageLine);
+        if (options.expanded) {
+          if (summary) contentLines.push(...summary.split("\n").map((line) => truncateToWidth(line, Math.max(0, width - 6))));
+          if (details.name || details.sessionFile) {
+            contentLines.push("");
+            if (details.name) contentLines.push(theme.fg("dim", `Session preserved: message only for NEW instructions → subagent_message({ name: "${details.name}" })`));
+            if (details.sessionFile) contentLines.push(theme.fg("muted", `Session file: ${details.sessionFile}`));
+          }
+        } else {
+          if (summary) {
+            const previewLines = summary.split("\n").slice(0, 5);
+            contentLines.push(...previewLines.map((line) => theme.fg("dim", truncateToWidth(line, Math.max(0, width - 6)))));
+            if (summary.split("\n").length > 5) contentLines.push(theme.fg("muted", `… ${summary.split("\n").length - 5} more lines`));
+          }
+          contentLines.push(theme.fg("muted", keyHint("app.tools.expand", "to expand")));
+        }
+
+        const box = new Box(1, 1, bgFn);
+        box.addChild(new Text(contentLines.join("\n"), 0, 0));
+        return ["", ...box.render(width)];
+      },
+    };
+  });
+
+  // 历史会话兼容:旧版本曾以 subagent_batch_result 消息回注批次结果,
+  // 生成逻辑已随硬屏障移除,但渲染器保留,保证 /reload 或恢复会话时旧消息仍可显示。
+  pi.registerMessageRenderer("subagent_batch_result", (message, options, theme) => {
+    const details = message.details as any;
+    const results = Array.isArray(details?.results) ? details.results : [];
+    if (results.length === 0) return undefined;
+
+    return {
+      invalidate() {},
+      render(width: number): string[] {
+        const lineWidth = Math.max(0, width - 6);
+        const contentLines = [
+          `${theme.fg("accent", "◆")} ${theme.fg("toolTitle", theme.bold(`Sub-agent batch · ${results.length} results`))}`,
+        ];
+        for (const entry of results) {
+          const failed = (entry.exitCode ?? 0) !== 0 || !!entry.errorMessage;
+          const icon = failed ? theme.fg("error", "✗") : theme.fg("success", "✓");
+          const elapsed = entry.elapsed != null ? formatElapsed(entry.elapsed) : "?";
+          const agentTag = entry.agent ? theme.fg("dim", ` (${entry.agent})`) : "";
+          const reason = failed
+            ? (entry.errorMessage ? "failed (provider/agent error)" : `failed (exit ${entry.exitCode})`)
+            : "completed";
+          contentLines.push(
+            `${icon} ${theme.fg("toolTitle", theme.bold(entry.name ?? "subagent"))}${agentTag}` +
+              theme.fg(failed ? "error" : "dim", ` — ${reason}`) +
+              theme.fg("dim", ` · ${elapsed}`),
+          );
+        }
+        if (options.expanded) {
+          for (const entry of results) {
+            contentLines.push("", theme.fg("toolTitle", theme.bold(entry.name ?? "subagent")));
+            const summary = typeof entry.summary === "string" ? entry.summary : "";
+            if (summary) {
+              contentLines.push(...summary.split("\n").map((line: string) => theme.fg("dim", truncateToWidth(line, lineWidth))));
+            }
+            if (entry.sessionFile) contentLines.push(theme.fg("muted", `Session file: ${entry.sessionFile}`));
+          }
+        } else {
+          contentLines.push(theme.fg("muted", keyHint("app.tools.expand", "to expand")));
+        }
+        const box = new Box(1, 1, (text: string) => theme.bg("customMessageBg", text));
+        box.addChild(new Text(contentLines.join("\n"), 0, 0));
+        return ["", ...box.render(width)];
+      },
+    };
+  });
+
+  pi.registerMessageRenderer("subagent_status", (message, options, theme) => {
+    const details = message.details as any;
+    const lines = Array.isArray(details?.lines) ? details.lines : [];
+    const overflow = typeof details?.overflow === "number" ? details.overflow : 0;
+    if (lines.length === 0 && overflow === 0) return undefined;
+
+    return {
+      invalidate() {},
+      render(width: number): string[] {
+        const lineWidth = Math.max(0, width - 6);
+        const contentLines = [
+          `${theme.fg("accent", "•")} ${theme.fg("toolTitle", theme.bold("Subagent status"))}`,
+          ...lines.map((line: string) => theme.fg("dim", truncateToWidth(line, lineWidth))),
+        ];
+        if (overflow > 0) contentLines.push(theme.fg("muted", `+${overflow} more running.`));
+        if (!options.expanded) contentLines.push(theme.fg("muted", keyHint("app.tools.expand", "to expand")));
+        const box = new Box(1, 1, (text: string) => theme.bg("customMessageBg", text));
+        box.addChild(new Text(contentLines.join("\n"), 0, 0));
+        return ["", ...box.render(width)];
+      },
+    };
+  });
+
+  pi.registerMessageRenderer("subagent_question", (message, options, theme) => {
+    const details = message.details as any;
+    if (!details) return undefined;
+    return {
+      invalidate() {},
+      render(width: number): string[] {
+        const name = details.name ?? "subagent";
+        const agentTag = details.agent ? theme.fg("dim", ` (${details.agent})`) : "";
+        const header = `${theme.fg("accent", "?")} ${theme.fg("toolTitle", theme.bold(name))}${agentTag} ${theme.fg("dim", "— asks a question")}`;
+        const contentLines = [header];
+        if (options.expanded) {
+          contentLines.push("", details.question ?? "", "", theme.fg("dim", `Reply: subagent_message({ name: "${name}", message: "…" })`));
+        } else {
+          contentLines.push(theme.fg("dim", (details.question ?? "").split("\n")[0].slice(0, Math.max(0, width - 10))), theme.fg("muted", keyHint("app.tools.expand", "to expand")));
+        }
+        const box = new Box(1, 1, (text: string) => theme.bg("toolSuccessBg", text));
+        box.addChild(new Text(contentLines.join("\n"), 0, 0));
+        return ["", ...box.render(width)];
+      },
+    };
+  });
+}

package/modules/subagents/src/result.ts

@@ -0,0 +1,43 @@
+import { existsSync } from "node:fs";
+import {
+  findLastAssistantMessage,
+  getNewEntriesAsync,
+  getSessionId,
+  summarizeSessionStatsAsync,
+  type SessionStats,
+} from "./session.ts";
+
+export interface ResultExit {
+  exitCode: number;
+  errorMessage?: string;
+}
+
+export interface ExtractedSubagentResult {
+  summary: string;
+  sessionId: string | null;
+  stats: SessionStats | null;
+}
+
+export async function extractSubagentResult(
+  sessionFile: string,
+  exit: ResultExit,
+  afterLine = 0,
+  fallbackPrefix = "Sub-agent",
+): Promise<ExtractedSubagentResult> {
+  const fallback = exit.errorMessage
+    ? `Subagent error: ${exit.errorMessage}`
+    : exit.exitCode !== 0
+      ? `${fallbackPrefix} exited with code ${exit.exitCode}`
+      : `${fallbackPrefix} exited without output`;
+
+  if (!existsSync(sessionFile)) {
+    return { summary: fallback, sessionId: null, stats: null };
+  }
+
+  const entries = await getNewEntriesAsync(sessionFile, afterLine);
+  return {
+    summary: findLastAssistantMessage(entries) ?? fallback,
+    sessionId: getSessionId(sessionFile),
+    stats: await summarizeSessionStatsAsync(sessionFile),
+  };
+}

package/modules/subagents/src/retention.ts

@@ -0,0 +1,114 @@
+import { existsSync, rmSync } from "node:fs";
+import { debugLog } from "./diagnostics.ts";
+
+/**
+ * 会话保留策略(spawn 参数 retention):
+ * - "auto"(默认):headless 自动子代理成功终态后清理本次会话工件;失败/
+ *   取消/handed-off 保留,主代理可用 subagent_message resume;
+ * - "preserve":永不清理(pane/演示子代理无论参数如何恒为 preserve);
+ * - "discard":headless 自动子代理到达非 handed-off 终态后一律清理
+ *   (含失败/取消),显式声明"不需要 resume"。
+ */
+export type RetentionPolicy = "auto" | "preserve" | "discard";
+
+export interface RetentionInput {
+  policy: RetentionPolicy;
+  /** 交互式演示子代理(可见 pane 归用户操作)。 */
+  interactive: boolean;
+  /** 运行载体;缺省(旧 mock/记录)按可见 pane 对待:未显式声明 headless 就不删。 */
+  kind?: "pane" | "headless";
+  cancelled: boolean;
+  failed: boolean;
+  handedOff: boolean;
+}
+
+export type RetentionDecision =
+  | { action: "preserve"; reason: string }
+  | { action: "delete"; reason: string };
+
+/**
+ * 纯决策函数:给定策略与终态,判定是否清理会话工件。
+ * 恒 preserve 的边界(优先级从高到低):handed-off(进程仍在跑,交给恢复
+ * 路径)、pane/演示/未声明 headless 的运行(可见会话归用户;载体未知时
+ * 保守不删)。discard 只跳过这几类,失败/取消也清理——显式声明不需要
+ * resume。auto 在失败/取消时保留以便 resume。
+ */
+export function resolveRetentionDecision(input: RetentionInput): RetentionDecision {
+  if (input.handedOff) return { action: "preserve", reason: "handed-off" };
+  if (input.interactive || input.kind !== "headless") {
+    return { action: "preserve", reason: "pane" };
+  }
+  if (input.policy === "preserve") return { action: "preserve", reason: "policy=preserve" };
+  if (input.policy === "discard") return { action: "delete", reason: "policy=discard" };
+  if (input.cancelled) return { action: "preserve", reason: "cancelled" };
+  if (input.failed) return { action: "preserve", reason: "failed" };
+  return { action: "delete", reason: "auto-success" };
+}
+
+/** 待处理 ask_question 的 sidecar;存在即表示还有未投递的问题。 */
+export function pendingAskSidecarPath(sessionFile: string): string {
+  return `${sessionFile}.ask`;
+}
+
+/** subagent-done 错误路径写入的退出 sidecar。 */
+export function exitSidecarPath(sessionFile: string): string {
+  return `${sessionFile}.exit`;
+}
+
+export interface RetentionCleanupTarget {
+  /** 子代理会话 JSONL(清理主体)。 */
+  sessionFile: string;
+  /** 活动快照文件(artifactDir/subagent-activity/<id>.json)。 */
+  activityFile?: string;
+  /** 本次 spawn 写入父会话 artifactDir/context/ 的任务与系统提示文件。 */
+  contextFiles?: string[];
+}
+
+export interface RetentionCleanupResult {
+  /** 实际删除的文件路径。 */
+  removed: string[];
+  /** 因待处理 .ask 而保留的文件路径(此时 removed 必为空)。 */
+  skipped: string[];
+  /** 删除失败的文件路径与原因;只能 debug,不覆盖子代理结果。 */
+  errors: Array<{ path: string; error: string }>;
+}
+
+/**
+ * 删除一次 headless 自动子代理的全部会话工件:会话 JSONL、.loadout.json、
+ * .exit sidecar、activity 快照与 context 任务/系统提示文件。
+ * 存在待处理 .ask(未投递的问题)时整体跳过——不能删除运行中/待处理的
+ * 提问信号。单个文件删除失败只收集不抛出,由调用方 debug 上报。
+ */
+export function cleanupSubagentArtifacts(target: RetentionCleanupTarget): RetentionCleanupResult {
+  const askPath = pendingAskSidecarPath(target.sessionFile);
+  if (existsSync(askPath)) {
+    debugLog(`Subagent artifact cleanup skipped (pending ask sidecar): ${askPath}`);
+    return { removed: [], skipped: [askPath], errors: [] };
+  }
+
+  const removed: string[] = [];
+  const errors: RetentionCleanupResult["errors"] = [];
+  const candidates = [
+    target.sessionFile,
+    `${target.sessionFile}.loadout.json`,
+    exitSidecarPath(target.sessionFile),
+    ...(target.activityFile ? [target.activityFile] : []),
+    ...(target.contextFiles ?? []),
+  ];
+  for (const path of candidates) {
+    if (!existsSync(path)) continue;
+    try {
+      rmSync(path, { force: true });
+      removed.push(path);
+    } catch (error: any) {
+      errors.push({ path, error: error?.message ?? String(error) });
+    }
+  }
+  if (errors.length > 0) {
+    debugLog(
+      `Subagent artifact cleanup partially failed for ${target.sessionFile}`,
+      errors.map((item) => `${item.path}: ${item.error}`).join("; "),
+    );
+  }
+  return { removed, skipped: [], errors };
+}