@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/src/subagent-manager-handle.ts

@@ -0,0 +1,8 @@
+import type { SubagentManager } from "../subagents/src/contracts.js";
+
+const SUBAGENT_MANAGER_KEY = Symbol.for("pi-extensible-workflows.subagent-manager");
+const globalSubagentManagers = globalThis as typeof globalThis & Record<symbol, SubagentManager | undefined>;
+
+export function setSubagentManager(manager: SubagentManager | undefined): void { globalSubagentManagers[SUBAGENT_MANAGER_KEY] = manager; }
+export function getSubagentManager(): SubagentManager | undefined { return globalSubagentManagers[SUBAGENT_MANAGER_KEY]; }
+export function clearSubagentManager(manager: SubagentManager): void { if (globalSubagentManagers[SUBAGENT_MANAGER_KEY] === manager) globalSubagentManagers[SUBAGENT_MANAGER_KEY] = undefined; }

package/src/tool-timing.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI, ExtensionFactory, ToolExecutionEndEvent, ToolExecutionStartEvent } from "@earendil-works/pi-coding-agent";
+
+export const TOOL_TIMING_ENTRY_TYPE = "pi-workflows:tool-timing";
+
+export interface ToolTimingEntry {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly startedAt: number;
+  readonly completedAt: number;
+  readonly durationMs: number;
+  readonly isError: boolean;
+}
+
+// NOTE: Keep this factory closure-free because Herdr serializes its source for the child Pi process.
+// NOTE: The entry type literal must match TOOL_TIMING_ENTRY_TYPE; it is local for the same serialization boundary.
+type ClockedToolTimingExtension = (pi: ExtensionAPI, clock?: () => number) => void;
+// Bound unfinished executions so missing end events cannot grow session state indefinitely.
+const toolTimingExtension: ClockedToolTimingExtension = (pi, clock = Date.now) => {
+  const MAX_ACTIVE_TOOL_TIMINGS = 400;
+  const starts = new Map<string, { toolName: string; startedAt: number }>();
+  pi.on("tool_execution_start", (event: ToolExecutionStartEvent) => {
+    if (!starts.has(event.toolCallId) && starts.size >= MAX_ACTIVE_TOOL_TIMINGS) return;
+    starts.set(event.toolCallId, { toolName: event.toolName, startedAt: clock() });
+  });
+  pi.on("tool_execution_end", (event: ToolExecutionEndEvent) => {
+    const started = starts.get(event.toolCallId);
+    if (started === undefined) return;
+    starts.delete(event.toolCallId);
+    const completedAt = clock();
+    pi.appendEntry<ToolTimingEntry>("pi-workflows:tool-timing", {
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      startedAt: started.startedAt,
+      completedAt,
+      durationMs: Math.max(0, completedAt - started.startedAt),
+      isError: event.isError,
+    });
+  });
+  pi.on("session_shutdown", () => { starts.clear(); });
+};
+
+export const TOOL_TIMING_EXTENSION: ExtensionFactory = toolTimingExtension;
+
+export function createToolTimingExtension(clock: () => number = Date.now): ExtensionFactory {
+  if (clock === Date.now) return TOOL_TIMING_EXTENSION;
+  return (pi: ExtensionAPI) => { toolTimingExtension(pi, clock); };
+}

package/src/trajectory-contracts.ts

@@ -0,0 +1,13 @@
+export type TrajectoryAction = "checkpoint-approve" | "checkpoint-reject" | "pause" | "resume" | "steer" | "stop" | "retry" | "share";
+export type TrajectoryTarget = { kind: "run" | "subagent"; id: string };
+
+const TRAJECTORY_ACTIONS: readonly TrajectoryAction[] = ["checkpoint-approve", "checkpoint-reject", "pause", "resume", "steer", "stop", "retry", "share"];
+
+export function isTrajectoryAction(value: unknown): value is TrajectoryAction { return typeof value === "string" && TRAJECTORY_ACTIONS.includes(value as TrajectoryAction); }
+export function isTrajectoryTarget(value: unknown): value is TrajectoryTarget {
+  const target = value as { kind?: unknown; id?: unknown };
+  return typeof value === "object" && value !== null && !Array.isArray(value) && (target.kind === "run" || target.kind === "subagent") && typeof target.id === "string" && target.id.length >= 1 && target.id.length <= 200;
+}
+export function trajectoryActionError(action: TrajectoryAction, target: TrajectoryTarget): string | undefined {
+  return target.kind === "subagent" && (action === "checkpoint-approve" || action === "checkpoint-reject" || action === "pause" || action === "resume" || action === "share") ? `Trajectory action ${action} is not supported for subagent targets` : target.kind === "run" && action === "steer" ? "Trajectory action steer is not supported for run targets" : undefined;
+}

package/src/trajectory-host-handle.ts

