@fitchmultz/pi-subagents 0.51.0 → 0.52.0

package/docs/performance.md

@@ -2,8 +2,8 @@
 
 ## Rebuild measurements
 
-The baseline and enforced size ceilings are in
-[the rebuild evidence](single-agent-rebuild.md). `node scripts/measure-size.mjs`
+The baseline is in [the rebuild evidence](single-agent-rebuild.md); the only
+enforced ceiling is the 1 MiB total production bytes. `node scripts/measure-size.mjs`
 measures production source, schemas, generated code and scripts; tests are separate.
 Line/byte reductions are not measurements of latency, resident memory, provider
 cost, or throughput.
@@ -36,7 +36,13 @@ speedup claim. The long-lived costs remain explicit: a main reconciles receipts
 when watched completion inputs change and stats those inputs each second, native
 actors check their parent each second and scan durable commands on change, and the
 broker maintains connections/presence. Completed actors stay messageable
-while attached; observed owner detachment ends their lifetime. Native lifecycle
+while attached; observed owner detachment ends their lifetime. On the fork, when native
+working-session capture and broker parking support are both available, a child
+idle for five minutes parks its exact working state and exits, releasing its
+process and heap. On official Pi, or with an older broker that lacks parking
+support, idle children stay resident. A genuine message or continuation restores that exact
+state at the cost of one cold actor start. No retained measurement quantifies
+the memory released or the wake latency. Native lifecycle
 and live acceptance checks verify disposal/exit, rather than inferring cleanup
 from a timer or package size.
 
@@ -137,6 +143,28 @@ The [issue 248 evidence](evidence/issue-248/README.md) includes both waits,
 switch-to-first-tool measurements, ranges, profiler results, exact runtime and
 build identities, reproducible commands, and retained synthetic RPC transcripts.
 
+### Empty-owner idle CPU (#238)
+
+The issue 238 idle ceiling of 30 ms CPU per 10 s still fails against the
+observer-only floor on official Pi 1.4.0 and the maintained fork. No runtime
+change or waiver is claimed. In the sampled configurations, most of the
+increment is a one-shot pair of V8 memory-reducer collections about 8 s after
+`session_start`. An isolated package that only imports `typebox` showed a
+128,968-byte C++ heap reading at `session_start`, followed by the same pair of
+collections. That is consistent with Pi's bundled Jiti 2.7.0 loader compiling it
+through `vm.runInThisContext`, which allocates on the C++ heap. Jiti
+can try a native ESM import first when no transformation is needed, so this is
+not a rule for every extension or host import. That two-line package added
+38–41 ms in the same campaign. Against it,
+the measured `bb38f682` artifact (build `fc084c36`) added 20.7 ms on official
+Pi and 15.0 ms on the fork. Most of that difference is one-shot work right
+after `session_start`, chiefly the intercom broker and owner attachment. In two
+official-host 40 s floor/`0b6da9b` pairs, the later windows of about 10 s each
+stayed within 1.1 ms of the paired floor. There is no fork long run, and this
+is not an indefinite-idle bound. The
+[issue 238 evidence](evidence/issue-238-idle/README.md) has the samples, host
+hashes, native causal chain and limits.
+
 ## Necessary costs
 
 - Native Pi owns context loading and model execution. The extension cannot remove

package/docs/reference.md

@@ -96,7 +96,18 @@ acceptance is not admission, and admission is not model consumption. Inspect the
 if guidance became stale; do not infer acceptance from the old completed output.
 
 A completed child can remain alive and messageable while its main remains
