@jeffober/thatch 0.2.4 → 0.2.6

package/src/opencode/v2.ts

@@ -2,11 +2,15 @@ import type { Plugin } from "@opencode/plugin";
 import { z } from "zod";
 import type { Tool } from "@opencode/schema/tool";
 import type { ToolContext as V2ToolContext } from "@opencode/plugin/promise/tool";
+import type { ThatchDB } from "../db";
 import type { HostCapabilities, PromptPart, ToastInput } from "../capabilities";
 import { createRuntime } from "../runtime";
-import { wrapUpCommandContent } from "../commands";
+import { wrapUpCommandContent, wrapUpCommandDescription } from "../commands";
 import { deriveTitle } from "../extraction";
-import { TOOL_DEFS, trimHostContext, type HostToolContext } from "../tool-defs";
+import { detectRepo, detectWorktreeKind } from "../git";
+import { chatEnabled, loadConfig } from "../config";
+import { EXIT_TAB_CLOSED_EVENT, SESSION_TAB_RPC, TAB_CLOSED_EVENT, TAB_OPENED_EVENT, TOAST_EVENT, buildSubordinatePrompt, tabClosedEventType, tabOpenedEventType } from "../session-tab-shared";
+import { TOOL_DEFS, trimHostContext, type HostToolContext, type SessionTabCloseInput, type SessionTabHost, type SessionTabSpawnInput, type SessionTabSpawnResult } from "../tool-defs";
 
 // The opencode v2 adapter (opencode 2.x, plugin API @opencode/plugin 2.x).
 // Loaded only by v2 hosts - the dual entry (src/index.ts) lazy-imports this
@@ -25,9 +29,9 @@ import { TOOL_DEFS, trimHostContext, type HostToolContext } from "../tool-defs";
 //   array; the runtime's plain strings convert to {type: "text", text}
 //   parts at the boundary.
 // - per-message nudges: the prompt hook computes the turn's injections;
-//   the generate hook appends them to the outbound request's last user
-//   message `content` array (v2 wire Messages have no `parts` field).
-//   Injections stay out of the stored prompt text.
+//   the context hook appends them to the outbound request's user message
+//   that matches the entry's prompt text (v2 wire Messages have no
+//   `parts` field). Injections stay out of the stored prompt text.
 // - noReply deliveries (chat echoes, session-start reminder): v2's prompt
 //   endpoint cannot suppress the model turn, so the runtime gates them off
 //   via capabilities.noReplyDelivery.
@@ -39,17 +43,55 @@ import { TOOL_DEFS, trimHostContext, type HostToolContext } from "../tool-defs";
 //   {type, data, location?}. Filtered client-side the way the v1 host
 //   filters server-side: events resolve to a directory (their own, the
 //   session cache, or session.get) and drop when it is not ours.
-// - toasts, tui commands, session delete/list endpoints:
+// - TUI reach: the ONLY server-to-TUI channel is the rpc event bridge - the
+//   session-tab rpc definition is registered at setup and its events reach
+//   the TUI CLI plugin (the package's ./tui entrypoint), which drives the
+//   tab strip (ui.tabs) and shows toasts (ui.toast). Keymap-command pushes
+//   still have no surface.
+// - wrap-up actions: compact rides session.compact on the promise domain
+//   (upstream #52385, newer than the pinned dev types, so runtime-guarded);
+//   exit records the session's watcher deaths synchronously in the runtime
+//   and then emits the bridge's exit-tab-closed event, which the TUI plugin
+//   turns into closing the session's OWN tab (see exitHost in
+//   buildCapabilities).
+// - toasts ride the bridge's toast event (TUI plugin's ui.toast.show);
+//   extraction-child cleanup rides session.remove (upstream #52387, also
+//   runtime-guarded). tui commands, session list endpoints:
 //   no v2 surface reachable from a plugin - degrades as no-op/null.
 //   fetchStatuses returns {} because the wake gate treats an unknown session
 //   as idle; the event-fed status map inside the runtime does the gating.
 //   Session MESSAGES are readable via session.context (mapped into the v1
-//   shape), so the wrap-up greenlight check works; the compaction TRIGGER
-//   does not (no session.compact on the promise domain).
+//   shape), so the wrap-up greenlight check works.
 
 type V2Context = Plugin.Context;
 type V2Cleanup = Plugin.Cleanup;
 
