pi-sessions 0.14.3 → 0.16.0

package/README.md

@@ -51,9 +51,8 @@ pi -e /absolute/path/to/pi-sessions
 ## Quick start
 
 1. Install the package.
-2. Open Pi and run `/session-index`.
-3. Press `r` to build the index for all your prior sessions.
-4. Try the main flows:
+2. Open Pi. Your prior sessions are indexed automatically in the background.
+3. Try the main flows:
 
 ```text
 What session did I implement the db layer?
@@ -75,7 +74,7 @@ Open the frontend implementation task in a session to the right.
 | Session Index      | `/session-index` slash command                                         | Shows index status and rebuilds the local session index |
 | Session Auto Title | in background, `/title` slash command                                  | Give sessions titles                                    |
 
-Every feature is on by default. Turn one off with `enable: false` under its own settings namespace, which unregisters its tools and hooks.
+Every feature is on by default. Turn one off with `enable: false` under its own settings namespace. Index recovery and startup/switch sync always run, including when search is disabled. `hooks.enable` controls turn, tree, and compaction sync, not startup recovery.
 
 ```json
 {
@@ -110,6 +109,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 +121,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
 
@@ -174,12 +229,11 @@ Subagents require the handoff and messaging features. Limit recursive delegation
 
 ## Session Index
 
-By default, `pi-sessions` will start indexing all conversations moving forward. If you want to backfill all prior conversations:
+The index is a shared cache of your transcripts, used by search, messaging, and the other session features. Pi checks transcripts at startup and syncs files that changed, including sessions run without pi-sessions loaded. Missing, older-schema, or unreadable indexes rebuild automatically in the background; unreadable databases are moved aside rather than overwritten. A malformed transcript is skipped and reported.
 
-- run `/session-index`
-- hit `r` to (re)index everything
+During recovery, a tool may say "Session indexing in progress; try again shortly." Only one process rebuilds at a time, and readers retain the old index until its replacement is ready. Failed attempts share a backoff of 1 minute, then 5 minutes, then 30 minutes. `/session-index` shows status; press `r` to rebuild now, ignoring the backoff.
 
-this is idempotent, so if you run into any issues, or disable pi-sessions for a while, feel free to re-index to see if that resolves anything.
+If another Pi writes a newer index schema, the older process stops using the index and displays "pi-sessions was updated; /reload to use it". Reload instead of rebuilding: older code cannot replace a newer schema.
 
 By default the index lives at:
 

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,
       }),
@@ -130,18 +156,18 @@ export default function piSessions(pi: ExtensionAPI): void {
       }),
     );
   }
-  if (settings.features.hooks) {
-    lifecycles.push(installHooks(pi, { index }));
-  }
+  lifecycles.push(index, installHooks(pi, { index, turnSync: settings.features.hooks }));
   // Messaging leads every session_start so the broker connection is registered before any
   // other feature hook runs. A side effect is that messaging's first relation snapshot can
   // predate hooks' index sync for this session; getCachedRelationTo self-heals on miss, so
   // 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/metadata.ts

@@ -10,6 +10,8 @@ import {
 } from "./launch-target.ts";
 
 export const HANDOFF_METADATA_CUSTOM_TYPE = "pi-sessions.handoff";
+// Agent Switchboard's swb adopt (packages/cli/src/commands/adopt.ts) reads this
+// customType and data.subagent; renaming either breaks its subagent check.
 export const HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap";
 export const HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap-consumed";
 export const HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap-failed";

package/extensions/session-handoff/query.ts

@@ -1,5 +1,6 @@
 import { stripSearchSnippetMarkers } from "../shared/search-snippet.ts";
 import {
+  formatRequiredSessionIndexError,
   getSessionByPath,
   type SearchSessionResult,
   type SessionIndexDatabase,
@@ -100,7 +101,7 @@ export function listSessionPickerItems(
           defaultScopeLabel,
         };
       }) ?? {
-        items: [buildIndexErrorItem()],
+        items: [buildIndexErrorItem(options.indexPath)],
         scopeMode,
         defaultScopeLabel,
       }
@@ -309,11 +310,11 @@ function getSessionMarker(
   }
 }
 
-function buildIndexErrorItem(): SessionPickerNoticeItem {
+function buildIndexErrorItem(indexPath: string): SessionPickerNoticeItem {
   return {
     kind: "error",
-    title: "Session index missing or incompatible",
-    description: "Run /session-index to rebuild it.",
+    title: "Session index unavailable",
+    description: formatRequiredSessionIndexError(indexPath),
   };
 }
 

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);