-attached. Parent exit or session replacement stops its actors and verified owned
+attached. On a Pi fork with native working-session capture, a child that stays
+idle for five minutes (no run, turn, journal change, live viewer or owned shell)
+parks: it saves its exact working state and its process exits, while its intercom
+identity stays listed with no departure. Passive messages, topic updates and
+`last` reads do not wake it; the main answers `last` from the saved history, and
+without its main the read reports that history unavailable. Receipt reads also do
+not wake it and report `publication_unavailable`. A
+normal message, ask or continuation restores the exact saved state into a new
+process, which then receives retained messages in order. If the final save
+fails, the child records `park-failed.json` and nothing restarts implicitly;
+retained messages stay queued and continuing reports the failure. Official Pi
+keeps idle children resident. Parent exit or session replacement stops its actors and verified owned
 native shells, allowing native abort a short grace period before escalation.
 Actors also watch for parent death, including a hard kill. Ordinary extension
 reload keeps children alive because the parent has not exited.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/scripts/measure-size.mjs

@@ -4,7 +4,7 @@ import { extname, join } from "node:path";
 
 const roots = ["src", "scripts", "generated"];
 const extensions = new Set([".ts", ".js", ".mjs", ".cjs", ".json", ".sh"]);
-const ceilings = { sourceLines: 19000, productionLines: 22500, productionBytes: 1048576 };
+const ceilings = { productionBytes: 1048576 };
 
 /**
  * @param {string} directory

package/src/agent/child-runtime.ts

@@ -0,0 +1,105 @@
+import * as fs from "node:fs";
+import type {
+  CreateAgentSessionRuntimeFactory,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Launch } from "./contracts.ts";
+import type { loadSDK, WorkingState } from "./host.ts";
+import { shellCommand } from "./process.ts";
+import { localCwdOwner } from "./cwd.ts";
+import type { ToolEvent } from "./observation-state.ts";
+
+function guard(pi: ExtensionAPI, directory: string, token: string): void {
+  pi.on("tool_call", (event) => {
+    if (event.toolName === "delegate" || event.toolName === "agent_runs") {
+      return { block: true, reason: "Only a main session may delegate or control children." };
+    }
+    const owner = pi.getAllTools().find((tool) => tool.name === "bash")?.sourceInfo;
+    if (
+      event.toolName === "bash" &&
+      typeof event.input.command === "string" &&
+      owner &&
+      (owner.source === "builtin" || localCwdOwner(owner))
+    ) {
+      // Preserve the selected local owner's cwd/env and leave remote/custom tools alone.
+      const input = event.input;
+      input.command = shellCommand(event.input.command, directory, token);
+    }
+    return;
+  });
+}
+interface ChildHooks {
+  readonly directory: string;
+  readonly token: string;
+  /** Exact parked working state; absent means the saved journal alone. */
+  readonly saved: WorkingState | undefined;
+  readonly started: (pi: ExtensionAPI, ctx: ExtensionContext) => void;
+  readonly tool: (event: ToolEvent) => void;
+}
+/** One native child session with this package's child policy and live-view hooks. */
+export function childRuntime(
+  sdk: Awaited<ReturnType<typeof loadSDK>>,
+  launch: Launch,
+  hooks: ChildHooks,
+): CreateAgentSessionRuntimeFactory {
+  return async ({ sessionManager }) => {
+    // Exact restore keeps settings, tool policy and accepted queues; it never replays input.
+    const restore = hooks.saved ? { workingSession: hooks.saved } : {};
+    if (!fs.existsSync(launch.sessionFile)) {
+      throw new Error("Missing saved native session; refusing to create another.");
+    }
+    const settingsManager = sdk.SettingsManager.create(launch.cwd, launch.agentDir, {
+      projectTrusted: launch.trusted,
+    });
+    const services = await sdk.createAgentSessionServices({
+      ...restore,
+      cwd: launch.cwd,
+      agentDir: launch.agentDir,
+      settingsManager,
+      resourceLoaderOptions: {
+        additionalExtensionPaths: [launch.entry],
+        extensionFactories: [
+          {
+            name: "codemode",
+            builtin: true,
+            factory: sdk.createCodemodeExtension({ mode: "on" }),
+          },
+          { name: "tool_search", builtin: true, factory: sdk.createToolSearchExtension() },
+          { name: "mcp", builtin: true, factory: sdk.createMcpExtension() },
+          (pi) => {
+            guard(pi, hooks.directory, hooks.token);
+            pi.on("session_start", (_event, ctx) => {
+              hooks.started(pi, ctx);
+            });
+            // Sparse tool lifecycle keeps the live view's tools even while nobody watches.
+            pi.on("tool_execution_start", hooks.tool);
+            pi.on("tool_execution_update", hooks.tool);
+            pi.on("tool_execution_end", hooks.tool);
+          },
+        ],
+      },
+    });
+    const diagnostics = services.resourceLoader.getExtensions().errors;
+    if (diagnostics.length > 0) {
+      throw new Error(`Child extension load failed: ${JSON.stringify(diagnostics)}`);
+    }
+    const model = services.modelRuntime.getModel(launch.provider, launch.model);
+    if (!model) {
+      throw new Error(
+        `Saved model ${launch.provider}/${launch.model} is unavailable; no fallback was used.`,
+      );
+    }
+    return {
+      ...(await sdk.createAgentSessionFromServices({
+        ...restore,
+        services,
+        sessionManager,
+        model,
+        thinkingLevel: launch.thinking,
+      })),
+      services,
+      diagnostics: services.diagnostics,
+    };
+  };
+}