+// Both ends of the prompt-text binding must reconstruct text the same way:
+// the prompt-session adapter joins outbound prompt parts with this helper,
+// and the context hook joins a wire message's text parts with it before
+// comparing against the stored prompt text. A separator mismatch would
+// silently fail the equality and drop the turn's nudges.
+function joinTextParts(parts: Array<{ text: string }>): string {
+  return parts.map((p) => p.text).join("\n\n");
+}
+
+// Reconstructs a wire message's text for the prompt-text binding. A string
+// content is the common case; multi-part messages join with joinTextParts
+// so the read side agrees with the write side's separator.
+function messageText(message: { content: unknown }): string {
+  if (typeof message.content === "string") return message.content;
+  const parts = (Array.isArray(message.content) ? message.content : []).filter(
+    (p: any) => p?.type === "text",
+  );
+  return joinTextParts(parts);
+}
+
+// The wrap-up exit's tab-close emitter, late-bound in setup (see the
+// tuiBridge holder there). One shape, referenced at the holder, the
+// buildCapabilities seam, and the assignment - a local alias so the payload
+// shape has a single drift point in this file.
+type ExitTabCloseEmitter = (data: { sessionID: string }) => Promise<unknown>;
+
 // Raw setup function: the dual entry (src/index.ts) owns the plugin id and
 // the merged default export; this adapter only implements the v2 setup.
 export async function setup(context: V2Context): Promise<V2Cleanup | void> {
@@ -69,15 +111,27 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   // differs from this instance's directory whenever opencode is launched
   // below the project root. Their events would never pass the directory
   // filter, so they are forwarded by ID: sessionCreate records every child
-  // here, and the pump lets their events through.
+  // here, and the pump lets their events through. Ids are never removed
+  // (children are deleted, but their id never recurs and the set dies with
+  // this activation - only a long-lived instance grows it).
   const childSessions = new Set<string>();
 
   // Tool executions currently running against this instance's runtime (see
   // the counter in the tool execute wrapper below).
   let inflightTools = 0;
 
-  const capabilities = buildCapabilities(context, worktree, childSessions);
-  const runtime = await createRuntime({ capabilities, directory, worktree });
+  // TUI-bridge holder: the wrap-up exit emits the exit-tab-closed rpc event
+  // (the TUI plugin closes the session's own tab) and every runtime toast
+  // rides the toast event - both through this late-bound holder, because
+  // capabilities are built before the rpc registration exists. Assigned when
+  // the registration wires (below); undefined forever on an SDK floor
+  // without the rpc surface, which both emitters' guards degrade.
+  const tuiBridge: {
+    emitExitTabClose?: ExitTabCloseEmitter;
+    emitToast?: (toast: ToastInput) => Promise<unknown>;
+  } = {};
+  const capabilities = buildCapabilities(context, worktree, childSessions, tuiBridge);
+  const runtime = await createRuntime({ capabilities, directory, worktree, v2Tools: true });
   // Seed the forwarding set from rehydrated child bookkeeping: after a
   // reload, an in-flight extraction child's maps come back from the journal,
   // but this NEW adapter instance's childSessions set starts empty - without
@@ -85,6 +139,51 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   // (the below-root launch case).
   for (const id of runtime.childSessionIds()) childSessions.add(id);
 
+  // Session-tab surface: register the rpc definition once per activation and
+  // wire the host flow into the shared CoreContext (post-construction - the
+  // seam closes over both the runtime's db and the plugin context; see
+  // CoreContext.sessionTabHost in tool-defs.ts). The events are the ONLY
+  // server-to-TUI channel on v2: the TUI CLI plugin (the package's ./tui
+  // entrypoint) consumes them and calls ui.tabs.open. A TUI that is absent
+  // (headless run, still connecting) simply never acts on them.
+  //
+  // SDK-floor guard: the rpc surface is newer than some @opencode/plugin
+  // builds. An absent rpc domain must not crash setup - degrade by leaving
+  // the seam unwired; the session_tab tools refuse cleanly through it
+  // ("did not wire the session-tab surface") like any other unwired host.
+  const tabRegistration = typeof context.rpc?.register === "function"
+    ? await context.rpc.register(SESSION_TAB_RPC, {})
+    : undefined;
+  if (tabRegistration) {
+    const emitTabOpened = (data: { sessionID: string; directory: string }) =>
+      tabRegistration.events.emit(TAB_OPENED_EVENT, data);
+    // The session_tab_close tool's confirmed-close emitter: the pump
+    // translates this event into the runtime's death path, so it is the
+    // tool's only route to that bookkeeping.
+    const emitTabClosed = (data: { sessionID: string; chatName: string | null }) =>
+      tabRegistration.events.emit(TAB_CLOSED_EVENT, data);
+    // The wrap-up exit's own emitter: TUI-only (the runtime records the
+    // exit's deaths synchronously before the action fires, so the pump
+    // deliberately never translates this one).
+    tuiBridge.emitExitTabClose = (data) => tabRegistration.events.emit(EXIT_TAB_CLOSED_EVENT, data);
+    // Every runtime toast rides this emitter (alerts, extraction metrics,
+    // chat registration, blocked wrap-ups) - TUI-only by nature. The spread
+    // widens the interface into a plain object type: the rpc emit's
+    // schema-inferred input wants an index signature, which interfaces
+    // never carry.
+    tuiBridge.emitToast = (toast) => tabRegistration.events.emit(TOAST_EVENT, { ...toast });
+    runtime.coreContext.sessionTabHost = buildSessionTabHost({
+      context,
+      directory,
+      db: runtime.coreContext.db,
+      emitTabOpened,
+      emitTabClosed,
+      debug: runtime.debug,
+    });
+  } else {
+    console.error("[thatch] opencode v2 rpc surface unavailable - session_tab tools will report unwired");
+  }
+
   // Tool registration: the same CoreContext the v1 adapter feeds to
   // createTools, registered through the v2 ToolEditor instead.
   //
@@ -160,12 +259,34 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   //   (the v1 contract); v2's system parts are { type: "text", text }
   //   objects, so convert at the boundary.
   // - per-turn nudges: append the prompt hook's stored injections to the
-  //   OUTBOUND request's last user message. The stored user message stays
-  //   clean (v1 delivered nudges as TUI-hidden synthetic parts; v2's prompt
-  //   text IS the stored message), and the request is rebuilt per round
-  //   trip, so injecting here reproduces v1's persistent-synthetic-part
-  //   semantics: the model sees the nudges on every call of the turn.
-  const pendingInjections = new Map<string, string[]>();
+  //   OUTBOUND request's user message whose text matches the entry's
+  //   stored prompt (see the binding check below). The stored user message
+  //   stays clean (v1 delivered nudges as TUI-hidden synthetic parts; v2's
+  //   prompt text IS the stored message), and the request is rebuilt per
+  //   round trip, so injecting here reproduces v1's
+  //   persistent-synthetic-part semantics: the model sees the nudges on
+  //   every call of the turn.
+  // Per-turn nudge injections, keyed by session, then by the prompt text
+  // they were computed from. Each entry is bound to that text: the context
+  // hook injects an entry only when the request contains a user message
+  // whose text equals it. A bare sessionID-keyed entry that outlives its
+  // turn (the prompt hook missed or failed on a later message) replays a
+  // stale nudge block onto a message it was never computed for - deleted
+  // predictions surfaced as current with their old confidence labels (the
+  // October 2026 staleness report).
+  //
+  // The per-session set holds a small bounded number of entries (oldest
+  // evicted) so a prompt queued mid-turn keeps its own fresh entry instead
+  // of evicting the running turn's: the running turn's remaining rounds
+  // still match their own prompt, and the queued prompt's turn matches
+  // its own. A prompt whose nudge computation comes up empty clears the
+  // session's whole set - an entry left behind would match its own prompt
+  // text in the session HISTORY of later requests and replay a stale block
+  // there - so a queued prompt with no nudges drops the running turn's
+  // remaining-round block. That cost is smaller than the staleness it
+  // prevents; opencode-plugin.md discloses it.
+  const PENDING_INJECTION_CAP = 3;
+  const pendingInjections = new Map<string, Map<string, { promptText: string; injections: string[] }>>();
   const registerSystem = await context.session.hook(
     "context",
     async (request: { sessionID: string; system: unknown[]; messages?: any[] }) => {
@@ -174,16 +295,51 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
       for (const part of pushed) {
         request.system.push(typeof part === "string" ? { type: "text", text: part } : part);
       }
-      const injections = pendingInjections.get(request.sessionID);
-      if (!injections?.length) return;
-      const lastUser = [...(request.messages ?? [])].reverse().find((m) => m?.role === "user");
-      if (!lastUser) return;
+      const pending = pendingInjections.get(request.sessionID);
+      if (!pending?.size) return;
+      // Binding check: a stored v2 user message IS its prompt text (the
+      // prompt hook's injections are computed from it), so text equality
+      // identifies the message an entry belongs to. Wire message ids are
+      // optional on the v2 Message schema and cannot be relied on here.
+      //
+      // The match searches the request's user messages for the LAST one
+      // whose joined text equals the entry's prompt - it is not simply the
+      // request's last user message. Sibling context hooks (opencode's plan
+      // plugin) splice their own user-role reminder into the request
+      // mid-turn: BEFORE the prompt when the request's last message is
+      // user-role, but AT THE TAIL when it is not (mid-turn rounds), which
+      // would make the reminder the last user message, fail the equality,
+      // and silently drop every nudge for the turn. Injecting into the
+      // prompt's own message is v1's persistent-synthetic-part semantics.
+      //
+      // Entries are tried newest first: when several are pending for the
+      // session, the latest prompt-hook run wins a text match.
+      //
+      // Text equality is the tightest binding available here, not an
+      // airtight one: an identical prompt re-submitted after a missed
+      // prompt hook still matches and replays. The next prompt-hook run
+      // that fires is the recovery.
+      let target: any;
+      let matched: { promptText: string; injections: string[] } | undefined;
+      for (const entry of [...pending.values()].reverse()) {
+        target = [...(request.messages ?? [])]
+          .reverse()
+          .find((m) => m?.role === "user" && messageText(m) === entry.promptText);
+        if (target) {
+          matched = entry;
+          break;
+        }
+      }
+      if (!matched) {
+        runtime.debug("v2:hook:context", `session=${request.sessionID} no user message matches a stored prompt; skipping injections`);
+        return;
+      }
       // v2's wire Message carries parts in `content: Array<ContentPart>` -
       // it has no `parts` field, so injecting there would write a stray
       // property the provider formatter never reads (silent nudge loss).
-      const content = Array.isArray(lastUser.content) ? lastUser.content : (lastUser.content = []);
-      for (const text of injections) content.push({ type: "text", text });
-      runtime.debug("v2:hook:context", `session=${request.sessionID} injected=${injections.length} messages=${request.messages?.length}`);
+      const content = Array.isArray(target.content) ? target.content : (target.content = []);
+      for (const text of matched.injections) content.push({ type: "text", text });
+      runtime.debug("v2:hook:context", `session=${request.sessionID} injected=${matched.injections.length} messages=${request.messages?.length}`);
     },
   );
 
@@ -202,12 +358,29 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
         );
       } catch (err) {
         console.error(`[thatch] v2 prompt hook failed: ${err}`);
+        // The hook owns no fresh entry for this prompt; a retained one
+        // belongs to a superseded prompt and would replay on an identical
+        // re-submission. Drop the session's whole set.
+        pendingInjections.delete(request.sessionID);
         return;
       }
       const injections = parts.slice(1).map((part) => part.text);
       if (injections.length > 0) runtime.debug("v2:hook:prompt", `session=${request.sessionID} injections=${injections.length}`);
