pi-sessions 0.11.0 → 0.11.2

package/README.md

@@ -108,7 +108,7 @@ Use `kind: "user"` or `kind: "subagent"` to filter by session type across the wh
 
 The `session_handoff` tool lets the agent create a child session with a self-contained task. Ask for a direction when you want a visible split, ask for a deferred handoff when you only want the prepared session, or let the agent delegate suitable independent work to a background subagent.
 
-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.
+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.
 
 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.
 

package/extensions/session-handoff/bootstrap-failed-renderer.ts

@@ -0,0 +1,28 @@
+import type { EntryRenderer } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import type { RenderTheme } from "../shared/rendering/theme.ts";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import { HANDOFF_BOOTSTRAP_FAILED_SCHEMA, type HandoffBootstrapFailed } from "./metadata.ts";
+
+export const renderHandoffBootstrapFailedEntry: EntryRenderer = (entry, _options, theme) => {
+  const failure = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_FAILED_SCHEMA, entry.data);
+  if (!failure) {
+    return undefined;
+  }
+
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(presentHandoffBootstrapFailure(failure, theme), 0, 0));
+  return box;
+};
+
+export function presentHandoffBootstrapFailure(
+  failure: HandoffBootstrapFailed,
+  theme: RenderTheme,
+): string {
+  const header = `${theme.fg("error", theme.bold("handoff failed"))} ${theme.fg("muted", "draft generation did not complete")}`;
+  const retry = theme.fg(
+    "dim",
+    "The handoff is retried every time this session starts, until a message is sent.",
+  );
+  return [header, "", theme.fg("toolOutput", failure.error), "", retry].join("\n");
+}

package/extensions/session-handoff/bootstrap.ts