package/src/agent/contracts.ts

@@ -103,6 +103,16 @@ export const commandSchema = Type.Object({
 });
 export type Command = Static<typeof commandSchema>;
 export const successorSchema = Type.Object({ id: Type.String() });
+/** Authority to restore exact working state, valid only after the named actor has exited. */
+/** Exact parked authority: one exited generation's state bytes for this session and leaf. */
+export const parkedSchema = Type.Object({
+  token: Type.String(),
+  state: Type.String(),
+  digest: Type.String(),
+  sessionId: Type.String(),
+  leafId: Type.Union([Type.String(), Type.Null()]),
+});
+export type Parked = Static<typeof parkedSchema>;
 export const exitSchema = Type.Object({
   pid: Type.Integer(),
   code: Type.Union([Type.Integer(), Type.Null()]),

package/src/agent/host.ts

@@ -9,8 +9,28 @@ import { readIntercomLineage } from "../pi-intercom/identity.ts";
 
 export { errorMessage as errorText } from "../shared/unknown.ts";
 
-// The native resolver is optional until official Pi exports it at the package root.
-type HostSDK = typeof SDK & {
+/** Fork-only exact native working state; official Pi lacks it, so its children stay resident. */
+interface LocalWorkingState {
+  readonly header: { readonly id: string };
+  readonly sessionFile?: string;
+  readonly leafId: string | null;
+  readonly entries: readonly SDK.SessionEntry[];
+}
+type NativeWorkingState = typeof SDK extends { readWorkingSession: (file: string) => infer S }
+  ? S
+  : never;
+export type WorkingState = [NativeWorkingState] extends [never]
+  ? LocalWorkingState
+  : NativeWorkingState;
+// Working sessions stay optional even when the selected graph declares them, so both hosts
+// keep one checked path. The native resolver is optional until official Pi exports it.
+type HostSDK = Omit<
+  typeof SDK,
+  "readWorkingSession" | "writeWorkingSession" | "openWorkingSession"
+> & {
+  readWorkingSession?: (file: string) => WorkingState;
+  writeWorkingSession?: (file: string, state: WorkingState) => void;
+  openWorkingSession?: (state: WorkingState) => SDK.SessionManager;
   resolveModelReference?: (
     request: { text: string; provider: string; thinkingSuffix: "strict"; fuzzy: false },
     models: readonly Model<Api>[],

package/src/agent/index.ts

@@ -11,11 +11,13 @@ import {
   alive,
   ensureActor,
   ownIdentity,
+  parkFailure,
   requestStop,
   signalProcess,
   stopChildren,
 } from "./process.ts";
 import { isChild, errorText } from "./host.ts";
+import { serveParked } from "./parking.ts";
 import {
   resultSchema,
   attachmentSchema,
@@ -36,6 +38,7 @@ import {
   runDirectory,
   ownerDirectory,
   conversation,
+  successor,
   write,
 } from "./storage.ts";
 import { notifications, deliver, settle } from "./notifications.ts";
@@ -335,22 +338,6 @@ class AgentRuntime {
       .sort((a, b) => a.createdAt - b.createdAt);
     return renderInventory(this.base, all, this.ctx, input);
   }
-  private successor(launch: Launch, prompt: string): Launch | undefined {
-    const id = randomUUID();
-    const next: Launch = { ...launch, id, predecessor: launch.id, prompt, createdAt: Date.now() };
-    fs.mkdirSync(runDirectory(this.base, id), { mode: 0o700 });
-    write(path.join(runDirectory(this.base, id), "launch.json"), next, true);
-    try {
-      write(path.join(runDirectory(this.base, launch.id), "successor.json"), { id }, true);
-    } catch (error) {
-      fs.rmSync(runDirectory(this.base, id), { recursive: true });
-      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) {
-        throw error;
-      }
-      return undefined;
-    }
-    return next;
-  }
   private continuationResult(launch: Launch): Result | "pending" | undefined {
     const result = read(path.join(runDirectory(this.base, launch.id), "result.json"), resultSchema);
     if (result) {
@@ -406,7 +393,8 @@ class AgentRuntime {
         note: "Guidance queued, not actual completion or model consumption.",
       });
     }
-    const next = this.successor(launch, input.prompt);
+    parkFailure(this.base, launch);
+    const next = successor(this.base, launch, input.prompt);
     if (!next) {
       return renderReceipt(this.base, latest(this.base, launch), this.ctx, {
         receipt: "existing-successor",
@@ -465,6 +453,11 @@ class AgentRuntime {
   }
   register(): void {
     registerCompactMessages(this.pi, ["agent-completion", "subagent-notify"]);
+    serveParked(
+      this.pi,
+      () => (this.child || !this.ctx ? undefined : { base: this.base, owner: this.owner }),
+      this.shutdown.signal,
+    );
     this.pi.on("session_start", (_event, context) => this.start(context));
     this.pi.on("turn_end", (event, context) => {
       // The public pending flag covers user input; the preview also includes custom messages.

package/src/agent/observation.ts

@@ -168,6 +168,10 @@ export class ActorObservation {
     const { session } = this;
     return this.running || session.isStreaming || session.isCompacting || session.isRetrying;
   }
+  /** A live viewer keeps its actor resident; parking would end the native stream it reads. */
+  get watched(): boolean {
+    return this.viewers.size + this.greeting.size > 0;
+  }
   private details(): number {
     return [...this.viewers].filter((viewer) => viewer.level === "detail").length;
   }

package/src/agent/parking.ts

@@ -0,0 +1,341 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentSession, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { parkedSchema, type Launch, type Parked } from "./contracts.ts";
+import { errorText, loadSDK, type WorkingState } from "./host.ts";
+import { conversation, latest, launchAt, list, read, runDirectory, write } from "./storage.ts";
+import { alive, shells, wakeActor } from "./process.ts";
+import {
+  isHistoryRequest,
+  PARK,
+  PARKED_HISTORY,
+  WAKE,
+  type ParkRequest,
+} from "../shared/parking.ts";
+import { nativePeerId } from "../pi-intercom/session-targets.ts";
+import type { NativeHistory } from "../pi-intercom/last-message.ts";
+
+type SDK = Awaited<ReturnType<typeof loadSDK>>;
+type Restore = NonNullable<SDK["readWorkingSession"]>;
+export type Runtime = Awaited<ReturnType<SDK["createAgentSessionRuntime"]>>;
+type SessionManager = Parameters<SDK["createAgentSessionRuntime"]>[1]["sessionManager"];
+interface WorkingHold {
+  readonly state: WorkingState;
+  readonly sleepReady: boolean;
+  readonly blockers: readonly string[];
+  readonly assertHeld: () => void;
+  readonly release: () => Promise<void>;
+}
+/** Fork-only native cut and strict final exit; official Pi children stay resident. */
+type Parkable = AgentSession & {
+  readonly acquireWorkingSession: (options: {
+    boundary: "settled";
+    signal?: AbortSignal;
+  }) => Promise<WorkingHold>;
+};
+/** The runner's view of its own work; parking never admits or runs commands itself. */
+interface Resident {
+  readonly pi: ExtensionAPI | undefined;
+  readonly busy: boolean;
+  /**
+   * False once queued commands, work, stopping or a viewer appeared. Never admits: a prompt
+   * started under the native hold fails, so the runner admits only after release.
+   */
+  readonly quiet: () => boolean;
+  readonly errors: string[];
+  /** Aborts preparation once the owner stops or dies. */
+  readonly signal: AbortSignal;
+}
+interface Finalizing {
+  readonly setFinalization: (
+    finalization: (session: AgentSession) => Promise<void>,
+    options: { strictShutdown: boolean },
+  ) => void;
+}
+function parkable(session: AgentSession): session is Parkable {
+  return typeof Reflect.get(session, "acquireWorkingSession") === "function";
+}
+function finalizing(runtime: Runtime): runtime is Runtime & Finalizing {
+  return typeof Reflect.get(runtime, "setFinalization") === "function";
+}
+function fence(pi: ExtensionAPI, park: boolean): Promise<boolean> {
+  let fenced = Promise.resolve(false);
+  pi.events.emit(PARK, {
+    park,
+    reply: (parked) => {
+      fenced = parked;
+    },
+  } satisfies ParkRequest);
+  return fenced;
+}
+async function cut(
+  pi: ExtensionAPI,
+  session: Parkable,
+  { quiet, errors, signal }: Omit<Resident, "pi" | "busy">,
+): Promise<WorkingHold | undefined> {
+  try {
+    // Save handlers may legitimately append entries; only the pre-cut leaf proves idleness.
+    if ((await fence(pi, true)) && quiet() && session.isIdle) {
+      return await session.acquireWorkingSession({ boundary: "settled", signal });
+    }
+  } catch (error) {
+    errors.push(errorText(error));
+  }
+  return undefined;
+}
+const PARK_AFTER_MS = 5 * 60_000;
+const digest = (file: string): string =>
+  createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+/** Parked authority names this session and exactly the saved generation's state bytes. */
+function exact(
+  restore: Restore,
+  parked: Parked,
+  state: string,
+  launch: Launch,
+): WorkingState | undefined {
+  if (
+    parked.sessionId !== launch.sessionId ||
+    parked.state !== state ||
+    digest(state) !== parked.digest
+  ) {
+    return undefined;
+  }
+  const saved = restore(state);
+  return saved.sessionFile === launch.sessionFile &&
+    saved.header.id === launch.sessionId &&
+    saved.leafId === parked.leafId
+    ? saved
+    : undefined;
+}
+/** This child's exact parked generation, if any; mismatched authority restores nothing. */
+export function parkedState(
+  dir: string,
+  launch: Launch,
+  restore: Restore | undefined,
+): { readonly state: string; readonly saved: WorkingState } | undefined {
+  const parked = read(path.join(dir, "parked.json"), parkedSchema);
+  if (!parked) {
+    return undefined;
+  }
+  if (!restore) {
+    throw new Error("Parked working state needs the Pi fork that saved it; nothing was reopened.");
+  }
+  // Native working state requires a canonical parent, not a symlinked alias like macOS /var.
+  const state = path.join(fs.realpathSync(dir), `working-${parked.token}.json`);
+  const saved = exact(restore, parked, state, launch);
+  if (!saved) {
+    throw new Error(
+      "Parked working state is not this child's saved generation; nothing was reopened.",
+    );
+  }
+  return { state, saved };
+}
+/** One actor generation's idle parking and exact restore; commands stay with the runner. */
+export class Parking {
+  saved?: WorkingState;
+  private restored?: string;
+  private since = 0;
+  private leaf?: string | null;
+  private readonly base: string;
+  private readonly launch: Launch;
+  private readonly token: string;
+  private readonly sdk: SDK;
+  constructor(base: string, launch: Launch, token: string, sdk: SDK) {
+    this.base = base;
+    this.launch = launch;
+    this.token = token;
+    this.sdk = sdk;
+  }
+  private get dir(): string {
+    return runDirectory(this.base, this.launch.rootId);
+  }
+  private get file(): string {
+    return path.join(this.dir, "parked.json");
+  }
+  /** Parked authority is exact state or nothing; never a journal-only reopen. */
+  open(): SessionManager {
+    const { sdk, launch } = this;
+    const { openWorkingSession: restore } = sdk;
+    const parked = parkedState(this.dir, launch, restore && sdk.readWorkingSession);
+    if (!parked || !restore) {
+      return sdk.SessionManager.open(launch.sessionFile, undefined, launch.cwd);
+    }
+    this.saved = parked.saved;
+    this.restored = parked.state;
+    return restore(parked.saved);
+  }
+  /** The ready restored generation owns this state now; a later park writes a new cut. */
+  adopt(): void {
+    if (this.restored !== undefined) {
+      fs.rmSync(this.file);
+      fs.rmSync(this.restored, { force: true });
+    }
+  }
+  /** True once this generation has exited its runtime with or without parked authority. */
+  async park(runtime: Runtime, actor: Resident): Promise<boolean> {
+    if (
+      !actor.pi ||
+      !this.due(runtime.session, actor.busy) ||
+      shells(this.base, this.launch, this.token).some(alive)
+    ) {
+      return false;
+    }
+    const hold = await this.prepare(runtime, actor.pi, actor);
+    if (hold) {
+      await this.commit(runtime, hold, actor.errors);
+    }
+    return hold !== undefined;
+  }
+  /** Final idle: no run, turn, journal change or viewer since the period began. */
+  private due(session: AgentSession, busy: boolean): boolean {
+    const leaf = session.sessionManager.getLeafId();
+    if (busy || !session.isIdle || leaf !== this.leaf) {
+      this.leaf = leaf;
+      this.since = performance.now();
+      return false;
+    }
+    return performance.now() - this.since >= PARK_AFTER_MS;
+  }
+  /**
+   * Fence broker input, then hold a settled sleep-ready cut of the same quiet idle leaf. Any
+   * failure or raced command releases, unfences and keeps this actor resident.
+   */
+  private async prepare(
+    runtime: Runtime,
+    pi: ExtensionAPI,
+    { quiet, errors, signal }: Resident,
+  ): Promise<WorkingHold | undefined> {
+    const { session } = runtime;
+    this.since = performance.now();
+    if (!parkable(session) || !this.sdk.writeWorkingSession || !finalizing(runtime)) {
+      return undefined;
+    }
+    // A launcher that enqueues after this marker waits for exit, then wakes the saved state.
+    const marker = path.join(this.dir, "actor.lock", "parking.json");
+    write(marker, { at: Date.now() });
+    const hold = await cut(pi, session, {
+      quiet: () => quiet() && session.sessionManager.getLeafId() === this.leaf,
+      errors,
+      signal,
+    });
+    // Revalidate after the awaited fence and save, immediately before the irreversible commit.
+    if (hold?.sleepReady === true && quiet()) {
+      return hold;
+    }
+    await hold?.release();
+    await fence(pi, false);
+    fs.rmSync(marker, { force: true });
+    return undefined;
+  }
+  /** Commit: native strict exit, then capture; failure leaves no parked authority. */
+  private async commit(runtime: Runtime, hold: WorkingHold, errors: string[]): Promise<void> {
+    const save = this.sdk.writeWorkingSession;
+    if (save && finalizing(runtime)) {
+      runtime.setFinalization((final) => this.capture(final, save), { strictShutdown: true });
+    }
+    // No await between release and dispose: native final exit fences new turns in this tick.
+    const released = hold.release();
+    const disposed = runtime.dispose();
+    try {
+      await Promise.all([released, disposed]);
+    } catch (error) {
+      errors.push(errorText(error));
+    }
+    if (read(this.file, parkedSchema)?.token !== this.token) {
+      // Truthful boundary: retained input stays queued and nothing restarts implicitly.
+      write(path.join(this.dir, "park-failed.json"), { token: this.token, errors });
+    }
+  }
+  private async capture(
+    session: AgentSession,
+    save: (file: string, state: WorkingState) => void,
+  ): Promise<void> {
+    if (!parkable(session)) {
+      throw new Error("Native working state is unavailable.");
+    }
+    const hold = await session.acquireWorkingSession({ boundary: "settled" });
+    try {
+      if (!hold.sleepReady) {
+        throw new Error(`Final working state is not sleep-ready: ${hold.blockers.join("; ")}`);
+      }
+      const state = path.join(fs.realpathSync(this.dir), `working-${this.token}.json`);
+      save(state, hold.state);
+      hold.assertHeld();
+      write(this.file, {
+        token: this.token,
+        state,
+        digest: digest(state),
+        sessionId: this.launch.sessionId,
+        leafId: hold.state.leafId,
+      });
+    } finally {
+      await hold.release();
+    }
+  }
+}
+interface Runs {
+  readonly base: string;
+  readonly owner: string;
+}
+
+/** The broker names a parked child by native peer ID; only this owner's conversations match. */
+function ownedRun(runs: Runs | undefined, peer: unknown): Launch | undefined {
+  const launch =
+    runs && typeof peer === "string"
+      ? list(runs.base)
+          .map((id) => launchAt(runs.base, id, runs.owner))
+          .find((candidate) => nativePeerId(candidate.sessionId) === peer)
+      : undefined;
+  return launch && runs && latest(runs.base, launch);
+}
+
+/** The captured leaf's root-to-leaf path, as a live session manager reports it. */
+function branchOf(state: WorkingState): ReturnType<NativeHistory["getBranch"]> {
+  const entries = new Map(state.entries.map((entry) => [entry.id, entry]));
+  const branch = [];
+  for (
+    let entry = entries.get(state.leafId ?? "");
+    entry !== undefined;
+    entry = entries.get(entry.parentId ?? "")
+  ) {
+    branch.unshift(entry);
+  }
+  return branch;
+}
+async function history(runs: Runs | undefined, peer: string): Promise<NativeHistory | undefined> {
+  const launch = ownedRun(runs, peer);
+  const restore = launch && (await loadSDK(launch.sdk)).readWorkingSession;
+  const state =
+    runs && launch && parkedState(conversation(runs.base, launch), launch, restore)?.saved;
+  return state && { getBranch: () => branchOf(state) };
+}
+
+/**
+ * Wakes this owner's parked children for broker input and reads their saved history.
+ * `runs` is undefined while this session owns no children.
+ */
+export function serveParked(
+  pi: ExtensionAPI,
+  runs: () => Runs | undefined,
+  signal: AbortSignal,
+): void {
+  pi.events.on(WAKE, (peer) => {
+    // On failure, retained input stays queued at the broker until the next main registration.
+    (async () => {
+      const current = runs();
+      const launch = ownedRun(current, peer);
+      if (current && launch) {
+        await wakeActor(current.base, launch, signal);
+      }
+    })().catch((error: unknown) => {
+      console.error(`Agent wake: ${errorText(error)}`);
+    });
+  });
+  pi.events.on(PARKED_HISTORY, (request) => {
+    if (isHistoryRequest(request)) {
+      request.reply(history(runs(), request.peer));
+    }
+  });
+}