@baique/pi-web-sky 0.1.55 → 0.1.57

package/lib/subagents.ts

@@ -0,0 +1,602 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { dump as stringifyYaml } from "js-yaml";
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { parseFrontmatter } from "./frontmatter";
+import { writePrivateFileAtomicSync } from "./atomic-file";
+import { isExistingPathWithinRoots } from "./path-security";
+import { PRESET_READ_ONLY, DEFAULT_TOOLS } from "./tool-presets";
+import type { SessionEntry, SubagentSessionStatus } from "./types";
+
+export const SUBAGENT_META_TYPE = "pi-web:subagent";
+export const SUBAGENT_STATUS_TYPE = "pi-web:subagent-status";
+export const SUBAGENT_RESULT_TYPE = "pi-web:subagent-result";
+export const SUBAGENT_CONTROL_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"] as const;
+
+export type SubagentStatus = SubagentSessionStatus;
+export type SubagentScope = "builtin" | "global" | "workspace" | "project";
+export type SubagentWritableScope = Extract<SubagentScope, "global" | "project">;
+
+export interface SubagentProfile {
+  name: string;
+  displayName: string;
+  description: string;
+  systemPrompt: string;
+  tools: string[];
+  extensionTools?: string[];
+  loadSkills: boolean;
+  loadExtensions: boolean;
+  model?: string;
+  thinking?: ThinkingLevel;
+  maxTurns?: number;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  promptMode: "replace" | "append";
+  color?: string;
+  isolation?: "worktree" | "off";
+  persistSession?: boolean;
+  enabled: boolean;
+  scope: SubagentScope;
+  filePath?: string;
+}
+
+export interface SubagentMetadata {
+  version: 1;
+  parentSessionId: string;
+  parentSessionPath: string;
+  parentToolCallId: string;
+  profile: string;
+  description: string;
+  task: string;
+  runInBackground: boolean;
+  createdAt: string;
+  resourceSnapshot: SubagentResourceSnapshot;
+  worktreePath?: string;
+  worktreeBranch?: string;
+}
+
+export interface SubagentResourceSnapshot {
+  version: 1;
+  appendSystemPrompt: string[];
+  tools: string[];
+  loadSkills: boolean;
+  loadExtensions: boolean;
+  exactSystemPrompt?: string;
+}
+
+export interface SubagentSessionResources {
+  appendSystemPrompt: string[];
+  tools: string[];
+  loadSkills: boolean;
+  loadExtensions: boolean;
+  exactSystemPrompt?: string;
+}
+
+export interface SubagentResultMetadata {
+  version: 1;
+  status: Exclude<SubagentStatus, "starting" | "running" | "queued" | "interrupted">;
+  completedAt: string;
+  result?: string;
+  error?: string;
+  worktreeCleanupError?: string;
+}
+
+export interface SubagentStatusMetadata {
+  version: 1;
+  status: Extract<SubagentStatus, "queued" | "running">;
+}
+
+export interface SubagentRunInfo {
+  sessionId: string;
+  sessionPath: string;
+  parentSessionId: string;
+  parentToolCallId: string;
+  profile: string;
+  description: string;
+  task: string;
+  runInBackground: boolean;
+  status: SubagentStatus;
+  createdAt: string;
+  completedAt?: string;
+  result?: string;
+  error?: string;
+  worktreePath?: string;
+  worktreeBranch?: string;
+  worktreeCleanupError?: string;
+}
+
+const BUILTIN_TOOLS = new Set(DEFAULT_TOOLS);
+const SUBAGENT_CONTROL_TOOLS = new Set<string>(SUBAGENT_CONTROL_TOOL_NAMES);
+const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+/**
+ * Frontmatter keys the web UI owns. Everything else in a profile file belongs to
+ * whichever runtime reads it (pi-subagents and friends), so a save from this app must
+ * carry those keys through untouched. Dropping them silently changed behaviour:
+ * `allowed_subagents` was lost and an orchestrator could no longer spawn anything,
+ * `exclude_extensions` was lost and an opt-out became an opt-in.
+ */
+const MANAGED_FRONTMATTER_KEYS = new Set([
+  "description",
+  "display_name",
+  "tools",
+  "load_skills",
+  "load_extensions",
+  "enabled",
+  "inherit_context",
+  "run_in_background",
+  "model",
+  "thinking",
+  "max_turns",
+  "prompt_mode",
+  "color",
+  "isolation",
+  "persist_session",
+]);
+
+const FRONTMATTER_OPEN_RE = /^(?:\uFEFF)?---[ \t]*(?:\r\n|\n|\r)/;
+
+/**
+ * The UI exposes two booleans (`load_skills` / `load_extensions`); pi-subagents reads
+ * the aliases `skills` / `extensions`, which also accept a whitelist. Aliases are
+ * carried through by `unmanagedFrontmatter` and only rewritten once we own them.
+ */
+const OWNED_ALIAS_VALUES = new Set(["none", "all", "true", "false"]);
+
+const BUILTIN_PROFILES: SubagentProfile[] = [
+  {
+    name: "general-purpose",
+    displayName: "General purpose",
+    description: "Handle a focused implementation or investigation task",
+    systemPrompt: "Work autonomously on the delegated task. Keep the final answer concise and include important files, decisions, and remaining risks.",
+    tools: DEFAULT_TOOLS,
+    loadSkills: false,
+    loadExtensions: false,
+    promptMode: "append",
+    inheritContext: false,
+    runInBackground: false,
+    enabled: true,
+    scope: "builtin",
+  },
+  {
+    name: "explore",
+    displayName: "Explore",
+    description: "Quickly inspect a codebase without modifying it",
+    systemPrompt: "Explore the codebase to answer the delegated question. Do not modify files. Report concrete findings with file paths and relevant symbols.",
+    tools: [...PRESET_READ_ONLY],
+    loadSkills: false,
+    loadExtensions: false,
+    promptMode: "append",
+    inheritContext: false,
+    runInBackground: false,
+    enabled: true,
+    scope: "builtin",
+  },
+  {
+    name: "plan",
+    displayName: "Plan",
+    description: "Design an implementation plan without modifying files",
+    systemPrompt: "Produce an implementation-ready plan for the delegated task. Inspect the repository as needed, do not modify files, and call out dependencies, risks, and verification steps.",
+    tools: [...PRESET_READ_ONLY],
+    loadSkills: false,
+    loadExtensions: false,
+    promptMode: "append",
+    inheritContext: false,
+    runInBackground: false,
+    enabled: true,
+    scope: "builtin",
+  },
+];
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function booleanValue(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function resourceBoolean(value: unknown, fallback: boolean): boolean {
+  if (typeof value === "boolean") return value;
+  return Array.isArray(value) || typeof value === "string" ? true : fallback;
+}
+
+function stringList(value: unknown): string[] {
+  const values = Array.isArray(value)
+    ? value
+    : typeof value === "string"
+      ? value.split(",")
+      : [];
+  return values.map((item) => String(item).trim()).filter(Boolean);
+}
+
+function parseTools(value: unknown, fallback: string[]): string[] {
+  const tools = stringList(value);
+  if (tools.includes("none")) return [];
+  if (tools.includes("all") || tools.includes("*")) return [...DEFAULT_TOOLS];
+  if (tools.length === 0) return [...fallback];
+  return [...new Set(tools.filter((tool) => BUILTIN_TOOLS.has(tool)))];
+}
+
+function rawToolValues(value: unknown): string[] {
+  return stringList(value);
+}
+
+function parseExtensionToolSelectors(value: unknown): string[] {
+  return [...new Set(rawToolValues(value).filter((tool) => tool.toLowerCase().startsWith("ext:")))];
+}
+
+/** Read existing frontmatter without allowing malformed metadata to be overwritten. */
+function readStoredFrontmatter(filePath: string): Record<string, unknown> {
+  if (!existsSync(filePath)) return {};
+  const source = readFileSync(filePath, "utf8");
+  const { data } = parseFrontmatter(source);
+  if (data) return data;
+  if (FRONTMATTER_OPEN_RE.test(source)) {
+    throw new Error("Cannot save agent profile: existing frontmatter is invalid");
+  }
+  return {};
+}
+
+/** Keys another runtime owns, in file order, so a save round-trips them. */
+function unmanagedFrontmatter(stored: Record<string, unknown>): Record<string, unknown> {
+  const preserved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(stored)) {
+    if (!MANAGED_FRONTMATTER_KEYS.has(key)) preserved[key] = value;
+  }
+  return preserved;
+}
+
+/**
+ * pi-web filters `tools` down to the built-ins it can dispatch, which would drop
+ * another runtime's `ext:<name>` selectors on every save — carry them through.
+ */
+function composeToolsField(tools: string[], storedTools: unknown): string {
+  const selectors = stringList(storedTools).filter((tool) => tool.startsWith("ext:"));
+  const combined = [...tools, ...selectors.filter((selector) => !tools.includes(selector))];
+  return combined.length > 0 ? combined.join(", ") : "none";
+}
+
+/**
+ * Keep the alias in step with the boolean the UI owns. A boolean (or a "none" /
+ * "all" spelling) is ours to rewrite; a whitelist such as `extensions:
+ * pi-advisor-flow` expresses scoping the UI cannot show, so it stays as authored.
+ */
+function syncFlagAlias(
+  frontmatter: Record<string, unknown>,
+  alias: string,
+  storedValue: unknown,
+  flag: boolean,
+): void {
+  const owned = storedValue === undefined
+    || typeof storedValue === "boolean"
+    || (typeof storedValue === "string" && OWNED_ALIAS_VALUES.has(storedValue.trim().toLowerCase()));
+  if (owned) frontmatter[alias] = flag;
+}
+function parseProfileFile(filePath: string, scope: SubagentScope): SubagentProfile | null {
+  try {
+    const source = readFileSync(filePath, "utf8");
+    const { data, rest } = parseFrontmatter(source);
+    const name = stringValue(data?.name) ?? basename(filePath, ".md");
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) return null;
+    const thinkingValue = stringValue(data?.thinking) as ThinkingLevel | undefined;
+    const maxTurnsValue = typeof data?.max_turns === "number" ? Math.floor(data.max_turns) : undefined;
+    const tools = parseTools(data?.tools, DEFAULT_TOOLS);
+    const disallowedTools = new Set(parseTools(data?.disallowed_tools, []));
+    const disallowedExtensionTools = new Set(parseExtensionToolSelectors(data?.disallowed_tools).map((tool) => tool.toLowerCase()));
+    const extensionTools = parseExtensionToolSelectors(data?.tools)
+      .filter((tool) => !disallowedExtensionTools.has(tool.toLowerCase()));
+    return {
+      name,
+      displayName: stringValue(data?.display_name) ?? name,
+      description: stringValue(data?.description) ?? name,
+      systemPrompt: rest.trim(),
+      tools: tools.filter((tool) => !disallowedTools.has(tool)),
+      ...(extensionTools.length > 0 ? { extensionTools } : {}),
+      loadSkills: resourceBoolean(data?.load_skills ?? data?.skills, false),
+      loadExtensions: resourceBoolean(data?.load_extensions ?? data?.extensions, extensionTools.length > 0),
+      ...(stringValue(data?.model) ? { model: stringValue(data?.model) } : {}),
+      ...(thinkingValue && THINKING_LEVELS.has(thinkingValue) ? { thinking: thinkingValue } : {}),
+      ...(maxTurnsValue && maxTurnsValue > 0 ? { maxTurns: maxTurnsValue } : {}),
+      inheritContext: booleanValue(data?.inherit_context, false),
+      runInBackground: booleanValue(data?.run_in_background, false),
+      promptMode: data?.prompt_mode === "replace" ? "replace" : "append",
+      ...(stringValue(data?.color) ? { color: stringValue(data?.color) } : {}),
+      ...(data?.isolation === "worktree" || data?.isolation === "off" ? { isolation: data.isolation } : {}),
+      ...(typeof data?.persist_session === "boolean" ? { persistSession: data.persist_session } : {}),
+      enabled: booleanValue(data?.enabled, true),
+      scope,
+      filePath,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function isProjectProfilePathAllowed(cwd: string, target: string): boolean {
+  return isExistingPathWithinRoots(target, new Set([cwd]));
+}
+
+function readProfileDirectory(dir: string, scope: SubagentScope, cwd: string): SubagentProfile[] {
+  if (!existsSync(dir)) return [];
+  if (scope !== "global" && !isProjectProfilePathAllowed(cwd, dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => parseProfileFile(join(dir, entry.name), scope))
+    .filter((profile): profile is SubagentProfile => profile !== null);
+}
+
+function profileDirectories(cwd: string): Array<[string, Exclude<SubagentScope, "builtin">]> {
+  return [
+    [join(getAgentDir(), "agents"), "global"],
+    [join(resolve(cwd), ".agents", "agents"), "workspace"],
+    [join(resolve(cwd), ".pi", "agents"), "project"],
+  ];
+}
+
+/** Every configured source, including profiles shadowed by a higher-precedence scope. */
+export function listSubagentProfileSources(cwd: string): SubagentProfile[] {
+  const profiles = BUILTIN_PROFILES.map((profile) => ({ ...profile, tools: [...profile.tools] }));
+  for (const [dir, scope] of profileDirectories(cwd)) {
+    profiles.push(...readProfileDirectory(dir, scope, cwd));
+  }
+  return profiles.sort((a, b) => a.displayName.localeCompare(b.displayName));
+}
+
+export function listSubagentProfiles(cwd: string): SubagentProfile[] {
+  const byName = new Map(BUILTIN_PROFILES.map((profile) => [profile.name.toLowerCase(), { ...profile, tools: [...profile.tools] }]));
+  for (const [dir, scope] of profileDirectories(cwd)) {
+    for (const profile of readProfileDirectory(dir, scope, cwd)) byName.set(profile.name.toLowerCase(), profile);
+  }
+  return [...byName.values()].sort((a, b) => a.displayName.localeCompare(b.displayName));
+}
+
+export function resolveSubagentProfile(cwd: string, name: string): SubagentProfile | undefined {
+  return listSubagentProfiles(cwd).find((profile) => profile.name.toLowerCase() === name.trim().toLowerCase() && profile.enabled);
+}
+
+function assertProfileName(name: string): string {
+  const normalized = name.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) {
+    throw new Error("Agent name may contain only letters, numbers, dots, underscores, and hyphens");
+  }
+  return normalized;
+}
+
+function writableProfileDirectory(cwd: string, scope: SubagentWritableScope): string {
+  if (scope === "global") return join(getAgentDir(), "agents");
+  if (scope === "project") return join(resolve(cwd), ".pi", "agents");
+  throw new Error("Agent scope must be global or project");
+}
+
+function assertWritableProfileDirectory(cwd: string, scope: SubagentWritableScope): string {
+  const dir = writableProfileDirectory(cwd, scope);
+  if (scope === "global") return dir;
+
+  let existingAncestor = dir;
+  while (!existsSync(existingAncestor)) {
+    const parent = dirname(existingAncestor);
+    if (parent === existingAncestor) throw new Error("Agent profile directory is outside the project root");
+    existingAncestor = parent;
+  }
+  if (!isProjectProfilePathAllowed(cwd, existingAncestor)) {
+    throw new Error("Agent profile directory is outside the project root");
+  }
+  return dir;
+}
+
+export function saveSubagentProfile(
+  cwd: string,
+  scope: SubagentWritableScope,
+  profile: Omit<SubagentProfile, "scope" | "filePath">,
+): SubagentProfile {
+  const name = assertProfileName(profile.name);
+  const tools = [...new Set(profile.tools.filter((tool) => BUILTIN_TOOLS.has(tool)))];
+  const extensionTools = [...new Set(profile.extensionTools ?? [])];
+  if (profile.thinking && !THINKING_LEVELS.has(profile.thinking)) {
+    throw new Error(`Invalid thinking level: ${profile.thinking}`);
+  }
+  if (profile.maxTurns !== undefined && (!Number.isFinite(profile.maxTurns) || profile.maxTurns < 0)) {
+    throw new Error("Max turns must be a non-negative number");
+  }
+  const maxTurns = profile.maxTurns && profile.maxTurns > 0
+    ? Math.floor(profile.maxTurns)
+    : undefined;
+  const displayName = profile.displayName.trim() || name;
+  const description = profile.description.trim() || name;
+  const systemPrompt = profile.systemPrompt.trim();
+  const model = profile.model?.trim() || undefined;
+  const loadSkills = profile.loadSkills === true;
+  const loadExtensions = profile.loadExtensions === true;
+  const promptMode = profile.promptMode === "replace" ? "replace" : "append";
+  const dir = assertWritableProfileDirectory(cwd, scope);
+  mkdirSync(dir, { recursive: true });
+  if (scope === "project" && !isProjectProfilePathAllowed(cwd, dir)) {
+    throw new Error("Agent profile directory is outside the project root");
+  }
+  const filePath = join(dir, `${name}.md`);
+  const stored = readStoredFrontmatter(filePath);
+  const managed: Record<string, unknown> = {
+    description,
+    display_name: displayName,
+    tools: composeToolsField([...tools, ...extensionTools], stored.tools),
+    load_skills: loadSkills,
+    load_extensions: loadExtensions,
+    enabled: profile.enabled,
+    inherit_context: profile.inheritContext,
+    run_in_background: profile.runInBackground,
+    prompt_mode: promptMode,
+  };
+  syncFlagAlias(managed, "skills", stored.skills, loadSkills);
+  syncFlagAlias(managed, "extensions", stored.extensions, loadExtensions);
+  if (model) managed.model = model;
+  if (profile.thinking) managed.thinking = profile.thinking;
+  if (maxTurns) managed.max_turns = maxTurns;
+  if (profile.color?.trim()) managed.color = profile.color.trim();
+  if (profile.isolation) managed.isolation = profile.isolation;
+  if (profile.persistSession !== undefined) managed.persist_session = profile.persistSession;
+  // Managed keys win; keys this app does not own follow in their original order.
+  const frontmatter: Record<string, unknown> = { ...managed };
+  for (const [key, value] of Object.entries(unmanagedFrontmatter(stored))) {
+    if (!(key in frontmatter)) frontmatter[key] = value;
+  }
+  const yaml = stringifyYaml(frontmatter, { noRefs: true, lineWidth: 1000 }).trimEnd();
+  writePrivateFileAtomicSync(filePath, `---\n${yaml}\n---\n\n${systemPrompt}\n`);
+  return {
+    ...profile,
+    name,
+    displayName,
+    description,
+    systemPrompt,
+    tools,
+    ...(extensionTools.length > 0 ? { extensionTools } : {}),
+    loadSkills,
+    loadExtensions,
+    ...(model ? { model } : { model: undefined }),
+    ...(maxTurns ? { maxTurns } : { maxTurns: undefined }),
+    promptMode,
+    ...(profile.color ? { color: profile.color } : {}),
+    ...(profile.isolation ? { isolation: profile.isolation } : {}),
+    ...(profile.persistSession !== undefined ? { persistSession: profile.persistSession } : {}),
+    scope,
+    filePath,
+  };
+}
+
+export function deleteSubagentProfile(cwd: string, scope: SubagentWritableScope, name: string): void {
+  const safeName = assertProfileName(name);
+  const filePath = join(assertWritableProfileDirectory(cwd, scope), `${safeName}.md`);
+  if (existsSync(filePath)) unlinkSync(filePath);
+}
+
+export function saveProjectSubagentProfile(cwd: string, profile: Omit<SubagentProfile, "scope" | "filePath">): SubagentProfile {
+  return saveSubagentProfile(cwd, "project", profile);
+}
+
+export function deleteProjectSubagentProfile(cwd: string, name: string): void {
+  deleteSubagentProfile(cwd, "project", name);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+type ValidSubagentMetadataData = Record<string, unknown> & {
+  version: 1;
+  parentSessionId: string;
+  parentSessionPath: string;
+};
+
+function subagentMetadataData(entries: readonly SessionEntry[]): ValidSubagentMetadataData | null {
+  const metaEntry = entries.find((entry) => entry.type === "custom" && entry.customType === SUBAGENT_META_TYPE);
+  if (!metaEntry || metaEntry.type !== "custom" || !isRecord(metaEntry.data)) return null;
+  const data = metaEntry.data;
+  if (data.version !== 1 || typeof data.parentSessionId !== "string" || typeof data.parentSessionPath !== "string") return null;
+  return data as ValidSubagentMetadataData;
+}
+
+/** Restore the isolated prompt and tool scope used by a persisted subagent session. */
+export function readSubagentSessionResources(
+  entries: readonly SessionEntry[],
+): SubagentSessionResources | null {
+  const data = subagentMetadataData(entries);
+  if (!data) return null;
+  const snapshot = data.resourceSnapshot;
+  const loadSkills = isRecord(snapshot) && snapshot.loadSkills === true;
+  const loadExtensions = isRecord(snapshot) && snapshot.loadExtensions === true;
+  if (
+    isRecord(snapshot)
+    && snapshot.version === 1
+    && Array.isArray(snapshot.appendSystemPrompt)
+    && snapshot.appendSystemPrompt.every((item) => typeof item === "string")
+    && Array.isArray(snapshot.tools)
+    && snapshot.tools.every((item) =>
+      typeof item === "string"
+      && item.length > 0
+      && !SUBAGENT_CONTROL_TOOLS.has(item)
+      && (BUILTIN_TOOLS.has(item) || loadExtensions)
+    )
+  ) {
+    return {
+      appendSystemPrompt: [...snapshot.appendSystemPrompt],
+      tools: [...new Set(snapshot.tools)],
+      loadSkills,
+      loadExtensions,
+      ...(typeof snapshot.exactSystemPrompt === "string" ? { exactSystemPrompt: snapshot.exactSystemPrompt } : {}),
+    };
+  }
+  return null;
+}
+
+export function withSubagentExtensionTools(
+  profileTools: readonly string[],
+  extensionToolNames: Iterable<string>,
+): string[] {
+  return [...new Set([
+    ...profileTools,
+    ...[...extensionToolNames].filter((name) => !SUBAGENT_CONTROL_TOOLS.has(name)),
+  ])];
+}
+
+export function selectSubagentExtensionTools(
+  extensions: Iterable<{ path: string; sourceInfo?: { source?: string }; tools: Map<string, unknown> }>,
+  selectors: readonly string[],
+): string[] {
+  const wanted = selectors.map((selector) => selector.slice(4).toLowerCase());
+  return [...extensions].flatMap((extension) => {
+    const pathName = extension.path.replaceAll("\\", "/").split("/").at(-2) ?? extension.path;
+    const sourceName = (extension.sourceInfo?.source ?? "").replace(/^npm:/, "");
+    const extensionNames = new Set([pathName.toLowerCase(), sourceName.toLowerCase()]);
+    const selected = wanted.some((selector) => {
+      if (selector === "*") return true;
+      const [extensionName, toolName] = selector.split("/", 2);
+      return extensionNames.has(extensionName) && (!toolName || extension.tools.has(toolName));
+    });
+    if (!selected) return [];
+    return [...extension.tools.keys()].filter((toolName) => wanted.some((selector) => {
+      if (selector === "*" || selector.endsWith("/*")) return selector === "*" || extensionNames.has(selector.slice(0, -2));
+      const [extensionName, selectedTool] = selector.split("/", 2);
+      return extensionNames.has(extensionName) && (!selectedTool || selectedTool === toolName);
+    }));
+  });
+}
+
+export function readSubagentRun(entries: readonly SessionEntry[], sessionId: string, sessionPath: string): SubagentRunInfo | null {
+  const data = subagentMetadataData(entries);
+  if (!data) return null;
+  const lifecycleEntry = [...entries].reverse().find((entry) =>
+    entry.type === "custom" && (entry.customType === SUBAGENT_RESULT_TYPE || entry.customType === SUBAGENT_STATUS_TYPE)
+  );
+  const resultEntry = lifecycleEntry?.type === "custom" && lifecycleEntry.customType === SUBAGENT_RESULT_TYPE
+    ? lifecycleEntry
+    : undefined;
+  const result = resultEntry?.type === "custom" && isRecord(resultEntry.data) ? resultEntry.data : undefined;
+  const statusEntry = lifecycleEntry?.type === "custom" && lifecycleEntry.customType === SUBAGENT_STATUS_TYPE
+    ? lifecycleEntry
+    : undefined;
+  const statusData = statusEntry?.type === "custom" && isRecord(statusEntry.data) ? statusEntry.data : undefined;
+  const persistedStatus = result && (result.status === "completed" || result.status === "failed" || result.status === "aborted")
+    ? result.status
+    : statusData?.version === 1 && (statusData.status === "queued" || statusData.status === "running")
+      ? statusData.status
+      : "interrupted";
+  return {
+    sessionId,
+    sessionPath,
+    parentSessionId: data.parentSessionId,
+    parentToolCallId: typeof data.parentToolCallId === "string" ? data.parentToolCallId : "",
+    profile: typeof data.profile === "string" ? data.profile : "general-purpose",
+    description: typeof data.description === "string" ? data.description : "Subagent",
+    task: typeof data.task === "string" ? data.task : "",
+    runInBackground: data.runInBackground === true,
+    status: persistedStatus,
+    createdAt: typeof data.createdAt === "string" ? data.createdAt : "",
+    ...(result && typeof result.completedAt === "string" ? { completedAt: result.completedAt } : {}),
+    ...(result && typeof result.result === "string" ? { result: result.result } : {}),
+    ...(result && typeof result.error === "string" ? { error: result.error } : {}),
+    ...(typeof data.worktreePath === "string" ? { worktreePath: data.worktreePath } : {}),
+    ...(typeof data.worktreeBranch === "string" ? { worktreeBranch: data.worktreeBranch } : {}),
+    ...(result && typeof result.worktreeCleanupError === "string" ? { worktreeCleanupError: result.worktreeCleanupError } : {}),
+  };
+}

package/lib/task-scheduler.test.mjs

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
 import test from "node:test";
 import { DatabaseSync } from "node:sqlite";
 import { createJiti } from "jiti";
@@ -76,3 +77,29 @@ test("clearSchedulerLeaderForTesting 清空后可重新注册", () => {
   assert.equal(getLeaderInstanceId(), null);
   assert.equal(tryBecomeLeader("inst-b"), true);
 });
+
+// ── 派发时的归属失败不能静默 ──
+// assignSessionToTask 会拒绝（返回 false）：祖先属别的任务 / 会话解析不出。丢了返回值的话
+// 「派发了但会话没进任务区」在日志里毫无痕迹（reconcile 会把它当孤儿卡）。
+
+const schedulerSource = await readFile(new URL("./task-scheduler.ts", import.meta.url), "utf8");
+
+/** 取 [from, to) 之间的源码片段；锚点找不到就报错（避免静默退化成整文件切片）。 */
+function sliceBetween(text, from, to) {
+  const start = text.indexOf(from);
+  assert.ok(start >= 0, `切片起点不存在：${from}`);
+  const end = text.indexOf(to, start);
+  assert.ok(end > start, `切片终点不存在（或不在起点之后）：${to}`);
+  return text.slice(start, end);
+}
+
+test("派发会话归属失败不静默：检查 assignSessionToTask 返回值并 console.warn", () => {
+  const assignBlock = sliceBetween(
+    schedulerSource,
+    "const board = getBoard(card.boardId);",
+    "if (session.session.isRunning())",
+  );
+  assert.match(assignBlock, /const assigned = await assignSessionToTask\(/, "返回值必须接住");
+  assert.match(assignBlock, /if \(!assigned\)[\s\S]*?console\.warn\(/, "失败必须可见（console.warn）");
+  assert.match(assignBlock, /派发的会话未能归属任务/);
+});

package/lib/task-scheduler.ts

@@ -156,7 +156,14 @@ export async function dispatchCard(card: TaskCard): Promise<boolean> {
 
     const board = getBoard(card.boardId);
     if (board?.taskId) {
-      assignSessionToTask(session.realSessionId, board.taskId);
+      // 返回值不能丢：拒绝（祖先属别的任务 / 会话解析不出）时这个会话不会进任务区，
+      // 而 reconcile 按「卡在任务里」补卡——静默失败会让派发结果不可解释。
+      const assigned = await assignSessionToTask(session.realSessionId, board.taskId);
+      if (!assigned) {
+        console.warn(
+          `[task-scheduler] #${card.number} ${card.name} 派发的会话未能归属任务 task=${board.taskId} session=${session.realSessionId}`,
+        );
+      }
       // 注意：不在 assignSessionToTask 后 reconcile——此刻卡 sessionId 未落表，
       // reconcile 只能补会话卡、建不了 exec 线 → 造成「先出卡后出线」。
       // 统一在 updateCard(sessionId) 之后触发（补卡+建线同一次事务、一次广播）。