@@ -0,0 +1,16 @@
+import type { TrajectoryPublisherInput } from "./trajectory.js";
+
+export type TrajectoryPublisherProvider = (context: unknown) => TrajectoryPublisherInput;
+
+export type TrajectoryHost = {
+  open(provider: TrajectoryPublisherProvider, context: unknown): Promise<void>;
+  autoAttach(provider: TrajectoryPublisherProvider, context: { hasUI: boolean }): void;
+  close(): Promise<void>;
+};
+
+const TRAJECTORY_HOST_KEY = Symbol.for("pi-extensible-workflows.trajectory-host");
+const globalTrajectoryHosts = globalThis as typeof globalThis & Record<symbol, TrajectoryHost | undefined>;
+
+export function setTrajectoryHost(host: TrajectoryHost | undefined): void { globalTrajectoryHosts[TRAJECTORY_HOST_KEY] = host; }
+export function getTrajectoryHost(): TrajectoryHost | undefined { return globalTrajectoryHosts[TRAJECTORY_HOST_KEY]; }
+export function clearTrajectoryHost(host: TrajectoryHost): void { if (globalTrajectoryHosts[TRAJECTORY_HOST_KEY] === host) globalTrajectoryHosts[TRAJECTORY_HOST_KEY] = undefined; }

package/src/trajectory.ts

