pi-sessions 0.14.3 → 0.15.0

package/README.md

@@ -110,6 +110,8 @@ The `session_handoff` tool lets the agent create a child session with a self-con
 
 Directional launches use tmux when the current terminal is inside tmux, or Ghostty on macOS. Deferred launches create the child without starting it and copy its resume command to the clipboard. A background subagent runs in a detached tmux window and reports back when finished; note that subagents are started with `--approve`, meaning pi will always start in the directory as trusted.
 
+When an external host registers, its name replaces all directional launch values, even inside tmux or Ghostty. Deferred and subagent launches remain available. External-host children start automatically without draft review; their resume commands also carry `--approve`.
+
 Run `/handoff` to open the **Handoffs** board. The Subagents and User sessions tabs show status, age, launch details, and the actions currently available: stop, copy an observation command, or copy a resume command.
 
 ## Session Messaging
@@ -120,7 +122,61 @@ Agents can coordinate with live Pi sessions and their own subagents:
 - `session_send_message` sends a message to a live session or own subagent
 - `session_cancel` aborts another live session's current turn
 
-Incoming messages start the recipient agent when idle and steer it when already running. Messaging a dormant owned subagent resumes it automatically; other inactive sessions cannot receive messages, but you can still use `session_search` and `session_ask` with them.
+Incoming messages start the recipient agent when idle and steer it when already running. Messaging a dormant owned subagent or a dormant session listed by a wake-capable host resumes it automatically. Hosted sessions appear in `session_reachable` with a `host` field and a broker-derived `live`, `starting`, or `dormant` state. Other inactive sessions cannot receive messages, but you can still use `session_search` and `session_ask` with them.
+
+## Host extension API (v1)
+
+A host controls where user-facing handoff children run. Built-in hosts launch tmux splits, Ghostty splits, or deferred resume commands. External extensions register over `pi.events`; neither extension imports the other.
+
+Install a listener during extension initialization, **not** in your `session_start` handler:
+
+```ts
+pi.events.on("pi-sessions:hosts:v1", (request) => {
+  const { register } = request as HostRegistrationRequest;
+  register({ name: "swb", launch, listSessions, wake });
+});
+```
+
+The structural types below are the public contract; copy them into your extension or define compatible types locally:
+
+```ts
+interface HostRegistrationRequest {
+  register(host: Host): void;
+}
+
+interface Host {
+  name: string;
+  launch(input: HostLaunchInput): Promise<HostLaunchResult>;
+  listSessions?(): Promise<HostSession[]>;
+  wake?(sessionId: string): Promise<void>;
+}
+
+interface HostLaunchInput {
+  sessionId: string;
+  sessionFile: string;
+  cwd: string;
+  title: string;
+  model: string;
+  resumeCommand: string;
+}
+
+type HostLaunchResult =
+  | { success: true; clipboardStatus?: "copied" | "failed" }
+  | { success: false; error: string };
+
+interface HostSession {
+  sessionId: string;
+  cwd: string;
+  title: string;
+}
+```
+
+- **Registration:** pi-sessions emits `pi-sessions:hosts:v1` at each `session_start`, including reloads and session switches. Call `register` synchronously, before returning or awaiting anything. Registration freezes when `emit` returns; late calls throw. Names must match `[a-z][a-z0-9-]*`, be unique, and cannot be `left`, `right`, `up`, `down`, `deferred`, `subagent`, `tmux`, or `ghostty`. Registration and callback results are validated with TypeBox. Multiple external hosts are offered in registration order; any external host suppresses all split targets. Without one, precedence remains tmux, then Ghostty, then deferred. Subagent availability still depends on tmux installation and delegation depth.
+- **Launch:** the child file, lineage, title, and automatic bootstrap are durable before `launch` runs. External-host children always use Pi's default session directory for `cwd`, even when the parent uses a custom directory. Start interactive Pi in that cwd with `--session-id`, `--approve`, and `--model` using the supplied `model` (including its thinking suffix, such as `provider/model:high`), or execute `resumeCommand`. Preserve the same Pi agent directory and load pi-sessions in the child. Do not inject a second initial prompt. Return `{ success: true }` after starting the process; return `{ success: false, error }` or throw on failure. The tool surfaces the surviving child's resume command on failure. `clipboardStatus` is used by the deferred host; external hosts normally omit it.
+- **Discovery:** `listSessions()` returns all open user-facing sessions this host can wake, whether running or dormant. Exclude closed sessions and subagents. It is called on demand by `session_reachable` and dormant-message routing, not polled in the background. Return unique session IDs; competing host ownership is an error. Hosts without both `listSessions` and `wake` do not contribute dormant reachability. `wake` without `listSessions` is invalid.
+- **Wake:** `wake(sessionId)` starts or resumes an owned session and resolves with no value; throw on failure. It must be idempotent across callers because different Pi processes can wake the same target concurrently. Within one sender, concurrent wakes are coalesced. After it resolves, pi-sessions waits **30 seconds** for broker registration before delivering. It retries wake/delivery once if the target disconnects before acceptance, but does not restart a host session on registration timeout. The broker alone supplies liveness; do not wait for broker readiness inside `wake`. Host callbacks have no imposed timeout: bound your own I/O. Built-in split launch commands use a 15-second timeout; subagent stale-window recovery retains two 30-second registration waits.
+
+Subagents are not hosts. They retain parent-owned tmux windows, automatic approval, their own ledger, and their own wake/recovery policy. `/handoff` remains a receipt board; it accepts external-host launch receipts but does not provide a separate launch picker or wake action.
 
 ## Session picker
 

package/extensions/hosts/contract.ts