-      if (injections.length > 0) pendingInjections.set(request.sessionID, injections);
-      else pendingInjections.delete(request.sessionID);
+      if (injections.length > 0) {
+        const entries = pendingInjections.get(request.sessionID) ?? new Map();
+        if (!entries.has(request.prompt.text) && entries.size >= PENDING_INJECTION_CAP) {
+          // Bounded set: evict the oldest entry (insertion order).
+          entries.delete(entries.keys().next().value!);
+        }
+        entries.set(request.prompt.text, { promptText: request.prompt.text, injections });
+        pendingInjections.set(request.sessionID, entries);
+      } else {
+        // A prompt that produced no nudges clears the session's whole set:
+        // an entry left behind would match its own prompt text in the
+        // session history of later requests and replay a stale block there.
+        // See the pendingInjections comment above for the disclosed cost.
+        pendingInjections.delete(request.sessionID);
+      }
     },
   );
 
@@ -239,10 +412,9 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
     for (const kind of ["compact", "exit"] as const) {
       editor.add({
         name: `thatch/${kind}`,
-        description:
-          kind === "compact"
-            ? "Flush thatch persistence, check for loose ends, then compact if clear"
-            : "Flush thatch persistence, check for loose ends, then exit opencode if clear",
+        // Shared with the v1 command file's frontmatter so the two hosts'
+        // menu descriptions cannot drift.
+        description: wrapUpCommandDescription(kind),
         // The user's typed arguments ride invocation.prompt (a
         // PromptInput.Prompt with a text field). v1's host expanded
         // $ARGUMENTS from the command file; v2's session.prompt does no
@@ -301,11 +473,44 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
             location?: { directory?: string };
           };
           const data = located.data ?? {};
-          if (data.sessionID && located.location?.directory) sessionDirs.set(data.sessionID, located.location.directory);
-          if (data.sessionID && data.location?.directory) sessionDirs.set(data.sessionID, data.location.directory);
+          // rpc events (the session-tab bridge) stamp the PUBLISHING
+          // instance's location, not the session's - caching a tab event's
+          // location would pin the subordinate's sessionID to the
+          // coordinator's directory, and its later location-less execution
+          // events would route to the wrong instance (or be dropped by the
+          // right one). The tab-opened payload's directory IS authoritative
+          // (the subordinate's final, post-move directory) and is cached
+          // explicitly below.
+          const fromRpc = located.type.startsWith("rpc.");
+          if (!fromRpc && data.sessionID && located.location?.directory) sessionDirs.set(data.sessionID, located.location.directory);
+          if (!fromRpc && data.sessionID && data.location?.directory) sessionDirs.set(data.sessionID, data.location.directory);
+          if (located.type === tabOpenedEventType) {
+            const opened = (data ?? {}) as { sessionID?: string; directory?: string };
+            if (opened.sessionID && opened.directory) sessionDirs.set(opened.sessionID, opened.directory);
+          }
           let eventDir = located.location?.directory ?? (data.sessionID ? sessionDirs.get(data.sessionID) : undefined);
           if (!eventDir && data.sessionID) eventDir = await resolveSessionDir(data.sessionID);
           runtime.debug("v2:pump", `event ${located.type} dir=${eventDir} self=${directory}`);
+          if (located.type === tabClosedEventType) {
+            // The session-tab tool's confirmed tab close: translated here
+            // rather than in translateEvent because the payload shape is
+            // tab-domain, and the death path is runtime-domain. Routed by
+            // the CLOSED session's own location, never the event's: the rpc
+            // event carries the publishing (coordinator) instance's
+            // directory, while the watchers and status bookkeeping live in
+            // the instance that owns the session (its post-move location).
+            // A later located event repairs the cache; resolve live when
+            // nothing is cached.
+            const closed = (data ?? {}) as { sessionID?: string; chatName?: string | null };
+            if (closed.sessionID) {
+              let closedDir = sessionDirs.get(closed.sessionID);
+              if (!closedDir) closedDir = await resolveSessionDir(closed.sessionID);
+              if (eventMatchesInstance(closedDir, closed.sessionID, directory, childSessions)) {
+                await runtime.onEvent({ type: "session.tab_closed", properties: { sessionID: closed.sessionID, chatName: closed.chatName ?? null } });
+              }
+            }
+            continue;
+          }
           if (eventMatchesInstance(eventDir, data.sessionID, directory, childSessions)) {
             for (const translated of translateEvent(located)) {
               await runtime.onEvent(translated);
@@ -346,6 +551,7 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
     registerPrompt.dispose();
     registerCompaction.dispose();
     registerCommands.dispose();
+    tabRegistration?.dispose();
     await runtime.dispose();
   };
 }
@@ -506,14 +712,161 @@ export function translateEvent(located: { type: string; data?: any }): { type: s
   }
 }
 
+/**
+ * The session-tab host flow - everything behind the CoreContext.sessionTabHost
+ * seam, host-executed end to end (the model supplies only the args; see the
+ * host-owned-handshake rule: no ids cross a prompt boundary). Order is
+ * load-bearing (docs/dev/features/session-tabs.md, "How it works"):
+ *
+ *   create -> move -> register subordinate -> emit tab-opened -> prompt
+ *
+ * (The calling session's chat name is resolved by the tool definition - it
+ * has the db handle and the session context.)
+ *
+ * The emit runs AFTER the move: the event routes by THIS instance's location
+ * (the coordinator's directory) regardless of the session's directory, so
+ * tab placement is identical either way, and a failed move leaves no
+ * stranded open tab. The move targets an idle session, so its default
+ * "steer" delivery applies immediately - the subordinate's whole first turn
+ * runs in its final directory.
+ *
+ * The subordinate is chat-registered deliberately - participant semantics,
+ * like an explicit chat_register; it is NEVER marked machinery, and its
+ * title cannot collide with the machinery title (validateTitle rejects it).
+ */
+function buildSessionTabHost(input: {
+  context: V2Context;
+  /** This instance's directory - the coordinator session's cwd. */
+  directory: string;
+  db: ThatchDB;
+  emitTabOpened: (data: { sessionID: string; directory: string }) => Promise<unknown>;
+  emitTabClosed: (data: { sessionID: string; chatName: string | null }) => Promise<unknown>;
+  debug(tag: string, message: string): void;
+}): SessionTabHost {
+  return {
+    directory: input.directory,
+    spawnSubordinate: async (spec: SessionTabSpawnInput): Promise<SessionTabSpawnResult> => {
+      const worktreeDir = typeof spec.worktree === "string" ? spec.worktree : undefined;
+      const isWorktreeFlow = worktreeDir !== undefined;
+      const createDirectory = isWorktreeFlow ? input.directory : spec.directory;
+      const finalDirectory = worktreeDir ?? spec.directory;
+      // Failure narration for the error below: a mid-flow throw (move
+      // refused, prompt endpoint down) must leave the calling model the
+      // session id and what already happened, or the created session is
+      // stranded with no way to name it - there is no session delete on
+      // the v2 surface, so rollback is not an option either.
+      const steps: string[] = [];
+      let sessionID: string | undefined;
+      let chatName: string | null = null;
+      try {
+        const created = await input.context.session.create({
+          title: spec.title,
+          metadata: {
+            thatch: {
+              coordinatedBy: spec.coordinatorChatName,
+              coordinatorSessionID: spec.coordinatorSessionID,
+              ...(worktreeDir !== undefined ? { worktree: worktreeDir } : {}),
+            },
+          },
+          location: { directory: createDirectory },
+        });
+        sessionID = created.id;
+        steps.push(`created session ${sessionID ?? "(no id returned)"}`);
+        if (worktreeDir !== undefined) {
+          await input.context.session.move({ sessionID, directory: worktreeDir });
+          steps.push(`moved to ${worktreeDir}`);
+        }
+        // Pre-register the subordinate AFTER the move, so the roster row
+        // records the session's FINAL directory (right repo slug, right
+        // worktree kind) and a failed move leaves no row behind. Deliberate
+        // participant semantics - like an explicit chat_register, never marked
+        // machinery - so the response carries its chat name and the
+        // coordinator's first chat_send resolves; the later auto-register
+        // converges (same id, same name). Gated on the chat-enabled config
+        // like every other registration path: with chat off, the tool
+        // response reports no chat name and advertises no supervision.
+        const repo = await detectRepo(finalDirectory);
+        const registered = chatEnabled(loadConfig().config)
+          ? input.db.registerChatSession(
+              sessionID,
+              repo,
+              null,
+              "opencode",
+              null,
+              detectWorktreeKind(finalDirectory),
+            )
+          : { ok: false as const, error: "chat disabled in config" };
+        if (registered.ok) chatName = registered.name;
+        steps.push(registered.ok ? `registered in chat as ${registered.name}` : "chat registration skipped");
+        input.debug(
+          "session-tab",
+          `created ${sessionID} dir=${finalDirectory} repo=${repo} chat=${registered.ok ? registered.name : registered.error}`,
+        );
+        // The payload's directory is the subordinate's FINAL (post-move)
+        // directory, not this instance's: the TUI guard routes by the event
+        // envelope's location, while the pump caches this field so the
+        // subordinate's later location-less execution events resolve to the
+        // instance that owns it.
+        await input.emitTabOpened({ sessionID, directory: finalDirectory });
+        steps.push("tab-opened emitted");
+        await input.context.session.prompt({
+          sessionID,
+          text: buildSubordinatePrompt(spec.coordinatorChatName, spec.prompt),
+        });
+        steps.push("task prompt delivered");
+        return { sessionID, chatName, directory: finalDirectory };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `session_tab spawn failed: ${reason}. Completed steps: ${steps.length > 0 ? steps.join("; ") : "none"}.` +
+            (sessionID
+              ? ` The session ${sessionID} was created and still exists - name it in your report so it can be recovered (sessions list, or thatch_session_tab_close${chatName ? ` by chat name ${chatName}` : ""}).`
+              : " No session was created."),
+        );
+      }
+    },
+    closeTab: async (spec: SessionTabCloseInput): Promise<void> => {
+      await input.emitTabClosed({ sessionID: spec.sessionID, chatName: spec.chatName });
+      input.debug("session-tab", `tab-close emitted for ${spec.sessionID} (${spec.chatName ?? "unnamed"})`);
+    },
+  };
+}
+
+// Runtime guard for promise-domain members newer than the pinned dev types
+// (compact - upstream #52385; remove - #52387): a typed call fails tsc
+// against the pin, and an unguarded cast crashes on an older host. Returns
+// the member as a callable, or undefined on the floor - the CALLER owns the
+// degrade (a log for user-requested actions like compact; silence for
+// best-effort ones like the child cleanup). The rpc registration guard in
+// setup is the same idiom at domain granularity and stays inline: it gates
+// a whole registration, not one call.
+export function optionalDomainMethod(
+  domain: object,
+  method: string,
+): ((input: unknown) => Promise<unknown>) | undefined {
+  const fn = (domain as Record<string, unknown>)[method];
+  return typeof fn === "function" ? (fn as (input: unknown) => Promise<unknown>) : undefined;
+}
+
 // The HostCapabilities implementation over the v2 promise context. Every
 // operation the v2 surface lacks degrades as a no-op or null - the shared
 // runtime's callers treat those results as best-effort and log, never crash.
