@ian-pascoe/pi-minimal-subagents 0.2.3 → 0.4.0

package/README.md

@@ -130,6 +130,11 @@ children: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
 only the three adjacent-coordination tools: `agent_message`, `subagent_wait`,
 and `subagent_status`.
 
+Targeted `subagent_status` includes `recent_activity`, a bounded tail of message
+text, reasoning, tool calls, and tool results. It includes the current streaming
+assistant message but omits image data. Timeout Wait Events include the same
+detailed status snapshot.
+
 The `subagent` `tools` argument distinguishes capability presets from exact
 lists: `"read"` grants `read`, `grep`, `find`, and `ls`; `"modify"` adds
 `bash`, `edit`, and `write`; an array such as `["read"]` grants exactly the
@@ -148,6 +153,10 @@ optional `turn_id` to address an older retained turn exactly. Without it, waits
 select the oldest observable claimed or pending turn before the active/latest
 turn. A caller may have only one outstanding wait for the same source turn; a
 concurrent duplicate is rejected instead of competing for one Wait Event.
+When `timeout_ms` expires, the wait returns an observational `event: "timeout"`
+with the requested turn identity and the same detailed Child Agent status used
+by targeted `subagent_status`. It removes only the waiter, leaving the child
+running and all pending delivery unclaimed. Abort signals remain errors.
 
 The persisted Delivery Ledger records Coordination Messages, terminal results,
 globally increasing sequence, and wait ownership before delivery. Existing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -21,6 +21,7 @@
   },
   "files": [
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -42,6 +43,9 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "scripts": {

package/skills/pi-minimal-subagents/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: pi-minimal-subagents
+description: Configure or diagnose Pi Minimal Subagents for spawn, capability, delivery, wait, restore, reload, or fork failures.
+license: MIT
+---
+
+# Pi Minimal Subagents
+
+1. Read the relevant spawn, capability, delivery, or recovery section of [`../../README.md`](../../README.md).
+2. From the direct parent, use `subagent_status` to capture the Child Agent's Launch Contract, Runtime Profile, dependencies, result, and Recent Activity.
+3. Classify the fault as launch resolution, adjacency, ordinary-tool ceiling, delivery state, or Registry recovery.
+4. For configuration changes, identify the effective layer, make one scoped edit, validate JSON, and reload Pi.
+5. Repeat the same spawn or coordination operation. Finish when it succeeds or one named launch, adjacency, capability, delivery, or recovery boundary is evidenced.
+
+A wait timeout observes without cancelling. Tool arrays contain only ordinary tools. Cancellation preserves a Child Session; deletion removes it.

package/src/minimal-subagents-capabilities.ts

@@ -39,11 +39,10 @@ export function buildEligibleModelIds(input: {
   return [...new Set(source.map(({ provider, id }) => `${provider}/${id}`))];
 }
 
-/** Supplies inherited tools, the ancestor ceiling, and runtime availability for exact tool resolution. */
+/** Supplies inherited tools and the ancestor ceiling for exact tool resolution. */
 export interface ToolResolutionContext {
   ordinaryTools: readonly string[];
   capabilityCeiling: readonly string[];
-  availableTools: readonly string[];
 }
 
 /** Resolve an exact ordinary-tool contract and reject missing or over-ceiling capabilities. */
@@ -69,13 +68,9 @@ export function resolveOrdinaryToolSelection(
       `Minimal subagents ordinary tool selection: coordinator tools are injected separately and must not appear in tools: ${requestedCoordinatorTools.join(", ")}`,
     );
   }
-  const available = new Set(context.availableTools);
+  // ponytail: availableTools and capabilityCeiling are identical at every production site,
+  // so availability and the ancestor ceiling are enforced by a single membership check.
   const ceiling = new Set(context.capabilityCeiling);
-  const missing = uniqueRequested.filter((name) => !available.has(name));
-  if (missing.length > 0) {
-    throw new Error(`Minimal subagents tool resolution: unavailable tool: ${missing.join(", ")}`);
-  }
-
   const exceeded = uniqueRequested.filter((name) => !ceiling.has(name));
   if (exceeded.length > 0) {
     throw new Error(`Minimal subagents capability ceiling exceeded: ${exceeded.join(", ")}`);

package/src/minimal-subagents-context.ts

@@ -1,5 +1,11 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { SessionContextMode } from "./minimal-subagents-types.js";
+import { contentText, type ImageContent, type TextContent } from "@earendil-works/pi-ai";
+import { truncateTail } from "@earendil-works/pi-coding-agent";
+import type { RecentAgentActivity, SessionContextMode } from "./minimal-subagents-types.js";
+
+const RECENT_AGENT_ACTIVITY_LIMIT = 12;
+const RECENT_AGENT_ACTIVITY_MAX_LINES = 20;
+const RECENT_AGENT_ACTIVITY_MAX_BYTES = 2 * 1024;
 
 /** Clone committed caller messages and exclude only the currently streaming assistant message. */
 export function snapshotCommittedContext(
@@ -11,6 +17,71 @@ export function snapshotCommittedContext(
   return structuredClone(committed);
 }
 
+function boundedRecentActivityContent(label: string, content: string): RecentAgentActivity {
+  const bounded = truncateTail(content, {
+    maxLines: RECENT_AGENT_ACTIVITY_MAX_LINES,
+    maxBytes: RECENT_AGENT_ACTIVITY_MAX_BYTES,
+  });
+  return { label, content: bounded.content, truncated: bounded.truncated };
+}
+
+function visibleMessageContent(content: string | readonly (TextContent | ImageContent)[]): string {
+  return contentText(content, "\n\n") || "(no text content)";
+}
+
+/** Build a bounded recent activity tail from message text, reasoning, and tool work. */
+export function buildRecentAgentActivity(messages: readonly AgentMessage[]): RecentAgentActivity[] {
+  const activity: RecentAgentActivity[] = [];
+  for (const message of messages) {
+    if (message.role === "assistant") {
+      for (const content of message.content) {
+        if (content.type === "text" && content.text) {
+          activity.push(boundedRecentActivityContent("assistant message", content.text));
+        } else if (content.type === "thinking") {
+          activity.push(
+            boundedRecentActivityContent(
+              "reasoning",
+              content.thinking ||
+                (content.redacted ? "[redacted reasoning]" : "(no reasoning text)"),
+            ),
+          );
+        } else if (content.type === "toolCall") {
+          activity.push(
+            boundedRecentActivityContent(
+              `tool call ${content.name}`,
+              JSON.stringify(content.arguments, null, 2),
+            ),
+          );
+        }
+      }
+    } else if (message.role === "toolResult") {
+      activity.push(
+        boundedRecentActivityContent(
+          `tool result ${message.toolName}${message.isError ? " (error)" : ""}`,
+          visibleMessageContent(message.content),
+        ),
+      );
+    } else if (message.role === "user" || message.role === "custom") {
+      activity.push(
+        boundedRecentActivityContent(
+          `${message.role} message`,
+          visibleMessageContent(message.content),
+        ),
+      );
+    } else if (message.role === "branchSummary" || message.role === "compactionSummary") {
+      activity.push(boundedRecentActivityContent(`${message.role} message`, message.summary));
+    } else if (message.role === "bashExecution") {
+      activity.push(
+        boundedRecentActivityContent(
+          `${message.role} message`,
+          `$ ${message.command}\n${message.output || "(no output)"}`,
+        ),
+      );
+    }
+  }
+  return activity.slice(-RECENT_AGENT_ACTIVITY_LIMIT);
+}
+
 /** Carries the selected caller messages and whether child preparation should compact them. */
 export interface ImportedSubagentContext {
   messages: AgentMessage[];

package/src/minimal-subagents-coordinator.ts

@@ -1,5 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { assembleImportedContext, contextContainsImages } from "./minimal-subagents-context.js";
+import {
+  assembleImportedContext,
+  buildRecentAgentActivity,
+  contextContainsImages,
+} from "./minimal-subagents-context.js";
 import {
   canAgentContractSpawn,
   DEFAULT_MAX_SUBAGENT_DEPTH,
@@ -29,6 +33,7 @@ import {
   type DeliveryLedgerTransition,
 } from "./minimal-subagents-delivery-ledger.js";
 import { addCoordinatorMessageEnvelope } from "./minimal-subagents-message-envelope.js";
+import { unavailableAgent } from "./minimal-subagents-sessions.js";
 import { createRegistryEvent } from "./minimal-subagents-registry.js";
 import type {
   AgentDetail,
@@ -51,7 +56,6 @@ import type {
   SpawnParameters,
   SpawnResult,
   StatusResult,
-  TurnId,
   TurnResult,
   WaitMessageResult,
   WaitResult,
@@ -203,7 +207,6 @@ export class MinimalSubagentsCoordinator {
     const ordinaryTools = resolveOrdinaryToolSelection(parameters.tools, {
       ordinaryTools: excludeCoordinatorTools(caller.ordinaryTools),
       capabilityCeiling: excludeCoordinatorTools(caller.capabilityCeiling),
-      availableTools: excludeCoordinatorTools(caller.availableTools),
     });
     const committedMessages = structuredClone(caller.messages);
     const imported = assembleImportedContext(sessionContext, committedMessages);
@@ -296,7 +299,6 @@ export class MinimalSubagentsCoordinator {
       thinkingLevel: agent.launch_contract.thinking_level,
       ordinaryTools: [...agent.launch_contract.ordinary_tools],
       capabilityCeiling: [...agent.capability_ceiling],
-      availableTools: [...agent.capability_ceiling],
       spawnEntryId,
     };
   }
@@ -354,7 +356,7 @@ export class MinimalSubagentsCoordinator {
     }
   }
 
-  /** Wait for one exact turn and claim its message/result delivery from automatic fallback. */
+  /** Wait for one exact turn, returning detailed child status if the waiter times out. */
   wait(
     callerId: string,
     agentId: string,
@@ -405,13 +407,16 @@ export class MinimalSubagentsCoordinator {
         reject(error);
       };
       if (timeoutMs !== undefined) {
-        waiter.timeout = setTimeout(
-          () =>
-            stopWaiting(
-              new Error(`Minimal subagents wait timed out for ${agentId} after ${timeoutMs}ms`),
-            ),
-          timeoutMs,
-        );
+        waiter.timeout = setTimeout(() => {
+          this.removeWaiter(key, waiter);
+          resolve({
+            event: "timeout",
+            agent_id: agentId,
+            turn_id: turnId,
+            timeout_ms: timeoutMs,
+            agent: this.buildAgentDetail(agent, false),
+          });
+        }, timeoutMs);
       }
       if (signal) {
         waiter.abortListener = () =>
@@ -492,7 +497,6 @@ export class MinimalSubagentsCoordinator {
       agent_id: agentId,
       recursive,
       deleted_agent_ids: [],
-      tombstoned_agent_ids: [],
       trashed_session_files: [],
       failures: [],
     };
@@ -520,7 +524,6 @@ export class MinimalSubagentsCoordinator {
         this.pruneRecentMessageProjectionsForDeletedAgent(agent.agent_id);
         this.tombstones.add(agent.agent_id);
         result.deleted_agent_ids.push(agent.agent_id);
-        result.tombstoned_agent_ids.push(agent.agent_id);
         this.dependencies.registry.append(
           createRegistryEvent(this.dependencies.registry.rootSessionId, "agent-deleted", {
             agent_ids: [agent.agent_id],
@@ -567,12 +570,8 @@ export class MinimalSubagentsCoordinator {
     this.runtimeInitializations.clear();
     this.pendingAgentIds.clear();
     this.tombstones.clear();
-    this.deliveryLedger = createDeliveryLedger();
     this.waiters.clear();
-    this.pendingParentMessages.clear();
     this.waitHandedDeliveryIds.clear();
-    this.recipientQueues.clear();
-    this.backgroundOperations.clear();
     this.automaticDeliveryKeys.clear();
     this.automaticCoordinationDeliveryIds.clear();
     this.deliveryLedger = createDeliveryLedger({
@@ -916,9 +915,8 @@ export class MinimalSubagentsCoordinator {
     return initialization;
   }
 
-  private beginTurn(agent: PersistedAgent): TurnId {
-    // SAFETY: The generated value embeds the canonical agent ID and a fresh turn UUID before branding.
-    const turnId = `${agent.agent_id}:turn-${randomUUID()}` as TurnId;
+  private beginTurn(agent: PersistedAgent): string {
+    const turnId = `${agent.agent_id}:turn-${randomUUID()}`;
     const startedAt = this.now().toISOString();
     agent.active_turn_id = turnId;
     agent.active_turn_started_at = startedAt;
@@ -1027,11 +1025,6 @@ export class MinimalSubagentsCoordinator {
           this.settleDelivery(delivery);
           return;
         }
-        if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery)) return;
-        if (this.hasDeliveryEvidence(delivery)) {
-          this.settleDelivery(delivery);
-          return;
-        }
         const message: CoordinatorMessage = {
           customType: "minimal-subagents.result",
           content: result.output,
@@ -1478,11 +1471,6 @@ export class MinimalSubagentsCoordinator {
       elapsed_ms: elapsed ?? agent.latest_result?.elapsed_ms,
       latest_activity_at: agent.latest_activity_at ?? agent.created_at,
       task: agent.task,
-      latest_activity: agent.active_turn_id
-        ? "turn running"
-        : agent.latest_result
-          ? `turn ${agent.latest_result.status}`
-          : "created",
       child_count: directChildren.length,
       children,
     };
@@ -1490,7 +1478,8 @@ export class MinimalSubagentsCoordinator {
 
   private buildAgentDetail(agent: PersistedAgent, includeDescendants = true): AgentDetail {
     const summary = this.buildAgentSummary(agent, includeDescendants);
-    const runtimeUsage = this.runtimes.get(agent.agent_id)?.getUsage();
+    const runtime = this.runtimes.get(agent.agent_id);
+    const runtimeUsage = runtime?.getUsage();
     return {
       ...summary,
       session_file: agent.session_file,
@@ -1498,6 +1487,7 @@ export class MinimalSubagentsCoordinator {
       capability_ceiling: [...agent.capability_ceiling],
       spawn_entry_id: agent.spawn_entry_id,
       recent_messages: structuredClone(agent.recent_messages),
+      recent_activity: buildRecentAgentActivity(runtime?.snapshotActivityMessages() ?? []),
       latest_result: agent.latest_result ? structuredClone(agent.latest_result) : undefined,
       missing_dependencies: [...agent.missing_dependencies],
       unavailable_reason: agent.unavailable_reason,
@@ -1621,19 +1611,7 @@ export class MinimalSubagentsCoordinator {
   }
 
   private createForkPlaceholder(agent: PersistedAgent, cloneError: string): PersistedAgent {
-    return {
-      ...structuredClone(agent),
-      session_file: undefined,
-      session_id: undefined,
-      session_leaf_id: undefined,
-      clone_error: cloneError,
-      active_turn_id: undefined,
-      active_turn_started_at: undefined,
-      latest_activity_at: this.now().toISOString(),
-      availability: "unavailable",
-      missing_dependencies: [cloneError],
-      unavailable_reason: cloneError,
-    };
+    return unavailableAgent(agent, cloneError, this.now().toISOString());
   }
 
   private rejectAllWaiters(error: Error): void {

package/src/minimal-subagents-extension.ts

@@ -39,6 +39,7 @@ import {
   findDeliveryEvidence,
   PiAgentSessionFactory,
   type PiAgentSessionFactoryOptions,
+  unavailableAgent,
 } from "./minimal-subagents-sessions.js";
 import { shutdownMinimalSubagentsSession } from "./minimal-subagents-shutdown.js";
 import { createCoordinatorToolDefinitions } from "./minimal-subagents-tools.js";
@@ -53,6 +54,7 @@ import type {
   CoordinatorNotification,
   ForkSnapshot,
   PersistedAgent,
+  PersistedSessionIdentity,
   RegistrySnapshot,
   RootConversationEndpoint,
 } from "./minimal-subagents-types.js";
@@ -75,7 +77,6 @@ function rootCallerSnapshot(pi: ExtensionAPI, context: ExtensionContext): Caller
     thinkingLevel: context.thinkingLevel ?? pi.getThinkingLevel(),
     ordinaryTools: activeTools,
     capabilityCeiling: availableTools,
-    availableTools,
     spawnEntryId: context.sessionManager.getLeafId() ?? "root",
   };
 }
@@ -183,57 +184,84 @@ function orderForkAgentsParentFirst(agents: readonly PersistedAgent[]): Persiste
 }
 
 function unavailableForkAgent(agent: PersistedAgent, error: string): PersistedAgent {
-  return {
-    ...structuredClone(agent),
-    session_file: undefined,
-    session_id: undefined,
-    session_leaf_id: undefined,
-    clone_error: error,
-    active_turn_id: undefined,
-    active_turn_started_at: undefined,
-    availability: "unavailable",
-    missing_dependencies: [error],
-    unavailable_reason: error,
-  };
+  return unavailableAgent(agent, error);
 }
 
-async function cloneSelectedForkSessions(
-  sessionFactory: AgentSessionFactory,
-  snapshot: RegistrySnapshot,
-  sourceRootSessionFile: string,
-  sourceRootSessionId: string,
+/** One per-agent fork rebind step returning the destination session identity. */
+type ForkAgentRebind = (agent: PersistedAgent) => Promise<PersistedSessionIdentity>;
+
+interface ForkRebindOptions {
+  /** Require an existing clone session before rebinding (ownership pass only). */
+  readonly requiresCloneSession: boolean;
+  /** Message for agents skipped because an ancestor's rebind failed. */
+  readonly skippedMessage: (agent: PersistedAgent, failedAncestor: string) => string;
+  /** Human label used in failure notifications. */
+  readonly notifyLabel: string;
+}
+
+/** Walk fork agents parent-first, rebind each session, and quarantine failed subtrees. */
+async function rebindForkAgents(
+  snapshotAgents: readonly PersistedAgent[],
+  rebind: ForkAgentRebind,
+  options: ForkRebindOptions,
   context: ExtensionContext,
-): Promise<ForkSnapshot> {
+): Promise<PersistedAgent[]> {
   const agents: PersistedAgent[] = [];
   const failedSubtrees = new Set<string>();
-  for (const agent of orderForkAgentsParentFirst(snapshot.agents)) {
+  for (const agent of orderForkAgentsParentFirst(snapshotAgents)) {
     const failedAncestor = [...failedSubtrees].find(
       (agentId) => agent.agent_id === agentId || agent.agent_id.startsWith(`${agentId}.`),
     );
-    if (failedAncestor) {
-      agents.push(unavailableForkAgent(agent, `Ancestor clone failed: ${failedAncestor}`));
+    const missingCloneSession =
+      options.requiresCloneSession && (!agent.session_file || !agent.session_id);
+    if (failedAncestor !== undefined || missingCloneSession) {
+      const message =
+        failedAncestor !== undefined
+          ? options.skippedMessage(agent, failedAncestor)
+          : (agent.clone_error ?? `Ancestor ownership failed: ${agent.agent_id}`);
+      agents.push(unavailableForkAgent(agent, message));
       continue;
     }
     try {
-      const clone = await sessionFactory.cloneForkSourceSession(agent, sourceRootSessionId);
-      if (!clone.sessionLeafId) {
+      const identity = await rebind(agent);
+      if (!identity.sessionLeafId) {
         throw new Error(
           `Minimal subagents fork recovery: no selected session leaf for ${agent.agent_id}`,
         );
       }
       agents.push({
         ...structuredClone(agent),
-        session_file: clone.sessionFile,
-        session_id: clone.sessionId,
-        session_leaf_id: clone.sessionLeafId,
+        session_file: identity.sessionFile,
+        session_id: identity.sessionId,
+        session_leaf_id: identity.sessionLeafId,
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       failedSubtrees.add(agent.agent_id);
       agents.push(unavailableForkAgent(agent, message));
-      context.ui.notify(`Fork recovery clone failed for ${agent.agent_id}: ${message}`, "error");
+      context.ui.notify(`${options.notifyLabel} for ${agent.agent_id}: ${message}`, "error");
     }
   }
+  return agents;
+}
+
+async function cloneSelectedForkSessions(
+  sessionFactory: AgentSessionFactory,
+  snapshot: RegistrySnapshot,
+  sourceRootSessionFile: string,
+  sourceRootSessionId: string,
+  context: ExtensionContext,
+): Promise<ForkSnapshot> {
+  const agents = await rebindForkAgents(
+    snapshot.agents,
+    (agent) => sessionFactory.cloneForkSourceSession(agent, sourceRootSessionId),
+    {
+      requiresCloneSession: false,
+      skippedMessage: (_agent, failedAncestor) => `Ancestor clone failed: ${failedAncestor}`,
+      notifyLabel: "Fork recovery clone failed",
+    },
+    context,
+  );
   return {
     ...structuredClone(snapshot),
     source_root_session_file: sourceRootSessionFile,
@@ -247,44 +275,16 @@ async function bindForkSnapshotToDestination(
   snapshot: ForkSnapshot,
   context: ExtensionContext,
 ): Promise<ForkSnapshot> {
-  const agents: PersistedAgent[] = [];
-  const failedSubtrees = new Set<string>();
-  for (const agent of orderForkAgentsParentFirst(snapshot.agents)) {
-    const failedAncestor = [...failedSubtrees].find(
-      (agentId) => agent.agent_id === agentId || agent.agent_id.startsWith(`${agentId}.`),
-    );
-    if (failedAncestor || !agent.session_file || !agent.session_id) {
-      agents.push(
-        unavailableForkAgent(
-          agent,
-          agent.clone_error ?? `Ancestor ownership failed: ${failedAncestor ?? agent.agent_id}`,
-        ),
-      );
-      continue;
-    }
-    try {
-      const owned = await sessionFactory.adoptForkSessionOwnership(
-        agent,
-        snapshot.source_root_session_id,
-      );
-      if (!owned.sessionLeafId) {
-        throw new Error(
-          `Minimal subagents fork ownership: no selected session leaf for ${agent.agent_id}`,
-        );
-      }
-      agents.push({
-        ...structuredClone(agent),
-        session_file: owned.sessionFile,
-        session_id: owned.sessionId,
-        session_leaf_id: owned.sessionLeafId,
-      });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      failedSubtrees.add(agent.agent_id);
-      agents.push(unavailableForkAgent(agent, message));
-      context.ui.notify(`Fork ownership failed for ${agent.agent_id}: ${message}`, "error");
-    }
-  }
+  const agents = await rebindForkAgents(
+    snapshot.agents,
+    (agent) => sessionFactory.adoptForkSessionOwnership(agent, snapshot.source_root_session_id),
+    {
+      requiresCloneSession: true,
+      skippedMessage: () => "Ancestor ownership failed",
+      notifyLabel: "Fork ownership failed",
+    },
+    context,
+  );
   return { ...structuredClone(snapshot), agents };
 }
 

package/src/minimal-subagents-fork-lifecycle.ts

@@ -1,6 +1,5 @@
-import { existsSync, realpathSync } from "node:fs";
-import { resolve } from "node:path";
 import type { ForkSnapshot } from "./minimal-subagents-types.js";
+import { canonicalPath } from "./minimal-subagents-sessions.js";
 
 declare global {
   // eslint-disable-next-line no-var -- A process-global handoff must be visible to replacement extension instances.
@@ -12,11 +11,6 @@ function forkSnapshotStore(): Map<string, ForkSnapshot> {
   return globalThis.minimalSubagentsForkSnapshots;
 }
 
-function canonicalSessionFile(sessionFile: string): string {
-  const absolutePath = resolve(sessionFile);
-  return existsSync(absolutePath) ? realpathSync(absolutePath) : absolutePath;
-}
-
 /** Prove a process-loss fork destination was derived from the expected canonical source file. */
 export function isForkDestinationForSource(
   destinationHeader: { parentSession?: string } | null,
@@ -24,14 +18,13 @@ export function isForkDestinationForSource(
 ): boolean {
   return (
     destinationHeader?.parentSession !== undefined &&
-    canonicalSessionFile(destinationHeader.parentSession) ===
-      canonicalSessionFile(previousSessionFile)
+    canonicalPath(destinationHeader.parentSession) === canonicalPath(previousSessionFile)
   );
 }
 
 /** Retain a complete pre-fork hierarchy across Pi extension-instance replacement. */
 export function rememberForkSnapshot(snapshot: ForkSnapshot): void {
-  const canonicalSourceFile = canonicalSessionFile(snapshot.source_root_session_file);
+  const canonicalSourceFile = canonicalPath(snapshot.source_root_session_file);
   const retained = structuredClone(snapshot);
   retained.source_root_session_file = canonicalSourceFile;
   forkSnapshotStore().set(canonicalSourceFile, retained);
@@ -39,7 +32,7 @@ export function rememberForkSnapshot(snapshot: ForkSnapshot): void {
 
 /** Consume the pre-fork hierarchy once when the destination root session starts. */
 export function takeForkSnapshot(previousSessionFile: string): ForkSnapshot | undefined {
-  const key = canonicalSessionFile(previousSessionFile);
+  const key = canonicalPath(previousSessionFile);
   const snapshot = forkSnapshotStore().get(key);
   if (snapshot) forkSnapshotStore().delete(key);
   return snapshot ? structuredClone(snapshot) : undefined;

package/src/minimal-subagents-registry-wire.ts

@@ -102,7 +102,6 @@ export const RegistryAgentWireSchema = Type.Object({
   missing_dependencies: Type.Array(NonEmptyStringSchema),
   unavailable_reason: Type.Optional(NonEmptyStringSchema),
   recent_messages: Type.Array(RegistryRecentMessageWireSchema),
-  deleted: Type.Optional(Type.Boolean()),
 });
 
 /** Parses one terminal Delivery Ledger item without applying ownership semantics. */

package/src/minimal-subagents-registry.ts

@@ -399,7 +399,6 @@ function parseRegistryAgent(value: RegistryAgentWire, version: 1 | 2): Persisted
     agent.latest_result = cloneRegistryTurnResult(value.latest_result);
   }
   if (value.unavailable_reason !== undefined) agent.unavailable_reason = value.unavailable_reason;
-  if (value.deleted !== undefined) agent.deleted = value.deleted;
   return agent;
 }
 
@@ -620,12 +619,6 @@ function validateRegistrySnapshot(
       "tombstone agent ID is not canonical",
     );
   }
-  if (agents.some((agent) => agent.deleted === true)) {
-    return invalidRegistrySnapshot(
-      "invalid-agent-hierarchy",
-      "live snapshot agents cannot be deleted",
-    );
-  }
   const agentIds = new Set(agents.map((agent) => agent.agent_id));
   if (tombstones.some((agentId) => agentIds.has(agentId))) {
     return invalidRegistrySnapshot(
@@ -1245,8 +1238,7 @@ export function replayRegistryEntries(
         if (
           event.agent.active_turn_id ||
           event.agent.latest_result ||
-          event.agent.recent_messages.length > 0 ||
-          event.agent.deleted
+          event.agent.recent_messages.length > 0
         ) {
           reportDiagnostic(
             diagnostics,

package/src/minimal-subagents-render-contract.ts

@@ -5,15 +5,9 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
+import { COORDINATOR_TOOL_NAMES } from "./minimal-subagents-capabilities.js";
 
-/** Names of the six coordinator tools with custom transcript renderers. */
-export type CoordinatorToolName =
-  | "subagent"
-  | "agent_message"
-  | "subagent_wait"
-  | "subagent_status"
-  | "subagent_cancel"
-  | "subagent_delete";
+export type CoordinatorToolName = (typeof COORDINATOR_TOOL_NAMES)[number];
 
 const RenderUsageSchema = Type.Object({
   input: Type.Number(),
@@ -55,6 +49,11 @@ const RenderRecentMessageSchema = Type.Object({
   source_agent_id: Type.Optional(Type.String()),
   content: Type.Optional(Type.String()),
 });
+const RenderRecentActivitySchema = Type.Object({
+  label: Type.String(),
+  content: Type.String(),
+  truncated: Type.Boolean(),
+});
 
 /** Structurally parsed hierarchy status used only by transcript presentation. */
 export const RenderStatusAgentSchema = Type.Object({
@@ -80,6 +79,7 @@ export const RenderStatusAgentSchema = Type.Object({
   capability_ceiling: Type.Optional(Type.Array(Type.String())),
   spawn_entry_id: Type.Optional(Type.String()),
   recent_messages: Type.Optional(Type.Array(RenderRecentMessageSchema)),
+  recent_activity: Type.Optional(Type.Array(RenderRecentActivitySchema)),
   latest_result: Type.Optional(RenderTurnResultSchema),
   missing_dependencies: Type.Optional(Type.Array(Type.String())),
   unavailable_reason: Type.Optional(Type.String()),
@@ -148,6 +148,13 @@ const WaitTurnDetailsSchema = Type.Object({
   usage: Type.Optional(RenderUsageSchema),
   messages: Type.Optional(Type.Array(WaitMessageDetailsSchema)),
 });
+const WaitTimeoutDetailsSchema = Type.Object({
+  event: Type.Literal("timeout"),
+  agent_id: Type.String(),
+  turn_id: Type.String(),
+  timeout_ms: Type.Number(),
+  agent: RenderStatusAgentSchema,
+});
 const StatusDetailsSchema = Type.Union([
   Type.Object({
     parent_id: Type.Optional(Type.String()),
@@ -165,7 +172,6 @@ const DeleteDetailsSchema = Type.Object({
   agent_id: Type.String(),
   recursive: Type.Boolean(),
   deleted_agent_ids: Type.Array(Type.String()),
-  tombstoned_agent_ids: Type.Array(Type.String()),
   trashed_session_files: Type.Array(Type.String()),
   failures: Type.Array(
     Type.Object({
@@ -179,7 +185,11 @@ const MessageRenderDetailsSchema = Type.Union([
   CurrentMessageDetailsSchema,
   LegacyMessageDetailsSchema,
 ]);
-const WaitRenderDetailsSchema = Type.Union([WaitMessageDetailsSchema, WaitTurnDetailsSchema]);
+const WaitRenderDetailsSchema = Type.Union([
+  WaitMessageDetailsSchema,
+  WaitTurnDetailsSchema,
+  WaitTimeoutDetailsSchema,
+]);
 
 export type SpawnCallArguments = Static<typeof SpawnCallArgumentsSchema>;
 export type MessageCallArguments = Static<typeof MessageCallArgumentsSchema>;

package/src/minimal-subagents-rendering.ts

@@ -62,7 +62,8 @@ type SubagentPresentationStatus =
   | "delivered"
   | "delivered-via-wait"
   | "queued"
-  | "message";
+  | "message"
+  | "timed out";
 
 type SubagentStatusPresentation = { readonly symbol: string; readonly color: ThemeColor };
 
@@ -79,6 +80,7 @@ const SUBAGENT_STATUS_PRESENTATION = {
   "delivered-via-wait": { symbol: "→", color: "accent" },
   queued: { symbol: "↗", color: "accent" },
   message: { symbol: "→", color: "accent" },
+  "timed out": { symbol: "!", color: "warning" },
 } satisfies { readonly [Status in SubagentPresentationStatus]: SubagentStatusPresentation };
 
 function coordinatorMessageText(content: RenderableCoordinatorMessage["content"]): string {
@@ -96,11 +98,21 @@ function toolResultText(result: AgentToolResult<unknown>): string {
   return text?.type === "text" ? text.text : "";
 }
 
+/** Shared unavailable → running → latest-turn → idle status ladder for one subagent. */
+export function subagentStatusLadder(agent: {
+  readonly availability?: string;
+  readonly state?: string;
+  readonly latest_turn?: { readonly status?: string };
+}): string {
+  if (agent.availability === "unavailable") return "unavailable";
+  if (agent.state === "running") return "running";
+  return agent.latest_turn?.status ?? "idle";
+}
+
 function subagentStatusPresentation(status: string): SubagentStatusPresentation {
-  for (const [knownStatus, presentation] of Object.entries(SUBAGENT_STATUS_PRESENTATION)) {
-    if (knownStatus === status) return presentation;
-  }
-  return SUBAGENT_STATUS_PRESENTATION.idle;
+  // SAFETY: unknown statuses fall back to the idle presentation below.
+  const known = status as keyof typeof SUBAGENT_STATUS_PRESENTATION;
+  return SUBAGENT_STATUS_PRESENTATION[known] ?? SUBAGENT_STATUS_PRESENTATION.idle;
 }
 
 /** Render the shared semantic symbol and color for one subagent status. */
@@ -338,10 +350,19 @@ function renderWaitResult(
     ? "waiting"
     : details.event === "message"
       ? "message"
-      : details.status;
-  const duration = formatSubagentDuration(details.elapsed_ms);
-  const tokens = formatSubagentTokenCount(details.usage?.totalTokens);
-  const drainedMessageCount = details.event === "message" ? 0 : (details.messages?.length ?? 0);
+      : details.event === "timeout"
+        ? "timed out"
+        : details.status;
+  const duration = formatSubagentDuration(
+    details.event === "timeout" ? details.timeout_ms : details.elapsed_ms,
+  );
+  const tokens = formatSubagentTokenCount(
+    details.event === "timeout" ? undefined : details.usage?.totalTokens,
+  );
+  const drainedMessageCount =
+    details.event === "message" || details.event === "timeout"
+      ? 0
+      : (details.messages?.length ?? 0);
   const metrics = [
     duration,
     tokens ? `${tokens} tokens` : undefined,
@@ -359,6 +380,15 @@ function renderWaitResult(
     container.addChild(renderLabelValue(theme, "Message ID", details.message_id));
     return container;
   }
+  if (details.event === "timeout") {
+    appendComponentSection(
+      container,
+      theme,
+      "Child status",
+      renderDetailedStatusAgent(details.agent, options, theme),
+    );
+    return container;
+  }
   if (details.messages && details.messages.length > 0) {
     appendTextSection(
       container,
@@ -402,9 +432,7 @@ function countDirectStatusAgents(agents: readonly RenderStatusAgent[]): DirectSt
 }
 
 function statusAgentPresentation(agent: RenderStatusAgent): string {
-  if (agent.availability === "unavailable") return "unavailable";
-  if (agent.state === "running") return "running";
-  return agent.latest_turn?.status ?? "idle";
+  return subagentStatusLadder(agent);
 }
 
 function renderDirectStatusRows(
@@ -484,6 +512,20 @@ function renderDetailedStatusAgent(
   if (agent.unavailable_reason) {
     appendTextSection(container, theme, "Unavailable reason", agent.unavailable_reason);
   }
+  const recentActivity = agent.recent_activity ?? [];
+  if (recentActivity.length > 0) {
+    appendTextSection(
+      container,
+      theme,
+      "Recent activity",
+      recentActivity
+        .map(
+          (activity) =>
+            `${activity.label}${activity.truncated ? " (truncated)" : ""}\n${activity.content}`,
+        )
+        .join("\n\n"),
+    );
+  }
   const recentMessages = agent.recent_messages ?? [];
   if (recentMessages.length > 0) {
     appendTextSection(
@@ -577,7 +619,7 @@ function renderDeleteResult(
   const status = details.failures.length > 0 ? "failed" : "completed";
   const metrics = [
     `${details.deleted_agent_ids.length} agents deleted`,
-    `${details.tombstoned_agent_ids.length} tombstoned`,
+    `${details.deleted_agent_ids.length} tombstones`,
     details.failures.length > 0 ? `${details.failures.length} failed` : undefined,
   ].filter((metric): metric is string => metric !== undefined);
   const summary = renderSubagentSummary(theme, status, details.agent_id, metrics);
@@ -594,12 +636,6 @@ function renderDeleteResult(
     "Deleted agents",
     details.deleted_agent_ids.join("\n") || "(none)",
   );
-  appendTextSection(
-    container,
-    theme,
-    "Tombstones",
-    details.tombstoned_agent_ids.join("\n") || "(none)",
-  );
   appendTextSection(
     container,
     theme,

package/src/minimal-subagents-sessions.ts

@@ -131,11 +131,35 @@ export function buildDepthBoundSubagentPrompt(
   });
 }
 
-function canonicalPath(path: string): string {
+/** Canonicalize one path, resolving symlinks only when the target exists. */
+export function canonicalPath(path: string): string {
   const absolutePath = resolve(path);
   return existsSync(absolutePath) ? realpathSync(absolutePath) : absolutePath;
 }
 
+/** Build the shared unavailable-agent projection used by fork recovery and ownership binding. */
+export function unavailableAgent(
+  agent: PersistedAgent,
+  error: string,
+  latestActivityAt?: string,
+): PersistedAgent {
+  // SAFETY: the spread preserves every required PersistedAgent field; only optional session fields are cleared.
+  const unavailable = {
+    ...structuredClone(agent),
+    session_file: undefined,
+    session_id: undefined,
+    session_leaf_id: undefined,
+    clone_error: error,
+    active_turn_id: undefined,
+    active_turn_started_at: undefined,
+    availability: "unavailable",
+    missing_dependencies: [error],
+    unavailable_reason: error,
+  } as PersistedAgent;
+  if (latestActivityAt !== undefined) unavailable.latest_activity_at = latestActivityAt;
+  return unavailable;
+}
+
 function appendImportedMessage(sessionManager: SessionManager, message: AgentMessage): void {
   if (message.role === "compactionSummary") {
     sessionManager.appendCustomMessageEntry(
@@ -439,54 +463,40 @@ function assistantText(message: AgentMessage | undefined): string {
     .join("\n");
 }
 
-/** Collects finalized turn messages without relying on mutable post-compaction session state. */
-export class ChildTurnOutcomeCollector {
-  private readonly messages: AgentMessage[] = [];
-  private readonly unsubscribe: () => void;
-
-  constructor(session: Pick<AgentSession, "subscribe">) {
-    this.unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-      if (event.type === "message_end") this.messages.push(event.message);
-    });
+/** Collect finalized turn messages and reduce them to one runtime outcome. */
+function collectChildTurnOutcome(
+  messages: readonly AgentMessage[],
+  aborted: boolean,
+): RuntimeTurnOutcome {
+  const finalAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+  if (!finalAssistant || finalAssistant.role !== "assistant") {
+    return {
+      status: aborted ? "cancelled" : "failed",
+      output: "",
+      error: "No terminal assistant response",
+    };
   }
-
-  dispose(): void {
-    this.unsubscribe();
+  if (finalAssistant.stopReason === "aborted") {
+    return {
+      status: "cancelled",
+      output: assistantText(finalAssistant),
+      error: finalAssistant.errorMessage,
+      usage: sumUsage(messages),
+    };
   }
-
-  toOutcome(aborted: boolean): RuntimeTurnOutcome {
-    const finalAssistant = [...this.messages]
-      .reverse()
-      .find((message) => message.role === "assistant");
-    if (!finalAssistant || finalAssistant.role !== "assistant") {
-      return {
-        status: aborted ? "cancelled" : "failed",
-        output: "",
-        error: "No terminal assistant response",
-      };
-    }
-    if (finalAssistant.stopReason === "aborted") {
-      return {
-        status: "cancelled",
-        output: assistantText(finalAssistant),
-        error: finalAssistant.errorMessage,
-        usage: sumUsage(this.messages),
-      };
-    }
-    if (finalAssistant.stopReason === "error") {
-      return {
-        status: "failed",
-        output: assistantText(finalAssistant),
-        error: finalAssistant.errorMessage ?? "Provider request failed",
-        usage: sumUsage(this.messages),
-      };
-    }
+  if (finalAssistant.stopReason === "error") {
     return {
-      status: "completed",
+      status: "failed",
       output: assistantText(finalAssistant),
-      usage: sumUsage(this.messages),
+      error: finalAssistant.errorMessage ?? "Provider request failed",
+      usage: sumUsage(messages),
     };
   }
+  return {
+    status: "completed",
+    output: assistantText(finalAssistant),
+    usage: sumUsage(messages),
+  };
 }
 
 /** Run one child operation while retaining its finalized outcome across compaction. */
@@ -495,10 +505,13 @@ export async function captureChildTurnOutcome(
   operation: () => Promise<void>,
   isAborted: () => boolean,
 ): Promise<RuntimeTurnOutcome> {
-  const collector = new ChildTurnOutcomeCollector(session);
+  const messages: AgentMessage[] = [];
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "message_end") messages.push(event.message);
+  });
   try {
     await operation();
-    return collector.toOutcome(isAborted());
+    return collectChildTurnOutcome(messages, isAborted());
   } catch (error) {
     return {
       status: isAborted() ? "cancelled" : "failed",
@@ -506,7 +519,7 @@ export async function captureChildTurnOutcome(
       error: error instanceof Error ? error.message : String(error),
     };
   } finally {
-    collector.dispose();
+    unsubscribe();
   }
 }
 
@@ -600,6 +613,11 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     return snapshotCommittedContext(this.session.messages, this.session.isStreaming);
   }
 
+  snapshotActivityMessages(): AgentMessage[] {
+    const streamingMessage = this.session.state.streamingMessage;
+    return [...this.session.messages, ...(streamingMessage ? [streamingMessage] : [])];
+  }
+
   hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: string): boolean {
     return findDeliveryEvidence(
       this.session.sessionManager.getBranch(),

package/src/minimal-subagents-tools.ts

@@ -202,7 +202,7 @@ export function createCoordinatorToolDefinitions(
     name: "subagent_wait",
     label: "Subagent Wait",
     description:
-      "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. An already settled turn returns event=turn once with queued messages in messages. Timeout never cancels the child.",
+      "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. An already settled turn returns event=turn once with queued messages in messages. Timeout returns event=timeout with detailed child status and never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     async execute(_toolCallId, parameters, signal, onUpdate) {
@@ -248,7 +248,7 @@ export function createCoordinatorToolDefinitions(
     name: "subagent_status",
     label: "Subagent Status",
     description:
-      "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, and dependencies.",
+      "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, dependencies, and bounded recent activity including message text and reasoning.",
     promptSnippet: "Inspect direct child state",
     parameters: options.schemas.subagent_status,
     async execute(_toolCallId, parameters) {

package/src/minimal-subagents-types.ts

@@ -1,9 +1,6 @@
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Usage } from "@earendil-works/pi-ai";
 
-/** Stable identity for one prompt and its complete assistant/tool loop. */
-export type TurnId = string & { readonly __turnId: unique symbol };
-
 /** Controls how much committed caller conversation enters a new child session. */
 export type SessionContextMode = "inherit" | "compact" | "omit";
 /** Controls whether child resource discovery includes project instructions, skills, and prompts. */
@@ -81,8 +78,19 @@ export interface WaitTurnResult extends TurnResult {
   messages?: WaitMessageResult[];
 }
 
-/** Reports one terminal child turn returned by subagent_wait. */
-export type WaitResult = WaitMessageResult | WaitTurnResult;
+/** Reports an observational wait timeout with the current detailed child status. */
+export interface WaitTimeoutResult {
+  event: "timeout";
+  agent_id: string;
+  turn_id: string;
+  /** Requested timeout duration that expired. */
+  timeout_ms: number;
+  /** Detailed child status captured when the timeout callback won. */
+  agent: AgentDetail;
+}
+
+/** Reports one message, terminal turn, or timeout returned by subagent_wait. */
+export type WaitResult = WaitMessageResult | WaitTurnResult | WaitTimeoutResult;
 
 /** Provides bounded hierarchy, usage, and best-known Runtime Profile data for one persistent agent. */
 export interface AgentSummary extends RuntimeProfile {
@@ -94,7 +102,6 @@ export interface AgentSummary extends RuntimeProfile {
   latest_turn?: Pick<TurnResult, "turn_id" | "status">;
   tools: string[];
   elapsed_ms?: number;
-  latest_activity?: string;
   latest_activity_at?: string;
   task?: string;
   child_count: number;
@@ -108,13 +115,22 @@ export interface RecentAgentMessage {
   content: string;
 }
 
-/** Extends summary status with launch, dependency, and recent-message diagnostics. */
+/** Reports one labeled, bounded child activity item without image data. */
+export interface RecentAgentActivity {
+  label: string;
+  content: string;
+  truncated: boolean;
+}
+
+/** Extends summary status with launch, dependency, recent-message, and recent-work diagnostics. */
 export interface AgentDetail extends AgentSummary {
   session_file?: string;
   launch_contract: LaunchContract;
   capability_ceiling: string[];
   spawn_entry_id: string;
   recent_messages: RecentAgentMessage[];
+  /** The 12 most recent work items, each capped at 20 lines and 2 KiB. */
+  recent_activity: RecentAgentActivity[];
   latest_result?: TurnResult;
   missing_dependencies: string[];
   unavailable_reason?: string;
@@ -142,7 +158,6 @@ export interface DeleteResult {
   agent_id: string;
   recursive: boolean;
   deleted_agent_ids: string[];
-  tombstoned_agent_ids: string[];
   trashed_session_files: string[];
   failures: Array<{ agent_id: string; error: string }>;
 }
@@ -163,7 +178,6 @@ export interface CallerSnapshot {
   thinkingLevel: ThinkingLevel;
   ordinaryTools: string[];
   capabilityCeiling: string[];
-  availableTools: string[];
   spawnEntryId: string;
 }
 
@@ -209,7 +223,10 @@ export interface ChildAgentRuntime {
   dispose(): void;
   /** Return the live Runtime Profile, or undefined when the SDK session has no model. */
   getRuntimeProfile(): RuntimeProfile | undefined;
+  /** Clone committed child transcript messages while excluding the streaming assistant tail. */
   snapshotCommittedMessages(): AgentMessage[];
+  /** Clone child transcript messages including the current streaming assistant tail. */
+  snapshotActivityMessages(): AgentMessage[];
   hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: string): boolean;
   getUsage(): Usage | undefined;
 }
@@ -276,7 +293,6 @@ export interface PersistedAgent {
   missing_dependencies: string[];
   unavailable_reason?: string;
   recent_messages: RecentAgentMessage[];
-  deleted?: boolean;
 }
 
 /** Records which conversation path owns one successful terminal result. */

package/src/minimal-subagents-ui.ts

@@ -15,6 +15,7 @@ import {
   formatSubagentDuration,
   renderSubagentStatusLabel,
   renderSubagentStatusSymbol,
+  subagentStatusLadder,
 } from "./minimal-subagents-rendering.js";
 import type {
   AgentSummary,
@@ -65,9 +66,9 @@ function flattenAgentHierarchy(agents: readonly AgentSummary[]): FlattenedAgentS
 }
 
 function agentTerminalStatus(agent: AgentSummary): TurnStatus | "idle" | "unavailable" {
-  if (agent.availability === "unavailable") return "unavailable";
-  if (agent.state === "running") return "running";
-  return agent.latest_turn?.status ?? "idle";
+  const status = subagentStatusLadder(agent);
+  // SAFETY: the shared ladder emits exactly the unavailable/running/TurnStatus/idle vocabulary.
+  return status as TurnStatus | "idle" | "unavailable";
 }
 
 function terminalTimestamp(agent: AgentSummary): number {