@signalridge/pi-subagents 1.12.0 → 1.14.0

package/src/index.ts

@@ -37,6 +37,7 @@ import {
   Spacer,
   Text,
 } from "@earendil-works/pi-tui";
+import { parseOwnedConversationOpenRequest, replyChannel, WORKFLOW_UI_CHANNELS } from "@signalridge/pi-subagents-protocol";
 import { wrapCustomUi } from "@signalridge/pi-ui";
 import { Type } from "@sinclair/typebox";
 import { abortable } from "./abortable.js";
@@ -57,6 +58,7 @@ import {
 import {
   AgentManager,
   MANAGED_SPAWN_ENTRY_TYPE,
+  type ManagedSpawnCallbacks,
   type ManagedSpawnEntryLike,
   type ManagedSpawnPolicy,
   type ManagedSpawnRequest,
@@ -213,11 +215,8 @@ import {
   type Theme,
 } from "./ui/agent-display.js";
 import { createMentionProvider, mentionRoster } from "./ui/agent-mention.js";
-import {
-  ConversationViewer,
-  VIEWPORT_HEIGHT_PCT,
-} from "./ui/conversation-viewer.js";
-import { FleetList, type FleetUICtx } from "./ui/fleet-list.js";
+import { getConversationOverlayOptions } from "./ui/conversation-viewer.js";
+import { type AgentSelection, captureAgentSelection, FleetList, type FleetUICtx } from "./ui/fleet-list.js";
 import {
   safeTerminalText,
   sanitizeDisplayText,
@@ -230,6 +229,7 @@ import {
   getAgentStatusLabel,
   getAgentStatusMark,
 } from "./ui/status-label.js";
+import { WorkflowUiClient } from "./ui/workflow-ui-client.js";
 import {
   addUsage,
   getLifetimeTotal,
@@ -811,6 +811,12 @@ function activateRootRuntime(
     // tokens is omitted when nothing was ever produced (e.g. agent errored before
     // any message_end fired), preserving prior payload shape.
     const u = record.lifetimeUsage;
+    const managedUsage = record.owner ? manager.getManagedUsage(record.id, record.owner) : undefined;
+    const managedTokens = managedUsage ? {
+      input: managedUsage.input,
+      output: managedUsage.output,
+      total: getLifetimeTotal(managedUsage),
+    } : undefined;
     const total = getLifetimeTotal(u);
     const tokens =
       total > 0 ? { input: u.input, output: u.output, total } : undefined;
@@ -824,6 +830,7 @@ function activateRootRuntime(
       toolUses: record.toolUses,
       durationMs,
       tokens,
+      ...(managedTokens ? { managedTokens: { ...managedTokens } } : {}),
       ...(record.outputFile ? { outputFile: record.outputFile } : {}),
       ...(record.invocation?.agentTier === undefined
         ? {}
@@ -919,13 +926,25 @@ function activateRootRuntime(
     string,
     { runs: number; usage: LifetimeUsage }
   >();
+  const accountedUsage = new WeakMap<AgentRecord, { usage: LifetimeUsage; completion: string; promise: AgentRecord["promise"] }>();
   function recordSessionUsage(record: AgentRecord): void {
+    const previous = accountedUsage.get(record);
+    const completion = JSON.stringify([record.owner, record.startedAt, record.completedAt]);
+    if (previous?.completion === completion && previous.promise === record.promise) return;
+    const usage = {
+      input: Math.max(0, record.lifetimeUsage.input - (previous?.usage.input ?? 0)),
+      output: Math.max(0, record.lifetimeUsage.output - (previous?.usage.output ?? 0)),
+      cacheWrite: Math.max(0, record.lifetimeUsage.cacheWrite - (previous?.usage.cacheWrite ?? 0)),
+    };
+    // Records survive native resumes; lifetime totals must be credited only once.
+    // Weak ownership releases bookkeeping when the manager evicts the record.
+    accountedUsage.set(record, { usage: { ...record.lifetimeUsage }, completion, promise: record.promise });
     const entry = sessionUsageByType.get(record.type) ?? {
       runs: 0,
       usage: { input: 0, output: 0, cacheWrite: 0 },
     };
     entry.runs++;
-    addUsage(entry.usage, record.lifetimeUsage);
+    addUsage(entry.usage, usage);
     sessionUsageByType.set(record.type, entry);
   }
 
@@ -935,6 +954,14 @@ function activateRootRuntime(
       // Nested children report only through their owning parent's scoped tools.
       // Keep them out of top-level lifecycle, transcript, notification, and UI channels.
       if (record.parentAgentId || record.detached) return;
+      // Native thread resumes do not pass the fresh-spawn stream finalizer.
+      // Flush and retire this owned attempt's UI subscription before publishing
+      // its terminal payload; the next admission installs a new anchored stream.
+      if (record.owner) {
+        const cleanup = record.outputCleanup;
+        record.outputCleanup = undefined;
+        cleanup?.();
+      }
 
       // Emit lifecycle event based on terminal status
       const isError =
@@ -1058,6 +1085,10 @@ function activateRootRuntime(
       append: (tombstone) =>
         pi.appendEntry(MANAGED_SPAWN_ENTRY_TYPE, tombstone),
     },
+    (record) => {
+      record.joinMode = "async";
+      refreshAgentSurfaces();
+    },
   );
 
   // Expose the validated root manager via Symbol.for() for cross-package access.
@@ -1283,6 +1314,7 @@ function activateRootRuntime(
   ): Promise<void> {
     // A successful session_start is the commit point for a reused runtime. A
     // cancelled session_before_switch leaves the old context and scheduler live.
+    retireFleetUi();
     if (currentCtx) {
       scheduler.stop();
       manager.detachForBranchChange();
@@ -1402,6 +1434,7 @@ function activateRootRuntime(
     }
     if (ownsRpcRegistry && isSchedulingEnabled() && !scheduler.isActive())
       startScheduler(ctx);
+    bindFleetUi();
   }
 
   // Both before-events are cancellable. A later handler may veto, and tree
@@ -1413,6 +1446,7 @@ function activateRootRuntime(
   const detachCommittedTree = (event: unknown): void => {
     if (!currentCtx || detachedTreeEvent === event) return;
     detachedTreeEvent = event;
+    retireFleetUi();
     parentQuestions.retire();
     manager.detachForBranchChange();
   };
@@ -1446,6 +1480,7 @@ function activateRootRuntime(
     manager.clearCompleted(true);
     for (const tombstone of recovered) persistRecoveredManaged(tombstone);
     if (isSchedulingEnabled() && !scheduler.isActive()) startScheduler(ctx);
+    bindFleetUi();
   });
 
   // Shutdown is idempotent and also serves same-session hot-reload handoff. The
@@ -1473,6 +1508,7 @@ function activateRootRuntime(
       });
       scheduler.stop();
       parentQuestions.retire();
+      retireFleetUi();
       currentCtx = undefined; // reject new spawns; owned cleanup RPC remains bound
       if (pending.length > 0) {
         let timer: ReturnType<typeof setTimeout> | undefined;
@@ -1549,6 +1585,60 @@ function activateRootRuntime(
   // used to carry the same rows, with the same summary repeated again in the
   // footer status; one surface, below the prompt, replaces all three.
   const fleet = new FleetList(manager, agentActivity);
+  let workflowUiClient: WorkflowUiClient | undefined;
+  let ownedConversationUnsubscribe: (() => void) | undefined;
+  const retiredWorkflowSurfaces = new Set<string>();
+
+  function rootUiFence(): () => boolean {
+    const root = currentCtx;
+    const generation = sessionGeneration;
+    const managerIdentity = root?.sessionManager;
+    const sessionId = boundSessionId;
+    return () => !!root && currentCtx === root && generation === sessionGeneration &&
+      currentCtx.sessionManager === managerIdentity && boundSessionId === sessionId &&
+      currentCtx.sessionManager.getSessionId() === sessionId;
+  }
+
+  function retireFleetUi(): void {
+    ownedConversationUnsubscribe?.();
+    ownedConversationUnsubscribe = undefined;
+    workflowUiClient?.dispose();
+    workflowUiClient = undefined;
+    fleet.dispose();
+  }
+
+  function bindFleetUi(): void {
+    if (!currentCtx || !ownsRpcRegistry) return;
+    const ctx = currentCtx;
+    const isCurrent = rootUiFence();
+    ownedConversationUnsubscribe = pi.events.on(WORKFLOW_UI_CHANNELS.openConversation, raw => {
+      let request: ReturnType<typeof parseOwnedConversationOpenRequest>;
+      try { request = parseOwnedConversationOpenRequest(raw); } catch { return; }
+      const channel = replyChannel(WORKFLOW_UI_CHANNELS.openConversation, request.requestId);
+      const retained = manager.getRecordMutable(request.agentId);
+      const selection = retained ? captureAgentSelection(manager, retained, isCurrent) : undefined;
+      const owner = selection?.owner;
+      if (!isCurrent() || ctx.mode !== "tui" || !ctx.hasUI || !selection?.session || !selection.current() ||
+        retained?.parentAgentId || owner?.extension !== request.owner.extension || owner.runId !== request.owner.runId ||
+        owner.nodeId !== request.owner.nodeId || owner.attemptId !== request.owner.attemptId || !fleet.canOpenConversation(selection)) {
+        pi.events.emit(channel, { success: false, error: "Exact retained agent conversation is not available in the active TUI." });
+        return;
+      }
+      // Reserve the exact selection before replying: reply listeners can issue
+      // another request or retire this root synchronously. Only construction yields.
+      if (!fleet.openConversation(selection, true)) {
+        pi.events.emit(channel, { success: false, error: "Exact retained agent conversation is already reserved or unavailable." });
+        return;
+      }
+      pi.events.emit(channel, { success: true, data: { accepted: true } });
+    });
+    if (ctx.mode !== "tui" || !ctx.hasUI) return;
+    fleet.setUICtx(ctx.ui as unknown as FleetUICtx);
+    workflowUiClient = new WorkflowUiClient(pi.events, () => isCurrent() && ctx.mode === "tui" && ctx.hasUI,
+      () => fleet.update(), retiredWorkflowSurfaces);
+    fleet.setWorkflowClient(workflowUiClient);
+  }
+
   let fleetViewEnabled = true;
   function isFleetViewEnabled(): boolean {
     return fleetViewEnabled;
@@ -1570,6 +1660,7 @@ function activateRootRuntime(
   function seatFleet(ctx: ExtensionContext): boolean {
     if (ctx.mode !== "tui" || !ctx.hasUI) return false;
     fleet.setUICtx(ctx.ui as unknown as FleetUICtx);
+    fleet.setWorkflowClient(workflowUiClient);
     return true;
   }
 
@@ -1586,6 +1677,7 @@ function activateRootRuntime(
     // session that has not run a tool yet. Re-seat from the live context so the
     // guard and the draw target agree; the setter is idempotent.
     fleet.setUICtx(currentCtx.ui as unknown as FleetUICtx);
+    fleet.setWorkflowClient(workflowUiClient);
     // Arm the tickers after the draw, not before: both tear their own timer down
     // when they find nothing to show, and the fleet finds nothing until the child
     // session lands a moment later. A spawn that entered through the manager has
@@ -1676,16 +1768,17 @@ function activateRootRuntime(
       },
     };
 
-    const { state, callbacks } = createActivityTracker(undefined, () => {
-      fleet.update();
-    });
+    // Allocate tracking only at a real fresh/reused-thread admission. An
+    // idempotent request replay must not create another tracker at all.
+    let tracker: ReturnType<typeof createActivityTracker> | undefined;
+    const tracking = () => tracker ??= createActivityTracker(undefined, () => fleet.update());
     const outputTranscript =
       getAgentConfig(dispatch.type)?.outputTranscript ??
       getOutputTranscriptDefault();
     let id = "";
     const initializeRecord = (spawnedId: string): void => {
       id = spawnedId;
-      agentActivity.set(id, state);
+      agentActivity.set(id, tracking().state);
       const record = manager.getRecordMutable(id);
       if (record && outputTranscript) {
         record.outputFile = createOutputFilePath(
@@ -1703,12 +1796,31 @@ function activateRootRuntime(
       fleet.ensureTimer();
       fleet.update();
     };
-    const onSessionCreated = callbacks.onSessionCreated;
-    const managedCallbacks = {
-      ...callbacks,
+    const managedCallbacks: ManagedSpawnCallbacks = {
+      onToolActivity: activity => tracker?.callbacks.onToolActivity(activity),
+      onTextDelta: (delta, text) => tracker?.callbacks.onTextDelta(delta, text),
+      onTurnEnd: count => tracker?.callbacks.onTurnEnd(count),
+      onAssistantUsage: usage => tracker?.callbacks.onAssistantUsage(usage),
       onSpawned: initializeRecord,
+      onResumeStarting: (record: AgentRecord, startMessageIndex: number) => {
+        id = record.id;
+        const { state } = tracking();
+        state.session = record.session;
+        state.toolUses = record.toolUses;
+        state.lifetimeUsage = { ...record.lifetimeUsage };
+        agentActivity.set(id, state);
+        record.outputCleanup?.();
+        record.outputCleanup = undefined;
+        if (outputTranscript && record.session) {
+          record.outputFile ??= createOutputFilePath(ctxRef.cwd, id, ctxRef.sessionManager.getSessionId());
+          ensureOutputFile(record.outputFile);
+          record.outputCleanup = streamToOutputFile(record.session, record.outputFile, id, ctxRef.cwd, startMessageIndex);
+        }
+        fleet.ensureTimer();
+        fleet.update();
+      },
       onSessionCreated: (session: AgentSession) => {
-        onSessionCreated(session);
+        tracking().callbacks.onSessionCreated(session);
         const record = manager.getRecordMutable(id);
         if (record?.outputFile) {
           record.outputCleanup = streamToOutputFile(
@@ -1734,11 +1846,9 @@ function activateRootRuntime(
     // transcript, timer, or callback chain. The original Agent record owns all
     // first-class UI and streaming state.
     if (!managedResult.created) return managedResult;
-    if (!id) {
-      const record = manager.getRecordMutable(managedResult.id);
-      if (record?.status === "queued" || record?.status === "running")
-        initializeRecord(managedResult.id);
-    }
+    // New records invoke onSpawned synchronously. Reused threads invoke only
+    // onResumeStarting at actual admission (possibly after waiting for capacity).
+    // Never fall through to the truncating new-record initializer on reentry.
     return managedResult;
   }
 
@@ -3161,8 +3271,12 @@ Terse command-style prompts produce shallow, generic work.
       let spinnerFrame = 0;
       const startedAt = Date.now();
       let fgId: string | undefined;
+      let foregroundUpdates = true;
+      let handedOff = false;
 
       const streamUpdate = () => {
+        fleet.update();
+        if (!foregroundUpdates) return;
         const details: AgentDetails = {
           ...detailBase,
           toolUses: fgState.toolUses,
@@ -3248,21 +3362,30 @@ Terse command-style prompts produce shallow, generic work.
           (fgAgentId) => {
             // onSpawned: called synchronously after spawn, before onSessionCreated fires.
             // Set up the output file so streamToOutputFile can pick it up.
+            fgId = fgAgentId;
             const fgRec = manager.getRecordMutable(fgAgentId);
+            if (fgRec) fgRec.toolCallId = toolCallId;
             attachTranscript(fgRec, fgAgentId);
           },
         );
         record = fgResult.record;
+        handedOff = fgResult.handedOff === true;
       } finally {
-        // Always stop the spinner and drop the row, including startup errors
-        // that now propagate to pi as failed tool calls.
+        // A transfer ends this tool's spinner, not the child's activity or stream.
+        foregroundUpdates = false;
         clearInterval(spinnerInterval);
-        if (fgId) {
+        if (fgId && !handedOff) {
           agentActivity.delete(fgId);
           fleet.onAgentFinished(fgId);
         }
       }
 
+      if (handedOff) {
+        return textResult(`${fallbackNote}Agent continues in background.\nAgent ID: ${record.id}\n` +
+          "You will be notified when it completes. Use get_subagent_result for results or steer_subagent to send messages.",
+          buildDetails(detailBase, record, fgState, { status: "background" }));
+      }
+
       // Get final token count
       const tokenText = formatLifetimeTokens(fgState);
 
@@ -3559,6 +3682,8 @@ Terse command-style prompts produce shallow, generic work.
   }
 
   async function showAgentsMenu(ctx: ExtensionCommandContext) {
+    const isCurrent = rootUiFence();
+    if (!isCurrent()) return;
     reloadCustomAgents();
     const allNames = getAllTypes();
 
@@ -3606,31 +3731,31 @@ Terse command-style prompts produce shallow, generic work.
     }
 
     const choice = await ctx.ui.select("Agents", options);
-    if (!choice) return;
+    if (!choice || !isCurrent()) return;
 
     if (choice.startsWith("Agent runs (")) {
       await showAgentRuns(ctx);
-      await showAgentsMenu(ctx);
+      if (isCurrent()) await showAgentsMenu(ctx);
     } else if (choice.startsWith("Agent types (")) {
       await showAllAgentsList(ctx);
-      await showAgentsMenu(ctx);
+      if (isCurrent()) await showAgentsMenu(ctx);
     } else if (choice.startsWith("Scheduled jobs (")) {
       await showSchedulesMenu(ctx, scheduler);
-      await showAgentsMenu(ctx);
+      if (isCurrent()) await showAgentsMenu(ctx);
     } else if (choice.startsWith("Model tiers (")) {
       await showModelTiersMenu(ctx);
-      await showAgentsMenu(ctx);
+      if (isCurrent()) await showAgentsMenu(ctx);
     } else if (choice === "Create new agent") {
       await showCreateWizard(ctx);
     } else if (choice === "Settings") {
       await showSettings(ctx);
-      await showAgentsMenu(ctx);
+      if (isCurrent()) await showAgentsMenu(ctx);
     } else if (choice.startsWith("Usage (")) {
       showSessionUsage(ctx);
-      await showAgentsMenu(ctx);
+      if (isCurrent()) await showAgentsMenu(ctx);
     } else if (choice === "Diagnostics") {
       await showDiagnostics(ctx);
-      await showAgentsMenu(ctx);
+      if (isCurrent()) await showAgentsMenu(ctx);
     }
   }
 
@@ -3754,29 +3879,33 @@ Terse command-style prompts produce shallow, generic work.
   }
 
   async function showAgentRuns(ctx: ExtensionCommandContext) {
-    const agents = manager.listAgentsMutable().filter((a) => !a.parentAgentId);
+    const isCurrent = rootUiFence();
+    const agents = manager.listAgentsMutable().filter((a) => !a.parentAgentId && !a.detached)
+      .map(record => captureAgentSelection(manager, record, isCurrent));
     if (agents.length === 0) {
       ctx.ui.notify("No agents.", "info");
       return;
     }
 
-    const record = await selectItem(ctx.ui, "Agent runs", agents, (agent) => {
+    const selection = await selectItem(ctx.ui, "Agent runs", agents, ({ snapshot: agent }) => {
       const dn = getDisplayName(agent.type);
       const dur = formatDuration(agent.startedAt, agent.completedAt);
       return `${dn} (${sanitizeDisplayText(agent.description)}) · ${agent.toolUses} tools · ${getAgentStatusLabel(agent.status)} · ${dur}`;
     });
-    if (!record) return;
+    if (!selection || !isCurrent() || !selection.current()) return;
 
-    await viewAgentConversation(ctx, record);
-    // Back-navigation: re-show the list
-    await showAgentRuns(ctx);
+    await viewAgentConversation(ctx, selection);
+    // Back-navigation stays on the same root/tree, never a replacement.
+    if (isCurrent()) await showAgentRuns(ctx);
   }
 
   async function viewAgentConversation(
     ctx: ExtensionCommandContext,
-    record: AgentRecord,
+    selection: AgentSelection,
   ) {
-    if (!record.session) {
+    const record = selection.snapshot;
+    if (!selection.current()) return;
+    if (!selection.session) {
       if (record.status === "queued") {
         const handleHint = record.handle
           ? ` Use @${record.handle} <message> to chat while it waits.`
@@ -3785,7 +3914,7 @@ Terse command-style prompts produce shallow, generic work.
           "Queued agent",
           `"${sanitizeDisplayText(record.description)}" has not started yet.${handleHint}\n\nStop this queued run?`,
         );
-        if (stop && manager.abort(record.id)) {
+        if (stop && selection.current() && manager.abort(record.id)) {
           ctx.ui.notify(
             `Stopped queued agent "${sanitizeDisplayText(record.description)}".`,
             "info",
@@ -3797,38 +3926,19 @@ Terse command-style prompts produce shallow, generic work.
       return;
     }
 
-    const session = record.session;
-    const activity = agentActivity.get(record.id);
-
-    await wrapCustomUi(ctx.ui).custom<undefined>(
+    seatFleet(ctx);
+    const mode = fleet.conversationMode();
+    // Fullscreen owns its entire native viewport; an extra shared border would
+    // clip its controls. Floating conversations retain the normal treatment.
+    const viewerUi = mode === "fullscreen" ? ctx.ui : wrapCustomUi(ctx.ui);
+    await viewerUi.custom<undefined>(
       (tui, theme, keybindings, done) => {
-        return new ConversationViewer(
-          tui,
-          session,
-          record,
-          activity,
-          theme,
-          done,
-          () => {
-            if (manager.abort(record.id)) {
-              ctx.ui.notify(
-                `Stopped "${sanitizeDisplayText(record.description)}".`,
-                "info",
-              );
-            }
-          },
-          keybindings,
-          (message: string) => manager.steer(record.id, message),
-          () => manager.getRecord(record.id),
-        );
+        if (!selection.current()) { done(undefined); return { render: () => [], invalidate: () => {} }; }
+        return fleet.conversation(selection, tui, theme, keybindings, done, message => ctx.ui.notify(message, "info"), mode);
       },
       {
         overlay: true,
-        overlayOptions: {
-          anchor: "center",
-          width: "90%",
-          maxHeight: `${VIEWPORT_HEIGHT_PCT}%`,
-        },
+        overlayOptions: getConversationOverlayOptions({ mode: mode === "fullscreen" ? "fullscreen" : undefined }),
       },
     );
   }

package/src/operation-approvals.ts

@@ -0,0 +1,49 @@
+import { randomUUID } from "node:crypto";
+import { defineTool, type ExtensionContext, type ExtensionToolContext, type SettingsManager, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type ApprovalService, createApprovalToolDefinitions } from "@signalridge/pi-approval-core";
+import { captureQuestionOrigin } from "./question-origin.js";
+
+/** Human service capture and native context leases live for the entire child session. */
+export function createChildApprovalTools(options: {
+  service: ApprovalService;
+  assertServiceCurrent: () => void;
+  root: ExtensionContext;
+  rootOrigin: (current: ExtensionContext) => boolean;
+  agentId?: string;
+  settings: SettingsManager;
+  waiting: (toolCallId: string) => () => void;
+  isBound: () => boolean;
+  isToolCurrent: (name: string) => boolean;
+}): ToolDefinition[] {
+  const leases = new WeakMap<ExtensionToolContext, () => boolean>();
+  const [edit, write, bash] = createApprovalToolDefinitions({
+    source: `child:${options.agentId ?? randomUUID()}`,
+    shellPath: options.settings.getShellPath(),
+    commandPrefix: options.settings.getShellCommandPrefix(),
+    isToolCurrent: (_ctx, name) => options.isToolCurrent(name),
+    isCurrent: (ctx) => {
+      let lease = leases.get(ctx);
+      if (!lease) {
+        const childOrigin = captureQuestionOrigin(ctx);
+        const invocationRoot = captureQuestionOrigin(options.root);
+        lease = () => {
+          if (ctx.signal?.aborted || !options.isBound() || !options.rootOrigin(options.root) ||
+            !invocationRoot(options.root) || !childOrigin(ctx)) return false;
+          options.assertServiceCurrent();
+          return true;
+        };
+        leases.set(ctx, lease);
+      }
+      return lease();
+    },
+    request: async (operation, owner) => {
+      const resume = options.waiting(operation.toolCallId);
+      try {
+        await options.service.request(operation, owner);
+      } finally {
+        resume();
+      }
+    },
+  });
+  return [defineTool(edit), defineTool(write), defineTool(bash)];
+}

package/src/output-file.ts

@@ -95,17 +95,32 @@ export function streamToOutputFile(
   cwd: string,
   startIndex?: number,
 ): () => void {
-  // Index of the first message this stream is responsible for. A spawn writes
-  // messages[0] as the initial prompt entry, so it starts at 1. A resume hands
-  // in the session's length as of just before the run: the session already
-  // holds every prior turn, and re-emitting those would duplicate history that
-  // is already in the file.
-  let writtenCount = startIndex ?? 1;
+  if (startIndex !== undefined && (!Number.isSafeInteger(startIndex) || startIndex < 0)) {
+    throw new RangeError("startIndex must be a nonnegative safe integer");
+  }
+  // A resume supplies the index past history already on disk. A fresh spawn
+  // has seeded its prompt separately, but Pi may add the actual user later or
+  // handle the input via a custom-message turn with no user at all. Dedup is
+  // independent of the cursor so legitimate pre-user records still stream.
+  let writtenCount = startIndex ?? 0;
+  let initialUserPending = startIndex === undefined;
+  let disposed = false;
 
   const flush = () => {
+    if (disposed) return;
     const messages = session.messages;
     while (writtenCount < messages.length) {
-      const msg = messages[writtenCount];
+      const msg = messages[writtenCount++];
+      // Native prompt/tool-loadout records have no Claude Code transcript entry.
+      if (msg.role === "system") continue;
+      if (initialUserPending && msg.role === "user") {
+        initialUserPending = false;
+        continue;
+      }
+      // An actual assistant response proves a turn ran without the seeded user.
+      // Its later follow-up must be kept, even if both reach the same flush.
+      // Custom guidance alone is not that evidence: the user can still arrive.
+      if (msg.role === "assistant") initialUserPending = false;
       const entry = {
         isSidechain: true,
         agentId,
@@ -117,11 +132,11 @@ export function streamToOutputFile(
       try {
         appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
       } catch { /* ignore write errors */ }
-      writtenCount++;
     }
   };
 
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (disposed) return;
     if (event.type === "turn_end") flush();
     // Compaction replaces session.messages with a shorter, summarized array,
     // leaving writtenCount past the new end — without re-anchoring, the flush
@@ -135,12 +150,16 @@ export function streamToOutputFile(
     // session.messages untouched, so only successful ones re-anchor.
     if (event.type === "compaction_start") flush();
     if (event.type === "compaction_end" && !event.aborted && event.result) {
-      queueMicrotask(() => { writtenCount = session.messages.length; });
+      queueMicrotask(() => {
+        if (!disposed) writtenCount = session.messages.length;
+      });
     }
   });
 
   return () => {
+    if (disposed) return;
     flush();
+    disposed = true;
     unsubscribe();
   };
 }

package/src/types.ts

@@ -180,8 +180,9 @@ export interface AgentRecord {
   /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
   compactionCount: number;
   /**
-   * Whether this agent was spawned to run in the background. Tri-state, set at
-   * spawn from `SpawnOptions.isBackground`: `true` = background, `false` =
+   * Whether this agent currently runs in the background. Tri-state, initially
+   * set from `SpawnOptions.isBackground`; a foreground handoff sets it to true.
+   * `true` = background, `false` =
    * foreground (has an inline Agent tool-result surface), `undefined` = the
    * caller never declared it (e.g. a cross-extension RPC spawn, which is detached
    * and has no inline surface). The widget's background-only filter keys off this
@@ -190,7 +191,7 @@ export interface AgentRecord {
    * which only the Agent-tool path populates.
    */
   isBackground?: boolean;
-  /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
+  /** Resolved spawn params for UI display; handoff updates runInBackground. */
   invocation?: AgentInvocation;
   /** Nesting depth: top-level subagent = 1. */
   depth?: number;