@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-intercom/index.ts

@@ -1,11 +1,12 @@
-import { defineTool, type ExtensionAPI, type ExtensionContext } from "@selesai/code";
+import { BorderedLoader, defineTool, type ExtensionAPI, type ExtensionContext } from "@selesai/code";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { randomUUID } from "crypto";
 import { Type } from "typebox";
 import { Text } from "@earendil-works/pi-tui";
 import { IntercomClient, type SendResult } from "./broker/client.ts";
 import { spawnBrokerIfNeeded } from "./broker/spawn.ts";
-import { SessionListOverlay } from "./ui/session-list.ts";
+import { SessionListOverlay, type SessionListSelection } from "./ui/session-list.ts";
+import { HandoverPicker, type HandoverPickerResult, type RemoteSessionLister } from "./ui/handover-picker.ts";
 import { ComposeOverlay, type ComposeResult } from "./ui/compose.ts";
 import { InlineMessageComponent } from "./ui/inline-message.ts";
 import { getAskTimeoutMs, loadConfig, type IntercomConfig } from "./config.ts";
@@ -16,6 +17,7 @@ import {
   INTERCOM_EXTENSION_REGISTRY_READY_EVENT,
   INTERCOM_OUTBOX_REQUEST_EVENT,
   INTERCOM_OUTBOX_RESULT_EVENT,
+  INTERCOM_SESSION_IDENTITY_EVENT,
   type IntercomExtensionChannel,
   type IntercomExtensionEvent,
   type IntercomExtensionOwner,
@@ -30,14 +32,20 @@ import {
   type IntercomRpcEventData as IntercomRpcEvent, type IntercomRpcDelivery,
   RELEASE_READINESS_EVENT, answerReleaseReadiness,
   STOP_ALL_BACKGROUND_EVENT, answerStopAllBackground,
+  type IntercomSessionIdentityRequestV1,
 } from "./extension-api.ts";
 import { intercomReleaseBlockers, stopIntercom } from "./release-readiness.ts";
 import { isMessage } from "./broker/protocol.ts";
 import { ReplyTracker } from "./reply-tracker.ts";
-import { resolve as resolvePath } from "node:path";
+import { homedir } from "node:os";
+import { join as joinPath, resolve as resolvePath } from "node:path";
 import { sameCwd } from "./cwd.ts";
 import { formatContextUsage } from "./format-context.ts";
 import { openProjectPane, resolveTargetInCwd, waitForProjectSession, type ProjectPaneLaunch } from "./project-agent.ts";
+import { relaySenderName } from "./cross-machine-envelope.ts";
+import { runCommand, sendCrossMachine } from "./cross-machine-transport.ts";
+import { listMachineAgents, listSavedMachines, parseCrossMachineTarget } from "./cross-machine-discovery.ts";
+import { formatHandoverMessage, generateHandoverBody, readGitState } from "./handover.ts";
 
 const INTERCOM_TOOL_NAME = "intercom";
 const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
@@ -79,6 +87,25 @@ interface DeliveryTarget {
   projectPane?: ProjectPaneLaunch;
 }
 
+interface DeliveryRequest {
+  to?: string;
+  cwd?: string;
+  openProjectPaneIfMissing?: boolean;
+  focus?: boolean;
+  message: string;
+  attachments?: Attachment[];
+  replyTo?: string;
+  supersedes?: string;
+  retryOf?: string;
+  /** Handovers are always new messages and are not sent once the signal aborts. */
+  handover?: boolean;
+}
+
+interface IntercomToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+}
+
 interface OutboxTarget {
   id: string;
   label: string;
@@ -120,6 +147,25 @@ function getErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+export function explicitCrossMachineSendRestriction(options: {
+  to?: string;
+  cwd?: string;
+  openProjectPaneIfMissing?: boolean;
+  attachments?: readonly unknown[];
+  replyTo?: string;
+  supersedes?: string;
+  retryOf?: string;
+}): string | undefined {
+  if (!options.to?.includes("@")) return undefined;
+  if (options.cwd || options.openProjectPaneIfMissing) {
+    return "Cross-machine send does not support cwd or opening project panes.";
+  }
+  if (options.replyTo || options.supersedes || options.retryOf || options.attachments?.length) {
+    return "Cross-machine send only supports a new text message; attachments, reply relationships, supersede, and retry are not supported.";
+  }
+  return undefined;
+}
+
 function deliveryDetails(result: SendResult): Record<string, unknown> {
   return {
     messageId: result.id,
@@ -524,6 +570,14 @@ function currentTmuxPane(): string | undefined {
   const pane = process.env.TMUX_PANE?.trim();
   return pane ? pane : undefined;
 }
+// Herdr exports a launch-time pane alias to hosted processes. Its visible,
+// workspace-qualified id can change when the pane moves, so registration also
+// carries the stable Pi session file and the broker resolves both against a
+// fresh snapshot. Workspace and tab ids are intentionally never registered.
+function currentHerdrPane(): string | undefined {
+  const pane = process.env.HERDR_PANE_ID?.trim();
+  return pane ? pane : undefined;
+}
 function formatIntercomContactSnippet(sessionId: string): string {
   return `Use pi-intercom: intercom({ action: "send", to: "${sessionId}", message: "..." })`;
 }
@@ -535,13 +589,22 @@ function formatSessionLabel(session: SessionInfo, duplicates: Set<string>): stri
     ? `${session.name} (${session.id.slice(0, 8)})`
     : session.name;
 }
+function formatHerdrLocation(session: SessionInfo): string {
+  const location = session.herdrLocation;
+  if (!location) return "";
+  if (location.status === "not_hosted") return "not under Herdr";
+  if (location.status === "unavailable") return `Herdr location unavailable: ${location.reason} (pane ${location.paneId})`;
+  return `Herdr ${location.workspace.label} [${location.workspace.id}] / ${location.tab.label} [${location.tab.id}] / pane ${location.paneId}`;
+}
 function formatSessionListRow(session: SessionInfo, currentCwd: string, isSelf: boolean, idPrefix: string): string {
   const name = session.name || "Unnamed session";
   const tags = [isSelf ? "self" : session.cwd === currentCwd ? "same cwd" : undefined, session.status]
     .filter((tag): tag is string => Boolean(tag));
   const suffix = tags.length ? ` [${tags.join(", ")}]` : "";
   const pane = session.tmuxPane ? ` · tmux ${session.tmuxPane}` : "";
-  return `• ${name} (${idPrefix}) — ${session.cwd} (${session.model}${formatContextUsage(session)}${pane})${suffix}`;
+  const herdrLocation = formatHerdrLocation(session);
+  const herdr = herdrLocation ? ` · ${herdrLocation}` : "";
+  return `• ${name} (${idPrefix}) — ${session.cwd} (${session.model}${formatContextUsage(session)}${pane})${herdr}${suffix}`;
 }
 function previewText(value: unknown, maxLength = 72): string | undefined {
   if (typeof value !== "string") {
@@ -553,6 +616,9 @@ function previewText(value: unknown, maxLength = 72): string | undefined {
   }
   return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 1)}…` : normalized;
 }
+function expandHomePath(path: string): string {
+  return path === "~" ? homedir() : path.startsWith("~/") ? joinPath(homedir(), path.slice(2)) : path;
+}
 function firstTextContent(result: { content?: Array<{ type: string; text?: string }> }): string {
   return result.content?.find((item) => item.type === "text" && typeof item.text === "string")?.text?.replace(/\*\*/g, "") ?? "";
 }
@@ -613,6 +679,27 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   let runtimeStarted = false;
   let runtimeGeneration = 0;
   let agentRunning = false;
+  // A wake prompt stays pending until agent_start: Pi marks the run active only after its async
+  // preflight. Pi exposes no prompt completion, and a handled or failed preflight never emits
+  // agent_start, so the reservation expires after a bounded window instead of latching.
+  let idleWakeRequestedAt = 0;
+  const idleWakePending = () => idleWakeRequestedAt > 0 && Date.now() - idleWakeRequestedAt < 10_000;
+  const heldInboundMessages: InboundMessageEntry[] = [];
+  let heldInboundTimer: NodeJS.Timeout | null = null;
+  function dropHeldInboundMessage(messageId: string, receipt: { status: MessageReceiptStatus; detail?: string }): boolean {
+    const index = heldInboundMessages.findIndex((entry) => entry.message.id === messageId);
+    if (index < 0) return false;
+    heldInboundMessages.splice(index, 1);
+    if (heldInboundMessages.length === 0) clearHeldInboundTimer();
+    emitMessageReceipt(messageId, receipt.status, receipt.detail);
+    return true;
+  }
+  function expireHeldInboundMessages(detail: string): void {
+    for (const entry of heldInboundMessages.splice(0)) {
+      emitMessageReceipt(entry.message.id, "expired", detail);
+    }
+    clearHeldInboundTimer();
+  }
   const activeTools = new Map<string, string>();
   const replyTracker = new ReplyTracker();
 
@@ -622,6 +709,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   const pendingOutboxRequests = new Map<string, PendingOutboxRequest>();
   function dismissIncomingAsk(messageId: string): void {
     replyTracker.dismissPendingAsk(messageId);
+    dropHeldInboundMessage(messageId, { status: "acknowledged", detail: "answered before injection" });
   }
   function hasSeenInboundMessage(from: SessionInfo, message: Message, now = Date.now()): boolean {
     for (const [key, seenAt] of seenInboundMessages) {
@@ -655,11 +743,15 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   }
   function handleMessageControl(control: MessageControl): void {
     replyTracker.dismissPendingAsk(control.messageId);
+    const supersededDetail = control.supersededBy ? `superseded by ${control.supersededBy}` : undefined;
+    if (dropHeldInboundMessage(control.messageId, control.action === "cancel"
+      ? { status: "cancelled", detail: "dropped before injection" }
+      : { status: "superseded", detail: supersededDetail })) return;
     if (control.action === "cancel") {
       emitMessageReceipt(control.messageId, "cancellation_requested", "message may already be injected or processed");
       return;
     }
-    emitMessageReceipt(control.messageId, "superseded", control.supersededBy ? `superseded by ${control.supersededBy}` : undefined);
+    emitMessageReceipt(control.messageId, "superseded", supersededDetail);
   }
   function latestDeliveryState(messageId: string | null, fallback: string): string {
     if (!messageId) {
@@ -878,6 +970,8 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
 
     const identity = buildPresenceIdentity(pi, currentIntercomSessionId ?? currentSessionId);
     const tmuxPane = currentTmuxPane();
+    const herdrPaneId = currentHerdrPane();
+    const herdrSessionPath = herdrPaneId ? liveContext.sessionManager.getSessionFile() : undefined;
     return {
       ...identity,
       cwd: liveContext.cwd,
@@ -887,6 +981,8 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       lastActivity: Date.now(),
       status: currentStatus(),
       ...(tmuxPane ? { tmuxPane } : {}),
+      ...(herdrPaneId ? { herdrPaneId } : {}),
+      ...(herdrSessionPath ? { herdrSessionPath } : {}),
       ...(localExtensions.size > 0
         ? {
             extensions: currentExtensionCapabilities(),
@@ -1308,19 +1404,21 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       return;
     }
     const injectedMessage = { ...entry.message, injectedAt: Date.now() };
-    emitMessageReceipt(injectedMessage.id, "injected");
     const replyCommand = delivery === "steer" && entry.replyCommand && entry.message.expectsReply
       ? `intercom({ action: "reply", replyTo: ${JSON.stringify(entry.message.id)}, message: "..." })`
       : entry.replyCommand;
     const deliveredEntry = { ...entry, message: injectedMessage, replyCommand };
     replyTracker.queueTurnContext({ from: entry.from, message: injectedMessage, receivedAt: Date.now() });
-    const senderDisplay = entry.from.name || entry.from.id.slice(0, 8);
+    const senderDisplay = injectedMessage.crossMachine
+      ? `${relaySenderName(injectedMessage.crossMachine.origin)} · unverified cross-machine`
+      : entry.from.name || entry.from.id.slice(0, 8);
     // The tool may be an inactive optional capability: say how to activate it, not just its call.
     const activateHint = pi.getActiveTools().includes("intercom")
       ? ""
-      : ' (not active yet: call capability_discover with name "intercom" first)';
+      : ' (not active yet: use codemode searchTools() (or tool_search when enabled) to find and expose "intercom" first)';
     const replyInstruction = replyCommand ? `\n\nTo reply, use the intercom tool${activateHint}: ${replyCommand}` : "";
     const deliveryMetadata = formatInboundDeliveryMetadata(injectedMessage);
+    const trigger = delivery === "trigger" && shouldTriggerInboundMessage(entry, forceTrigger);
     pi.sendMessage(
       {
         customType: "intercom_message",
@@ -1328,14 +1426,71 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
         display: true,
         details: deliveredEntry,
       },
-      delivery === "trigger" && shouldTriggerInboundMessage(entry, forceTrigger)
-        ? { triggerTurn: true }
-        : { deliverAs: "steer" }
+      trigger ? undefined : { deliverAs: "steer" }
     );
+    // Pi skips before_agent_start for sendMessage({ triggerTurn: true }) turns (pi#5581),
+    // so wake an idle session with a user prompt that runs the normal prompt lifecycle.
+    if (trigger && !idleWakePending() && getLiveContext(runtimeContext, generation)?.isIdle()) {
+      idleWakeRequestedAt = Date.now();
+      pi.sendUserMessage("New intercom message above.");
+    }
+    emitMessageReceipt(injectedMessage.id, "injected");
   }
   function sendIncomingBrokerMessage(entry: InboundMessageEntry, delivery: "trigger" | "steer", generation = runtimeGeneration): void {
     sendIncomingMessage(entry, delivery, generation);
   }
+  function deliverIncomingBrokerMessage(entry: InboundMessageEntry, ctx: ExtensionContext, generation: number): void {
+    const activeContext = getLiveContext(ctx, generation);
+    if (!activeContext) return;
+    if (!activeContext.isIdle()) {
+      if (!activeContext.hasUI) {
+        const activeClient = client;
+        if (!entry.message.replyTo && activeClient?.isConnected()) {
+          void (async () => {
+            try {
+              const result = await activeClient.send(entry.from.id, {
+                text: "This agent is running in non-interactive mode and cannot respond to intercom messages while it is working. It will continue its current task and exit when done.",
+                replyTo: entry.message.id,
+              });
+              if (result.delivered && getLiveContext(ctx, generation)) dismissIncomingAsk(entry.message.id);
+            } catch {
+              // Best-effort reply; keep the busy non-interactive session running either way.
+            }
+          })();
+        }
+        return;
+      }
+      sendIncomingBrokerMessage(entry, "steer", generation);
+      return;
+    }
+    sendIncomingBrokerMessage(entry, "trigger", generation);
+  }
+  function flushHeldInboundMessages(ctx: ExtensionContext, generation: number): void {
+    if (!getLiveContext(ctx, generation)) return;
+    if (config.busyDelivery === "human-first" && ctx.hasUI) {
+      if (ctx.isIdle() && !idleWakePending() && heldInboundMessages.length > 0) {
+        deliverIncomingBrokerMessage(heldInboundMessages.shift()!, ctx, generation);
+      }
+      if (heldInboundMessages.length === 0) clearHeldInboundTimer();
+      return;
+    }
+    while (heldInboundMessages.length > 0 && (ctx.isIdle() || agentRunning) && getLiveContext(ctx, generation)) {
+      deliverIncomingBrokerMessage(heldInboundMessages.shift()!, ctx, generation);
+    }
+    if (heldInboundMessages.length === 0) clearHeldInboundTimer();
+  }
+  function clearHeldInboundTimer(): void {
+    if (heldInboundTimer) clearInterval(heldInboundTimer);
+    heldInboundTimer = null;
+  }
+  function holdIncomingBrokerMessage(entry: InboundMessageEntry, ctx: ExtensionContext, generation: number): void {
+    heldInboundMessages.push(entry);
+    emitMessageReceipt(entry.message.id, "queued", "held until delivery is safe");
+    if (!heldInboundTimer) {
+      heldInboundTimer = setInterval(() => flushHeldInboundMessages(ctx, generation), 100);
+      heldInboundTimer.unref();
+    }
+  }
   function handleIncomingMessage(ctx: ExtensionContext, from: SessionInfo, message: Message): void {
     const messageGeneration = runtimeGeneration;
     const liveContext = getLiveContext(ctx, messageGeneration);
@@ -1365,42 +1520,20 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       ? formatAttachments(receivedMessage.content.attachments)
       : "";
     const bodyText = `${receivedMessage.content.text}${attachmentText}`;
-    const replyCommand = config.replyHint && receivedMessage.expectsReply
-      ? `intercom({ action: "reply", message: "..." })`
-      : undefined;
+    const replyCommand = config.replyHint && receivedMessage.crossMachine
+      ? `intercom({ action: "send", to: ${JSON.stringify(relaySenderName(receivedMessage.crossMachine.origin))}, message: "..." })`
+      : config.replyHint && receivedMessage.expectsReply
+        ? `intercom({ action: "reply", message: "..." })`
+        : undefined;
     replyTracker.recordIncomingMessage(from, receivedMessage, receiverReceivedAt);
     emitMessageReceipt(receivedMessage.id, "acknowledged", "accepted by receiver");
     const entry = { from, message: receivedMessage, replyCommand, bodyText };
-    void (async () => {
-      const activeContext = getLiveContext(liveContext, messageGeneration);
-      if (!activeContext) {
-        return;
-      }
-      if (!activeContext.isIdle()) {
-        if (!activeContext.hasUI) {
-          const activeClient = client;
-          if (!message.replyTo && activeClient?.isConnected()) {
-            try {
-              const result = await activeClient.send(from.id, {
-                text: "This agent is running in non-interactive mode and cannot respond to intercom messages while it is working. It will continue its current task and exit when done.",
-                replyTo: message.id,
-              });
-              if (result.delivered && getLiveContext(liveContext, messageGeneration)) {
-                dismissIncomingAsk(message.id);
-              }
-            } catch {
-              // Best-effort reply; keep the busy non-interactive session running either way.
-            }
-          }
-          return;
-        }
-        sendIncomingBrokerMessage(entry, "steer");
-        return;
-      }
-      if (getLiveContext(liveContext, messageGeneration)) {
-        sendIncomingBrokerMessage(entry, "trigger", messageGeneration);
-      }
-    })();
+    // Busy without an agent run cannot steer; manual compaction can discard an appended custom entry.
+    if (heldInboundMessages.length > 0 || (!liveContext.isIdle() && (!agentRunning || (config.busyDelivery === "human-first" && liveContext.hasUI)))) {
+      holdIncomingBrokerMessage(entry, liveContext, messageGeneration);
+    } else {
+      deliverIncomingBrokerMessage(entry, liveContext, messageGeneration);
+    }
   }
   function attachClientHandlers(nextClient: IntercomClient): void {
     nextClient.onBrokerMessage((message: BrokerMessage) => {
@@ -1666,6 +1799,196 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     });
     return { id: session.id, label: session.name || session.id, projectPane };
   }
+  /** Shared by send, handover, and /handover. Never throws; failures are returned as error results. */
+  async function deliverMessage(
+    connectedClient: IntercomClient,
+    ctx: ExtensionContext,
+    signal: AbortSignal | undefined,
+    request: DeliveryRequest,
+  ): Promise<IntercomToolResult> {
+    const { to, cwd, openProjectPaneIfMissing, focus, message, attachments, replyTo, supersedes, retryOf } = request;
+    try {
+      const crossMachineTarget = Boolean(to?.includes("@"));
+      const crossMachineRestriction = explicitCrossMachineSendRestriction({
+        to, cwd, openProjectPaneIfMissing, attachments, replyTo, supersedes, retryOf,
+      });
+      if (crossMachineRestriction) {
+        return {
+          content: [{ type: "text", text: crossMachineRestriction }],
+          details: { error: true, crossMachine: false },
+        };
+      }
+      if (crossMachineTarget) {
+        try {
+          parseCrossMachineTarget(to!);
+        } catch (error) {
+          return {
+            content: [{ type: "text", text: getErrorMessage(error) }],
+            details: { error: true, crossMachine: false },
+          };
+        }
+      }
+      if (openProjectPaneIfMissing && !cwd) {
+        return {
+          content: [{ type: "text", text: "openProjectPaneIfMissing requires a target cwd." }],
+          details: { error: true },
+        };
+      }
+      const confirmSend = !replyTo && config.confirmSend && ctx.hasUI;
+      const attachmentText = attachments?.length ? formatAttachments(attachments) : "";
+      if (confirmSend && cwd && openProjectPaneIfMissing) {
+        const confirmed = await ctx.ui.confirm(
+          "Send message",
+          `Send to "${to ?? cwd}":\n\n${message}${attachmentText}`,
+        );
+        if (!confirmed) {
+          return {
+            content: [{ type: "text", text: "Message cancelled by user" }],
+            details: {},
+          };
+        }
+      }
+      if (confirmSend && crossMachineTarget) {
+        const confirmed = await ctx.ui.confirm("Send message", `Send to "${to}":\n\n${message}`);
+        if (!confirmed) {
+          return {
+            content: [{ type: "text", text: "Message cancelled by user" }],
+            details: {},
+          };
+        }
+      }
+      if (crossMachineTarget) {
+        if (request.handover && signal?.aborted) {
+          return { content: [{ type: "text", text: "Handover was cancelled before delivery." }], details: { error: true } };
+        }
+        const identity = buildPresenceIdentity(pi, connectedClient.sessionId ?? ctx.sessionManager.getSessionId());
+        try {
+          const remote = await sendCrossMachine(to!, message, {
+            name: identity.name,
+            sessionId: connectedClient.sessionId ?? ctx.sessionManager.getSessionId(),
+            machine: config.crossMachine.machineName,
+          }, {
+            remoteCommand: config.crossMachine.remoteCommand,
+          });
+          const remoteTarget = relaySenderName({ name: remote.agent.name, machine: remote.machine.label });
+          pi.appendEntry("intercom_sent", {
+            to: remoteTarget,
+            message: { text: message },
+            timestamp: Date.now(),
+            crossMachine: true,
+          });
+          return {
+            content: [{ type: "text", text: `Message sent to ${remoteTarget} over SSH (origin identity is SSH-asserted)` }],
+            details: { delivered: true, crossMachine: true, machine: remote.machine.label, target: remote.agent.name, trust: "ssh-asserted" },
+          };
+        } catch (remoteError) {
+          return {
+            content: [{ type: "text", text: `Explicit cross-machine message to "${to}" was not delivered: ${getErrorMessage(remoteError)}` }],
+            details: { error: true, crossMachine: false },
+          };
+        }
+      }
+      const target: DeliveryTarget = cwd
+        ? await resolveCwdDeliveryTarget(connectedClient, { to, cwd, openProjectPaneIfMissing, focus, signal })
+        : { id: await resolveSessionTarget(connectedClient, to) ?? to!, label: to! };
+      const sendTo = target.id;
+      const targetDisplay = target.projectPane ? target.label : to ?? target.label;
+      if (sendTo === connectedClient.sessionId) {
+        return {
+          content: [{ type: "text", text: "Cannot message the current session" }],
+          details: { error: true },
+        };
+      }
+      const activeReplyMismatch = replyTo ? null : replyTracker.findActiveReplyTargetMismatch(sendTo);
+      if (activeReplyMismatch) {
+        const senderLabel = activeReplyMismatch.from.name || activeReplyMismatch.from.id;
+        return {
+          content: [{ type: "text", text: `This turn is responding to an intercom ask from "${senderLabel}". Use intercom({ action: "reply", message: "..." }) or set replyTo: "${activeReplyMismatch.message.id}". Refusing non-reply send to "${targetDisplay}" to avoid a misdirected reply.` }],
+          details: { error: true, replyTo: activeReplyMismatch.message.id },
+        };
+      }
+      const inferredAsk = replyTo || request.handover ? null : replyTracker.findUniquePendingAskFrom(sendTo);
+      const effectiveReplyTo = replyTo ?? inferredAsk?.message.id;
+      if (confirmSend && !(cwd && openProjectPaneIfMissing)) {
+        const confirmed = await ctx.ui.confirm(
+          "Send message",
+          `Send to "${targetDisplay}":\n\n${message}${attachmentText}`,
+        );
+        if (!confirmed) {
+          return {
+            content: [{ type: "text", text: "Message cancelled by user" }],
+            details: {},
+          };
+        }
+      }
+      if (request.handover && signal?.aborted) {
+        return { content: [{ type: "text", text: "Handover was cancelled before delivery." }], details: { error: true } };
+      }
+      const result = await connectedClient.send(sendTo, {
+        text: message,
+        attachments,
+        replyTo: effectiveReplyTo,
+        supersedes,
+        retryOf,
+      });
+      if (!result.delivered) {
+        const errorText = result.reason ?? "Session may not exist or has disconnected.";
+        return {
+          content: [{ type: "text", text: `Message to "${targetDisplay}" was not delivered: ${errorText}` }],
+          details: deliveryDetails(result),
+        };
+      }
+      pi.appendEntry("intercom_sent", {
+        to: targetDisplay,
+        message: { text: message, attachments, replyTo: effectiveReplyTo, supersedes, retryOf },
+        messageId: result.id,
+        timestamp: Date.now(),
+      });
+      if (effectiveReplyTo) {
+        dismissIncomingAsk(effectiveReplyTo);
+      }
+      return {
+        content: [{
+          type: "text",
+          text: target.projectPane
+            ? `Opened Herdr project pane ${target.projectPane.paneId} for ${target.projectPane.projectRoot} and sent message to ${targetDisplay}`
+            : inferredAsk ? `Reply sent to ${targetDisplay} (inferred from pending ask)` : `Message sent to ${targetDisplay}`,
+        }],
+        details: {
+          ...deliveryDetails(result),
+          ...(effectiveReplyTo ? { replyTo: effectiveReplyTo } : {}),
+          ...(target.projectPane ? { openedProjectPane: true, paneId: target.projectPane.paneId, projectRoot: target.projectPane.projectRoot } : {}),
+        },
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Failed to send: ${getErrorMessage(error)}` }],
+        details: { error: true },
+      };
+    }
+  }
+  async function buildHandoverText(
+    connectedClient: IntercomClient,
+    ctx: ExtensionContext,
+    options: { goal?: string; crossMachine: boolean },
+    signal: AbortSignal | undefined,
+  ): Promise<string> {
+    const [body, git] = await Promise.all([
+      generateHandoverBody(ctx, options.goal, signal),
+      readGitState(ctx.cwd),
+    ]);
+    if (signal?.aborted) {
+      throw new Error("Handover generation was aborted.");
+    }
+    const sessionId = connectedClient.sessionId ?? ctx.sessionManager.getSessionId();
+    return formatHandoverMessage({
+      senderName: pi.getSessionName()?.trim() || sessionId.slice(0, 8),
+      senderCwd: ctx.cwd,
+      sessionFile: options.crossMachine ? undefined : ctx.sessionManager.getSessionFile(),
+      git,
+      body,
+    });
+  }
   function deliverLocalSubagentRelayMessage(sender: "subagent-control" | "subagent-result", status: string, messageText: string): void {
     const liveContext = getLiveContext();
     const now = Date.now();
@@ -1704,6 +2027,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     disposed = false;
     runtimeStarted = true;
     runtimeGeneration += 1;
+    idleWakeRequestedAt = 0;
     outboxRequestIds.clear();
     reconnectAttempt = 0;
     clearReconnectTimer();
@@ -1717,7 +2041,15 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     }
     runtimeContext = ctx;
     currentSessionId = ctx.sessionManager.getSessionId();