@@ -11,6 +11,7 @@ import {
   findPendingHandoffBootstrap,
   getHandoffMetadataFromEntries,
   HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE,
+  HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE,
   HANDOFF_METADATA_CUSTOM_TYPE,
   HANDOFF_STALE_SESSION_MESSAGE,
   type HandoffBootstrapConsumedReason,
@@ -54,6 +55,7 @@ export async function consumePendingHandoffBootstrap(
     ctx,
     bootstrap,
     scan.entryId,
+    scan.failure !== undefined,
     consumeBootstrap,
     getModelRuntime,
     destinationThinkingLevel,
@@ -66,6 +68,7 @@ async function startChildGeneratedHandoff(
   ctx: ExtensionContext,
   bootstrap: ChildGeneratedHandoffBootstrap,
   bootstrapEntryId: string,
+  hasEarlierFailure: boolean,
   consumeBootstrap: (reason: HandoffBootstrapConsumedReason) => void,
   getModelRuntime: ModelRuntimeProvider,
   destinationThinkingLevel: ThinkingLevel | undefined,
@@ -80,8 +83,13 @@ async function startChildGeneratedHandoff(
     return;
   }
 
+  // An automatic bootstrap exits on its first failure because only an
+  // unattended worker ever reaches that attempt. Every later start is someone
+  // opening the session deliberately, so it latches open for them instead.
+  const exitOnFailure = bootstrap.bootstrapMode === "automatic" && !hasEarlierFailure;
+
   if (!ctx.hasUI) {
-    if (bootstrap.bootstrapMode === "automatic") {
+    if (exitOnFailure) {
       ctx.shutdown();
     }
     return;
@@ -164,8 +172,15 @@ async function startChildGeneratedHandoff(
       { triggerTurn: true },
     );
   } catch (error) {
-    ctx.ui.notify(formatHandoffError(error), "error");
-    if (bootstrap.bootstrapMode === "automatic") {
+    // An exiting bootstrap takes the notification down with it, so the reason
+    // has to live in the transcript instead.
+    const message = formatHandoffError(error);
+    pi.appendEntry(HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE, {
+      bootstrapEntryId,
+      error: message,
+    });
+    ctx.ui.notify(message, "error");
+    if (exitOnFailure) {
       ctx.shutdown();
     }
   }

package/extensions/session-handoff/extract.ts

@@ -1,4 +1,4 @@
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type {
   Api,
   AssistantMessage,
@@ -247,6 +247,13 @@ async function runHandoffExtractionAgent(
       if (capturedArguments) {
         break;
       }
+      // A failed turn carries no refusal to re-prompt: retrying only burns the
+      // remaining attempts and buries the provider's reason behind the generic
+      // "did not return structured context" error.
+      const providerError = findProviderError(session.messages);
+      if (providerError) {
+        throw new Error(`Handoff extraction failed: ${providerError}`);
+      }
     }
   } finally {
     signal?.removeEventListener("abort", abortHandler);
@@ -272,6 +279,14 @@ async function runHandoffExtractionAgent(
   };
 }
 
+function findProviderError(messages: readonly AgentMessage[]): string | undefined {
+  const lastAssistant = messages.findLast((message) => message.role === "assistant");
+  if (lastAssistant?.role !== "assistant" || lastAssistant.stopReason !== "error") {
+    return undefined;
+  }
+  return lastAssistant.errorMessage || "the provider returned an error.";
+}
+
 export function assembleHandoffDraft(
   sessionId: string,
   sessionPath: string | undefined,

package/extensions/session-handoff/install.ts

@@ -10,11 +10,13 @@ import { THINKING_LEVELS } from "../shared/thinking-levels.ts";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
 import { type HandoffBoardServices, openHandoffBoard } from "./board.ts";
 import { consumePendingHandoffBootstrap } from "./bootstrap.ts";
+import { renderHandoffBootstrapFailedEntry } from "./bootstrap-failed-renderer.ts";
 import { HANDOFF_KICKOFF_CUSTOM_TYPE, renderHandoffKickoffMessage } from "./kickoff.ts";
 import type { ClipboardStatus } from "./launch/backend.ts";
 import { resolveSplitLaunchBackend } from "./launch/resolution.ts";
 import { createHandoffLaunchTargets } from "./launch-options.ts";
 import type { HandoffLaunchTarget } from "./launch-target.ts";
+import { HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE } from "./metadata.ts";
 import { openSessionReferencePicker } from "./picker.ts";
 import { SESSION_TOKEN_PREFIX } from "./query.ts";
 import {
@@ -51,6 +53,7 @@ export function installHandoff(
   });
 
   pi.registerMessageRenderer(HANDOFF_KICKOFF_CUSTOM_TYPE, renderHandoffKickoffMessage);
+  pi.registerEntryRenderer(HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE, renderHandoffBootstrapFailedEntry);
   function registerHandoffTool(
     models: readonly Model<Api>[],
     launchTargets: readonly HandoffLaunchTarget[],

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

@@ -59,6 +59,8 @@ export interface HandoffLaunchTarget {
   description?: string | undefined;
   requestResponseDefault: boolean;
   bootstrapMode: "review" | "automatic";
+  /** Unattended children skip the startup trust prompt; watched ones let the user answer it. */
+  approveProjectTrust: boolean;
   /** Subagent launches stamp their child's identity into the child bootstrap. */
   describeSubagentChild?(input: {
     childSessionId: string;
@@ -79,6 +81,7 @@ export function createBackendLaunchTarget(
     ...(description ? { description } : {}),
     requestResponseDefault: false,
     bootstrapMode: "review",
+    approveProjectTrust: false,
     prepareChild() {},
     launch(input) {
       return backend.launch({

package/extensions/session-handoff/metadata.ts

@@ -12,10 +12,11 @@ import {
 export const HANDOFF_METADATA_CUSTOM_TYPE = "pi-sessions.handoff";
 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";
 export const HANDOFF_STALE_SESSION_MESSAGE =
   "Session handoff failed: target session already has user input.";
 export const SESSION_STARTING_MESSAGE =
-  "Target session is still starting. wait for it to show up in session_search, then resend.";
+  "Target session is still starting. wait for session_reachable to report it as live, then resend.";
 
 // A subagent's self-knowledge, stamped into its child-local bootstrap so the
 // child never opens the parent transcript to learn who it is.
@@ -62,6 +63,14 @@ export const HANDOFF_BOOTSTRAP_SCHEMA = Type.Union([
   }),
 ]);
 
+// A bootstrap whose generation failed stays pending so a resume can retry it,
+// but the failure is recorded so the session stops reading as one that is
+// still starting.
+export const HANDOFF_BOOTSTRAP_FAILED_SCHEMA = Type.Object({
+  bootstrapEntryId: Type.String(),
+  error: Type.String(),
+});
+
 export const HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA = Type.Object({
   bootstrapEntryId: Type.String(),
   reason: Type.Union([
@@ -77,6 +86,7 @@ export type HandoffSessionMetadata = Static<typeof HANDOFF_SESSION_METADATA_SCHE
 export type HandoffBootstrap = Static<typeof HANDOFF_BOOTSTRAP_SCHEMA>;
 export type ChildGeneratedHandoffBootstrap = HandoffBootstrap;
 export type HandoffBootstrapConsumed = Static<typeof HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA>;
+export type HandoffBootstrapFailed = Static<typeof HANDOFF_BOOTSTRAP_FAILED_SCHEMA>;
 export type HandoffBootstrapConsumedReason = HandoffBootstrapConsumed["reason"];
 
 export function createHandoffSessionMetadata(
@@ -125,7 +135,7 @@ export function createChildGeneratedHandoffBootstrap(options: {
 }
 
 export type PendingHandoffBootstrapScan =
-  | { kind: "pending"; entryId: string; bootstrap: HandoffBootstrap }
+  | { kind: "pending"; entryId: string; bootstrap: HandoffBootstrap; failure?: string | undefined }
   | { kind: "invalid"; entryId: string };
 
 /**
@@ -137,6 +147,7 @@ export function findPendingHandoffBootstrap(
   branch: readonly SessionEntry[],
 ): PendingHandoffBootstrapScan | undefined {
   const consumedEntryIds = new Set<string>();
+  const failuresByEntryId = new Map<string, string>();
   for (const entry of branch) {
     if (entry.type === "custom_message" && entry.customType === HANDOFF_KICKOFF_CUSTOM_TYPE) {
       const details = safeParseTypeBoxValue(HANDOFF_KICKOFF_DETAILS_SCHEMA, entry.details);
@@ -150,6 +161,12 @@ export function findPendingHandoffBootstrap(
         consumedEntryIds.add(consumed.bootstrapEntryId);
       }
     }
+    if (entry.type === "custom" && entry.customType === HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE) {
+      const failed = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_FAILED_SCHEMA, entry.data);
+      if (failed) {
+        failuresByEntryId.set(failed.bootstrapEntryId, failed.error);
+      }
+    }
   }
 
   for (let i = branch.length - 1; i >= 0; i -= 1) {
@@ -163,9 +180,11 @@ export function findPendingHandoffBootstrap(
     }
 
     const bootstrap = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_SCHEMA, entry.data);
-    return bootstrap
-      ? { kind: "pending", entryId: entry.id, bootstrap }
-      : { kind: "invalid", entryId: entry.id };
+    if (!bootstrap) {
+      return { kind: "invalid", entryId: entry.id };
+    }
+    const failure = failuresByEntryId.get(entry.id);
+    return { kind: "pending", entryId: entry.id, bootstrap, ...(failure ? { failure } : {}) };
   }
 
   return undefined;
@@ -175,10 +194,13 @@ export function findPendingHandoffBootstrap(
  * A session is *starting* when its active branch still carries an unconsumed,
  * well-formed handoff bootstrap: it has been prepared but has not received its
  * kickoff. An invalid bootstrap does not count — the child consumes it and
- * proceeds as an ordinary session rather than kicking off a handoff.
+ * proceeds as an ordinary session rather than kicking off a handoff. Neither
+ * does one whose generation already failed: it stays retryable on resume, but
+ * nothing is starting right now.
  */
 export function isSessionStarting(branch: readonly SessionEntry[]): boolean {
-  return findPendingHandoffBootstrap(branch)?.kind === "pending";
+  const scan = findPendingHandoffBootstrap(branch);
+  return scan?.kind === "pending" && scan.failure === undefined;
 }
 
 /**

package/extensions/session-handoff/spawn.ts

@@ -21,6 +21,7 @@ export function prepareHandoffLaunch(options: {
   parentSessionFile: string;
   title: string;
   model: string | undefined;
+  approveProjectTrust: boolean;
   buildBootstrap: (sessionId: string) => HandoffBootstrap;
   prepareChild?: ((manager: SessionManager, sessionId: string) => void) | undefined;
 }): PreparedHandoff {
@@ -52,6 +53,7 @@ export function prepareHandoffLaunch(options: {
     sessionId: manager.getSessionId(),
     sessionDir: manager.usesDefaultSessionDir() ? undefined : manager.getSessionDir(),
     model: options.model,
+    approveProjectTrust: options.approveProjectTrust,
   });
 
   return { sessionId: manager.getSessionId(), sessionFile, resumeCommand };
@@ -79,6 +81,11 @@ function flushPreparedSession(manager: SessionManager): void {
  * The canonical recovery artifact consumed by launch backends, failure
  * messages, clipboard delivery, and renderers. Self-locating: when the target
  * cwd differs from the parent's, the command starts with `cd <target> &&`.
+ *
+ * Unattended children carry `--approve`, which resolves project trust for that
+ * process without prompting: nobody is watching a detached worker's window, so
+ * a blocked trust selector there stalls the launch indefinitely. The override
+ * is process-scoped and never written to the trust store.
  */
 export function buildPiResumeCommand(options: {
   targetCwd: string;
@@ -86,12 +93,16 @@ export function buildPiResumeCommand(options: {
   sessionId: string;
   sessionDir?: string | undefined;
   model?: string | undefined;
+  approveProjectTrust: boolean;
 }): string {
   const args = ["pi"];
   if (options.sessionDir) {
     args.push("--session-dir", shellQuote(options.sessionDir));
   }
   args.push("--session-id", shellQuote(options.sessionId));
+  if (options.approveProjectTrust) {
+    args.push("--approve");
+  }
   if (options.model) {
     args.push("--model", shellQuote(options.model));
   }

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

@@ -40,14 +40,19 @@ export class HandoffToolComponent implements Component {
       return container.render(width);
     }
 
-    const commandLabel =
-      this.model.result.launch === "deferred"
-        ? formatDeferredCommandLabel(this.clipboardStatus)
-        : "recovery command";
-    container.addChild(new Spacer(1));
-    container.addChild(
-      createLaunchCommandComponent(this.model.result.resumeCommand, commandLabel, this.theme),
-    );
+    // Only a deferred handoff needs its command in the transcript, because the
+    // user is the one who has to run it. A launched child is already running;
+    // the board is where its command belongs.
+    if (this.model.result.launch === "deferred") {
+      container.addChild(new Spacer(1));
+      container.addChild(
+        createLaunchCommandComponent(
+          this.model.result.resumeCommand,
+          formatDeferredCommandLabel(this.clipboardStatus),
+          this.theme,
+        ),
+      );
+    }
     if (this.model.result.degradedFrom) {
       container.addChild(new Spacer(1));
       container.addChild(

package/extensions/session-handoff/tool.ts

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

package/extensions/subagents/launch-target.ts

@@ -21,6 +21,7 @@ export function createSubagentLaunchTarget(
       "'subagent' delegates one task to a detached tmux worker and requests a report by default.",
     requestResponseDefault: true,
     bootstrapMode: "automatic",
+    approveProjectTrust: true,
     describeSubagentChild(input) {
       return {
         childSessionId: input.childSessionId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
@@ -38,20 +38,20 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-agent-core": "^0.82.1",
-    "@earendil-works/pi-ai": "^0.82.1",
-    "@earendil-works/pi-coding-agent": "^0.82.1",
-    "@earendil-works/pi-tui": "^0.82.1",
+    "@earendil-works/pi-agent-core": "^0.83.0",
+    "@earendil-works/pi-ai": "^0.83.0",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
     "@types/node": "^25.6.2",
     "strip-ansi": "^7.2.0",
     "typebox": "^1.1.38",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.0",
     "vitest": "^4.1.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.82.1",
-    "@earendil-works/pi-ai": ">=0.82.1",
-    "@earendil-works/pi-coding-agent": ">=0.82.1",
-    "@earendil-works/pi-tui": ">=0.82.1"
+    "@earendil-works/pi-agent-core": ">=0.83.0",
+    "@earendil-works/pi-ai": ">=0.83.0",
+    "@earendil-works/pi-coding-agent": ">=0.83.0",
+    "@earendil-works/pi-tui": ">=0.83.0"
   }
 }