@@ -0,0 +1,543 @@
+import { createHash } from "node:crypto";
+import { open, readFile, readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, DefaultPackageManager, getAgentDir, SettingsManager, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
+import { listRunIds, RunStore, type AwaitingCheckpoint, type EffectiveSystemPrompt, type PersistedRun } from "./persistence.js";
+import { navigatorAttentionSortByState } from "./host-view.js";
+import type { AgentAttemptSummary, JsonValue, LaunchSnapshot, WorkflowAgentSessionReference } from "./types.js";
+import { normalizeSubagentRunRequest, type SubagentProgress, type SubagentRunRequest, type SubagentStatus } from "../subagents/src/contracts.js";
+import { statusValue, subagentErrorValue } from "../subagents/src/decode.js";
+import { isNodeError, jsonValue, object, resourcePatternHasMagic, selectResourcesByLayers } from "./utils.js";
+import type { TrajectoryAction, TrajectoryTarget } from "./trajectory-contracts.js";
+import { canonicalPath, sameFilesystemPath } from "./paths.js";
+
+export const TRAJECTORY_MAX_TRANSCRIPT_BYTES = 2 * 1024 * 1024;
+const TRAJECTORY_MAX_NON_TIMING_ENTRIES = 400;
+
+export type TrajectoryRun = {
+  run: PersistedRun;
+  snapshot: Readonly<LaunchSnapshot>;
+  awaiting: readonly AwaitingCheckpoint[];
+  createdAt?: string;
+  transcripts: Readonly<Record<string, readonly unknown[]>>;
+};
+export type TrajectoryTranscriptStatus = "available" | "empty" | "missing" | "failed" | "oversized" | "disconnected";
+export type TrajectoryTranscriptMetadata = { readonly revision: number; readonly status: TrajectoryTranscriptStatus; readonly bytes?: number; readonly timing?: readonly unknown[]; };
+export type TrajectoryRunMetadata = Omit<TrajectoryRun, "transcripts"> & { transcripts: Readonly<Record<string, TrajectoryTranscriptMetadata>> };
+export type TrajectorySubagentArtifact = { readonly truncated: true; readonly path: string; readonly bytes: number };
+export type TrajectorySubagent = {
+  id: string;
+  sessionId: string;
+  cwd: string;
+  label?: string;
+  role?: string;
+  mode: "background" | "foreground";
+  state: SubagentStatus["state"];
+  startedAt?: number;
+  finishedAt?: number;
+  attempts?: number;
+  error?: { readonly code: string; readonly message: string };
+  worktree?: { readonly path: string; readonly branch: string };
+  request: Readonly<SubagentRunRequest>;
+  tools: readonly string[];
+  toolDefinitions?: readonly { readonly name: string; readonly description: string }[];
+  model?: AgentAttemptSummary["setup"]["model"];
+  progress?: SubagentProgress;
+  attempt?: AgentAttemptSummary;
+  result?: JsonValue | TrajectorySubagentArtifact;
+  failure?: { readonly code: string; readonly message: string } | TrajectorySubagentArtifact;
+  transcript: readonly unknown[];
+};
+export type TrajectorySubagentMetadata = Omit<TrajectorySubagent, "transcript"> & { transcript: TrajectoryTranscriptMetadata };
+export type TrajectoryTranscriptRequest = { readonly runId?: string; readonly agentId?: string; readonly subagentId?: string; readonly revision?: number };
+export type TrajectorySubagentSessionResolver = (subagentId: string) => WorkflowAgentSessionReference | undefined;
+export type TrajectoryTranscriptResult = { readonly status: TrajectoryTranscriptStatus; readonly revision: number; readonly entries: readonly unknown[]; readonly bytes?: number; readonly error?: string };
+export type TrajectoryTranscriptLoader = (request: Readonly<TrajectoryTranscriptRequest>) => Promise<TrajectoryTranscriptResult>;
+export type TrajectoryRunMetadataLoader = () => Promise<readonly TrajectoryRunMetadata[]>;
+export type TrajectorySubagentMetadataLoader = () => Promise<readonly TrajectorySubagentMetadata[]>;
+export type TrajectoryPublisherMetadata = { readonly runs: readonly TrajectoryRunMetadata[]; readonly subagents: readonly TrajectorySubagentMetadata[] };
+export type TrajectoryPublisherMetadataLoader = () => Promise<TrajectoryPublisherMetadata>;
+export type TrajectorySubagentLoader = () => Promise<readonly TrajectorySubagent[]>;
+export type { TrajectoryAction, TrajectoryTarget } from "./trajectory-contracts.js";
+export { isTrajectoryAction, isTrajectoryTarget, trajectoryActionError } from "./trajectory-contracts.js";
+export type TrajectoryActionRequest = { action: TrajectoryAction; target: TrajectoryTarget; name?: string; payload?: unknown };
+export type TrajectoryActionResult = { readonly id: string; readonly state: "running" };
+export type TrajectoryActionHandler = (request: Readonly<TrajectoryActionRequest>) => Promise<void> | Promise<TrajectoryActionResult | undefined>;
+export type TrajectoryRunLoader = () => Promise<readonly TrajectoryRun[]>;
+export type TrajectoryPublisherInput = {
+  cwd: string;
+  sessionId: string;
+  port?: number;
+  themes: boolean;
+  loadRuns: TrajectoryRunLoader;
+  loadSubagents: TrajectorySubagentLoader;
+  loadMetadata: TrajectoryPublisherMetadataLoader;
+  loadTranscript?: TrajectoryTranscriptLoader;
+  handleAction: TrajectoryActionHandler;
+};
+
+function sessionFile(reference: WorkflowAgentSessionReference | undefined): string | undefined {
+  const locator = reference?.locator;
+  if (!object(locator) || typeof locator.sessionFile !== "string" || !locator.sessionFile) return undefined;
+  return locator.sessionFile;
+}
+function transcriptToolCallId(value: unknown): string | undefined {
+  if (!object(value)) return undefined;
+  if (typeof value.toolCallId === "string") return value.toolCallId;
+  const message = object(value.message) ? value.message : undefined;
+  if (message && typeof message.toolCallId === "string") return message.toolCallId;
+  if (!message || !Array.isArray(message.content)) return undefined;
+  for (const part of message.content) if (object(part) && typeof part.id === "string") return part.id;
+  return undefined;
+}
+function isTimingTranscriptEntry(value: unknown): boolean { return object(value) && value.type === "custom" && value.customType === "pi-workflows:tool-timing"; }
+function timingToolCallId(value: unknown): string | undefined {
+  if (!object(value) || !isTimingTranscriptEntry(value) || !object(value.data)) return undefined;
+  return typeof value.data.toolCallId === "string" ? value.data.toolCallId : undefined;
+}
+class OversizedTranscriptError extends Error {}
+async function readTranscript(path: string, throwOnError = false): Promise<readonly unknown[]> {
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) return [];
+    const startOffset = Math.max(0, info.size - TRAJECTORY_MAX_TRANSCRIPT_BYTES);
+    const length = info.size - startOffset;
+    handle = await open(path, "r");
+    const buffer = Buffer.alloc(length);
+    let bytesRead = 0;
+    while (bytesRead < length) {
+      const result = await handle.read(buffer, bytesRead, length - bytesRead, startOffset + bytesRead);
+      if (result.bytesRead === 0) break;
+      bytesRead += result.bytesRead;
+    }
+    let content = buffer.subarray(0, bytesRead).toString("utf8");
+    if (startOffset > 0) {
+      const boundary = Buffer.alloc(1);
+      const boundaryRead = await handle.read(boundary, 0, 1, startOffset - 1);
+      const startsAtRecordBoundary = boundaryRead.bytesRead === 1 && boundary[0] === 0x0a;
+      const firstLine = content.indexOf("\n");
+      if (firstLine < 0) {
+        if (!startsAtRecordBoundary && throwOnError) throw new OversizedTranscriptError("Transcript is too large");
+        if (!startsAtRecordBoundary) return [];
+      } else if (firstLine === content.length - 1 && content.slice(0, firstLine).trim() && !startsAtRecordBoundary) {
+        if (throwOnError) throw new OversizedTranscriptError("Transcript is too large");
+        return [];
+      } else content = content.slice(firstLine + 1);
+    }
+    const entries: unknown[] = [];
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const value: unknown = JSON.parse(line);
+        if (object(value)) entries.push(value);
+      } catch { /* A partially written JSONL line is ignored until the next poll. */ }
+    }
+    const retainedEntries = entries.filter((entry) => !isTimingTranscriptEntry(entry)).slice(-TRAJECTORY_MAX_NON_TIMING_ENTRIES);
+    const retainedIds = new Set(retainedEntries.map(transcriptToolCallId).filter((id): id is string => id !== undefined));
+    const retainedTiming = entries.filter((entry) => { const id = timingToolCallId(entry); return id !== undefined && retainedIds.has(id); });
+    const retained = new Set([...retainedEntries, ...retainedTiming]);
+    return entries.filter((entry) => retained.has(entry));
+  } catch (error) { if (throwOnError) throw error; return []; }
+  finally { await handle?.close(); }
+}
+
+function transcriptPaths(run: PersistedRun): ReadonlyMap<string, string> {
+  const paths = new Map<string, string>();
+  for (const agent of run.agents) {
+    const path = sessionFile(agent.attemptDetails?.at(-1)?.session);
+    if (path) paths.set(agent.id, path);
+  }
+  return paths;
+}
+
+async function runTranscripts(run: PersistedRun): Promise<Readonly<Record<string, readonly unknown[]>>> {
+  const result: Record<string, readonly unknown[]> = {};
+  for (const [agentId, path] of transcriptPaths(run)) result[agentId] = await readTranscript(path);
+  return result;
+}
+
+export function applySystemPrompts(run: PersistedRun, prompts: readonly EffectiveSystemPrompt[]): PersistedRun {
+  if (!prompts.length) return run;
+  const bySession = new Map<string, string>();
+  for (const entry of prompts) bySession.set(entry.sessionId, entry.prompt);
+  const agents = run.agents.map((agent) => {
+    if (agent.systemPrompt) return agent;
+    const sessionId = agent.attemptDetails?.at(-1)?.session?.sessionId;
+    const prompt = typeof sessionId === "string" ? bySession.get(sessionId) : undefined;
+    if (prompt === undefined) return agent;
+    return { ...agent, systemPrompt: prompt };
+  });
+  if (agents.every((agent, index) => agent === run.agents[index])) return run;
+  return { ...run, agents };
+}
+function toolDefinitionsFor(tools: readonly string[], catalog: ReadonlyMap<string, string>): readonly { readonly name: string; readonly description: string }[] {
+  return tools.flatMap((name) => {
+    const description = catalog.get(name);
+    return description ? [{ name, description }] : [];
+  });
+}
+export function applyToolDescriptions(run: PersistedRun, catalog: ReadonlyMap<string, string>): PersistedRun {
+  const agents = run.agents.map((agent) => {
+    if (agent.toolDefinitions?.length) return agent;
+    const toolDefinitions = toolDefinitionsFor(agent.tools, catalog);
+    if (!toolDefinitions.length) return agent;
+    return { ...agent, toolDefinitions };
+  });
+  if (agents.every((agent, index) => agent === run.agents[index])) return run;
+  return { ...run, agents };
+}
+
+function piToolCatalog(cwd = process.cwd()): ReadonlyMap<string, string> {
+  return new Map([
+    createReadToolDefinition(cwd),
+    createBashToolDefinition(cwd),
+    createGrepToolDefinition(cwd),
+    createFindToolDefinition(cwd),
+    createLsToolDefinition(cwd),
+    createEditToolDefinition(cwd),
+    createWriteToolDefinition(cwd),
+  ].map((tool) => [tool.name, tool.description]));
+}
+export function withPiToolDescriptions(run: PersistedRun): PersistedRun {
+  return applyToolDescriptions(run, piToolCatalog());
+}
+export function withPiToolDescriptionsForTools(tools: readonly string[], cwd: string): readonly { readonly name: string; readonly description: string }[] {
+  return toolDefinitionsFor(tools, piToolCatalog(cwd));
+}
+
+function canonicalExtensionSelector(selector: string, base: string): string {
+  const negated = selector.startsWith("!");
+  const body = negated ? selector.slice(1) : selector;
+  if (body === "*" || body === "**" || body.startsWith("**/")) return selector;
+  const resolved = resolve(base, body);
+  if (resourcePatternHasMagic(body)) return `${negated ? "!" : ""}${resolved}`;
+  return `${negated ? "!" : ""}${canonicalPath(resolved)}`;
+}
+function skillNameFromPath(path: string): string {
+  const file = basename(path);
+  return file.toLowerCase() === "skill.md" ? basename(dirname(path)) : file;
+}
+
+type DiscoveredResources = { skills: readonly string[]; extensions: readonly string[] };
+const discoveredResourcesByCwd = new Map<string, Promise<DiscoveredResources>>();
+async function discoveredResources(cwd: string): Promise<DiscoveredResources> {
+  const cached = discoveredResourcesByCwd.get(cwd);
+  if (cached) return cached;
+  const pending = (async (): Promise<DiscoveredResources> => {
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted: false });
+    const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+    const resolved = await packageManager.resolve();
+    return {
+      extensions: [...new Set(resolved.extensions.filter((entry) => entry.enabled).map((entry) => canonicalPath(entry.path)))],
+      skills: [...new Set(resolved.skills.filter((entry) => entry.enabled).map((entry) => skillNameFromPath(entry.path)))],
+    };
+  })();
+  discoveredResourcesByCwd.set(cwd, pending);
+  // A cached rejection would keep the fallback empty for the rest of the process lifetime.
+  pending.catch(() => discoveredResourcesByCwd.delete(cwd));
+  return pending;
+}
+type ResourceInspection = NonNullable<AgentAttemptSummary["setup"]["resourceSelectors"]>;
+async function resolveResourceInspection(inspection: ResourceInspection | undefined, cwd: string, selectorCwd = cwd): Promise<ResourceInspection | undefined> {
+  if (!inspection || inspection.skills.length && inspection.extensions.length) return inspection;
+  let discovered: DiscoveredResources;
+  try { discovered = await discoveredResources(cwd); } catch { return inspection; }
+  const sources = inspection.selectorSources ?? { global: inspection.selectors, project: {} };
+  const skills = inspection.skills.length ? inspection.skills : selectResourcesByLayers([sources.global.skills, sources.project.skills, sources.role?.skills, sources.call?.skills], discovered.skills);
+  const extensions = inspection.extensions.length ? inspection.extensions : selectResourcesByLayers([sources.global.extensions, sources.project.extensions, sources.role?.extensions, sources.call?.extensions].map((layer) => layer?.map((selector) => canonicalExtensionSelector(selector, selectorCwd))), discovered.extensions);
+  return skills === inspection.skills && extensions === inspection.extensions ? inspection : { ...inspection, skills, extensions };
+}
+export async function withResolvedAttemptResources(attempt: AgentAttemptSummary, cwd: string): Promise<AgentAttemptSummary> {
+  const resourceSelectors = await resolveResourceInspection(attempt.setup.resourceSelectors, cwd, attempt.setup.cwd || cwd);
+  if (resourceSelectors === attempt.setup.resourceSelectors) return attempt;
+  return { ...attempt, setup: { ...attempt.setup, ...(resourceSelectors === undefined ? {} : { resourceSelectors }) } };
+}
+export async function withResolvedResources(run: PersistedRun, cwd: string): Promise<PersistedRun> {
+  const agents = await Promise.all(run.agents.map(async (agent) => {
+    const details = agent.attemptDetails;
+    const last = details?.at(-1);
+    if (!details || !last) return agent;
+    const resourceSelectors = await resolveResourceInspection(last.setup.resourceSelectors, cwd, last.setup.cwd || cwd);
+    if (resourceSelectors === last.setup.resourceSelectors) return agent;
+    return { ...agent, attemptDetails: [...details.slice(0, -1), { ...last, setup: { ...last.setup, ...(resourceSelectors === undefined ? {} : { resourceSelectors }) } }] };
+  }));
+  if (agents.every((agent, index) => agent === run.agents[index])) return run;
+  return { ...run, agents };
+}
+function withoutAgentActivities(run: PersistedRun): PersistedRun {
+  const agents = run.agents.map((agent) => {
+    if (agent.activity === undefined) return agent;
+    const next = { ...agent };
+    delete next.activity;
+    return next;
+  });
+  return agents.every((agent, index) => agent === run.agents[index]) ? run : { ...run, agents };
+}
+
+async function loadTrajectoryRun(store: RunStore, includeTranscripts = true): Promise<TrajectoryRun> {
+  const value = await store.load();
+  const summary = await store.loadSummary().catch(() => undefined);
+  const prompts = await store.systemPrompts().catch(() => []);
+  const run = withoutAgentActivities(await withResolvedResources(withPiToolDescriptions(applySystemPrompts(value.run, prompts)), store.cwd));
+  return { run, snapshot: value.snapshot, awaiting: await store.awaitingCheckpoints(), ...(summary?.createdAt === undefined ? {} : { createdAt: summary.createdAt }), transcripts: includeTranscripts ? await runTranscripts(run) : {} };
+}
+
+export async function loadTrajectoryRuns(cwd: string, sessionId: string, home = homedir(), overlay?: (run: PersistedRun) => PersistedRun): Promise<readonly TrajectoryRun[]> {
+  const loaded: TrajectoryRun[] = [];
+  for (const runId of await listRunIds(cwd, sessionId, home, false)) {
+    try {
+      const value = await loadTrajectoryRun(new RunStore(cwd, sessionId, runId, home));
+      loaded.push(overlay ? { ...value, run: overlay(value.run) } : value);
+    } catch { /* Ignore corrupt or concurrently removed runs. */ }
+  }
+  return loaded;
+}
+
+async function fileMtime(path: string): Promise<number | undefined> { return stat(path).then((value) => value.mtimeMs).catch(() => undefined); }
+type CachedRunEntry<Value extends { run: PersistedRun }, Signature> = { value: Value; stateMtimeMs: number; journalMtimeMs: number; transcripts: ReadonlyMap<string, Signature> };
+/** Lists the session's runs, reloading one only when its state, journal, or a transcript (per `transcriptSignature`) changed. */
+function createCachedRunLoader<Value extends { run: PersistedRun }, Signature>(cwd: string, sessionId: string, home: string, load: (store: RunStore) => Promise<Value>, transcriptSignature: (path: string) => Promise<Signature>, overlay: ((run: PersistedRun) => PersistedRun) | undefined): () => Promise<readonly Value[]> {
+  const cache = new Map<string, CachedRunEntry<Value, Signature>>();
+  const changed = async (store: RunStore, entry: CachedRunEntry<Value, Signature>): Promise<boolean> => {
+    if (await fileMtime(join(store.directory, "state.json")) !== entry.stateMtimeMs) return true;
+    if (await fileMtime(join(store.directory, "journal.json")) !== entry.journalMtimeMs) return true;
+    for (const [agentId, path] of transcriptPaths(entry.value.run)) if (await transcriptSignature(path) !== entry.transcripts.get(agentId)) return true;
+    return false;
+  };
+  return async () => {
+    const ids = await listRunIds(cwd, sessionId, home, false);
+    const current = new Set(ids);
+    for (const runId of cache.keys()) if (!current.has(runId)) cache.delete(runId);
+    const loaded: Value[] = [];
+    for (const runId of ids) {
+      const store = new RunStore(cwd, sessionId, runId, home);
+      try {
+        let entry = cache.get(runId);
+        if (!entry || await changed(store, entry)) {
+          const value = await load(store);
+          const transcripts = new Map<string, Signature>();
+          for (const [agentId, path] of transcriptPaths(value.run)) transcripts.set(agentId, await transcriptSignature(path));
+          entry = { value, stateMtimeMs: (await fileMtime(join(store.directory, "state.json"))) ?? 0, journalMtimeMs: (await fileMtime(join(store.directory, "journal.json"))) ?? 0, transcripts };
+          cache.set(runId, entry);
+        }
+        loaded.push(overlay ? { ...entry.value, run: overlay(entry.value.run) } : entry.value);
+      } catch { cache.delete(runId); /* Ignore corrupt or concurrently removed runs. */ }
+    }
+    return loaded;
+  };
+}
+
+export function createTrajectoryRunLoader(cwd: string, sessionId: string, home = homedir(), overlay?: (run: PersistedRun) => PersistedRun): TrajectoryRunLoader {
+  return createCachedRunLoader(cwd, sessionId, home, (store) => loadTrajectoryRun(store), fileMtime, overlay);
+}
+function transcriptRevision(info: { mtimeNs: bigint; size: bigint }): number {
+  const digest = createHash("sha256").update(`${String(info.mtimeNs)}:${String(info.size)}`).digest();
+  return Math.max(1, digest.readUIntBE(0, 6));
+}
+async function transcriptMetadata(path: string | undefined): Promise<TrajectoryTranscriptMetadata> {
+  if (path === undefined) return { revision: 0, status: "missing" };
+  try {
+    const info = await stat(path, { bigint: true });
+    const bytes = info.size > BigInt(Number.MAX_SAFE_INTEGER) ? Number.MAX_SAFE_INTEGER : Number(info.size);
+    if (!info.isFile()) return { revision: transcriptRevision(info), status: "failed" };
+    const revision = transcriptRevision(info);
+    if (info.size === 0n) return { revision, status: "empty", bytes: 0, timing: [] };
+    try {
+      const entries = await readTranscript(path, true);
+      return { revision, status: "available", bytes, timing: entries.filter(isTimingTranscriptEntry) };
+    } catch (error) {
+      if (error instanceof OversizedTranscriptError) return { revision, status: "oversized", bytes, timing: [] };
+      throw error;
+    }
+  } catch (error) {
+    if (isNodeError(error, "ENOENT")) return { revision: 0, status: "missing" };
+    return { revision: 0, status: "failed" };
+  }
+}
+async function metadataForRun(value: TrajectoryRun): Promise<TrajectoryRunMetadata> {
+  const transcripts: Record<string, TrajectoryTranscriptMetadata> = {};
+  for (const [agentId, path] of transcriptPaths(value.run)) transcripts[agentId] = await transcriptMetadata(path);
+  return { ...value, transcripts };
+}
+async function fileSignature(path: string): Promise<string | undefined> {
+  try {
+    const info = await stat(path, { bigint: true });
+    return info.isFile() ? `${String(info.mtimeNs)}:${String(info.size)}` : undefined;
+  } catch {
+    return undefined;
+  }
+}
+export function createTrajectoryRunMetadataLoader(cwd: string, sessionId: string, home = homedir(), overlay?: (run: PersistedRun) => PersistedRun): TrajectoryRunMetadataLoader {
+  return createCachedRunLoader(cwd, sessionId, home, async (store) => metadataForRun(await loadTrajectoryRun(store, false)), fileSignature, overlay);
+}
+type CachedTrajectoryTranscriptMetadata = { path: string | undefined; signature: string | undefined; value: TrajectoryTranscriptMetadata };
+export function createTrajectorySubagentMetadataLoader(cwd: string, sessionId: string, agentDir: string, overlay?: (subagent: TrajectorySubagent) => TrajectorySubagent): TrajectorySubagentMetadataLoader {
+  const loader = createTrajectorySubagentLoader(cwd, sessionId, agentDir, undefined, false);
+  const cache = new Map<string, CachedTrajectoryTranscriptMetadata>();
+  return async () => {
+    const values = await loader();
+    const current = new Set(values.map((value) => value.id));
+    for (const id of cache.keys()) if (!current.has(id)) cache.delete(id);
+    return Promise.all(values.map(async (value) => {
+      const currentValue = overlay ? overlay(value) : value;
+      const path = sessionFile(currentValue.attempt?.session);
+      const signature = path === undefined ? undefined : await fileSignature(path);
+      let entry = cache.get(value.id);
+      if (!entry || entry.path !== path || entry.signature !== signature) {
+        entry = { path, signature, value: await transcriptMetadata(path) };
+        cache.set(value.id, entry);
+      }
+      return { ...currentValue, transcript: entry.value };
+    }));
+  };
+}
+function safeTrajectorySubagentId(id: string): boolean { return id !== "." && id !== ".." && /^[A-Za-z0-9._-]+$/.test(id); }
+export function createTrajectoryTranscriptLoader(cwd: string, sessionId: string, home = homedir(), agentDir: string, resolveSubagentSession?: TrajectorySubagentSessionResolver): TrajectoryTranscriptLoader {
+  return async (request) => {
+    let path: string | undefined;
+    try {
+      if (request.runId !== undefined && request.agentId !== undefined && request.subagentId === undefined) {
+        const value = await new RunStore(cwd, sessionId, request.runId, home).load();
+        path = sessionFile(value.run.agents.find((agent) => agent.id === request.agentId)?.attemptDetails?.at(-1)?.session);
+      } else if (request.subagentId !== undefined && request.runId === undefined && request.agentId === undefined) {
+        if (!safeTrajectorySubagentId(request.subagentId)) return { status: "missing", revision: 0, entries: [], error: "Transcript not found" };
+        const rawStatus = await readSubagentJson(join(agentDir, "subagents", request.subagentId, "status.json"));
+        const status = statusValue(rawStatus);
+        const statusRecord = object(rawStatus) ? rawStatus : undefined;
+        const statusCwd = statusRecord === undefined ? undefined : statusRecord.cwd;
+        if (!status || status.sessionId !== sessionId || typeof statusCwd === "string" && !sameFilesystemPath(statusCwd, cwd)) return { status: "missing", revision: 0, entries: [], error: "Transcript not found" };
+        path = sessionFile(resolveSubagentSession?.(request.subagentId) ?? status.attemptDetails?.at(-1)?.session);
+      }
+    } catch (error) {
+      return isNodeError(error, "ENOENT") ? { status: "missing", revision: 0, entries: [], error: "Transcript not found" } : { status: "failed", revision: 0, entries: [], error: "Transcript failed" };
+    }
+    const metadata = await transcriptMetadata(path);
+    if (request.revision !== undefined && request.revision !== metadata.revision) return { ...metadata, entries: [], error: "Transcript revision is stale" };
+    if (metadata.status === "missing") return { ...metadata, entries: [], error: "Transcript not found" };
+    if (metadata.status === "empty") return { ...metadata, entries: [] };
+    if (path === undefined) return { status: "missing", revision: 0, entries: [], error: "Transcript not found" };
+    if (metadata.status === "failed" || metadata.status === "oversized") return { ...metadata, entries: [], error: metadata.status === "oversized" ? "Transcript is too large" : "Transcript failed" };
+    try {
+      const entries = await readTranscript(path, true);
+      if (Buffer.byteLength(JSON.stringify(entries)) > TRAJECTORY_MAX_TRANSCRIPT_BYTES) return { ...metadata, status: "oversized", entries: [], error: "Transcript is too large" };
+      return { ...metadata, entries };
+    } catch { return { ...metadata, status: "failed", entries: [], error: "Transcript failed" }; }
+  };
+}
+type CachedTrajectorySubagent = { value: TrajectorySubagent; fileMtimes: ReadonlyMap<string, number | undefined>; transcriptMtime: number | undefined };
+const TRAJECTORY_SUBAGENT_FILES = ["status.json", "request.json", "result.json", "failure.json"] as const;
+const TRAJECTORY_SUBAGENT_ATTENTION_ORDER: Readonly<Record<SubagentStatus["state"], number>> = { running: 0, failed: 1, stopped: 2, completed: 3 };
+async function readSubagentJson(path: string, optional = false, maxBytes?: number): Promise<unknown> {
+  try {
+    if (maxBytes !== undefined) { const info = await stat(path); if (!info.isFile() || info.size > maxBytes) return undefined; }
+    return JSON.parse(await readFile(path, "utf8")) as unknown;
+  }
+  catch (error) { if (optional && isNodeError(error, "ENOENT")) return undefined; throw error; }
+}
+async function subagentFileBytes(path: string): Promise<number | undefined> {
+  try { const info = await stat(path); return info.isFile() ? info.size : undefined; } catch { return undefined; }
+}
+function subagentArtifact(path: string, bytes: number | undefined): TrajectorySubagentArtifact | undefined { return bytes === undefined ? undefined : { truncated: true, path, bytes }; }
+function boundedSubagentJson(value: unknown): JsonValue | undefined { return jsonValue(value) ? value : undefined; }
+function withoutProgressActivity(progress: SubagentProgress): SubagentProgress {
+  const rest = { ...progress };
+  delete rest.activity;
+  return rest;
+}
+async function loadTrajectorySubagent(directory: string, cwd: string, sessionId: string, includeTranscript = true): Promise<TrajectorySubagent | "foreign" | undefined> {
+  try {
+    const id = basename(directory);
+    const status = statusValue(await readSubagentJson(join(directory, "status.json")));
+    if (!status || status.id !== id) return undefined;
+    if (status.sessionId !== sessionId) return "foreign";
+    const progress = status.progress === undefined ? undefined : withoutProgressActivity(status.progress);
+    const request = normalizeSubagentRunRequest(await readSubagentJson(join(directory, "request.json")));
+    const resultPath = join(directory, "result.json");
+    const failurePath = join(directory, "failure.json");
+    const resultBytes = await subagentFileBytes(resultPath);
+    const failureBytes = await subagentFileBytes(failurePath);
+    const resultValue = await readSubagentJson(resultPath, true, DEFAULT_MAX_BYTES);
+    const failureValue = await readSubagentJson(failurePath, true, DEFAULT_MAX_BYTES);
+    const resultTruncated = resultValue === undefined && resultBytes !== undefined && resultBytes > DEFAULT_MAX_BYTES;
+    const failureTruncated = failureValue === undefined && failureBytes !== undefined && failureBytes > DEFAULT_MAX_BYTES;
+    if (!resultTruncated && resultValue !== undefined && boundedSubagentJson(resultValue) === undefined || !failureTruncated && failureValue !== undefined && subagentErrorValue(failureValue) === undefined) return undefined;
+    const resultArtifact = resultTruncated ? subagentArtifact(resultPath, resultBytes) : undefined;
+    const failureArtifact = failureTruncated ? subagentArtifact(failurePath, failureBytes) : undefined;
+    const result = resultArtifact ?? (resultValue === undefined ? undefined : boundedSubagentJson(resultValue));
+    const failure = failureArtifact ?? (failureValue === undefined ? undefined : subagentErrorValue(failureValue));
+    const rawAttempt = status.attemptDetails?.at(-1);
+    const attempt = rawAttempt === undefined ? undefined : await withResolvedAttemptResources(rawAttempt, cwd);
+    const tools = progress?.state?.tools ?? attempt?.setup.tools ?? [];
+    const toolDefinitions = toolDefinitionsFor(tools, piToolCatalog(cwd));
+    const model = progress?.state?.model ?? attempt?.setup.model;
+    const transcriptPath = sessionFile(attempt?.session);
+    const transcript = !includeTranscript ? [] : transcriptPath === undefined ? [] : await readTranscript(transcriptPath);
+    return {
+      id, sessionId, cwd, mode: request.mode ?? "background", state: status.state, request, tools, transcript,
+      ...(request.label === undefined ? {} : { label: request.label }),
+      ...(request.role === undefined ? {} : { role: request.role }),
+      ...(status.startedAt === undefined ? {} : { startedAt: status.startedAt }),
+      ...(status.finishedAt === undefined ? {} : { finishedAt: status.finishedAt }),
+      ...(status.attempts === undefined ? {} : { attempts: status.attempts }),
+      ...(status.error === undefined ? {} : { error: status.error }),
+      ...(status.worktree === undefined ? {} : { worktree: status.worktree }),
+      ...(model === undefined ? {} : { model }),
+      ...(toolDefinitions.length ? { toolDefinitions } : {}),
+      ...(progress === undefined ? {} : { progress }),
+      ...(attempt === undefined ? {} : { attempt }),
+      ...(result === undefined ? {} : { result }),
+      ...(failure === undefined ? {} : { failure }),
+    };
+  } catch { return undefined; }
+}
+async function subagentCacheEntryChanged(directory: string, entry: CachedTrajectorySubagent): Promise<boolean> {
+  for (const file of TRAJECTORY_SUBAGENT_FILES) if (await fileMtime(join(directory, file)) !== entry.fileMtimes.get(file)) return true;
+  const transcriptPath = sessionFile(entry.value.attempt?.session);
+  return transcriptPath !== undefined && await fileMtime(transcriptPath) !== entry.transcriptMtime;
+}
+export function createTrajectorySubagentLoader(cwd: string, sessionId: string, agentDir: string, overlay?: (subagent: TrajectorySubagent) => TrajectorySubagent, includeTranscript = true): TrajectorySubagentLoader {
+  const root = join(agentDir, "subagents");
+  const cache = new Map<string, CachedTrajectorySubagent>();
+  const negativeCache = new Map<string, number | undefined>();
+  return async () => {
+    let entries;
+    try { entries = await readdir(root, { withFileTypes: true }); }
+    catch (error) { if (isNodeError(error, "ENOENT")) return []; throw error; }
+    const ids = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    const current = new Set(ids);
+    for (const id of cache.keys()) if (!current.has(id)) cache.delete(id);
+    for (const id of negativeCache.keys()) if (!current.has(id)) negativeCache.delete(id);
+    const loaded: TrajectorySubagent[] = [];
+    for (const id of ids) {
+      const directory = join(root, id);
+      const statusPath = join(directory, "status.json");
+      try {
+        const statusMtime = await fileMtime(statusPath);
+        if (negativeCache.has(id) && negativeCache.get(id) === statusMtime) continue;
+        negativeCache.delete(id);
+        let entry = cache.get(id);
+        if (!entry || await subagentCacheEntryChanged(directory, entry)) {
+          const value = await loadTrajectorySubagent(directory, cwd, sessionId, includeTranscript);
+          if (value === "foreign") { cache.delete(id); negativeCache.set(id, statusMtime); continue; }
+          if (!value) { cache.delete(id); continue; }
+          const fileMtimes = new Map<string, number | undefined>();
+          for (const file of TRAJECTORY_SUBAGENT_FILES) fileMtimes.set(file, await fileMtime(join(directory, file)));
+          const transcriptPath = sessionFile(value.attempt?.session);
+          entry = { value, fileMtimes, transcriptMtime: transcriptPath === undefined ? undefined : await fileMtime(transcriptPath) };
+          cache.set(id, entry);
+        }
+        loaded.push(overlay ? overlay(entry.value) : entry.value);
+      } catch { cache.delete(id); /* Ignore corrupt or concurrently removed subagents. */ }
+    }
+    const attention = navigatorAttentionSortByState(loaded, (entry) => entry.state, () => undefined, TRAJECTORY_SUBAGENT_ATTENTION_ORDER);
+    return attention.sort((left, right) => {
+      if (left.state !== right.state) return 0;
+      const leftTime = left.finishedAt ?? left.startedAt ?? -1;
+      const rightTime = right.finishedAt ?? right.startedAt ?? -1;
+      return rightTime - leftTime || left.id.localeCompare(right.id);
+    });
+  };
+}