-    currentIntercomSessionId = resolveConfiguredIntercomSessionId(currentSessionId, config);
+    let claimedIntercomSessionId: string | undefined;
+    const identityRequest: IntercomSessionIdentityRequestV1 = {
+      version: 1,
+      claim: (stableId) => {
+        claimedIntercomSessionId ??= (typeof stableId === "string" && stableId.trim()) || undefined;
+      },
+    };
+    pi.events.emit(INTERCOM_SESSION_IDENTITY_EVENT, identityRequest);
+    currentIntercomSessionId = claimedIntercomSessionId ?? resolveConfiguredIntercomSessionId(currentSessionId, config);
     publishIntercomSessionId(currentIntercomSessionId);
     emitRpcConnection(false, "Session started");
     currentModel = ctx.model?.id ?? "unknown";
@@ -1726,6 +2058,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     lastPresenceName = initialPresenceIdentity.name;
     lastPresenceRuntimeFallbackAlias = initialPresenceIdentity.runtimeFallbackAlias;
     agentRunning = false;
+    expireHeldInboundMessages("session replaced before injection");
     activeTools.clear();
     startNamePoll();
     const startupGeneration = runtimeGeneration;
@@ -1899,6 +2232,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     rejectReplyWaiter(new Error("Session shutting down"));
     replyTracker.reset();
     agentRunning = false;
