@huynle/hub 0.7.4 → 0.8.1

package/src/migrate.ts

@@ -16,7 +16,7 @@ import {
   symlinkSync,
 } from "node:fs"
 import path from "node:path"
-import type { Env } from "./env"
+import { hubEnv, type Env } from "./env"
 
 export const APP_DIR = "hub"
 /** Legacy directory names under ~/.config and ~/.local/state, most recent first. */
@@ -24,8 +24,81 @@ export const LEGACY_APP_DIRS: readonly string[] = Object.freeze(["opencode-hub",
 
 /** $XDG_CONFIG_HOME or ~/.config. */
 export const configBase = (env: Env, home: string): string => env.XDG_CONFIG_HOME || path.join(home, ".config")
-/** ~/.local/state. */
-export const stateBase = (home: string): string => path.join(home, ".local", "state")
+/** $XDG_STATE_HOME when it is an absolute path (the XDG spec: a relative one is invalid and ignored), else undefined. */
+export const xdgStateHome = (env: Env): string | undefined => (env.XDG_STATE_HOME && path.isAbsolute(env.XDG_STATE_HOME) ? env.XDG_STATE_HOME : undefined)
+
+/** $XDG_STATE_HOME or ~/.local/state. The hub's own state dir is resolveHubStateDir (sticky), not this. */
+export const stateBase = (env: Env, home: string): string => xdgStateHome(env) ?? path.join(home, ".local", "state")
+
+export interface HubStateDir {
+  readonly dir: string
+  /** env: HUB_STATE_DIR; xdg: an existing $XDG_STATE_HOME/hub; legacy: an existing ~/.local/state/hub kept although
+   *  XDG_STATE_HOME is set; fresh: a new $XDG_STATE_HOME/hub; default: ~/.local/state/hub without XDG_STATE_HOME. */
+  readonly source: "env" | "xdg" | "legacy" | "fresh" | "default"
+  /** legacy only: one line for the log at startup (XDG_STATE_HOME is set, the existing dir is used, how to switch). */
+  readonly hint?: string
+  /** `dir`, then the other default places (~/.local/state/hub, $XDG_STATE_HOME/hub) it is not: the Concierge lock is read from all. */
+  readonly candidates: readonly string[]
+}
+
+/**
+ * What the hub writes in its state dir (the hub server's state.json, token-keys.json, agent/ and blobs/; the plugin's
+ * launchers bin/ and Concierge lock; the local hub's hub.log / hub.pid; the Claude Code and Codex spokes' dirs). A
+ * dir holding none of them (empty, or only `hubctl setup`'s bootstrap/) does not count as an existing state dir.
+ */
+export const HUB_STATE_MARKERS: readonly string[] = Object.freeze(["state.json", "token-keys.json", "agent", "blobs", "concierge-sessions.json", "bin", "hub.log", "hub.pid", "claude-code", "codex"])
+
+/** Whether `dir` holds hub state (any of HUB_STATE_MARKERS). */
+export const holdsHubState = (dir: string, exists: (p: string) => boolean = existsSync): boolean => HUB_STATE_MARKERS.some((marker) => exists(path.join(dir, marker)))
+
+const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+/**
+ * The hub state dir, "sticky" (FX-08): $HUB_STATE_DIR; else $XDG_STATE_HOME/hub when XDG_STATE_HOME is set and that
+ * dir holds hub state (HUB_STATE_MARKERS; `exists` is asked about each marker); else an existing ~/.local/state/hub (kept, never copied or moved; with a hint when XDG_STATE_HOME is
+ * set); else $XDG_STATE_HOME/hub when it is set (fresh installs); else ~/.local/state/hub. Every part of hub (plugin,
+ * local hub, hub server, the Claude Code and Codex spokes) uses this, so a shell and a service unit agree unless one
+ * sets HUB_STATE_DIR.
+ */
+export function resolveHubStateDir(env: Env, home: string, exists: (p: string) => boolean = existsSync): HubStateDir {
+  const legacy = path.join(home, ".local", "state", APP_DIR)
+  const xdg = xdgStateHome(env)
+  const xdgHub = xdg ? path.join(xdg, APP_DIR) : undefined
+  const defaults = [legacy, ...(xdgHub && xdgHub !== legacy ? [xdgHub] : [])]
+  const result = (dir: string, source: HubStateDir["source"], hint?: string): HubStateDir => ({
+    dir,
+    source,
+    ...(hint ? { hint } : {}),
+    candidates: [dir, ...defaults.filter((d) => d !== dir)],
+  })
+  const explicit = hubEnv(env).HUB_STATE_DIR
+  if (explicit) return result(explicit, "env")
+  const holdsState = (dir: string) => holdsHubState(dir, exists)
+  if (xdgHub && holdsState(xdgHub)) return result(xdgHub, "xdg")
+  if (holdsState(legacy)) {
+    const hint =
+      xdgHub && xdgHub !== legacy
+        ? `XDG_STATE_HOME is set, but the existing ${legacy} is used as the hub state dir; to switch, stop the hub and OpenCode, then: mv ${shellQuote(legacy)} ${shellQuote(xdgHub)}`
+        : undefined
+    return result(legacy, "legacy", hint)
+  }
+  return xdgHub ? result(xdgHub, "fresh") : result(legacy, "default")
+}
+
+let hinted = false
+/** Logs the resolver's hint once per process (at startup). */
+export function hintStateDirOnce(resolved: HubStateDir, log: (line: string) => void = console.warn): void {
+  if (!resolved.hint || hinted) return
+  hinted = true
+  log(`[hub] ${resolved.hint}`)
+}
+
+/** The legacy (opencode-hub, opencode-voice) state dirs, most recent first: under $XDG_STATE_HOME, then ~/.local/state. */
+export function stateLegacyPaths(env: Env, home: string): string[] {
+  const xdg = xdgStateHome(env)
+  const bases = [...(xdg ? [xdg] : []), path.join(home, ".local", "state")]
+  return [...new Set(bases.flatMap((base) => legacyPaths(base)))]
+}
 
 export type MigrationResult = "migrated" | "none" | "failed"
 
@@ -103,3 +176,36 @@ export function migrateFirst(legacies: readonly string[], target: string, option
 
 /** The legacy copies of `<base>/<APP_DIR>/<...rest>`, most recent first. */
 export const legacyPaths = (base: string, ...rest: string[]): string[] => LEGACY_APP_DIRS.map((dir) => path.join(base, dir, ...rest))
+
+/**
+ * migrateFirst for the hub state dir: a target that holds no hub state (missing, empty, or only `hubctl setup`'s
+ * bootstrap/) counts as missing. The newest existing legacy dir is copied through a temporary sibling, then each of
+ * its top-level entries is renamed into the target unless the target already has one by that name (bootstrap/ is
+ * never overwritten). Never throws; the legacy copies are never touched.
+ */
+export function migrateStateDir(legacies: readonly string[], target: string, options: MigrateOptions = {}): MigrationResult {
+  if (!exists(target)) return migrateFirst(legacies, target, options)
+  if (holdsHubState(target, exists)) return "none"
+  const legacy = legacies.find(exists)
+  if (legacy === undefined) return "none"
+  const tmp = `${target}.migrating-${process.pid}-${Date.now()}`
+  let moved = 0
+  try {
+    const present = new Set(readdirSync(target))
+    copyEntry(legacy, tmp, [...(options.skip ?? []), ...present])
+    for (const name of readdirSync(tmp)) {
+      if (exists(path.join(target, name))) continue
+      renameSync(path.join(tmp, name), path.join(target, name))
+      moved++
+    }
+    rmSync(tmp, { recursive: true, force: true })
+  } catch (cause) {
+    rmSync(tmp, { recursive: true, force: true })
+    ;(options.log ?? ((m: string) => console.warn(`[hub] warning: ${m}`)))(`could not migrate ${legacy} to ${target}: ${cause instanceof Error ? cause.message : cause}`)
+    return "failed"
+  }
+  // Everything was there already (an earlier migration of a legacy dir without hub-state markers): nothing to say.
+  if (moved === 0) return "none"
+  ;(options.log ?? ((m: string) => console.log(`[hub] ${m}`)))(`migrated ${legacy} to ${target} (the project is now Hub; the old copy is kept)`)
+  return "migrated"
+}

package/src/spoke/concierge-agent.ts

@@ -0,0 +1,33 @@
+// CON-04 the OpenCode agent the Concierge session runs on (contract "Agent"): registered by the plugin like the voice
+// agent (conversation.ts defineVoiceAgent), mode primary, hidden. Its rules are an ALLOW-LIST: deny everything
+// ("*"), then allow exactly CONCIERGE_TOOLS (hub, read, glob, grep, question). OpenCode evaluates the last matching
+// rule, so nothing else (subagent/task, execute, webfetch/websearch, shell, edit/write/patch, todo, skill,
+// external_directory, MCP or plugin tools, future tools) is allowed, even with no hub context. The hub also strips
+// every tool off that list from each turn (sessionContext tools.allow): defence in depth. The default agent's rules
+// are not inherited. Its instructions come from the hub with every turn (sessionContext), not from here.
+import { CONCIERGE_AGENT, CONCIERGE_TOOLS } from "../../packages/protocol/src/concierge.ts"
+import type { AgentEditorLike } from "./conversation"
+
+export const CONCIERGE_AGENT_NAME = "Concierge"
+export const CONCIERGE_AGENT_DESCRIPTION = "Hub Concierge: watches your sessions and acts only inside your grant. Hub-managed; not for direct use."
+const CONCIERGE_SYSTEM = "You are the hub's Concierge. Your instructions, situation board and notes arrive from the hub with every turn."
+
+export const CONCIERGE_RULES: ReadonlyArray<{ readonly action: string; readonly resource: string; readonly effect: "allow" | "deny" }> = [
+  { action: "*", resource: "*", effect: "deny" },
+  ...CONCIERGE_TOOLS.map((action) => ({ action, resource: "*", effect: "allow" as const })),
+]
+
+/** Adds (or refreshes) the hub's "concierge" agent; a "concierge" agent the user defined is left alone. */
+export function defineConciergeAgent(editor: AgentEditorLike): void {
+  // The description marks the hub's own agent, which is refreshed; a user's own "concierge" agent is left alone.
+  const existing = editor.get(CONCIERGE_AGENT)
+  if (existing && existing.description !== CONCIERGE_AGENT_DESCRIPTION) return
+  editor.update(CONCIERGE_AGENT, (agent) => {
+    agent.name = CONCIERGE_AGENT_NAME
+    agent.description = CONCIERGE_AGENT_DESCRIPTION
+    agent.mode = "primary"
+    agent.hidden = true
+    agent.system = CONCIERGE_SYSTEM
+    agent.permissions = CONCIERGE_RULES.map((r) => ({ ...r }))
+  })
+}

package/src/spoke/deliver.ts

@@ -34,13 +34,17 @@ export interface RecipientState {
  * (quirk hzmcqwpj), a steered one joins them in one call. With a form open OpenCode holds the message until the
  * form is answered ("retained").
  *
- * `wake:false` and subagent sessions are admitted without starting a turn ("queued"). They default to steer: a
- * queued item gets its own model call when a turn ends (that would wake the session), while a steered one
- * without resume waits for the next turn and arrives before its prompt (or joins a turn already running).
+ * `wake:false` and subagent sessions are admitted without starting a turn ("queued"), always steered (also over
+ * the hub's "queue", RF-05): a queued item gets its own model call when a turn ends, resume or not (that would wake
+ * the session), while a steered one without resume waits for the next turn and arrives before its prompt. A
+ * steered one admitted into a running turn costs a model call when the turn would have ended, so routine ones are
+ * refused while the session is busy (deferredWhileBusy).
  */
 export function planDelivery(req: { readonly wake: boolean; readonly meta: DeliverMeta }, state: RecipientState): DeliveryPlan {
   const resume = req.wake && !state.subagent
-  const chosen = req.meta.delivery ?? (!resume || req.meta.kind === "ask" ? "steer" : "queue")
+  // Not waking: always steer. OpenCode gives a queued item its own model call once a turn ends (resume or not),
+  // so a hub-chosen "queue" would wake the session after all; a steered one waits for the next turn.
+  const chosen = !resume ? "steer" : (req.meta.delivery ?? (req.meta.kind === "ask" ? "steer" : "queue"))
   // Idle: no running turn to queue behind; steered, the wake shares its model call with what already waits.
   const delivery = resume && !state.busy && !state.formOpen ? "steer" : chosen
   return { delivery, resume, delivered: deliveredAs(delivery, resume, state) }
@@ -71,5 +75,19 @@ export function deliverMetadata(req: { readonly messageID: string; readonly meta
   return { source: PROMPT_SOURCE, messageID: req.messageID, kind, from, to, ...(replyTo !== undefined ? { replyTo } : {}), ...(grant !== undefined ? { grant } : {}) }
 }
 
+/** The refusal of a routine quiet message to a busy session (the hub keeps it pending and retries). */
+export const QUIET_WHILE_BUSY = "The session is busy: a message that does not wake it is admitted after the running turn"
+
+/**
+ * Whether a message waits for the running turn to end (refused while busy, RF-05): a routine `wake:false` msg (not
+ * urgent: the hub sends routine msgs with delivery "queue") to a top-level session. OpenCode adds anything admitted
+ * into a running turn with a model call of its own when the turn would have ended. Urgent messages, asks, replies,
+ * primers and anything for a subagent (never woken; it may not be idle before its parent needs the answer) go in at
+ * once and accept that call.
+ */
+export function deferredWhileBusy(req: { readonly wake: boolean; readonly meta: DeliverMeta }, subagent: boolean): boolean {
+  return !req.wake && !subagent && req.meta.kind === "msg" && req.meta.delivery !== "steer"
+}
+
 // The prompt envelope, InboxOrigins and DeliveryLedger live in the spoke SDK (harness-neutral).
 export { deliverText, DeliveryLedger, InboxOrigins, renderPromptEnvelope, type Admission } from "../../packages/spoke-sdk/src/delivery.ts"

package/src/spoke/env-inject.ts

@@ -14,6 +14,7 @@
 // they get only the stripped env and PATH, no token.
 import { homedir } from "node:os"
 import path from "node:path"
+import { hubEnv } from "../env"
 import { defaultStateDir } from "./localhub"
 
 type Env = Record<string, string | undefined>
@@ -124,11 +125,17 @@ export function applyHubEnv(env: Env, identity: Identity | undefined, binDir: st
   env.PATH = [binDir, ...rest].join(path.delimiter)
 }
 
-/** Where the `hub`/`hubctl` launchers live: bin under the hub state dir ($HUB_STATE_DIR or ~/.local/state/hub). */
+/** Where the `hub`/`hubctl` launchers live: bin under the hub state dir ($HUB_STATE_DIR, else $XDG_STATE_HOME/hub, else ~/.local/state/hub). */
 export function hubBinDir(env: Env = process.env, home: string = homedir()): string {
   return path.join(defaultStateDir(env, home), "bin")
 }
 
+/** Where ~/.local/bin/hub may point: the default (resolved) hub bin dir; none with HUB_STATE_DIR (a custom state). */
+export function defaultHubBinDir(env: Env = process.env, home: string = homedir()): string | undefined {
+  if (hubEnv(env).HUB_STATE_DIR) return undefined
+  return path.join(defaultStateDir(env, home), "bin")
+}
+
 /** The hook handlers: tool execute.before/after and shell create.before. They never throw. */
 export function envInjector(options: { correlator: ShellCorrelator; binDir: string; identity: (sessionID: string) => Identity | undefined }) {
   const { correlator, binDir, identity } = options

package/src/spoke/fork-revert.ts

@@ -0,0 +1,142 @@
+// Fork and revert (features "fork" and "revert"): the pure parts of the spoke's fork, revertPreview, revert,
+// revertRestore and revertCommit ops. OpenCode semantics (checked against `opencode serve` 2.2.3, see
+// test/spoke-fork-revert.it.test.ts):
+//   - session.fork({sessionID, before}) copies the conversation BEFORE `before` into a new root session (allowed
+//     while the source runs).
+//   - session.revert.stage({sessionID, messageID, files: true}) marks the session reverted from that message and
+//     restores the files the session changed since then; OpenCode refuses it while the session runs
+//     (SessionBusyError). The messages stay in the session's history (message list and context): the CLIENT hides
+//     them, from the reverted message on. The session's `revert` field and session.revert.staged carry it.
+//   - session.revert.clear brings the files back (session.revert.cleared); session.revert.commit removes the hidden
+//     messages (session.revert.committed). The next prompt commits a staged revert by itself.
+import { REVERT_FILE_MAX_CHARS, REVERT_FILES_MAX, type MessageAttachment, type RevertFile, type SessionRevertInfo } from "../protocol"
+
+const record = (value: unknown): Record<string, any> => (value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, any>) : {})
+const STATUS = new Set(["added", "deleted", "modified"])
+const count = (value: unknown): number | undefined => (Number.isSafeInteger(value) && (value as number) >= 0 ? (value as number) : undefined)
+
+export const NOT_A_USER_MESSAGE = "Not a user message of this session"
+export const REVERT_BUSY = "The session is working; wait for it to finish (or stop it) before reverting"
+
+/** Epoch ms of an OpenCode timestamp (number or ISO string). */
+function millis(value: unknown): number | undefined {
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined
+  if (typeof value !== "string") return undefined
+  const ms = Date.parse(value)
+  return Number.isNaN(ms) ? undefined : ms
+}
+
+/** The index of the user message `messageID` in the session's messages (oldest first), or -1. */
+export function userIndex(messages: readonly unknown[], messageID: string): number {
+  return messages.findIndex((raw) => {
+    const m = record(raw)
+    return m.id === messageID && m.type === "user"
+  })
+}
+
+/** The text and attachments (metadata, never bytes) of a user message, for the composer. */
+export function userContent(message: unknown): { text: string; attachments: MessageAttachment[] } {
+  const m = record(message)
+  const text =
+    typeof m.text === "string"
+      ? m.text
+      : Array.isArray(m.content)
+        ? m.content.filter((p: any) => p?.type === "text" && typeof p.text === "string").map((p: any) => p.text as string).join("")
+        : ""
+  const attachments: MessageAttachment[] = []
+  if (Array.isArray(m.files)) {
+    m.files.forEach((raw: unknown, index: number) => {
+      const f = record(raw)
+      if (typeof f.mime !== "string") return
+      attachments.push({ index, mime: f.mime, ...(typeof f.name === "string" && f.name ? { name: f.name.slice(0, 200) } : {}) })
+    })
+  }
+  return { text, attachments }
+}
+
+/** User messages from `index` on (the reverted one and those after it). */
+function usersFrom(messages: readonly unknown[], index: number): number {
+  let n = 0
+  for (let i = Math.max(0, index); i < messages.length; i++) if (record(messages[i]).type === "user") n++
+  return n
+}
+
+/** At most REVERT_FILES_MAX files, unique by path, with the total. */
+function bounded(files: readonly RevertFile[]): { files: RevertFile[]; filesTotal: number } {
+  const seen = new Set<string>()
+  const unique = files.filter((f) => {
+    if (!f.file || f.file.length > REVERT_FILE_MAX_CHARS || seen.has(f.file)) return false
+    seen.add(f.file)
+    return true
+  })
+  return { files: unique.slice(0, REVERT_FILES_MAX), filesTotal: unique.length }
+}
+
+/** OpenCode's FileDiffInfo list as revert files (no patches). */
+function diffFiles(raw: unknown): RevertFile[] {
+  if (!Array.isArray(raw)) return []
+  return raw.flatMap((entry) => {
+    const f = record(entry)
+    if (typeof f.file !== "string" || !f.file) return []
+    const additions = count(f.additions)
+    const deletions = count(f.deletions)
+    return [
+      {
+        file: f.file,
+        ...(STATUS.has(f.status) ? { status: f.status as RevertFile["status"] } : {}),
+        ...(additions === undefined ? {} : { additions }),
+        ...(deletions === undefined ? {} : { deletions }),
+      },
+    ]
+  })
+}
+
+/**
+ * What reverting from the user message at `index` would hide, and the files the session's assistant messages
+ * changed from there on (their snapshots' file lists): what a revert with files restores.
+ */
+export function revertPreview(messages: readonly unknown[], index: number): { hidden: number; files: RevertFile[]; filesTotal: number } {
+  const files: RevertFile[] = []
+  for (let i = Math.max(0, index); i < messages.length; i++) {
+    const m = record(messages[i])
+    if (m.type !== "assistant") continue
+    for (const file of Array.isArray(m.snapshot?.files) ? m.snapshot.files : []) if (typeof file === "string" && file) files.push({ file })
+  }
+  return { hidden: usersFrom(messages, index), ...bounded(files) }
+}
+
+/**
+ * The summary of OpenCode's staged revert (session.revert, or session.revert.staged's data.revert) over the
+ * session's messages; undefined when nothing is staged.
+ */
+export function revertSummary(raw: unknown, messages: readonly unknown[]): SessionRevertInfo | undefined {
+  const revert = record(raw)
+  if (typeof revert.messageID !== "string" || !revert.messageID || revert.messageID.length > 300) return undefined
+  const index = messages.findIndex((m) => record(m).id === revert.messageID)
+  const at = index < 0 ? undefined : millis(record(messages[index]).time?.created)
+  return {
+    messageID: revert.messageID,
+    hidden: index < 0 ? 0 : usersFrom(messages, index),
+    ...(at === undefined ? {} : { at }),
+    ...bounded(diffFiles(revert.files)),
+  }
+}
+
+/** The messages a client shows while a revert is staged from `messageID`: those before it (all when unknown). */
+export function visibleMessages<T>(messages: readonly T[], messageID: string | undefined): readonly T[] {
+  if (!messageID) return messages
+  const index = messages.findIndex((m) => record(m).id === messageID)
+  return index < 0 ? messages : messages.slice(0, index)
+}
+
+/** Whether an OpenCode error says the session is busy (a revert refused while it runs). */
+export function busyError(cause: unknown): boolean {
+  const c = record(cause)
+  const text = `${c._tag ?? ""} ${c.name ?? ""} ${cause instanceof Error ? cause.message : String(cause ?? "")}`
+  return /SessionBusy|Session is busy/i.test(text)
+}
+
+/** Same revert summaries (so an unchanged one sends no snapshot). */
+export function sameRevert(a: SessionRevertInfo | undefined, b: SessionRevertInfo | undefined): boolean {
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+}

package/src/spoke/hub-rpc.ts

@@ -4,6 +4,7 @@
 // result or an error (redacted should the hub echo it). Labels are sanitised here, so the TUI shows them as is.
 import { HubClient, HubError, HubTransportError, sanitizeLabel, type AgentMessage, type DirectoryEntry } from "../../packages/sdk/src/index.ts"
 import type { HubToolSpoke } from "./hub-tool"
+import type { WhoReach, WhoTeamGroup, WhoTeamRef } from "./who-teams"
 
 /** The RPC error a failure answers with (src/rpc.ts lists them). */
 export type HubRpcErrorCode = "invalid" | "not_connected" | "unsupported" | "unreachable" | "server_error"
@@ -25,6 +26,19 @@ export interface WhoRow {
   readonly state?: string
   readonly online: boolean
   readonly roles: string[]
+  /** HWA-40 (additive): where it runs, its teams (roles there, the caller's reach) and whether it is the caller. */
+  readonly machineID?: string
+  readonly harness?: string
+  readonly teams?: WhoTeamRef[]
+  readonly reach?: WhoReach
+  readonly self?: true
+}
+
+/** /who's answer: the rows, and the team groups when the hub sent them (HWA-40). */
+export interface WhoResult {
+  readonly sessions: WhoRow[]
+  readonly teams?: WhoTeamGroup[]
+  readonly scope?: "team"
 }
 
 export interface MsgResult {
@@ -57,16 +71,23 @@ export async function hubMsg(spoke: HubToolSpoke, value: unknown): Promise<MsgRe
   })
 }
 
-/** /who: the named and role-holding sessions (optionally one project or one role), as session `sessionID`. */
-export async function hubWho(spoke: HubToolSpoke, value: unknown): Promise<{ sessions: WhoRow[] }> {
+/**
+ * /who: the named and role-holding sessions (optionally one project, role or team), as session `sessionID`. A bare
+ * `project` that names one of the caller's teams (listed in a team member's answer) is taken as that team (/who <team>).
+ */
+export async function hubWho(spoke: HubToolSpoke, value: unknown): Promise<WhoResult> {
   const input = inputOf(value)
   const sessionID = optStr(input, "sessionID")
   if (!sessionID) throw new HubRpcError("invalid", "Open a session first: /who asks the hub as the current session.")
   const project = optStr(input, "project")
   const role = optStr(input, "role")
+  const team = optStr(input, "team")
   return withClient(spoke, sessionID, undefined, async (client, signal) => {
-    const { sessions } = await client.who({ ...(project ? { project } : {}), ...(role ? { role } : {}), signal })
-    return { sessions: sessions.map(whoRow) }
+    let answer = await client.who({ ...(project ? { project } : {}), ...(role ? { role } : {}), ...(team ? { team } : {}), signal })
+    // A team member's answer lists all its teams; a bare word naming one of them is /who <team>.
+    if (project && !role && !team && answer.teams?.some((t) => t.name === project)) answer = await client.who({ team: project, signal })
+    const teams = (answer.teams ?? []).map((t) => ({ name: sanitizeLabel(t.name), mode: t.mode, ...(t.paused ? { paused: true } : {}), ...(t.yourRoles?.length ? { yourRoles: t.yourRoles.map((r) => sanitizeLabel(r)) } : {}), members: t.members.map((m) => ({ sessionID: sanitizeLabel(m.sessionID), role: sanitizeLabel(m.role) })) }))
+    return { sessions: answer.sessions.map((e) => whoRow(e, sessionID)), ...(teams.length ? { teams } : {}), ...(answer.scope === "team" ? { scope: "team" as const } : {}) }
   })
 }
 
@@ -93,10 +114,24 @@ async function withClient<T>(
   }
 }
 
-function whoRow(entry: DirectoryEntry): WhoRow {
+const reachRow = (r: DirectoryEntry["reach"]): WhoReach | undefined => (r ? { send: [...r.send], receive: [...r.receive], direction: r.direction, ...(r.unreachable ? { unreachable: true } : {}) } : undefined)
+
+function whoRow(entry: DirectoryEntry, caller?: string): WhoRow {
   const name = entry.name ? sanitizeLabel(entry.name) : ""
   const project = entry.project ? sanitizeLabel(entry.project) : ""
   const state = entry.state ? sanitizeLabel(entry.state) : ""
+  const teams = (entry.teams ?? []).map((t) => {
+    const reach = reachRow(t.reach)
+    return { team: sanitizeLabel(t.team), roles: t.roles.map((r) => sanitizeLabel(r)), ...(reach ? { reach } : {}) }
+  })
+  const reach = reachRow(entry.reach)
+  const extra = {
+    ...(entry.machineID ? { machineID: sanitizeLabel(entry.machineID) } : {}),
+    ...(entry.harness ? { harness: sanitizeLabel(entry.harness) } : {}),
+    ...(teams.length ? { teams } : {}),
+    ...(reach ? { reach } : {}),
+    ...(caller !== undefined && entry.sessionID === caller && teams.length ? { self: true as const } : {}),
+  }
   return {
     sessionID: sanitizeLabel(entry.sessionID),
     ...(name ? { name } : {}),
@@ -104,6 +139,7 @@ function whoRow(entry: DirectoryEntry): WhoRow {
     ...(state ? { state } : {}),
     online: entry.online === true,
     roles: (entry.roles ?? []).map((r) => sanitizeLabel(r.role)).filter(Boolean),
+    ...extra,
   }
 }