@hueyexe/opencode-ensemble 0.16.1 → 0.18.0

package/src/tools/team-spawn.ts

@@ -2,7 +2,9 @@ import type { ToolDeps, PermissionRule } from "../types"
 import { validateMemberName } from "../util"
 import { requireLead } from "./shared"
 import { claimTask } from "./team-claim"
-import { sendMessage } from "../messaging"
+import { notifyLead } from "../notify"
+import { releaseMemberTasks } from "../tasks"
+import { parseModelId } from "../member-model"
 import { log } from "../log"
 import type { EnsembleConfig } from "../config"
 import { getTeamResourceParts, teamWorktreeName } from "./merge-helper"
@@ -10,13 +12,6 @@ import { getTeamResourceParts, teamWorktreeName } from "./merge-helper"
 /** Tracks consecutive spawn failures per team for circuit breaker. */
 export const spawnFailures = new Map<string, { count: number; lastError: string }>()
 
-/** Parse "provider/model" string into { providerID, modelID } for the SDK. */
-function parseModelId(model: string): { providerID: string; modelID: string } | undefined {
-  const slash = model.indexOf("/")
-  if (slash <= 0 || slash === model.length - 1) return undefined
-  return { providerID: model.slice(0, slash), modelID: model.slice(slash + 1) }
-}
-
 /**
  * Resolve which model to use for a spawned agent.
  * Priority: explicit arg > modelsByAgent > rotation/random > defaultModel > undefined.
@@ -152,7 +147,21 @@ export async function executeTeamSpawn(
   // Permission rules on session.create are the hard gate (server-enforced).
   // For read-only agents, deny write tools and explicitly allow team tools.
   // For all agents with worktrees, allowlist the worktree path for edit/bash.
-  const TEAM_TOOLS = ["team_message", "team_broadcast", "team_tasks_list", "team_tasks_add", "team_tasks_complete", "team_claim"] as const
+  // The 9 member-accessible tools per the documented tool table: the 6 worker
+  // tools plus the 3 inspection tools (team_results/team_status/team_view —
+  // any member). Caught live 2026-09-15: teammates could not read each
+  // other's messages because team_results was missing from this list.
+  const TEAM_TOOLS = [
+    "team_message",
+    "team_broadcast",
+    "team_tasks_list",
+    "team_tasks_add",
+    "team_tasks_complete",
+    "team_claim",
+    "team_results",
+    "team_status",
+    "team_view",
+  ] as const
   const permission: PermissionRule[] = []
 
   if (worktreeDir) {
@@ -175,6 +184,12 @@ export async function executeTeamSpawn(
     ...TEAM_TOOLS.map(t => ({ permission: t, pattern: "*", action: "allow" as const })),
   )
 
+  // Code Mode is the invocation path for plugin tools on V2 — without this,
+  // read-only agents (deny-all policies like explore's) cannot reach any
+  // team tool. Safe: nested calls inside execute still enforce their own
+  // permissions, so explore stays read-only.
+  permission.push({ permission: "execute", pattern: "*", action: "allow" })
+
   // Create child session — bind to workspace if available (server-enforced CWD isolation).
   // Falls back to no workspace binding if workspace.create failed.
   let childSessionId: string | undefined
@@ -231,6 +246,12 @@ export async function executeTeamSpawn(
     [teamInfo.teamId, args.name, childSessionId, agent, resolvedModel ?? null, args.prompt, worktreeDir, worktreeBranch, workspaceId, planApproval, now, now]
   )
 
+  // Row is inserted as 'busy' directly -- there is no ready->busy status-event
+  // transition for a fresh spawn, so the watchdog's usual hook point never fires.
+  // Record the baseline here instead, or a member stalled on its first action
+  // is invisible to checkStalled() until its first step-finish event lands.
+  deps.progressTracker.recordBusyStart(childSessionId)
+
   // Register in memory
   deps.registry.register(teamInfo.teamId, args.name, childSessionId)
 
@@ -396,7 +417,7 @@ export async function executeTeamSpawn(
       // Release any task auto-claimed for this teammate so it returns to the pool.
       if (claimedTaskContent) {
         deps.db.run(
-          "UPDATE team_task SET status = 'pending', assignee = NULL, time_updated = ? WHERE id = ? AND assignee = ?",
+          "UPDATE team_task SET status = 'pending', assignee = NULL, time_updated = ? WHERE id = ? AND assignee = ? AND status = 'in_progress'",
           [Date.now(), args.claim_task, args.name]
         )
       }
@@ -414,12 +435,12 @@ export async function executeTeamSpawn(
         variant: "error",
         duration: 8000,
       }).catch(() => { /* TUI may not be available */ })