+    expireHeldInboundMessages("session shut down before injection");
     activeTools.clear();
     if (client) {
       await client.disconnect();
@@ -1909,17 +2243,27 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     currentIntercomSessionId = null;
     sessionStartedAt = null;
   });
-  pi.on("turn_end", () => {
+  pi.on("turn_end", (event, ctx) => {
     if (!getLiveContext()) {
       return;
     }
     replyTracker.endTurn();
+    // Aborted/error turns cannot consume a steer; leave their peers for the idle trigger.
+    if (config.busyDelivery === "human-first" && ctx.hasUI && event.message.role === "assistant"
+      && event.message.stopReason !== "aborted" && event.message.stopReason !== "error"
+      && heldInboundMessages.length > 0 && agentRunning
+      && !ctx.isIdle() && !ctx.hasPendingMessages() && getLiveContext(ctx)) {
+      sendIncomingBrokerMessage(heldInboundMessages.shift()!, "steer", runtimeGeneration);
+      if (heldInboundMessages.length === 0) clearHeldInboundTimer();
+    }
   });
   pi.on("agent_start", () => {
+    idleWakeRequestedAt = 0;
     if (!getLiveContext()) {
       return;
     }
     agentRunning = true;
+    if (runtimeContext) flushHeldInboundMessages(runtimeContext, runtimeGeneration);
     activeTools.clear();
     syncPresenceStatus();
   });
@@ -2003,11 +2347,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       label: "Contact Supervisor",
       description: "Subagent-only tool for contacting the supervisor agent that delegated this task. Use need_decision when blocked, uncertain, needing approval, or facing a product/API/scope decision before continuing; this waits for the supervisor's reply. Use interview_request when multiple structured questions need supervisor answers; this also waits for a reply. Use progress_update only for meaningful progress or unexpected discoveries that change the plan; this does not wait for a reply. Do not use for routine completion handoffs.",
       promptSnippet: "Subagent-only: contact the supervisor for decisions, structured interviews, or meaningful plan-changing updates. Do not use for routine completion handoffs.",
-      discovery: {
-        summary: "Subagent-only channel to ask the supervisor for decisions or send plan-changing updates",
-        aliases: ["contact supervisor", "ask supervisor"],
-        category: "coordination",
-      },
+      exposure: "model-only",
       promptGuidelines: [
         "Use contact_supervisor with reason='need_decision' when a subagent is blocked, uncertain, needs approval, or faces a product/API/scope decision before continuing.",
         "Use contact_supervisor with reason='interview_request' when the child needs multiple structured answers from the supervisor in one blocking exchange.",
@@ -2238,17 +2578,19 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
           };
         }
       },