-function buildCapabilities(context: V2Context, worktree: string, childSessions: Set<string>): HostCapabilities {
+function buildCapabilities(
+  context: V2Context,
+  worktree: string,
+  childSessions: Set<string>,
+  tuiBridge: {
+    emitExitTabClose?: ExitTabCloseEmitter;
+    emitToast?: (toast: ToastInput) => Promise<unknown>;
+  },
+): HostCapabilities {
   // Typed against the SDK's own SessionDomain: the shape errors the
   // original cast (as unknown as {...}) suppressed are exactly what the
-  // review caught (message.list and compact do not exist here; get takes
-  // {sessionID}). Let the typecheck keep holding that line.
+  // review caught (message.list does not exist here; get takes
+  // {sessionID}). compact and remove DO exist on newer SDK builds but not
+  // on the pinned dev types - both calls go through optionalDomainMethod
+  // (above). Let the typecheck keep holding that line for the pinned
+  // surface.
   const session = context.session;
 
   return {
@@ -538,14 +891,20 @@ function buildCapabilities(context: V2Context, worktree: string, childSessions:
       childSessions.add(id);
       return { id };
     },
-    // No delete on the v2 SessionDomain: extraction child sessions are not
-    // cleaned up on v2 (documented gap; the bookkeeping maps still keep the
-    // claim/completion lifecycle consistent). Two user-visible consequences: the session
-    // picker accumulates one thatch-extraction entry per extraction, and
-    // "continue last session" (-c) logic that picks the newest top-level
-    // session will land in an extraction child after any session that
-    // triggered extraction, because the child is top-level and newer.
-    sessionDelete: async () => {},
+    // Extraction child cleanup: upstream exposed session.remove on the
+    // promise domain (#52387), the same era as compact - guarded the same
+    // way (optionalDomainMethod; the pinned dev types predate the surface).
+    // An older host keeps the documented gap: the session picker accumulates
+    // one thatch-extraction entry per extraction, and "continue last session"
+    // (-c) logic that picks the newest top-level session lands in an
+    // extraction child after any session that triggered extraction,
+    // because the child is top-level and newer.
+    sessionDelete: async (id: string) => {
+      const remove = optionalDomainMethod(session, "remove");
+      // Best-effort by the caller's contract: the floor degrades silently.
+      if (!remove) return;
+      await remove({ sessionID: id });
+    },
     promptSession: async (sessionID, body, _mode) => {
       // v2's prompt endpoint takes text, not parts, and has no synthetic /
       // noReply semantics. Nudge injections ride the prompt hook.
@@ -556,7 +915,7 @@ function buildCapabilities(context: V2Context, worktree: string, childSessions:
       // prompt); v2's prompt enqueues the message and returns while the
       // model turn runs asynchronously, so the extraction background flag
       // degrades: both modes enqueue the same way.
-      const text = body.parts.map((part) => part.text).join("\n\n");
+      const text = joinTextParts(body.parts);
       if (!body.noReply && body.parts.length > 0 && body.parts.every((part) => part.synthetic)) {
         await session.synthetic({ sessionID, text });
         return;
@@ -571,36 +930,51 @@ function buildCapabilities(context: V2Context, worktree: string, childSessions:
     },
     sessionList: async () => null,
     sessionMessages: async (id) => {
-      // The v2 promise domain has no message-list endpoint (no
-      // `message` accessor and no compact/remove in the SessionDomain Pick).
+      // The pinned promise domain has no message-list endpoint (no `message`
+      // accessor; compact/remove exist on newer SDK builds but not here).
       // `session.context` IS exposed and returns the session's message list
       // (Array<SessionMessageInfo>); map into the v1 shape the wrap-up
       // greenlight check reads.
       const result = await session.context({ sessionID: id });
       return mapSessionContextMessages(result);
     },
-    showToast: async (_toast: ToastInput) => {
-      // No toast publish path reachable from the promise context (the
-      // tui.toast.show event has no producer surface here). A `tui`
-      // companion plugin entrypoint (ui.toast.show) is the known lift
-      // candidate - not yet wired. Degrades.
+    showToast: async (toast: ToastInput) => {
+      // The toast rpc event is the only TUI feedback channel on v2 - the
+      // TUI plugin's ui.toast.show. Best-effort by contract (the runtime's
+      // call sites catch-and-ignore): a TUI-less environment (headless run,
+      // still connecting) or an rpc-less SDK floor simply never shows it,
+      // and that is the correct silent degrade, not an error.
+      const emit = tuiBridge.emitToast;
+      if (!emit) return;
+      await emit(toast);
     },
-    compactSession: async () => {
-      // No compaction trigger is reachable from the promise context: the
-      // SessionDomain Pick has no session.compact, and the built-in
-      // /compact is a TUI palette action calling the server endpoint
-      // directly (the server command registry only knows config/plugin-
-      // registered names). The compact wrap-up still runs its checklist
-      // and flush; only the automatic compaction itself degrades.
-      console.error("[thatch] v2: compaction trigger unavailable; wrap-up checklist ran, compact skipped");
+    compactSession: async (sessionID: string) => {
+      // Upstream exposed session.compact on the promise SessionDomain
+      // (#52385) - the same core compaction the built-in /compact runs.
+      // The pinned dev types predate that surface, so the call goes through
+      // optionalDomainMethod: an older host degrades to a logged no-op (the
+      // wrap-up checklist and flush still ran).
+      const compact = optionalDomainMethod(session, "compact");
+      if (!compact) {
+        console.error("[thatch] v2: compaction trigger unavailable; wrap-up checklist ran, compact skipped");
+        return;
+      }
+      await compact({ sessionID });
     },
-    exitHost: async () => {
-      // No TUI surface on v2; the exit wrap-up's checklist and flush run,
-      // the exit itself does not. When upstream restores a publish path
-      // (or the `tui` companion entrypoint's ui.tabs.close is wired),
-      // the right v2 target closes THIS session's tab, not app.exit - on
-      // a shared daemon app.exit would take down every tab. Tracked in
-      // anomalyco/opencode#50984.
+    exitHost: async (sessionID: string) => {
+      // Tab-scoped close (the close anomalyco/opencode#50984 asks for):
+      // the daemon hosts every tab, so app.exit would take down unrelated
+      // sessions. This emit is TUI-only - the runtime records the
+      // session's watcher deaths synchronously BEFORE calling here, and
+      // the pump deliberately never translates this event (a second
+      // death pass would erase the durable death row the first one
+      // wrote).
+      const emit = tuiBridge.emitExitTabClose;
+      if (!emit) {
+        console.error("[thatch] v2: rpc surface unavailable; wrap-up checklist ran, tab close skipped");
+        return;
+      }
+      await emit({ sessionID });
     },
   };
 }