-      sendMessage(deps.db, {
-        teamId: teamInfo.teamId,
-        from: "system",
-        to: "lead",
-        content: `Teammate "${args.name}" failed to start and was removed${modelInfo}. Error: ${errMsg}. You may retry the spawn.`,
-      })
+      notifyLead(
+        deps.client,
+        deps.db,
+        teamInfo.teamId,
+        `Teammate "${args.name}" failed to start and was removed${modelInfo}. Error: ${errMsg}. You may retry the spawn.`,
+      )
     } catch { /* rollback failed — watchdog will clean up stale member */ }
   })
 

package/src/tools/team-status.ts

@@ -4,8 +4,28 @@ import { requireTeamMember } from "./shared"
 /** Tracks the last time team_status was called per team ID (epoch ms). */
 export const lastCallTime = new Map<string, number>()
 
+/** Tracks the state marker (see computeStateMarker) observed at the last real read per team. */
+export const lastKnownState = new Map<string, number>()
+
 const RATE_LIMIT_MS = 30_000
 
+/**
+ * Cheap per-team "has anything changed" fingerprint — the max time_updated/time_created
+ * across the three tables team_status reports on. One MAX() query, no hashing: the
+ * throttle only needs to detect "something changed," not what, so this is deliberately
+ * the simplest sufficient version (see Fix 3 in the spec).
+ */
+function computeStateMarker(deps: ToolDeps, teamId: string): number {
+  const row = deps.db.query(
+    `SELECT MAX(x) as marker FROM (
+       SELECT MAX(time_updated) as x FROM team_member WHERE team_id = ?
+       UNION SELECT MAX(time_updated) FROM team_task WHERE team_id = ?
+       UNION SELECT MAX(time_created) FROM team_message WHERE team_id = ?
+     )`
+  ).get(teamId, teamId, teamId) as { marker: number | null } | null
+  return row?.marker ?? 0
+}
+
 /** Format a duration in ms to a human-readable string. */
 export function formatDuration(ms: number): string {
   if (ms < 60_000) return `${Math.floor(ms / 1000)}s`
@@ -24,15 +44,20 @@ export async function executeTeamStatus(
 
   const now = Date.now()
   const last = lastCallTime.get(teamInfo.teamId)
-  if (last !== undefined && (now - last) < RATE_LIMIT_MS) {
+  const currentMarker = computeStateMarker(deps, teamInfo.teamId)
+  // The 30s throttle's purpose is preventing hammering, not lying about state — only
+  // short-circuit when nothing has actually changed since the last real read.
+  if (last !== undefined && (now - last) < RATE_LIMIT_MS && lastKnownState.get(teamInfo.teamId) === currentMarker) {
     return "No changes since last check."
   }
   lastCallTime.set(teamInfo.teamId, now)
+  lastKnownState.set(teamInfo.teamId, currentMarker)
 
   const members = deps.db.query(
-    "SELECT name, session_id, agent, status, execution_status, worktree_branch, worktree_dir, plan_approval, time_updated FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
+    "SELECT name, session_id, agent, status, execution_status, worktree_branch, worktree_dir, plan_approval, time_updated, last_nudged_at, retry_until, retry_attempt FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
   ).all(teamInfo.teamId) as Array<{
-    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null; worktree_dir: string | null; plan_approval: string; time_updated: number
+    name: string; session_id: string; agent: string; status: string; execution_status: string; worktree_branch: string | null; worktree_dir: string | null; plan_approval: string; time_updated: number; last_nudged_at: number | null
+    retry_until: number | null; retry_attempt: number | null
   }>
 
   const tasks = deps.db.query(
@@ -52,13 +77,22 @@ export async function executeTeamStatus(
       const duration = formatDuration(now - m.time_updated)
       const branch = m.worktree_branch ? `  branch: ${m.worktree_branch}` : ""
       const plan = m.plan_approval !== "none" ? `, plan: ${m.plan_approval}` : ""
+      // Additive display-staleness annotation (Fix 1) — surfaces a soft stall-nudge
+      // without inventing a new status value. Annotates the existing status, doesn't
+      // replace it.
+      const nudged = m.last_nudged_at ? `, nudged ${formatDuration(now - m.last_nudged_at)} ago` : ""
+      // Additive provider-retry annotation (Fix 4) — derived at read time from the
+      // retry_until TTL (Fix 3), same annotation pattern as `nudged` above. Generic
+      // "retrying" label, no rate-limit-specific wording (Fix 2).
+      const isRetrying = m.retry_until !== null && m.retry_until > now
+      const retrying = isRetrying ? `, retrying (attempt ${m.retry_attempt}, ~${formatDuration(m.retry_until! - now)})` : ""
 
       // Last message time
       const lastMsg = deps.db.query("SELECT MAX(time_created) as last_msg FROM team_message WHERE team_id = ? AND from_name = ?")
         .get(teamInfo.teamId, m.name) as { last_msg: number | null } | null
       const msgInfo = lastMsg?.last_msg ? `last msg: ${formatDuration(now - lastMsg.last_msg)} ago` : "no messages yet"
 
-      lines.push(`  ${m.name}  [${statusIcon} ${duration}, ${msgInfo}${plan}]  agent: ${m.agent}${branch}`)
+      lines.push(`  ${m.name}  [${statusIcon} ${duration}, ${msgInfo}${plan}${nudged}${retrying}]  agent: ${m.agent}${branch}`)
 
       // Current task
       const task = deps.db.query("SELECT content FROM team_task WHERE team_id = ? AND assignee = ? AND status = 'in_progress' LIMIT 1")

package/src/tools/team-view.ts

@@ -2,12 +2,14 @@ import type { ToolDeps } from "../types"
 import { requireTeamMember } from "./shared"
 
 /**
- * Execute the team_view tool. Navigates the TUI to a teammate's session
- * so the user can see what they're doing.
+ * Execute the team_view tool. Resolves a teammate's session; navigates the
+ * TUI to it ONLY when navigate: true is passed — an agent must never hijack
+ * the user's client unprompted. Default behavior reports where the session
+ * is so the user can open it themselves (ctrl+p).
  */
 export async function executeTeamView(
   deps: ToolDeps,
-  args: { member: string },
+  args: { member: string; navigate?: boolean },
   sessionId: string,
 ): Promise<string> {
   const teamInfo = requireTeamMember(deps, sessionId)
@@ -16,9 +18,13 @@ export async function executeTeamView(
     .get(teamInfo.teamId, args.member) as { session_id: string; status: string; agent: string } | null
   if (!member) throw new Error(`Teammate "${args.member}" not found in team "${teamInfo.teamName}"`)
 
+  if (args.navigate !== true) {
+    return `${args.member}'s session: ${member.session_id} (status: ${member.status}, agent: ${member.agent}). Open it from the session picker (ctrl+p) — or ask to view it and I'll switch for you.`
+  }
+
   try {
     await deps.client.tui.selectSession({ sessionID: member.session_id })
-    return `Switched to ${args.member}'s session.`
+    return `Switched to ${args.member}'s session. Use the session picker (ctrl+p) to return.`
   } catch {
     return `Could not switch to ${args.member}'s session (${member.session_id}). The session may not be accessible from the TUI.`
   }

package/src/tui-view.ts

@@ -0,0 +1,50 @@
+/** Minimal member shape for sidebar rendering. */
+export interface SidebarMember {
+  name: string
+  status: string
+}
+
+/** Rendered sidebar model: counts plus one line per member. */
+export interface SidebarSummary {
+  team: string
+  working: number
+  idle: number
+  total: number
+  lines: string[]
+}
+
+/** Glyph per member status (paired with text elsewhere — never color-only). */
+function glyph(status: string): string {
+  switch (status) {
+    case "busy":
+      return "●"
+    case "ready":
+      return "○"
+    case "shutdown_requested":
+      return "◐"
+    case "shutdown":
+      return "■"
+    case "error":
+      return "✕"
+    default:
+      return "?"
+  }
+}
+
+/**
+ * Build the sidebar model for a team. Busy members count as working, ready
+ * as idle, terminal states (shutdown/error) as done.
+ */
+export function summarizeMembers(team: string, members: SidebarMember[]): SidebarSummary {
+  if (members.length === 0) {
+    return { team, working: 0, idle: 0, total: 0, lines: ["No teammates"] }
+  }
+  let working = 0
+  let idle = 0
+  const lines = members.map((member) => {
+    if (member.status === "busy") working += 1
+    else if (member.status === "ready") idle += 1
+    return `${glyph(member.status)} ${member.name} (${member.status})`
+  })
+  return { team, working, idle, total: members.length, lines }
+}

package/src/tui.tsx

@@ -0,0 +1,101 @@
+/** @jsxImportSource @opentui/solid */
+import "@opentui/solid"
+import { createSignal, onCleanup, onMount, Show } from "solid-js"
+import { Plugin } from "@opencode/plugin/tui"
+import { EnsembleRpc } from "./rpc"
+
+/** Team context shape from the server bridge. */
+interface TeamContextData {
+  team: string | null
+  members: Array<{ name: string; status: string }>
+  tasks: { pending: number; done: number }
+}
+
+/** Sidebar widget: team members with status plus task counts. */
+function TeamSidebar(props: { fetchContext: () => Promise<TeamContextData | null>; onEvent: (cb: () => void) => () => void }) {
+  const [state, setState] = createSignal<TeamContextData | null>(null)
+  const load = async (): Promise<void> => {
+    try {
+      setState(await props.fetchContext())
+    } catch {
+      // Server unreachable — keep the last known state.
+    }
+  }
+  onMount(() => {
+    void load()
+    const off = props.onEvent(() => void load())
+    onCleanup(off)
+    // Heartbeat: events alone go stale (cleanup emits nothing, events can be
+    // missed across reconnects). Re-fetch on a slow tick — local RPC read.
+    const tick = setInterval(() => void load(), 10_000)
+    onCleanup(() => clearInterval(tick))
+  })
+  return (
+    <Show when={state()?.team} fallback={<text>Ensemble: no active team</text>}>
+      <box flexDirection="column">
+        <text>Ensemble: {state()?.team}</text>
+        {(state()?.members ?? []).map((member) => (
+          <text>
+            {member.status === "busy" ? "●" : member.status === "ready" ? "○" : "■"} {member.name} ({member.status})
+          </text>
+        ))}
+        <text>
+          tasks: {(state()?.tasks.pending ?? 0)} open / {(state()?.tasks.done ?? 0)} done
+        </text>
+      </box>
+    </Show>
+  )
+}
+
+/**
+ * Terminal companion for opencode-ensemble (issue #36).
+ *
+ * Two persistent surfaces only — transient toasts were removed as noise
+ * (live state lives in the sidebar; events live in the transcript as
+ * synthetic system lines):
+ *   1. Sidebar widget: live member status + task counts.
+ *   2. Native agent switching: team_view with navigate: true (user opt-in
+ *      only — agents never hijack the client unprompted).
+ *
+ * Enhancement only: desktop, web, and companion-less terminals lose nothing
+ * functional — tools, approvals, model-context messages, and the dashboard
+ * all live server-side.
+ */
+export default Plugin.define({
+  id: "ensemble.tui",
+  setup(context) {
+    const rpc = context.client.rpc(EnsembleRpc)
+
+    // Native agent switching: team_view(navigate: true) emits "view";
+    // the companion navigates the TUI to the teammate session (ctrl+p to return).
+    const offView = rpc.events.on("view", (event) => {
+      const data = event.data as unknown as { sessionID: string }
+      if (!data.sessionID) return
+      if (context.ui.tabs.enabled()) {
+        void context.ui.tabs.focus(data.sessionID)
+      } else {
+        void context.ui.router.navigate({ type: "session", sessionID: data.sessionID })
+      }
+    })
+
+    const onEvent = (cb: () => void): (() => void) => rpc.events.on("member", cb)
+
+    const offSidebar = context.ui.slot({
+      append: "sidebar.content",
+      render: (panel: { sessionID?: string }) => (
+        <TeamSidebar
+          fetchContext={async () => {
+            if (!panel.sessionID) return null
+            return (await rpc.teamContext({ sessionID: panel.sessionID })) as TeamContextData
+          }}
+          onEvent={onEvent}
+        />
+      ),
+    })
+
+    return () => {
+      offView()
+      offSidebar()
+    }
+  },
+})

package/src/types.ts

@@ -1,6 +1,7 @@
 import type { Database } from "./db"
 import type { MemberRegistry, DescendantTracker, PendingPurgeApprovals } from "./state"
 import type { EnsembleConfig } from "./config"
+import type { ProgressTracker } from "./progress"
 
 /**
  * Shared dependencies injected into every tool's execute function.
@@ -17,6 +18,8 @@ export interface ToolDeps {
   directory: string
   /** Plugin configuration. */
   config: Required<EnsembleConfig>
+  /** Stall/activity tracker — shared with the Watchdog. */
+  progressTracker: ProgressTracker
 }
 
 /** A single permission rule for session-level enforcement. */
@@ -47,6 +50,8 @@ export interface PluginClient {
       agent?: string
       tools?: Record<string, boolean>
       system?: string
+      /** V2: deliver as a synthetic (system) message instead of a user prompt. */
+      synthetic?: boolean
     }): Promise<unknown>
     abort(options: { sessionID: string }): Promise<unknown>
     status(): Promise<{ data?: Record<string, { type: string }> }>

package/src/v2-client.ts

@@ -0,0 +1,227 @@
+import type { PluginClient } from "./types"
+import { runCommand } from "./process"
+
+/** V2 plugin context subset Ensemble needs (structural, mock-friendly). */
+export interface V2Context {
+  session: {
+    create(input: Record<string, unknown>): Promise<{ id: string }>
+    prompt(input: Record<string, unknown>): Promise<unknown>
+    switchAgent(input: Record<string, unknown>): Promise<unknown>
+    switchModel(input: Record<string, unknown>): Promise<unknown>
+    interrupt(input: Record<string, unknown>): Promise<unknown>
+    get(input: Record<string, unknown>): Promise<unknown>
+    context(input: Record<string, unknown>): Promise<unknown[]>
+    active(): Promise<Record<string, { type: string }>>
+    synthetic(input: Record<string, unknown>): Promise<unknown>
+  }
+  worktree: {
+    create(input: Record<string, unknown>): Promise<{ directory: string }>
+    remove(input: Record<string, unknown>): Promise<unknown>
+    list(): Promise<Array<{ directory: string }>>
+    refresh(): Promise<unknown>
+  }
+  permission: {
+    rules(input: Record<string, unknown>): Promise<unknown>
+  }
+}
+
+/** Prefix marking a workspace id that is really a local directory (see below). */
+const DIR_WORKSPACE_PREFIX = "v2dir:"
+
+/** Injectable shell lookups (default to git; overridden in tests). */
+export interface V2ClientDeps {
+  /** Current branch checked out in a directory, or null when unknown. */
+  gitBranch?: (directory: string) => Promise<string | null>
+  /** Worktree directory currently on a branch, or null when none. */
+  gitDir?: (branch: string) => Promise<string | null>
+  /** RPC emitter for companion events (team_view navigation). */
+  rpcEmitter?: { events: { emit(name: string, data: unknown): Promise<unknown> } }
+}
+
+/** Current branch in a directory via git. */
+async function gitBranchDefault(directory: string): Promise<string | null> {
+  try {
+    const result = await runCommand(["git", "branch", "--show-current"], { cwd: directory })
+    const branch = result.stdout.trim()
+    return result.exitCode === 0 && branch ? branch : null
+  } catch {
+    return null
+  }
+}
+
+/** Concatenate the text parts of a promptAsync payload into one string. */
+function joinParts(parts: Array<{ type: "text"; text: string }>): string {
+  return parts
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("\n")
+}
+
+/**
+ * Adapt a V2 plugin context to the shared PluginClient interface so all 14
+ * team tools run unchanged on V2 (DRY: one adapter, zero logic forks).
+ *
+ * Mapping notes (all spike-verified live against v2.0.3 unless marked OQ):
+ * - create: V1 `permission` rules become V2 `{action, resource, effect}`;
+ *   `workspaceID`/`directory` nest under `location`.
+ * - promptAsync: queue delivery wakes idle sessions; `agent` is applied via
+ *   switchAgent first (V2 binds the agent at create/admission, and the shared
+ *   create signature has no agent slot — only spawn passes one).
+ * - abort: interrupt. status: derived from the active set — sessions absent
+ *   from it read as idle, which matches the shutdown default (team-shutdown
+ *   treats unknown as idle). OQ-V2-status: if V2 ever reports non-running
+ *   states here, extend the mapping.
+ * - tui.*: no-op. Toasts and session-select move to the CLI (`./tui`) plugin
+ *   in a later phase — the server plugin must not depend on a TUI.
+ * - worktree.create: V2 reports only the directory, so the branch is read
+ *   back via git (falls back to the requested name). OQ-V2-branch.
+ * - worktree.list: V2 entries carry directory only; name is the basename
+ *   (recovery filters on the `ensemble-` prefix — a non-matching dir is
+ *   skipped, never wrongly deleted). reset has no production callers and
+ *   maps to refresh. OQ-V2-wtname.
+ * - workspace.*: V2 ctx has no workspace domain (workspaces are
+ *   provider-based). create bridges a branch to its worktree directory and
+ *   returns a `v2dir:<dir>` id; session.create routes that id to
+ *   location.directory, preserving worktree isolation with zero tool
+ *   changes. list returns [] and remove resolves — the DB workspace_id
+ *   column stays the source of truth and is still nulled by cleanup.
+ */
+export function createV2Client(ctx: V2Context, deps: V2ClientDeps = {}): PluginClient {
+  const gitBranch = deps.gitBranch ?? gitBranchDefault
+  return {
+    session: {
+      create: async (options) => {
+        const input: Record<string, unknown> = { title: options.title }
+        if (options.parentID) input["parentID"] = options.parentID
+        // V1 action names predate the V2 vocabulary: bash is now shell.
+        const V1_ACTION_MAP: Record<string, string> = { bash: "shell" }
+        const permissions = options.permission?.map((rule) => ({
+          action: V1_ACTION_MAP[rule.permission] ?? rule.permission,
+          resource: rule.pattern,
+          effect: rule.action,
+        }))
+        if (permissions) input["permissions"] = permissions
+        if (options.workspaceID ?? options.directory) {
+          if (options.workspaceID?.startsWith(DIR_WORKSPACE_PREFIX)) {
+            input["location"] = {
+              directory: options.workspaceID.slice(DIR_WORKSPACE_PREFIX.length),
+            }
+          } else {
+            input["location"] = {
+              ...(options.directory ? { directory: options.directory } : {}),
+              ...(options.workspaceID ? { workspaceID: options.workspaceID } : {}),
+            }
+          }
+        }
+        const created = await ctx.session.create(input)
+        if (permissions) {
+          // Session.create permissions lose to agent rules (last match wins
+          // and agent rules apply later), which strips team tools from
+          // read-only agents. Re-assert here: rules() evaluates after the
+          // agent's rules, restoring the tools. OQ-V2-rules.
+          await ctx.permission.rules({ sessionID: created.id, permissions })
+        }
+        return { data: { id: created.id } }
+      },
+      promptAsync: async (options) => {
+        // Synthetic (system) messages render as persistent transcript entries
+        // instead of fake user turns — the native form for agent notifications.
+        if (options.synthetic) {
+          return ctx.session.synthetic({ sessionID: options.sessionID, text: joinParts(options.parts), delivery: "queue" })
+        }
+        if (options.agent) {
+          await ctx.session.switchAgent({ sessionID: options.sessionID, agent: options.agent })
+        }
+        // V2 binds model at create/admission; the shared create signature has
+        // no model slot, so apply it here (spawn is the only model passer).
+        // Caught live: without this, teammates inherit the server default.
+        if (options.model) {
+          await ctx.session.switchModel({
+            sessionID: options.sessionID,
+            model: { providerID: options.model.providerID, id: options.model.modelID },
+          })
+        }
+        const text = joinParts(options.parts)
+        return ctx.session.prompt({ sessionID: options.sessionID, text, delivery: "queue" })
+      },
+      abort: async (options) => ctx.session.interrupt({ sessionID: options.sessionID }),
+      status: async () => {
+        const active = await ctx.session.active()
+        const data: Record<string, { type: string }> = {}
+        for (const sessionID of Object.keys(active)) data[sessionID] = { type: "busy" }
+        return { data }
+      },
+      messages: async (options) => {
+        const messages = await ctx.session.context({ sessionID: options.sessionID })
+        return { data: messages as Array<{ info: unknown; parts: unknown[] }> }
+      },
+      get: async (options) => {
+        const data = await ctx.session.get({ sessionID: options.sessionID })
+        return { data }
+      },
+    },
+    tui: {
+      showToast: async () => undefined,
+      selectSession: async (options) => {
+        // Native agent switching on V2: shared team_view calls this, the
+        // companion receives the event and navigates the TUI to the
+        // teammate session. No server-side TUI API exists on V2.
+        if (deps.rpcEmitter) {
+          await deps.rpcEmitter.events.emit("view", { sessionID: options.sessionID }).catch(() => {
+            // Companion optional — never fail team_view for it.
+          })
+        }
+        return undefined
+      },
+    },
+    worktree: {
+      create: async (options) => {
+        const name = (options.worktreeCreateInput as { name?: string } | undefined)?.name ?? "ensemble-worktree"
+        const created = await ctx.worktree.create({ name })
+        const branch = (await gitBranch(created.directory)) ?? name
+        return { data: { name, branch, directory: created.directory } }
+      },
+      remove: async (options) => {
+        const directory = (options.worktreeRemoveInput as { directory: string }).directory
+        return ctx.worktree.remove({ directory, force: false })
+      },
+      list: async () => {
+        const entries = await ctx.worktree.list()
+        return {
+          data: entries.map((entry) => ({
+            name: entry.directory.split("/").pop() ?? entry.directory,
+            branch: "",
+            directory: entry.directory,
+          })),
+        }
+      },
+      reset: async () => ctx.worktree.refresh(),
+    },
+    workspace: {
+      create: async (options) => {
+        const branch = (options as { branch?: string }).branch ?? ""
+        const directory = await deps.gitDir?.(branch)
+        if (!directory) throw new Error(`V2 workspace bridge: no worktree found on branch "${branch}"`)
+        return {
+          data: {
+            id: `${DIR_WORKSPACE_PREFIX}${directory}`,
+            type: "local",
+            branch,
+            directory,
+            projectID: "",
+          },
+        }
+      },
+      remove: async () => undefined,
+      list: async () => ({
+        data: [] as Array<{
+          id: string
+          type: string
+          branch: string | null
+          directory: string | null
+          projectID: string
+        }>,
+      }),
+    },
+  } as PluginClient
+}