-      renderCall(args, theme) {
+      renderCall(args, theme, context) {
         const reason = typeof args.reason === "string" ? args.reason : "contact";
-        const messagePreview = previewText(args.message, 96);
+        const messageText = context.expanded && typeof args.message === "string"
+          ? args.message
+          : previewText(args.message, 96);
         const interview = args.interview && typeof args.interview === "object" ? args.interview as { title?: unknown } : undefined;
         let text = theme.fg("toolTitle", theme.bold("contact_supervisor "));
         text += theme.fg(reason === "need_decision" ? "warning" : reason === "progress_update" ? "muted" : "accent", reason);
         if (typeof interview?.title === "string" && interview.title.trim()) {
           text += " " + theme.fg("accent", interview.title.trim());
         }
-        if (messagePreview) {
-          text += "\n  " + theme.fg("dim", messagePreview);
+        if (messageText) {
+          text += "\n  " + theme.fg("dim", messageText);
         }
         return new Text(text, 0, 0);
       },
@@ -2277,11 +2619,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   pi.registerTool(defineTool({
     name: "intercom",
     label: "Intercom",
-    discovery: {
-      summary: "Send messages and coordinate with other local Selesai sessions",
-      aliases: ["contact session", "session message", "peer session"],
-      category: "coordination",
-    },
+    exposure: "deferred",
     description: `Send a message to another Selesai session running on this machine.
 Use this to communicate findings, request help, or coordinate work with other sessions.
 
@@ -2296,6 +2634,8 @@ Usage:
   intercom({ action: "send", to: "name-or-id", message: "..." })  → Send message
   intercom({ action: "send", cwd: "/path", openProjectPaneIfMissing: true, message: "..." }) → Open a visible Herdr project pane when needed, then send
   intercom({ action: "ask", to: "name-or-id", message: "..." })   → Ask and wait for reply
+  intercom({ action: "handover", to: "name-or-id", message: "next task" }) → Summarize this session and hand it over; the receiver acts on it
+  intercom({ action: "handover", cwd: "/path", openProjectPaneIfMissing: true }) → Hand over to the session in that project, opening a Herdr pane when needed
   intercom({ action: "cancel", messageId: "..." })                 → Request cancellation of a sent message
   intercom({ action: "reply", message: "..." })                      → Reply to the active/single pending ask
   intercom({ action: "pending" })                                      → List unresolved inbound asks
@@ -2304,14 +2644,14 @@ Usage:
       "Use to coordinate with other local Selesai sessions: list peers, send updates, ask for help, or check intercom connectivity.",
 
     parameters: Type.Object({
-      action: StringEnum(["list", "list-cwd", "send", "ask", "reply", "pending", "status", "cancel"] as const, {
-        description: "Action: 'list', 'list-cwd', 'send', 'ask', 'reply', 'pending', 'status', or 'cancel'",
+      action: StringEnum(["list", "list-cwd", "send", "ask", "handover", "reply", "pending", "status", "cancel"] as const, {
+        description: "Action: 'list', 'list-cwd', 'send', 'ask', 'handover', 'reply', 'pending', 'status', or 'cancel'. 'handover' summarizes this session with the current model and sends it to the target, which acts on it; 'message' is the optional next task.",
       }),
       to: Type.Optional(Type.String({
-        description: "Target session: name, full session ID, or the short id shown in parentheses by 'list' (a leading ID prefix resolves). For send/ask with cwd, omit to target the sole live session in that cwd or the newly opened project-pane session. For 'reply', disambiguates the pending ask.",
+        description: "Target session: name, full session ID, or the short id shown in parentheses by 'list' (a leading ID prefix resolves). For send/ask/handover with cwd, omit to target the sole live session in that cwd or the newly opened project-pane session. For 'reply', disambiguates the pending ask.",
       })),
       message: Type.Optional(Type.String({
-        description: "Message to send (for 'send', 'ask', or 'reply' action)",
+        description: "Message to send (for 'send', 'ask', or 'reply' action). For 'handover', the optional next task for the receiver.",
       })),
       attachments: Type.Optional(Type.Array(Type.Object({
         type: StringEnum(["file", "snippet", "context"] as const),
@@ -2332,10 +2672,10 @@ Usage:
         description: "Previous message ID this send/ask is a user-authored retry of. Retries always send a new message ID.",
       })),
       cwd: Type.Optional(Type.String({
-        description: "Working directory filter for 'list-cwd'. For send/ask, scopes target lookup to that directory; omit 'to' to target the sole live peer there. Absolute, or relative to the current session's cwd; '.' means the current cwd.",
+        description: "Working directory filter for 'list-cwd'. For send/ask/handover, scopes target lookup to that directory; omit 'to' to target the sole live peer there. Absolute, or relative to the current session's cwd; '.' means the current cwd.",
       })),
       openProjectPaneIfMissing: Type.Optional(Type.Boolean({
-        description: "For send/ask with cwd, open a visible Herdr project pane and launch Selesai there when no matching live session is connected.",
+        description: "For send/ask/handover with cwd, open a visible Herdr project pane and launch Selesai there when no matching live session is connected.",
       })),
       focus: Type.Optional(Type.Boolean({
         description: "For openProjectPaneIfMissing, focus the new Herdr pane. Defaults to true.",
@@ -2380,7 +2720,7 @@ Usage:
 
             return {
               content: [{ type: "text", text: `${currentSection}\n\n${otherSection}` }],
-              details: {},
+              details: { roster: { peers: otherSessions.length, total: sessions.length } },
             };
           } catch (error) {
             return {
@@ -2434,7 +2774,7 @@ Usage:
 
             return {
               content: [{ type: "text", text: `${currentSection}\n\n${otherSection}` }],
-              details: {},
+              details: { roster: { peers: otherSessions.length, total: sessions.length, cwd: filterCwd } },
             };
           } catch (error) {
             return {
@@ -2479,102 +2819,34 @@ Usage:
               details: { error: true },
             };
           }
-          try {
-            if (openProjectPaneIfMissing && !cwd) {
-              return {
-                content: [{ type: "text", text: "openProjectPaneIfMissing requires a target cwd." }],
-                details: { error: true },
-              };
-            }
-            const confirmSend = !replyTo && config.confirmSend && ctx.hasUI;
-            const attachmentText = attachments?.length ? formatAttachments(attachments) : "";
-            if (confirmSend && cwd && openProjectPaneIfMissing) {
-              const confirmed = await ctx.ui.confirm(
-                "Send message",
-                `Send to "${to ?? cwd}":\n\n${message}${attachmentText}`,
-              );
-              if (!confirmed) {
-                return {
-                  content: [{ type: "text", text: "Message cancelled by user" }],
-                  details: {},
-                };
-              }
-            }
-            const target: DeliveryTarget = cwd
-              ? await resolveCwdDeliveryTarget(connectedClient, { to, cwd, openProjectPaneIfMissing, focus, signal: _signal })
-              : { id: await resolveSessionTarget(connectedClient, to) ?? to, label: to };
-            const sendTo = target.id;
-            const targetDisplay = target.projectPane ? target.label : to ?? target.label;
-            if (sendTo === connectedClient.sessionId) {
-              return {
-                content: [{ type: "text", text: "Cannot message the current session" }],
-                details: { error: true },
-              };
-            }
-            const activeReplyMismatch = replyTo ? null : replyTracker.findActiveReplyTargetMismatch(sendTo);
-            if (activeReplyMismatch) {
-              const senderLabel = activeReplyMismatch.from.name || activeReplyMismatch.from.id;
-              return {
-                content: [{ type: "text", text: `This turn is responding to an intercom ask from "${senderLabel}". Use intercom({ action: "reply", message: "..." }) or set replyTo: "${activeReplyMismatch.message.id}". Refusing non-reply send to "${targetDisplay}" to avoid a misdirected reply.` }],
-                details: { error: true, replyTo: activeReplyMismatch.message.id },
-              };
-            }
-            const inferredAsk = replyTo ? null : replyTracker.findUniquePendingAskFrom(sendTo);
-            const effectiveReplyTo = replyTo ?? inferredAsk?.message.id;
-            if (confirmSend && !(cwd && openProjectPaneIfMissing)) {
-              const confirmed = await ctx.ui.confirm(
-                "Send message",
-                `Send to "${targetDisplay}":\n\n${message}${attachmentText}`,
-              );
-              if (!confirmed) {
-                return {
-                  content: [{ type: "text", text: "Message cancelled by user" }],
-                  details: {},
-                };
-              }
-            }
-            const result = await connectedClient.send(sendTo, {
-              text: message,
-              attachments,
-              replyTo: effectiveReplyTo,
-              supersedes,
-              retryOf,
-            });
-            if (!result.delivered) {
-              const errorText = result.reason ?? "Session may not exist or has disconnected.";
-              return {
-                content: [{ type: "text", text: `Message to "${targetDisplay}" was not delivered: ${errorText}` }],
-                details: deliveryDetails(result),
-              };
-            }
-            pi.appendEntry("intercom_sent", {
-              to: targetDisplay,
-              message: { text: message, attachments, replyTo: effectiveReplyTo, supersedes, retryOf },
-              messageId: result.id,
-              timestamp: Date.now(),
-            });
-            if (effectiveReplyTo) {
-              dismissIncomingAsk(effectiveReplyTo);
-            }
+          return deliverMessage(connectedClient, ctx, _signal, {
+            to, cwd, openProjectPaneIfMissing, focus, message, attachments, replyTo, supersedes, retryOf,
+          });
+        }
+
+        case "handover": {
+          if (!to && !cwd) {
             return {
-              content: [{
-                type: "text",
-                text: target.projectPane
-                  ? `Opened Herdr project pane ${target.projectPane.paneId} for ${target.projectPane.projectRoot} and sent message to ${targetDisplay}`
-                  : inferredAsk ? `Reply sent to ${targetDisplay} (inferred from pending ask)` : `Message sent to ${targetDisplay}`,
-              }],
-              details: {
-                ...deliveryDetails(result),
-                ...(effectiveReplyTo ? { replyTo: effectiveReplyTo } : {}),
-                ...(target.projectPane ? { openedProjectPane: true, paneId: target.projectPane.paneId, projectRoot: target.projectPane.projectRoot } : {}),
-              },
+              content: [{ type: "text", text: "Missing 'to' or 'cwd' parameter" }],
+              details: { error: true },
             };
+          }
+          if (replyTo || supersedes || retryOf || attachments?.length) {
+            return {
+              content: [{ type: "text", text: "Handover always sends a new message; replyTo, supersedes, retryOf, and attachments are not supported." }],
+              details: { error: true },
+            };
+          }
+          let handoverText: string;
+          try {
+            handoverText = await buildHandoverText(connectedClient, ctx, { goal: message, crossMachine: Boolean(to?.includes("@")) }, _signal);
           } catch (error) {
             return {
-              content: [{ type: "text", text: `Failed to send: ${getErrorMessage(error)}` }],
+              content: [{ type: "text", text: `Handover failed: ${getErrorMessage(error)}` }],
               details: { error: true },
             };
           }
+          return deliverMessage(connectedClient, ctx, _signal, { to, cwd, openProjectPaneIfMissing, focus, message: handoverText, handover: true });
         }
 
         case "ask": {
@@ -2805,10 +3077,12 @@ Usage:
           };
       }
     },
-    renderCall(args, theme) {
+    renderCall(args, theme, context) {
       const action = typeof args.action === "string" ? args.action : "intercom";
       const target = typeof args.to === "string" && args.to.trim() ? args.to.trim() : undefined;
-      const messagePreview = previewText(args.message, 96);
+      const messageText = context.expanded && typeof args.message === "string"
+        ? args.message
+        : previewText(args.message, 96);
       const attachmentCount = Array.isArray(args.attachments) ? args.attachments.length : 0;
       let text = theme.fg("toolTitle", theme.bold("intercom "));
       text += theme.fg(action === "ask" ? "warning" : action === "reply" ? "success" : "accent", action);
@@ -2818,8 +3092,8 @@ Usage:
       if (attachmentCount > 0) {
         text += " " + theme.fg("dim", `(${attachmentCount} attachment${attachmentCount === 1 ? "" : "s"})`);
       }
-      if (messagePreview) {
-        text += "\n  " + theme.fg("dim", messagePreview);
+      if (messageText) {
+        text += "\n  " + theme.fg("dim", messageText);
       }
       return new Text(text, 0, 0);
     },
@@ -2827,9 +3101,17 @@ Usage:
       if (isPartial) {
         return new Text(theme.fg("warning", "Intercom working..."), 0, 0);
       }
-      const details = result.details as { delivered?: boolean; error?: boolean; messageId?: string; reason?: string } | undefined;
+      const details = result.details as { delivered?: boolean; error?: boolean; messageId?: string; reason?: string; roster?: { peers: number; total: number; cwd?: string } } | undefined;
       const failed = Boolean(context.isError || details?.error === true || details?.delivered === false);
       let text = failed ? theme.fg("error", "✗ ") : theme.fg("success", "✓ ");
+      if (details?.roster && !failed && !context.expanded) {
+        // Collapsed rows are display-only; the model still receives the full roster text.
+        const { peers, total, cwd: rosterCwd } = details.roster;
+        const where = rosterCwd ? ` in ${rosterCwd}` : "";
+        text += theme.fg("text", peers === 0 ? `no other sessions${where}` : `${peers} other session${peers === 1 ? "" : "s"}${where}`);
+        text += theme.fg("dim", ` (${total} connected)`);
+        return new Text(text, 0, 0);
+      }
       text += theme.fg(failed ? "error" : "text", firstTextContent(result));
       if (details?.messageId && !context.expanded) {
         text += theme.fg("dim", ` (${details.messageId.slice(0, 8)})`);
@@ -2924,6 +3206,132 @@ Usage:
     notifyAliasCommand(liveContext, `Session alias set: ${alias}`, "info", commandGeneration);
   }
 
+  async function runHandoverCommand(args: string, ctx: ExtensionContext): Promise<void> {
+    const commandGeneration = runtimeGeneration;
+    const liveContext = getLiveContext(ctx, commandGeneration);
+    if (!liveContext) return;
+    if (!liveContext.hasUI || (liveContext as ExtensionContext & { mode?: string }).mode !== "tui") {
+      notifyAliasCommand(liveContext, "/handover requires the interactive terminal UI; use the intercom tool's handover action instead.", "error", commandGeneration);
+      return;
+    }
+    const input = args.trim();
+    if (!input) {
+      await openHandoverPicker(liveContext, commandGeneration);
+      return;
+    }
+    const target = input.split(/\s+/, 1)[0]!;
+    const goal = input.slice(target.length).trim() || undefined;
+    const isPath = /^(\/|\.\.?\/|~(\/|$))/.test(target);
+    const request = isPath ? { cwd: expandHomePath(target), openProjectPaneIfMissing: true } : { to: target };
+    await performHandover(liveContext, commandGeneration, request, { goal, crossMachine: !isPath && target.includes("@") });
+  }
+
+  async function openHandoverPicker(ctx: ExtensionContext, generation: number, preselectSessionId?: string): Promise<void> {
+    let pickerClient: IntercomClient;
+    try {
+      pickerClient = await ensureConnected("tool");
+    } catch (error) {
+      notifyIfLive(ctx, `Intercom unavailable: ${getErrorMessage(error)}`, "error", generation);
+      return;
+    }
+    if (!getLiveContext(ctx, generation)) return;
+    syncPresenceIdentity(ctx.sessionManager.getSessionId());
+
+    let sessions: SessionInfo[];
+    try {
+      sessions = await pickerClient.listSessions();
+    } catch (error) {
+      notifyIfLive(ctx, `Failed to list sessions: ${getErrorMessage(error)}`, "error", generation);
+      return;
+    }
+    const currentSession = sessions.find((session) => session.id === pickerClient.sessionId);
+    if (!currentSession) {
+      notifyIfLive(ctx, "Current session is missing from intercom session list", "error", generation);
+      return;
+    }
+    if (!getLiveContext(ctx, generation)) return;
+
+    const discoveryDeps = { run: runCommand, herdrBin: process.env.HERDR_BIN_PATH ?? "herdr" };
+    const lister: RemoteSessionLister = {
+      listMachines: () => listSavedMachines(discoveryDeps),
+      listAgents: (machine) => listMachineAgents(machine, discoveryDeps),
+    };
+    const picked = await ctx.ui.custom<HandoverPickerResult | undefined>(
+      (tui, theme, keybindings, done) => new HandoverPicker(tui, theme, keybindings, { currentSession, sessions, lister, preselectSessionId }, done),
+      { overlay: true, overlayOptions: { width: 88 } },
+    ).catch(() => undefined);
+    if (!picked || !getLiveContext(ctx, generation)) return;
+
+    const { target, goal } = picked;
+    if (target.kind === "local") {
+      await performHandover(ctx, generation, { to: target.session.id }, { goal, crossMachine: false });
+      return;
+    }
+    if (target.kind === "remote") {
+      await performHandover(ctx, generation, { to: target.target }, { goal, crossMachine: true });
+      return;
+    }
+    const path = (await ctx.ui.input("Project path for the new session", "~/dev/project"))?.trim();
+    if (!getLiveContext(ctx, generation)) return;
+    if (!path) {
+      notifyIfLive(ctx, "Handover cancelled", "info", generation);
+      return;
+    }
+    await performHandover(ctx, generation, { cwd: expandHomePath(path), openProjectPaneIfMissing: true }, { goal, crossMachine: false });
+  }
+
+  async function performHandover(
+    ctx: ExtensionContext,
+    generation: number,
+    request: Pick<DeliveryRequest, "to" | "cwd" | "openProjectPaneIfMissing">,
+    options: { goal?: string; crossMachine: boolean },
+  ): Promise<void> {
+    let handoverClient: IntercomClient;
+    try {
+      handoverClient = await ensureConnected("tool");
+    } catch (error) {
+      notifyIfLive(ctx, `Intercom unavailable: ${getErrorMessage(error)}`, "error", generation);
+      return;
+    }
+    if (!getLiveContext(ctx, generation)) return;
+
+    const generated = await ctx.ui.custom<{ text: string } | { error: string } | null>((tui, theme, _keybindings, done) => {
+      const loader = new BorderedLoader(tui, theme, "Generating handover...");
+      loader.onAbort = () => done(null);
+      buildHandoverText(handoverClient, ctx, options, loader.signal).then(
+        (text) => done({ text }),
+        (error) => done(loader.signal.aborted ? null : { error: getErrorMessage(error) }),
+      );
+      return loader;
+    });
+    if (!getLiveContext(ctx, generation)) return;
+    if (!generated) {
+      notifyIfLive(ctx, "Handover cancelled", "info", generation);
+      return;
+    }
+    if ("error" in generated) {
+      notifyIfLive(ctx, `Handover failed: ${generated.error}`, "error", generation);
+      return;
+    }
+
+    const edited = await ctx.ui.editor("Edit handover", generated.text);
+    if (!getLiveContext(ctx, generation)) return;
+    if (edited === undefined || !edited.trim()) {
+      notifyIfLive(ctx, "Handover cancelled", "info", generation);
+      return;
+    }
+
+    try {
+      handoverClient = await ensureConnected("tool");
+    } catch (error) {
+      notifyIfLive(ctx, `Intercom unavailable: ${getErrorMessage(error)}`, "error", generation);
+      return;
+    }
+    const result = await deliverMessage(handoverClient, ctx, undefined, { ...request, message: edited, handover: true });
+    const failed = result.details.error === true || result.details.delivered === false;
+    notifyIfLive(ctx, failed ? firstTextContent(result) : `Handover: ${firstTextContent(result)}`, failed ? "error" : "info", generation);
+  }
+
   async function openIntercomOverlay(ctx: ExtensionContext): Promise<void> {
     const overlayGeneration = runtimeGeneration;
     const liveContext = getLiveContext(ctx, overlayGeneration);
@@ -2960,12 +3368,17 @@ Usage:
       return;
     }
 
-    const selectedSession = await ctx.ui.custom<SessionInfo | undefined>(
+    const selection = await ctx.ui.custom<SessionListSelection | undefined>(
       (_tui, theme, keybindings, done) => new SessionListOverlay(theme, keybindings, currentSession, sessions, done),
       { overlay: true, overlayOptions: { width: 88 } }
     ).catch(() => undefined);
 
-    if (!selectedSession || !getLiveContext(ctx, overlayGeneration)) return;
+    if (!selection || !getLiveContext(ctx, overlayGeneration)) return;
+    if (selection.action === "handover") {
+      await openHandoverPicker(ctx, overlayGeneration, selection.session.id);
+      return;
+    }
+    const selectedSession = selection.session;
 
     try {
       overlayClient = await ensureConnected("overlay");
@@ -3008,6 +3421,11 @@ Usage:
     handler: async (args, ctx) => setIntercomAlias(args, ctx),
   });
 
+  pi.registerCommand("handover", {
+    description: "Summarize this session and hand it over to another session (usage: /handover to pick a session, or /handover <target or project path> [next task])",
+    handler: async (args, ctx) => runHandoverCommand(args, ctx),
+  });
+
   pi.registerShortcut("alt+m", {
     description: "Open session intercom",
     handler: async (ctx) => openIntercomOverlay(ctx),