@@ -0,0 +1,51 @@
+import { type Static, Type } from "typebox";
+
+export const HOSTS_CHANNEL = "pi-sessions:hosts:v1";
+
+export const HOST_LAUNCH_INPUT_SCHEMA = Type.Object({
+  sessionId: Type.String({ minLength: 1 }),
+  sessionFile: Type.String({ minLength: 1 }),
+  cwd: Type.String({ minLength: 1 }),
+  title: Type.String(),
+  model: Type.String({ minLength: 1 }),
+  resumeCommand: Type.String({ minLength: 1 }),
+});
+
+export const HOST_LAUNCH_RESULT_SCHEMA = Type.Union([
+  Type.Object({
+    success: Type.Literal(true),
+    clipboardStatus: Type.Optional(Type.Union([Type.Literal("copied"), Type.Literal("failed")])),
+  }),
+  Type.Object({ success: Type.Literal(false), error: Type.String() }),
+]);
+
+export const HOST_SESSION_SCHEMA = Type.Object({
+  sessionId: Type.String({ minLength: 1 }),
+  cwd: Type.String({ minLength: 1 }),
+  title: Type.String(),
+});
+
+export const HOST_SCHEMA = Type.Object({
+  name: Type.String({ pattern: "^[a-z][a-z0-9-]*$" }),
+  launch: Type.Function([HOST_LAUNCH_INPUT_SCHEMA], Type.Unknown()),
+  listSessions: Type.Optional(Type.Function([], Type.Unknown())),
+  wake: Type.Optional(Type.Function([Type.String()], Type.Unknown())),
+});
+
+export type HostLaunchInput = Static<typeof HOST_LAUNCH_INPUT_SCHEMA>;
+export type HostLaunchResult = Static<typeof HOST_LAUNCH_RESULT_SCHEMA>;
+export type HostSession = Static<typeof HOST_SESSION_SCHEMA>;
+export interface Host {
+  name: string;
+  launch(input: HostLaunchInput): Promise<HostLaunchResult>;
+  listSessions?(): Promise<HostSession[]>;
+  wake?(sessionId: string): Promise<void>;
+}
+
+export interface HostedSession extends HostSession {
+  host: string;
+}
+
+export interface HostRegistrationRequest {
+  register(host: Host): void;
+}

package/extensions/hosts/registry.ts

@@ -0,0 +1,129 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { parseTypeBoxValue } from "../shared/typebox.ts";
+import {
+  HOST_LAUNCH_RESULT_SCHEMA,
+  HOST_SCHEMA,
+  HOST_SESSION_SCHEMA,
+  HOSTS_CHANNEL,
+  type Host,
+  type HostedSession,
+  type HostLaunchInput,
+} from "./contract.ts";
+
+const RESERVED_NAMES = new Set([
+  "left",
+  "right",
+  "up",
+  "down",
+  "deferred",
+  "subagent",
+  "tmux",
+  "ghostty",
+]);
+
+export class HostRegistry {
+  private hosts: readonly Host[] = [];
+
+  discover(events: ExtensionAPI["events"]): void {
+    const hosts: Host[] = [];
+    let frozen = false;
+    let registrationError: unknown;
+    this.hosts = [];
+    try {
+      events.emit(HOSTS_CHANNEL, {
+        register(value: unknown) {
+          if (frozen) throw new Error("Host registration is closed.");
+          try {
+            const host = parseTypeBoxValue(HOST_SCHEMA, value, "Invalid host");
+            if (RESERVED_NAMES.has(host.name) || hosts.some((entry) => entry.name === host.name)) {
+              throw new Error(`Host name is reserved or already registered: ${host.name}`);
+            }
+            if (host.wake && !host.listSessions) {
+              throw new Error(`Host ${host.name}: wake requires listSessions.`);
+            }
+            const name = host.name;
+            const launch = host.launch.bind(host);
+            const listSessions = host.listSessions?.bind(host);
+            const wake = host.wake?.bind(host);
+            hosts.push(
+              Object.freeze({
+                name,
+                async launch(input: HostLaunchInput) {
+                  return parseTypeBoxValue(
+                    HOST_LAUNCH_RESULT_SCHEMA,
+                    await launch(input),
+                    `Host ${name} launch result`,
+                  );
+                },
+                ...(listSessions
+                  ? {
+                      listSessions: async () =>
+                        parseTypeBoxValue(
+                          Type.Array(HOST_SESSION_SCHEMA),
+                          await listSessions(),
+                          `Host ${name} sessions`,
+                        ),
+                    }
+                  : {}),
+                ...(wake
+                  ? {
+                      async wake(target: string) {
+                        parseTypeBoxValue(
+                          Type.Void(),
+                          await wake(target),
+                          `Host ${name} wake result`,
+                        );
+                      },
+                    }
+                  : {}),
+              }),
+            );
+          } catch (error) {
+            registrationError = error;
+            throw error;
+          }
+        },
+      });
+    } finally {
+      frozen = true;
+    }
+    // Pi logs listener errors instead of propagating them through emit.
+    if (registrationError) throw registrationError;
+    this.hosts = Object.freeze(hosts);
+  }
+
+  getHosts(): readonly Host[] {
+    return this.hosts;
+  }
+
+  async listSessions(): Promise<HostedSession[]> {
+    const sessions = await Promise.all(
+      this.hosts.map(async (host) => {
+        if (!host.wake || !host.listSessions) return [];
+        return (await host.listSessions()).map((session) => ({ ...session, host: host.name }));
+      }),
+    );
+    const result = sessions.flat();
+    const ids = new Set<string>();
+    for (const session of result) {
+      if (ids.has(session.sessionId))
+        throw new Error(`Multiple hosts claim session ${session.sessionId}.`);
+      ids.add(session.sessionId);
+    }
+    return result;
+  }
+
+  async owns(target: string): Promise<boolean> {
+    return (await this.listSessions()).some((session) => session.sessionId === target);
+  }
+
+  async wake(target: string): Promise<void> {
+    const hosts = this.hosts;
+    const session = (await this.listSessions()).find((session) => session.sessionId === target);
+    if (this.hosts !== hosts) throw new Error("The host registry changed while waking a session.");
+    const host = hosts.find((host) => host.name === session?.host);
+    if (!host?.wake) throw new Error(`No host can wake session ${target}.`);
+    await host.wake(target);
+  }
+}

package/extensions/pi-sessions.ts

@@ -3,12 +3,14 @@ import {
   type ModelRuntime,
   SessionManager,
 } from "@earendil-works/pi-coding-agent";
+import { HostRegistry } from "./hosts/registry.ts";
 import { installAsk } from "./session-ask/install.ts";
 import { installAutoTitle } from "./session-auto-title/install.ts";
 import { installHandoff } from "./session-handoff/install.ts";
 import { installHooks } from "./session-hooks/install.ts";
 import { installIndex } from "./session-index/install.ts";
 import { installMessaging } from "./session-messaging/install.ts";
+import { MessageRouter, type SessionWaker } from "./session-messaging/message-router.ts";
 import { createSessionReachableTool } from "./session-messaging/pi/reachable-tool.ts";
 import {
   createSessionCancelTool,
@@ -30,6 +32,7 @@ import { installSubagents } from "./subagents/install.ts";
 export default function piSessions(pi: ExtensionAPI): void {
   const settings = loadSettings();
   let sessionEpoch = 0;
+  const hosts = new HostRegistry();
 
   // The mirrored ModelRuntime is expensive to build and only changes across session
   // boundaries, so cache it per epoch (the root's own invalidation signal) instead of
@@ -54,31 +57,52 @@ export default function piSessions(pi: ExtensionAPI): void {
   if (messaging) {
     lifecycles.push(messaging);
   }
+  const wakers: SessionWaker[] = [hosts];
+  const messageRouter = messaging
+    ? new MessageRouter(messaging, wakers, () => sessionEpoch)
+    : undefined;
   const subagents =
-    settings.features.subagents && messaging
-      ? installSubagents(pi, { settings, messaging, readCompactionSettings })
+    settings.features.subagents && messaging && messageRouter
+      ? installSubagents(pi, {
+          settings,
+          messaging,
+          readCompactionSettings,
+          sendMessage: (request) => messageRouter.sendMessage(request),
+          hasHostedSessions: () => hosts.getHosts().some((host) => Boolean(host.wake)),
+        })
       : undefined;
   if (subagents) {
+    wakers.unshift(subagents.waker);
     lifecycles.push(subagents);
   }
-  if (messaging) {
+  const registerMessagingTools = (): void => {
+    if (!messaging || !messageRouter) return;
+    const isSubagent = subagents?.getParentSessionId() !== undefined;
+    const hostedSessions = hosts.getHosts().some((host) => Boolean(host.wake));
     pi.registerTool(
-      createSessionSendMessageTool(subagents ?? messaging, {
-        role: subagents ? { kind: "wakeCapable" } : { kind: "plain" },
+      createSessionSendMessageTool(messageRouter, {
+        role: isSubagent
+          ? { kind: "subagent" }
+          : subagents
+            ? { kind: "wakeCapable" }
+            : { kind: "plain" },
+        hostedSessions,
         getCachedRelationTo: messaging.getCachedRelationTo,
         ...(subagents ? { getParentSessionId: () => subagents.getParentSessionId() } : {}),
       }),
     );
     pi.registerTool(
       createSessionCancelTool(subagents ?? messaging, {
-        role: { kind: "plain" },
+        role: isSubagent ? { kind: "subagent" } : { kind: "plain" },
         ...(subagents ? { getParentSessionId: () => subagents.getParentSessionId() } : {}),
       }),
     );
     pi.registerTool(
       createSessionReachableTool({
         indexPath: index.path,
+        hostedSessions,
         listSessions: () => messaging.listSessions(),
+        listHostedSessions: () => hosts.listSessions(),
         getRelationTo: messaging.getCachedRelationTo,
         ...(subagents
           ? {
@@ -88,7 +112,8 @@ export default function piSessions(pi: ExtensionAPI): void {
           : {}),
       }),
     );
-  }
+  };
+  registerMessagingTools();
   if (settings.features.handoff) {
     const board = {
       roster: subagents?.roster,
@@ -103,6 +128,7 @@ export default function piSessions(pi: ExtensionAPI): void {
         settings,
         index,
         getModelRuntime,
+        getHosts: () => hosts.getHosts(),
         ...(subagents ? { getLaunchTargets: () => subagents.getLaunchTargets() } : {}),
         board,
       }),
@@ -139,9 +165,11 @@ export default function piSessions(pi: ExtensionAPI): void {
   // this ordering is intentional — do not reorder to "fix" it.
   pi.on("session_start", async (event, ctx) => {
     sessionEpoch += 1;
+    hosts.discover(pi.events);
     for (const lifecycle of lifecycles) {
       await lifecycle.onSessionStart?.(event, ctx);
     }
+    registerMessagingTools();
     for (const lifecycle of lifecycles) {
       lifecycle.onSessionReady?.(ctx);
     }

package/extensions/session-handoff/install.ts

@@ -2,6 +2,7 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import type { Host } from "../hosts/contract.ts";
 import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
 import type { ModelRuntimeProvider } from "../shared/model-runtime.ts";
 import { isTuiMode } from "../shared/pi-mode.ts";
@@ -46,6 +47,7 @@ export function installHandoff(
     index: IndexHandle;
     getModelRuntime: ModelRuntimeProvider;
     getLaunchTargets?: (() => readonly HandoffLaunchTarget[]) | undefined;
+    getHosts?: () => readonly Host[];
     board: HandoffBoardServices;
   },
 ): SessionLifecycle {
@@ -197,7 +199,7 @@ export function installHandoff(
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
-    if (splitBackend?.identifyTerminalId && ctx) {
+    if (!deps.getHosts?.().length && splitBackend?.identifyTerminalId && ctx) {
       identifiedGhosttyTerminalId =
         (await splitBackend.identifyTerminalId(ctx.cwd)) ?? identifiedGhosttyTerminalId;
     }
@@ -215,6 +217,7 @@ export function installHandoff(
           splitBackend,
           copyDeferredToClipboard: settings.handoff.deferred.copyToClipboard,
           additionalTargets: deps.getLaunchTargets?.() ?? [],
+          hosts: deps.getHosts?.() ?? [],
         }),
         resolveHandoffRoster({
           models,

package/extensions/session-handoff/launch/backend.ts

@@ -1,16 +1,9 @@
-import type { HandoffLaunchTargetOutcome } from "../launch-target.ts";
+import type { Host, HostLaunchInput } from "../../hosts/contract.ts";
 
 export type HandoffSplitDirection = "left" | "right" | "up" | "down";
 
-export interface LaunchInput {
-  cwd: string;
-  title: string;
-  resumeCommand: string;
-}
+export type LaunchInput = HostLaunchInput;
 
 export type ClipboardStatus = "copied" | "failed";
 
-export interface LaunchBackend {
-  name: string;
-  launch(input: LaunchInput): Promise<HandoffLaunchTargetOutcome>;
-}
+export type LaunchBackend = Host;

package/extensions/session-handoff/launch-options.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Host } from "../hosts/contract.ts";
 import { createDeferredLaunchBackend } from "./launch/deferred.ts";
 import type { SplitLaunchBackend } from "./launch/resolution.ts";
 import {
@@ -19,8 +20,10 @@ export function createHandoffLaunchTargets(options: {
   splitBackend: SplitLaunchBackend | undefined;
   copyDeferredToClipboard: boolean;
   additionalTargets: readonly HandoffLaunchTarget[];
+  hosts?: readonly Host[];
 }): HandoffLaunchTarget[] {
-  const splitBackend = options.splitBackend;
+  const hosts = options.hosts ?? [];
+  const splitBackend = hosts.length ? undefined : options.splitBackend;
   const splitTargets = splitBackend
     ? LAUNCH_DIRECTIONS.map((direction, index) =>
         createBackendLaunchTarget(
@@ -37,7 +40,19 @@ export function createHandoffLaunchTargets(options: {
     createDeferredLaunchBackend({ copyToClipboard: options.copyDeferredToClipboard }),
     "'deferred' creates the session and returns its resume command without opening anything.",
   );
-  return [...splitTargets, deferred, ...options.additionalTargets];
+  return [
+    ...hosts.map((host) =>
+      createBackendLaunchTarget(
+        host.name,
+        host,
+        `'${host.name}' opens a session in ${host.name}.`,
+        true,
+      ),
+    ),
+    ...splitTargets,
+    deferred,
+    ...options.additionalTargets,
+  ];
 }
 
 export function resolveHandoffLaunchTarget(

package/extensions/session-handoff/launch-target.ts

@@ -1,6 +1,8 @@
 import type { SessionManager } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
-import type { ClipboardStatus, HandoffSplitDirection, LaunchBackend } from "./launch/backend.ts";
+import type { Host } from "../hosts/contract.ts";
+import { formatError } from "../shared/errors.ts";
+import type { ClipboardStatus } from "./launch/backend.ts";
 import type { HandoffSubagent } from "./metadata.ts";
 import type { PreparedHandoff } from "./spawn.ts";
 
@@ -15,10 +17,9 @@ export const HANDOFF_DIRECTION_LAUNCH_SCHEMA = Type.Union([
   Type.Literal("down"),
 ]);
 
-export const HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA = Type.Union([
-  HANDOFF_DIRECTION_LAUNCH_SCHEMA,
-  Type.Literal(DEFERRED_LAUNCH),
-]);
+export const HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA = Type.String({
+  pattern: "^(?!subagent$)[a-z][a-z0-9-]*$",
+});
 
 export const HANDOFF_LAUNCH_VALUE_SCHEMA = Type.Union([
   HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA,
@@ -49,7 +50,7 @@ export type HandoffLaunchTargetOutcome =
   | {
       success: true;
       backend: string;
-      clipboardStatus?: ClipboardStatus | undefined;
+      clipboardStatus?: ClipboardStatus;
     }
   | { success: false; error: string };
 
@@ -61,6 +62,7 @@ export interface HandoffLaunchTarget {
   bootstrapMode: "review" | "automatic";
   /** Unattended children skip the startup trust prompt; watched ones let the user answer it. */
   approveProjectTrust: boolean;
+  useDefaultSessionDir?: boolean;
   /** Subagent launches stamp their child's identity into the child bootstrap. */
   describeSubagentChild?(input: {
     childSessionId: string;
@@ -72,23 +74,33 @@ export interface HandoffLaunchTarget {
 }
 
 export function createBackendLaunchTarget(
-  value: HandoffSplitDirection | "deferred",
-  backend: LaunchBackend,
+  value: string,
+  host: Host,
   description?: string | undefined,
+  external = false,
 ): HandoffLaunchTarget {
   return {
     value,
     ...(description ? { description } : {}),
     requestResponseDefault: false,
-    bootstrapMode: "review",
-    approveProjectTrust: false,
+    bootstrapMode: external ? "automatic" : "review",
+    approveProjectTrust: external,
+    useDefaultSessionDir: external,
     prepareChild() {},
-    launch(input) {
-      return backend.launch({
-        cwd: input.cwd,
-        title: input.title,
-        resumeCommand: input.prepared.resumeCommand,
-      });
+    async launch(input) {
+      try {
+        const result = await host.launch({
+          sessionId: input.prepared.sessionId,
+          sessionFile: input.prepared.sessionFile,
+          cwd: input.cwd,
+          title: input.title,
+          model: input.model,
+          resumeCommand: input.prepared.resumeCommand,
+        });
+        return result.success ? { ...result, backend: host.name } : result;
+      } catch (error) {
+        return { success: false, error: formatError(error) };
+      }
     },
   };
 }

package/extensions/session-handoff/spawn.ts

@@ -22,6 +22,7 @@ export function prepareHandoffLaunch(options: {
   title: string;
   model: string | undefined;
   approveProjectTrust: boolean;
+  useDefaultSessionDir?: boolean;
   buildBootstrap: (sessionId: string) => HandoffBootstrap;
   prepareChild?: ((manager: SessionManager, sessionId: string) => void) | undefined;
 }): PreparedHandoff {
@@ -31,7 +32,7 @@ export function prepareHandoffLaunch(options: {
   const sameCwd = options.targetCwd === options.parentCwd;
   const manager = SessionManager.create(
     options.targetCwd,
-    sameCwd ? options.parentSessionDir : undefined,
+    sameCwd && !options.useDefaultSessionDir ? options.parentSessionDir : undefined,
     { parentSession: options.parentSessionFile },
   );
   manager.appendSessionInfo(options.title);

package/extensions/session-handoff/tool-schema.ts

@@ -1,6 +1,6 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { type HandoffLaunchTarget, SUBAGENT_LAUNCH } from "./launch-target.ts";
+import { type HandoffLaunchTarget, LAUNCH_DIRECTIONS, SUBAGENT_LAUNCH } from "./launch-target.ts";
 import { formatRosterEntry, type HandoffRoster } from "./roster.ts";
 
 export function buildHandoffLaunchSchema(targets: readonly HandoffLaunchTarget[]) {
@@ -46,11 +46,19 @@ export function buildHandoffPromptGuidelines(
   roster: HandoffRoster | undefined,
 ): string[] {
   const hasSubagent = targets.some((target) => target.value === SUBAGENT_LAUNCH);
+  const hasHost = targets.some(
+    (target) =>
+      target.value !== "subagent" &&
+      target.value !== "deferred" &&
+      !LAUNCH_DIRECTIONS.some((direction) => direction === target.value),
+  );
   const selectable =
     roster?.map(formatRosterEntry) ?? models.map((model) => `${model.provider}/${model.id}`);
   return [
     ...(hasSubagent ? SUBAGENT_GUIDELINES : []),
-    LAUNCH_TARGET_GUIDELINE,
+    hasHost
+      ? "Use session_handoff host or deferred launches only when the user requests one."
+      : LAUNCH_TARGET_GUIDELINE,
     ...MODEL_INHERITANCE_GUIDELINES,
     hasSubagent ? SUBAGENT_MODEL_OVERRIDE_GUIDELINE : DEFAULT_MODEL_OVERRIDE_GUIDELINE,
     ...(selectable.length > 0

package/extensions/session-handoff/tool.ts

@@ -108,6 +108,7 @@ export async function executeSessionHandoffTool(
     title,
     model,
     approveProjectTrust: target.approveProjectTrust,
+    useDefaultSessionDir: target.useDefaultSessionDir ?? false,
     buildBootstrap: (sessionId) =>
       createChildGeneratedHandoffBootstrap({
         sessionId,

package/extensions/session-messaging/message-router.ts

@@ -0,0 +1,91 @@
+import type { SendMessageRequest, SendMessageResult } from "./install.ts";
+
+export interface SessionWaker {
+  owns(target: string): boolean | Promise<boolean>;
+  wake(target: string): Promise<void>;
+  restart?(target: string): Promise<void>;
+  afterSend?(): Promise<void> | void;
+}
+
+export interface WakeMessaging {
+  sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
+  listSessions(): Promise<string[]>;
+  waitForSession(sessionId: string, timeoutMs: number): Promise<boolean>;
+}
+
+export class MessageRouter {
+  private readonly waking = new Map<string, Promise<void>>();
+
+  constructor(
+    private readonly messaging: WakeMessaging,
+    private readonly wakers: readonly SessionWaker[],
+    private readonly getEpoch: () => number,
+    private readonly readyTimeoutMs = 30_000,
+  ) {}
+
+  async sendMessage(request: SendMessageRequest): Promise<SendMessageResult> {
+    const epoch = this.getEpoch();
+    let failedLiveSend: SendMessageResult | undefined;
+    if (await this.isLive(request.target)) {
+      this.requireCurrent(epoch);
+      const result = await this.messaging.sendMessage(request);
+      if (!isTargetDeparture(result)) return result;
+      failedLiveSend = result;
+    }
+    let owner: SessionWaker | undefined;
+    for (const waker of this.wakers) {
+      if (await waker.owns(request.target)) {
+        owner = waker;
+        break;
+      }
+    }
+    this.requireCurrent(epoch);
+    if (!owner) return failedLiveSend ?? this.messaging.sendMessage(request);
+
+    try {
+      for (let attempt = 0; ; attempt += 1) {
+        await this.wake(request.target, owner, epoch);
+        this.requireCurrent(epoch);
+        const result = await this.messaging.sendMessage(request);
+        if (attempt === 1 || !isTargetDeparture(result)) return result;
+      }
+    } finally {
+      if (epoch === this.getEpoch()) await owner.afterSend?.();
+    }
+  }
+
+  private wake(target: string, waker: SessionWaker, epoch: number): Promise<void> {
+    const key = `${epoch}:${target}`;
+    const existing = this.waking.get(key);
+    if (existing) return existing;
+    const wake = this.ensureReady(target, waker, epoch).finally(() => this.waking.delete(key));
+    this.waking.set(key, wake);
+    return wake;
+  }
+
+  private async ensureReady(target: string, waker: SessionWaker, epoch: number): Promise<void> {
+    if (await this.isLive(target)) return;
+    this.requireCurrent(epoch);
+    await waker.wake(target);
+    if (await this.messaging.waitForSession(target, this.readyTimeoutMs)) return;
+    this.requireCurrent(epoch);
+    if (waker.restart) {
+      await waker.restart(target);
+      if (await this.messaging.waitForSession(target, this.readyTimeoutMs)) return;
+    }
+    throw new Error(`Session ${target} did not register for messaging.`);
+  }
+
+  private async isLive(target: string): Promise<boolean> {
+    return (await this.messaging.listSessions()).includes(target);
+  }
+
+  private requireCurrent(epoch: number): void {
+    if (epoch !== this.getEpoch())
+      throw new Error("The current session changed while waking a session.");
+  }
+}
+
+function isTargetDeparture(result: SendMessageResult): boolean {
+  return !result.delivered && (result.reason === "no_session" || result.reason === "disconnected");
+}

package/extensions/session-messaging/pi/reachable-contract.ts

@@ -26,7 +26,8 @@ const REACHABLE_USER_SESSION_SCHEMA = Type.Object({
   cwd: Type.Optional(Type.String()),
   modifiedAt: Type.Optional(Type.String()),
   relation: Type.Optional(Type.String()),
-  state: Type.Union([Type.Literal("live"), Type.Literal("starting")]),
+  host: Type.Optional(Type.String()),
+  state: Type.Union([Type.Literal("live"), Type.Literal("starting"), Type.Literal("dormant")]),
 });
 
 const REACHABLE_SUBAGENT_SCHEMA = Type.Object({

package/extensions/session-messaging/pi/reachable-tool.ts

@@ -5,6 +5,7 @@ import {
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import type { HostedSession } from "../../hosts/contract.ts";
 import { isSessionStarting } from "../../session-handoff/metadata.ts";
 import { formatError } from "../../shared/errors.ts";
 import { ExpandableContentLayout } from "../../shared/rendering/expandable-content-layout.ts";
@@ -46,7 +47,9 @@ export interface ReachableSubagentEntry {
 
 export interface SessionReachableDeps {
   indexPath: string;
+  hostedSessions?: boolean;
   listSessions(): Promise<string[]>;
+  listHostedSessions?: () => Promise<HostedSession[]>;
   getRelationTo(sessionId: string): string | undefined;
   listSubagents?:
     | ((
@@ -75,6 +78,11 @@ export function createSessionReachableTool(deps: SessionReachableDeps): ToolDefi
       : "List addressable live sessions",
     promptGuidelines: [
       "Before session_send_message, use session_reachable to find the target session id.",
+      ...(deps.hostedSessions
+        ? [
+            "User sessions include dormant hosted sessions. session_send_message wakes them automatically; the host field identifies their host.",
+          ]
+        : []),
     ],
     annotations: { readOnlyHint: true, openWorldHint: false },
     parameters: subagentsAvailable ? SESSION_REACHABLE_PARAMS : SESSION_REACHABLE_USER_PARAMS,
@@ -129,7 +137,11 @@ async function listReachableUserSessions(
   }
 
   const parentSessionId = deps.getParentSessionId?.();
-  const targetIds = liveSessionIds.filter(
+  const hostedSessions = new Map(
+    ((await deps.listHostedSessions?.()) ?? []).map((session) => [session.sessionId, session]),
+  );
+  const liveIds = new Set(liveSessionIds);
+  const targetIds = [...new Set([...liveSessionIds, ...hostedSessions.keys()])].filter(
     (sessionId) => sessionId !== currentSessionId && sessionId !== parentSessionId,
   );
   return withSessionIndex(deps.indexPath, { mode: "read", required: true }, ({ db }) => {
@@ -140,12 +152,20 @@ async function listReachableUserSessions(
         continue;
       }
       const relation = deps.getRelationTo(sessionId);
+      const hosted = hostedSessions.get(sessionId);
+      const title = hosted?.title ?? row?.sessionName;
+      const cwd = hosted?.cwd ?? row?.cwd;
       sessions.push({
         kind: "user",
         sessionId,
-        state: row && isStartingSession(row) ? "starting" : "live",
-        ...(row?.sessionName ? { title: row.sessionName } : {}),
-        ...(row?.cwd ? { cwd: row.cwd } : {}),
+        state: !liveIds.has(sessionId)
+          ? "dormant"
+          : row && isStartingSession(row)
+            ? "starting"
+            : "live",
+        ...(hosted ? { host: hosted.host } : {}),
+        ...(title ? { title } : {}),
+        ...(cwd ? { cwd } : {}),
         ...(row?.modifiedAt ? { modifiedAt: row.modifiedAt } : {}),
         ...(relation === undefined ? {} : { relation }),
       });

package/extensions/session-messaging/pi/tools.ts

@@ -53,6 +53,7 @@ export type SessionSendMessageRole =
 
 export interface SessionSendMessageToolOptions {
   role: SessionSendMessageRole;
+  hostedSessions?: boolean;
   getCachedRelationTo(sessionId: string | undefined): string | undefined;
   /**
    * Resolved on every call: subagent identity depends on the active branch, so a rewind can
@@ -119,7 +120,14 @@ export function createSessionSendMessageTool(
     label: "Send Message to Session",
     description,
     promptSnippet,
-    promptGuidelines,
+    promptGuidelines: [
+      ...promptGuidelines,
+      ...(options.hostedSessions
+        ? [
+            "session_reachable also lists dormant hosted sessions; sending a message wakes them automatically.",
+          ]
+        : []),
+    ],
     parameters: SEND_MESSAGE_PARAMS,
     renderCall(args, theme, context) {
       const state = context.state as SendMessageRendererState;

package/extensions/subagents/install.ts

@@ -9,6 +9,7 @@ import type {
   SendMessageRequest,
   SendMessageResult,
 } from "../session-messaging/install.ts";
+import type { SessionWaker } from "../session-messaging/message-router.ts";
 import {
   createSessionCancelTool,
   createSessionSendMessageTool,
@@ -43,7 +44,7 @@ import {
   type SubagentChildSessionState,
 } from "./settle.ts";
 import { shouldMessageSubagent } from "./should-message.ts";
-import { SubagentMessageRouter } from "./wake.ts";
+import { SubagentWaker } from "./wake.ts";
 
 const SUBAGENT_PROMPT_SECTION = "pi_sessions_subagent";
 const SUBAGENT_PROMPT = `You are working as a subagent on one task delegated by a parent session. The handoff defines your task. Work independently, stay within its scope, and do not duplicate work assigned to the parent or another subagent. Use the available tools to complete the task and validate your conclusions. Messages from the parent may refine the task or request a follow-up, but they do not replace your original task with unrelated work.`;
@@ -65,6 +66,7 @@ interface CurrentSubagentSession {
 
 export interface SubagentsHandle extends SessionLifecycle {
   roster: SubagentRoster;
+  waker: SessionWaker;
   getLaunchTargets(): readonly HandoffLaunchTarget[];
   sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
   cancelSession(sessionId: string): Promise<SubagentCancelResult>;
@@ -79,6 +81,8 @@ export function installSubagents(
     settings: SessionSettings;
     messaging: MessagingHandle;
     readCompactionSettings: (cwd: string) => CompactionThresholdSettings;
+    sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
+    hasHostedSessions?: () => boolean;
   },
 ): SubagentsHandle {
   pi.registerMessageRenderer(SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE, renderSubagentReportMessage);
@@ -107,18 +111,12 @@ export function installSubagents(
     reconcile: () => reconciler.reconcile(),
     openSession: openRosterSession,
   });
-  const messageRouter = new SubagentMessageRouter(
-    pi,
-    deps.messaging,
-    () => current?.parent,
-    isCurrentSession,
-    {
-      onMaterialize: (launch) => pi.appendEntry(SUBAGENT_LAUNCHED_CUSTOM_TYPE, launch),
-      afterOwnedSend: async () => {
-        await reconciler.reconcile();
-      },
+  const waker = new SubagentWaker(pi, deps.messaging, () => current?.parent, isCurrentSession, {
+    onMaterialize: (launch) => pi.appendEntry(SUBAGENT_LAUNCHED_CUSTOM_TYPE, launch),
+    afterSend: async () => {
+      await reconciler.reconcile();
     },
-  );
+  });
   const cancellationRouter = new SubagentCancellationRouter(
     pi,
     deps.messaging,
@@ -232,6 +230,7 @@ export function installSubagents(
     pi.registerTool(
       createSessionSendMessageTool(handle, {
         role: isSubagent ? { kind: "subagent" } : { kind: "wakeCapable" },
+        hostedSessions: deps.hasHostedSessions?.() ?? false,
         getCachedRelationTo: deps.messaging.getCachedRelationTo,
         getParentSessionId: () => handle.getParentSessionId(),
       }),
@@ -257,7 +256,8 @@ export function installSubagents(
 
   const handle: SubagentsHandle = {
     roster,
-    sendMessage: (request) => messageRouter.sendMessage(request),
+    waker,
+    sendMessage: deps.sendMessage,
     cancelSession: (sessionId) => cancellationRouter.cancelSession(sessionId),
     shouldMessageSubagent: (sessionId) =>
       shouldMessageSubagent(sessionId, {

package/extensions/subagents/settle.ts

@@ -170,7 +170,7 @@ export function findSelfSubagentIdentity(
   if (
     bootstrap?.launch !== SUBAGENT_LAUNCH ||
     bootstrap.sessionId !== sessionId ||
-    bootstrap.subagent.childSessionId !== sessionId
+    bootstrap.subagent?.childSessionId !== sessionId
   ) {
     return undefined;
   }

package/extensions/subagents/wake.ts

@@ -1,5 +1,5 @@
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
-import type { SendMessageRequest, SendMessageResult } from "../session-messaging/install.ts";
+import type { SessionWaker, WakeMessaging } from "../session-messaging/message-router.ts";
 import {
   createTmuxWindow,
   killTmuxWindow,
@@ -9,125 +9,60 @@ import {
 } from "../shared/tmux.ts";
 import { findOwnedSubagentLaunch, type SubagentLaunched } from "./ledger.ts";
 
-const SESSION_READY_TIMEOUT_MS = 30_000;
-
 export interface WakeParentSession {
   sessionId: string;
   epoch: number;
   getBranch(): readonly SessionEntry[];
 }
 
-interface WakeMessaging {
-  sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
-  listSessions(): Promise<string[]>;
-  waitForSession(sessionId: string, timeoutMs: number): Promise<boolean>;
-}
-
-export interface SubagentMessageRouterOptions {
-  readyTimeoutMs?: number;
-  onMaterialize?(launch: SubagentLaunched): void;
-  afterOwnedSend?(): Promise<void> | void;
-}
-
-export class SubagentMessageRouter {
-  private readonly wakeBySessionId = new Map<string, Promise<void>>();
-
+export class SubagentWaker implements SessionWaker {
   constructor(
     private readonly executor: TmuxExecutor,
     private readonly messaging: WakeMessaging,
     private readonly getParent: () => WakeParentSession | undefined,
     private readonly isCurrent: (epoch: number) => boolean,
-    private readonly options: SubagentMessageRouterOptions = {},
+    private readonly options: {
+      onMaterialize?(launch: SubagentLaunched): void;
+      afterSend?(): Promise<void> | void;
+    } = {},
   ) {}
 
-  async sendMessage(request: SendMessageRequest): Promise<SendMessageResult> {
-    let failedLiveSend: SendMessageResult | undefined;
-    if (await this.isLive(request.target)) {
-      const result = await this.messaging.sendMessage(request);
-      if (result.delivered || !isTargetDeparture(result)) {
-        return result;
-      }
-      failedLiveSend = result;
-    }
-
+  owns(target: string): boolean {
     const parent = this.getParent();
-    const launch = parent
-      ? findOwnedSubagentLaunch(parent.getBranch(), parent.sessionId, request.target)
-      : undefined;
-    if (!parent || !launch) {
-      return failedLiveSend ?? this.messaging.sendMessage(request);
-    }
-
-    try {
-      await this.wake(parent, launch);
-      const result = await this.sendOwned(parent, request);
-      if (result.delivered || !isTargetDeparture(result)) {
-        return result;
-      }
-
-      await this.wake(parent, launch);
-      return this.sendOwned(parent, request);
-    } finally {
-      await this.options.afterOwnedSend?.();
-    }
+    return Boolean(parent && findOwnedSubagentLaunch(parent.getBranch(), parent.sessionId, target));
   }
 
-  private async wake(parent: WakeParentSession, launch: SubagentLaunched): Promise<void> {
-    const existing = this.wakeBySessionId.get(launch.childSessionId);
-    if (existing) {
-      return existing;
-    }
-
-    const wake = this.ensureReady(parent, launch).finally(() => {
-      if (this.wakeBySessionId.get(launch.childSessionId) === wake) {
-        this.wakeBySessionId.delete(launch.childSessionId);
-      }
-    });
-    this.wakeBySessionId.set(launch.childSessionId, wake);
-    return wake;
-  }
-
-  private async ensureReady(parent: WakeParentSession, launch: SubagentLaunched): Promise<void> {
-    if (await this.isLive(launch.childSessionId)) {
-      return;
-    }
-
+  async wake(target: string): Promise<void> {
+    const { parent, launch } = this.resolve(target);
     const tmuxSession = tmuxSessionName(parent.sessionId);
     const hasWindow = (await listTmuxWindows(this.executor, tmuxSession)).some(
-      (window) => window.piSessionId === launch.childSessionId,
+      (window) => window.piSessionId === target,
     );
+    if (!hasWindow) await this.createWindow(parent, launch, tmuxSession);
+  }
 
-    if (!hasWindow) {
-      await this.createWindow(parent, launch, tmuxSession);
-    }
-    if (
-      await this.messaging.waitForSession(
-        launch.childSessionId,
-        this.options.readyTimeoutMs ?? SESSION_READY_TIMEOUT_MS,
-      )
-    ) {
-      return;
-    }
-
-    this.requireCurrent(parent);
-    const killed = await killTmuxWindow(this.executor, tmuxSession, launch.childSessionId);
+  async restart(target: string): Promise<void> {
+    const { parent, launch } = this.resolve(target);
+    const tmuxSession = tmuxSessionName(parent.sessionId);
+    const killed = await killTmuxWindow(this.executor, tmuxSession, target);
     if (!killed) {
       throw new Error(
-        `Subagent ${launch.childSessionId} did not register and its stale tmux window could not be stopped.`,
+        `Subagent ${target} did not register and its stale tmux window could not be stopped.`,
       );
     }
-
     await this.createWindow(parent, launch, tmuxSession);
-    if (
-      !(await this.messaging.waitForSession(
-        launch.childSessionId,
-        this.options.readyTimeoutMs ?? SESSION_READY_TIMEOUT_MS,
-      ))
-    ) {
-      throw new Error(
-        `Subagent ${launch.childSessionId} was restarted but did not register for messaging.`,
-      );
-    }
+  }
+
+  afterSend(): Promise<void> | void {
+    return this.options.afterSend?.();
+  }
+
+  private resolve(target: string): { parent: WakeParentSession; launch: SubagentLaunched } {
+    const parent = this.getParent();
+    const launch = parent && findOwnedSubagentLaunch(parent.getBranch(), parent.sessionId, target);
+    if (!parent || !launch) throw new Error(`No owned subagent ${target}.`);
+    this.requireCurrent(parent);
+    return { parent, launch };
   }
 
   private async createWindow(
@@ -135,9 +70,7 @@ export class SubagentMessageRouter {
     launch: SubagentLaunched,
     tmuxSession: string,
   ): Promise<void> {
-    if (await this.isLive(launch.childSessionId)) {
-      return;
-    }
+    if ((await this.messaging.listSessions()).includes(launch.childSessionId)) return;
     this.requireCurrent(parent);
     this.options.onMaterialize?.(launch);
     await createTmuxWindow(this.executor, {
@@ -149,25 +82,8 @@ export class SubagentMessageRouter {
     });
   }
 
-  private sendOwned(
-    parent: WakeParentSession,
-    request: SendMessageRequest,
-  ): Promise<SendMessageResult> {
-    this.requireCurrent(parent);
-    return this.messaging.sendMessage(request);
-  }
-
-  private async isLive(sessionId: string): Promise<boolean> {
-    return (await this.messaging.listSessions()).includes(sessionId);
-  }
-
   private requireCurrent(parent: WakeParentSession): void {
-    if (!this.isCurrent(parent.epoch)) {
+    if (!this.isCurrent(parent.epoch))
       throw new Error("The parent session changed while waking its subagent.");
-    }
   }
 }
-
-function isTargetDeparture(result: SendMessageResult): boolean {
-  return !result.delivered && (result.reason === "no_session" || result.reason === "disconnected");
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
@@ -38,10 +38,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.10",
-    "@earendil-works/pi-agent-core": "^1.0.2",
-    "@earendil-works/pi-ai": "^1.0.2",
-    "@earendil-works/pi-coding-agent": "^1.0.2",
-    "@earendil-works/pi-tui": "^1.0.2",
+    "@earendil-works/pi-agent-core": "^1.0.4",
+    "@earendil-works/pi-ai": "^1.0.4",
+    "@earendil-works/pi-coding-agent": "^1.0.4",
+    "@earendil-works/pi-tui": "^1.0.4",
     "@types/node": "^24.13.3",
     "strip-ansi": "^7.2.0",
     "typebox": "1.3.27",