@prjct.app/pi-team 0.6.0 → 0.7.0

package/src/supervisor/tmux-adapter.ts

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { isAbsolute } from 'node:path';
+import { defaultProcessController, type ProcessController, type ProcessIdentity } from '../process-identity.ts';
+import type { OwnerIdentity, OwnedRuntime } from './runtime-store.ts';
+
+export const TMUX_RUNTIME_ID = '@pi-team-runtime-id';
+export const TMUX_OWNER_INSTANCE = '@pi-team-owner-instance';
+export const TMUX_TOKEN_HASH = '@pi-team-token-hash';
+
+const ENV_RUNTIME_ID = 'PI_TEAM_RUNTIME_ID';
+const ENV_OWNER_INSTANCE = 'PI_TEAM_OWNER_INSTANCE';
+const ENV_OWNER_PROCESS_NONCE = 'PI_TEAM_OWNER_PROCESS_NONCE';
+const ENV_TOKEN_HASH = 'PI_TEAM_TOKEN_HASH';
+const ENV_TEAM_ID = 'PI_TEAM_TEAM_ID';
+const ENV_MEMBER_ID = 'PI_TEAM_MEMBER_ID';
+const ENV_MEMBER_ALIAS = 'PI_TEAM_MEMBER_ALIAS';
+const ENV_MEMBER_SESSION = 'PI_TEAM_MEMBER_SESSION';
+const ENV_MEMBER_GENERATION = 'PI_TEAM_MEMBER_GENERATION';
+const ENV_MEMBER_LEASE_TOKEN = 'PI_TEAM_MEMBER_LEASE_TOKEN';
+const ENV_MEMBER_LEASE_GENERATION = 'PI_TEAM_MEMBER_LEASE_GENERATION';
+const ENV_AUTO_REQUESTS = 'PI_TEAM_AUTO_REQUESTS';
+const ENV_CONTROL_SOCKET = 'PI_TEAM_CONTROL_SOCKET';
+const ENV_CONTROL_TOKEN = 'PI_TEAM_CONTROL_TOKEN';
+
+export type TmuxCommandResult = { readonly stdout: string; readonly stderr: string };
+export type TmuxCommand = (program: string, args: readonly string[], cwd?: string) => Promise<TmuxCommandResult>;
+
+export type LaunchedTmuxRuntime = {
+  readonly session: string;
+  readonly identity: ProcessIdentity;
+  readonly ownershipTokenHash: string;
+};
+
+export type TmuxLaunchOptions = {
+  readonly runtimeId: string;
+  readonly owner: OwnerIdentity;
+  readonly cwd: string;
+  readonly command: readonly [string, ...string[]];
+  readonly environment?: Readonly<Record<string, string | undefined>>;
+  readonly controlSocket: string;
+  readonly controlToken: string;
+  readonly ownershipToken: string;
+  readonly workerMembership: {
+    readonly teamId: string;
+    readonly memberId: string;
+    readonly alias: string;
+    readonly sessionId: string;
+    readonly memberGeneration: number;
+    readonly leaseToken: string;
+    readonly leaseGeneration: number;
+  };
+  readonly autoRequests: boolean;
+};
+
+const defaultCommand: TmuxCommand = (program, args, cwd) => new Promise((resolvePromise, reject) => {
+  execFile(program, [...args], { cwd, env: process.env, timeout: 10_000 }, (error, stdout, stderr) => {
+    if (error) { reject(error); return; }
+    resolvePromise({ stdout: String(stdout), stderr: String(stderr) });
+  });
+});
+
+/**
+ * An exact-match session target. tmux 3.6 resolves a bare "=name" as a session
+ * for some commands but not for set-option or display-message, which then fail
+ * with "no such session"; "=name:" (session, current window) works for all.
+ */
+export const exact = (session: string): string => `=${session}:`;
+
+function hashToken(token: string): string { return createHash('sha256').update(token).digest('hex'); }
+
+function sessionName(runtimeId: string): string {
+  return `pi-team-v2-${createHash('sha256').update(runtimeId).digest('hex').slice(0, 24)}`;
+}
+
+function parsePid(value: string): number | undefined {
+  const processPid = Number(value.trim());
+  return Number.isSafeInteger(processPid) && processPid > 1 ? processPid : undefined;
+}
+
+function environment(output: string): ReadonlyMap<string, string> {
+  return new Map(output.split('\n').filter(line => line.includes('=')).map(line => {
+    const separator = line.indexOf('=');
+    return [line.slice(0, separator), line.slice(separator + 1)];
+  }));
+}
+
+const ENVIRONMENT_MAX_BYTES = 256 * 1024;
+const TMUX_MANAGED_ENVIRONMENT = new Set(['TMUX', 'TMUX_PANE', 'TERM', 'TERM_PROGRAM', 'TERM_PROGRAM_VERSION',
+  'PWD', 'OLDPWD', 'SHLVL', '_']);
+function clientEnvironment(source: TmuxLaunchOptions['environment']): readonly string[] {
+  const entries = Object.entries(source ?? {}).filter((entry): entry is [string, string] =>
+    entry[1] !== undefined && /^[A-Za-z_][A-Za-z0-9_]*$/.test(entry[0]) && !entry[0].startsWith('PI_TEAM_') &&
+    !TMUX_MANAGED_ENVIRONMENT.has(entry[0]))
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) => `${key}=${value}`);
+  if (Buffer.byteLength(entries.join('\0'), 'utf8') > ENVIRONMENT_MAX_BYTES) {
+    throw new Error('Supervised runtime environment exceeds its byte limit.');
+  }
+  return entries.flatMap(value => ['-e', value]);
+}
+
+export class TmuxAdapter {
+  constructor(
+    private readonly run: TmuxCommand = defaultCommand,
+    private readonly processes: ProcessController = defaultProcessController,
+  ) {}
+
+  async available(): Promise<boolean> {
+    return this.run('tmux', ['-V']).then(() => true, () => false);
+  }
+
+  async launch(options: TmuxLaunchOptions): Promise<LaunchedTmuxRuntime> {
+    if (!isAbsolute(options.cwd)) throw new Error('Supervised runtime cwd must be absolute.');
+    if (options.controlToken.length < 64 || options.ownershipToken.length < 64) throw new Error('Runtime control tokens are too short.');
+    const session = sessionName(options.runtimeId);
+    const tokenHash = hashToken(options.ownershipToken);
+    const target = exact(session);
+    const args = [
+      'new-session', '-d', '-s', session, '-c', options.cwd,
+      ...clientEnvironment(options.environment),
+      '-e', `${ENV_RUNTIME_ID}=${options.runtimeId}`,
+      '-e', `${ENV_OWNER_INSTANCE}=${options.owner.ownerInstanceId}`,
+      '-e', `${ENV_OWNER_PROCESS_NONCE}=${options.owner.ownerProcessNonce}`,
+      '-e', `${ENV_TOKEN_HASH}=${tokenHash}`,
+      '-e', `${ENV_TEAM_ID}=${options.workerMembership.teamId}`,
+      '-e', `${ENV_MEMBER_ID}=${options.workerMembership.memberId}`,
+      '-e', `${ENV_MEMBER_ALIAS}=${options.workerMembership.alias}`,
+      '-e', `${ENV_MEMBER_SESSION}=${options.workerMembership.sessionId}`,
+      '-e', `${ENV_MEMBER_GENERATION}=${options.workerMembership.memberGeneration}`,
+      '-e', `${ENV_MEMBER_LEASE_TOKEN}=${options.workerMembership.leaseToken}`,
+      '-e', `${ENV_MEMBER_LEASE_GENERATION}=${options.workerMembership.leaseGeneration}`,
+      '-e', `${ENV_AUTO_REQUESTS}=${options.autoRequests ? '1' : '0'}`,
+      '-e', `${ENV_CONTROL_SOCKET}=${options.controlSocket}`,
+      '-e', `${ENV_CONTROL_TOKEN}=${options.controlToken}`,
+      '--', ...options.command,
+    ];
+    await this.run('tmux', args, options.cwd);
+    try {
+      await this.run('tmux', ['set-option', '-t', target, TMUX_RUNTIME_ID, options.runtimeId]);
+      await this.run('tmux', ['set-option', '-t', target, TMUX_OWNER_INSTANCE, options.owner.ownerInstanceId]);
+      await this.run('tmux', ['set-option', '-t', target, TMUX_TOKEN_HASH, tokenHash]);
+      const pane = await this.run('tmux', ['display-message', '-p', '-t', target, '#{pane_pid}']);
+      const processPid = parsePid(pane.stdout);
+      const identity = processPid ? await this.processes.inspect(processPid) : undefined;
+      if (!identity) throw new Error('Could not verify the supervised runtime process identity.');
+      return { session, identity, ownershipTokenHash: tokenHash };
+    } catch (error) {
+      if (await this.environmentMatches(session, options.runtimeId, options.owner, tokenHash)) {
+        await this.run('tmux', ['kill-session', '-t', target]).catch(() => ({ stdout: '', stderr: '' }));
+      }
+      throw error;
+    }
+  }
+
+  async metadataMatches(runtime: OwnedRuntime): Promise<boolean> {
+    if (!runtime.tmuxSession || !runtime.tmuxOwnershipTokenHash) return false;
+    const format = `#{${TMUX_RUNTIME_ID}}\t#{${TMUX_OWNER_INSTANCE}}\t#{${TMUX_TOKEN_HASH}}`;
+    const output = await this.run('tmux', ['display-message', '-p', '-t', exact(runtime.tmuxSession), format])
+      .then(result => result.stdout.trim(), () => '');
+    return output === `${runtime.runtimeId}\t${runtime.owner.ownerInstanceId}\t${runtime.tmuxOwnershipTokenHash}`;
+  }
+
+  async environmentMatches(
+    session: string,
+    runtimeId: string,
+    owner: OwnerIdentity,
+    tokenHash: string,
+  ): Promise<boolean> {
+    const values = await this.run('tmux', ['show-environment', '-t', exact(session)])
+      .then(result => environment(result.stdout), () => new Map<string, string>());
+    return values.get(ENV_RUNTIME_ID) === runtimeId && values.get(ENV_OWNER_INSTANCE) === owner.ownerInstanceId &&
+      values.get(ENV_OWNER_PROCESS_NONCE) === owner.ownerProcessNonce && values.get(ENV_TOKEN_HASH) === tokenHash;
+  }
+
+  async reassign(runtime: OwnedRuntime, owner: OwnerIdentity): Promise<void> {
+    if (!await this.metadataMatches(runtime) || !runtime.tmuxSession) {
+      throw Object.assign(new Error('Tmux ownership metadata does not permit handoff.'), { code: 'FENCED' });
+    }
+    await this.run('tmux', ['set-option', '-t', exact(runtime.tmuxSession), TMUX_OWNER_INSTANCE, owner.ownerInstanceId]);
+  }
+
+  async killSession(runtime: OwnedRuntime): Promise<boolean> {
+    if (!runtime.tmuxSession || !await this.metadataMatches(runtime)) return false;
+    await this.run('tmux', ['kill-session', '-t', exact(runtime.tmuxSession)]);
+    return true;
+  }
+
+  async sessionExists(session: string): Promise<boolean> {
+    return this.run('tmux', ['has-session', '-t', exact(session)]).then(() => true, () => false);
+  }
+}

package/src/supervisor/worker-bootstrap.ts

@@ -0,0 +1,43 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { WorkerClient, workerOptionsFromEnvironment, type WorkerClientOptions } from './worker-client.ts';
+
+export type WorkerLifecycleContext = Pick<ExtensionContext, 'abort' | 'shutdown'>;
+
+export class WorkerBootstrap {
+  private context?: WorkerLifecycleContext;
+  private readonly client: WorkerClient;
+
+  constructor(
+    options: WorkerClientOptions,
+    createClient: (options: WorkerClientOptions) => WorkerClient = value => new WorkerClient(value),
+  ) {
+    this.client = createClient({
+      ...options,
+      hooks: {
+        abort: () => this.context?.abort(),
+        shutdown: () => this.context?.shutdown(),
+      },
+    });
+  }
+
+  attach(context: WorkerLifecycleContext): void { this.context = context; }
+
+  start(): Promise<void> {
+    if (!this.context) throw new Error('Worker lifecycle context must be attached before control starts.');
+    return this.client.start();
+  }
+
+  busy(requestId: string): void { this.client.busy(requestId); }
+
+  ready(): void { this.client.ready(); }
+
+  dispose(): void { this.client.stop(); }
+}
+
+export function createWorkerBootstrap(
+  environment: NodeJS.ProcessEnv = process.env,
+  createClient?: (options: WorkerClientOptions) => WorkerClient,
+): WorkerBootstrap | undefined {
+  const options = workerOptionsFromEnvironment({ abort: () => {}, shutdown: () => {} }, environment);
+  return options ? new WorkerBootstrap(options, createClient) : undefined;
+}

package/src/supervisor/worker-client.ts

@@ -0,0 +1,233 @@
+import { createConnection, type Socket } from 'node:net';
+import {
+  CONTROL_PROTOCOL_VERSION, NdjsonFrameDecoder, assertSupervisorFrame, encodeControlFrame,
+  type SupervisorFrame, type WorkerFrame, type WorkerFramePayload,
+} from './control-protocol.ts';
+
+export type WorkerHooks = {
+  readonly abort: (requestId: string) => Promise<void> | void;
+  readonly shutdown: (reason: 'stop' | 'close' | 'reload_failed' | 'owner_lost') => Promise<void> | void;
+};
+
+export type WorkerClientOptions = {
+  readonly socketPath: string;
+  readonly runtimeId: string;
+  readonly controlToken: string;
+  readonly ownerProcessNonce: string;
+  readonly hooks: WorkerHooks;
+  readonly orphanMs?: number;
+  readonly reconnectMs?: number;
+  readonly now?: () => number;
+};
+
+export class WorkerClient {
+  private socket?: Socket;
+  private sequence = 0;
+  private activeRequestId?: string;
+  private authenticated = false;
+  private ownerEpoch?: number;
+  private stopped = false;
+  private orphaned = false;
+  private lastContact: number;
+  private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private watchdogTimer?: ReturnType<typeof setTimeout>;
+  private startPromise?: Promise<void>;
+  private shutdownPromise?: Promise<void>;
+  private startResolve?: () => void;
+  private startReject?: (error: Error) => void;
+  private readonly orphanMs: number;
+  private readonly reconnectMs: number;
+  private readonly now: () => number;
+
+  constructor(private readonly options: WorkerClientOptions) {
+    this.orphanMs = options.orphanMs ?? 15_000;
+    this.reconnectMs = options.reconnectMs ?? 250;
+    this.now = options.now ?? Date.now;
+    this.lastContact = this.now();
+    if (!Number.isFinite(this.orphanMs) || this.orphanMs <= 0 || !Number.isFinite(this.reconnectMs) || this.reconnectMs <= 0) {
+      throw new Error('Invalid worker watchdog timing.');
+    }
+  }
+
+  private nextSequence(): number {
+    this.sequence += 1;
+    return this.sequence;
+  }
+
+  private send(frame: WorkerFramePayload): boolean {
+    if (!this.socket || this.socket.destroyed) return false;
+    const value = {
+      version: CONTROL_PROTOCOL_VERSION,
+      runtimeId: this.options.runtimeId,
+      seq: this.nextSequence(),
+      ...(frame.type === 'hello' ? {} : { ownerEpoch: this.ownerEpoch }),
+      ...frame,
+    } as WorkerFrame;
+    this.socket.write(encodeControlFrame(value));
+    return true;
+  }
+
+  private clearReconnect(): void {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = undefined;
+  }
+
+  private scheduleReconnect(): void {
+    if (this.stopped || this.reconnectTimer) return;
+    const timer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.connect();
+    }, this.reconnectMs);
+    timer.unref();
+    this.reconnectTimer = timer;
+  }
+
+  private scheduleWatchdog(): void {
+    if (this.watchdogTimer) clearTimeout(this.watchdogTimer);
+    if (this.stopped) return;
+    const remaining = Math.max(0, this.orphanMs - (this.now() - this.lastContact));
+    const timer = setTimeout(() => { void this.checkWatchdog().catch(() => {}); }, remaining);
+    timer.unref();
+    this.watchdogTimer = timer;
+  }
+
+  private async checkWatchdog(): Promise<void> {
+    if (this.stopped || this.now() - this.lastContact < this.orphanMs) {
+      this.scheduleWatchdog();
+      return;
+    }
+    if (this.orphaned) return;
+    this.orphaned = true;
+    const requestId = this.activeRequestId;
+    this.activeRequestId = undefined;
+    try {
+      if (requestId) {
+        try { await this.options.hooks.abort(requestId); } catch {}
+      }
+      await this.options.hooks.shutdown('owner_lost');
+    } finally { this.stop(); }
+  }
+
+  private accept(frame: SupervisorFrame): void {
+    if (frame.runtimeId !== this.options.runtimeId) throw new Error('Supervisor frame targets another runtime.');
+    if (frame.type === 'hello_ack') {
+      if (frame.owner.ownerProcessNonce !== this.options.ownerProcessNonce) {
+        throw Object.assign(new Error('Supervisor process nonce does not match the worker owner.'), { code: 'FENCED' });
+      }
+      this.authenticated = true;
+      this.ownerEpoch = frame.owner.ownerEpoch;
+      this.lastContact = this.now();
+      this.scheduleWatchdog();
+      this.startResolve?.();
+      this.startResolve = undefined;
+      this.startReject = undefined;
+      if (this.activeRequestId) this.send({ type: 'state', state: 'busy', requestId: this.activeRequestId });
+      else this.send({ type: 'ready' });
+      return;
+    }
+    if (!this.authenticated) throw new Error('Supervisor sent a frame before authentication.');
+    this.lastContact = this.now();
+    this.scheduleWatchdog();
+    if (frame.type === 'ping') {
+      this.send({ type: 'pong', nonce: frame.nonce });
+      return;
+    }
+    if (frame.type === 'cancel_request') {
+      if (this.activeRequestId === frame.requestId) void (async () => {
+        try { await this.options.hooks.abort(frame.requestId); } catch {}
+      })();
+      return;
+    }
+    if (frame.type === 'prepare_shutdown') {
+      void this.prepareShutdown(frame.reason).catch(() => {});
+    }
+  }
+
+  private prepareShutdown(reason: 'stop' | 'close' | 'reload_failed' | 'owner_lost'): Promise<void> {
+    if (this.shutdownPromise) return this.shutdownPromise;
+    const cleanup = (async () => {
+      const requestId = this.activeRequestId;
+      this.activeRequestId = undefined;
+      if (requestId) {
+        try { await this.options.hooks.abort(requestId); } catch {}
+      }
+      this.send({ type: 'shutdown_ack' });
+      await this.options.hooks.shutdown(reason);
+    })();
+    this.shutdownPromise = cleanup;
+    return cleanup;
+  }
+
+  private connect(): void {
+    if (this.stopped) return;
+    this.clearReconnect();
+    this.authenticated = false;
+    this.ownerEpoch = undefined;
+    const decoder = new NdjsonFrameDecoder<SupervisorFrame>(assertSupervisorFrame);
+    const socket = createConnection({ path: this.options.socketPath });
+    this.socket = socket;
+    socket.on('connect', () => {
+      this.send({ type: 'hello', token: this.options.controlToken, ownerProcessNonce: this.options.ownerProcessNonce });
+    });
+    socket.on('data', chunk => {
+      try { for (const frame of decoder.push(chunk)) this.accept(frame); }
+      catch { socket.destroy(); }
+    });
+    socket.on('error', () => {});
+    socket.on('close', () => {
+      if (this.socket === socket) this.socket = undefined;
+      this.authenticated = false;
+      this.scheduleReconnect();
+      this.scheduleWatchdog();
+    });
+  }
+
+  start(): Promise<void> {
+    if (this.startPromise) return this.startPromise;
+    this.startPromise = new Promise<void>((resolvePromise, reject) => {
+      this.startResolve = resolvePromise;
+      this.startReject = reject;
+    });
+    this.scheduleWatchdog();
+    this.connect();
+    return this.startPromise;
+  }
+
+  ready(): void {
+    this.activeRequestId = undefined;
+    if (this.authenticated) this.send({ type: 'state', state: 'ready' });
+  }
+
+  busy(requestId: string): void {
+    this.activeRequestId = requestId;
+    if (this.authenticated) this.send({ type: 'state', state: 'busy', requestId });
+  }
+
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.clearReconnect();
+    if (this.watchdogTimer) clearTimeout(this.watchdogTimer);
+    this.watchdogTimer = undefined;
+    this.socket?.destroy();
+    this.socket = undefined;
+    if (!this.authenticated) this.startReject?.(new Error('Worker control client stopped before authentication.'));
+    this.startResolve = undefined;
+    this.startReject = undefined;
+  }
+}
+
+export function workerOptionsFromEnvironment(
+  hooks: WorkerHooks,
+  environment: NodeJS.ProcessEnv = process.env,
+): WorkerClientOptions | undefined {
+  const socketPath = environment.PI_TEAM_CONTROL_SOCKET;
+  const runtimeId = environment.PI_TEAM_RUNTIME_ID;
+  const controlToken = environment.PI_TEAM_CONTROL_TOKEN;
+  const ownerProcessNonce = environment.PI_TEAM_OWNER_PROCESS_NONCE;
+  if (!socketPath && !runtimeId && !controlToken && !ownerProcessNonce) return undefined;
+  if (!socketPath || !runtimeId || !controlToken || !ownerProcessNonce) {
+    throw new Error('Incomplete supervised Team worker environment.');
+  }
+  return { socketPath, runtimeId, controlToken, ownerProcessNonce, hooks };
+}

package/src/ui/team-dashboard.ts

@@ -0,0 +1,179 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Key, matchesKey, truncateToWidth } from '@earendil-works/pi-tui';
+import type { Membership } from '../runtime/membership.ts';
+import type { TeamRuntime } from '../runtime/team-runtime.ts';
+import { ownerProcessNonce } from '../supervisor/supervisor.ts';
+
+export type DashboardSnapshot = {
+  readonly team: { readonly teamId: string; readonly state: string; readonly alias: string };
+  readonly members: readonly {
+    readonly id: string; readonly alias: string; readonly kind: string; readonly status: 'online' | 'offline';
+  }[];
+  readonly inbox: readonly {
+    readonly id: string; readonly kind: string; readonly from: string; readonly createdAt: string;
+  }[];
+  readonly runtimes: readonly {
+    readonly id: string; readonly memberId: string; readonly state: string; readonly requestId?: string;
+  }[];
+  readonly requests: readonly { readonly id: string; readonly status: string; readonly at: string }[];
+  readonly leases: readonly {
+    readonly id: string; readonly kind: string; readonly resource: string; readonly expiresAt: string;
+  }[];
+  readonly warnings: readonly string[];
+  readonly omitted: boolean;
+};
+
+type Row = { readonly id: string; readonly text: string };
+const DISPLAY_LIMIT = 10;
+
+export function sanitizeDashboardText(value: string): string {
+  return value.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '')
+    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export async function loadDashboardSnapshot(
+  runtime: TeamRuntime,
+  membership: Membership,
+): Promise<DashboardSnapshot> {
+  const [team, peers, inbox, runtimes, leases, receipts] = await Promise.all([
+    runtime.teams.read(membership.teamId),
+    runtime.memberships.peerPage(membership, 100),
+    runtime.delivery.inboxItems(membership, 100),
+    runtime.runtimes.list(membership.teamId),
+    runtime.leases.list(membership.teamId),
+    runtime.receipts.list(membership.teamId, membership.memberId, 100),
+  ]);
+  if (!team) throw new Error(`Team "${membership.teamId}" is missing.`);
+  const members = [
+    { id: membership.memberId, alias: sanitizeDashboardText(membership.alias), kind: membership.kind, status: 'online' as const },
+    ...peers.peers.map(peer => ({
+      id: peer.memberId,
+      alias: sanitizeDashboardText(peer.alias),
+      kind: peer.kind,
+      status: peer.status,
+    })),
+  ];
+  const activeRuntimes = runtimes.filter(record => record.state !== 'terminated' &&
+    record.owner.ownerSessionId === membership.sessionId && record.owner.ownerProcessNonce === ownerProcessNonce()).map(record => ({
+    id: record.runtimeId,
+    memberId: record.memberId,
+    state: record.state,
+    ...(record.activeRequestId ? { requestId: record.activeRequestId } : {}),
+  }));
+  const activeLeases = leases.filter(lease => !lease.releasedAt && Date.parse(lease.expiresAt) > Date.now()).map(lease => ({
+    id: lease.leaseId,
+    kind: lease.kind,
+    resource: sanitizeDashboardText(lease.resourceId),
+    expiresAt: lease.expiresAt,
+  }));
+  const warnings = [
+    ...(team.state === 'open' ? [] : [`Team state is ${team.state}.`]),
+    ...activeRuntimes.filter(record => ['lost', 'stopping'].includes(record.state))
+      .map(record => `Runtime ${record.id} is ${record.state}.`),
+  ];
+  return {
+    team: { teamId: team.teamId, state: team.state, alias: sanitizeDashboardText(membership.alias) },
+    members,
+    inbox: inbox.items.map(item => ({
+      id: item.messageId,
+      kind: item.kind,
+      from: item.fromMemberId,
+      createdAt: item.createdAt,
+    })),
+    runtimes: activeRuntimes,
+    requests: receipts.map(receipt => ({ id: receipt.messageId, status: receipt.status, at: receipt.at })),
+    leases: activeLeases,
+    warnings,
+    omitted: inbox.nextCursor !== undefined || peers.nextCursor !== undefined,
+  };
+}
+
+function dashboardRows(snapshot: DashboardSnapshot): readonly Row[] {
+  return [
+    { id: 'section-team', text: `TEAM · ${snapshot.team.teamId} · ${snapshot.team.state} · joined as ${snapshot.team.alias}` },
+    { id: 'section-members', text: `Members (${snapshot.members.length})` },
+    ...snapshot.members.slice(0, DISPLAY_LIMIT).map(member => ({
+      id: `member:${member.id}`,
+      text: `${member.status === 'online' ? '● online' : '○ offline'} · ${member.alias} · ${member.kind}`,
+    })),
+    { id: 'section-inbox', text: `Inbox (${snapshot.inbox.length}${snapshot.omitted ? '+' : ''})` },
+    ...snapshot.inbox.slice(0, DISPLAY_LIMIT).map(item => ({
+      id: `inbox:${item.id}`,
+      text: `◇ ${item.kind} · ${item.id} · from ${item.from} · ${item.createdAt}`,
+    })),
+    { id: 'section-runtimes', text: `Owned runtimes (${snapshot.runtimes.length})` },
+    ...snapshot.runtimes.slice(0, DISPLAY_LIMIT).map(runtime => ({
+      id: `runtime:${runtime.id}`,
+      text: `◆ ${runtime.state} · ${runtime.id} · member ${runtime.memberId}${runtime.requestId ? ` · request ${runtime.requestId}` : ''}`,
+    })),
+    { id: 'section-requests', text: `Requests (${snapshot.requests.length})` },
+    ...snapshot.requests.slice(0, DISPLAY_LIMIT).map(request => ({
+      id: `request:${request.id}`,
+      text: `◇ ${request.status} · ${request.id} · ${request.at}`,
+    })),
+    { id: 'section-leases', text: `Leases (${snapshot.leases.length})` },
+    ...snapshot.leases.slice(0, DISPLAY_LIMIT).map(lease => ({
+      id: `lease:${lease.id}`,
+      text: `◇ ${lease.kind} · ${lease.resource} · expires ${lease.expiresAt}`,
+    })),
+    { id: 'section-warnings', text: `Shutdown/recovery warnings (${snapshot.warnings.length})` },
+    ...snapshot.warnings.slice(0, DISPLAY_LIMIT).map((warning, index) => ({ id: `warning:${index}:${warning}`, text: `! warning · ${warning}` })),
+    { id: 'section-controls', text: '↑↓ select · Esc close view (operations continue)' },
+  ];
+}
+
+export function renderDashboard(snapshot: DashboardSnapshot, width: number, selectedId?: string): string[] {
+  const safeWidth = Math.max(1, width);
+  return dashboardRows(snapshot).map(row => {
+    const heading = row.id.startsWith('section-');
+    const prefix = row.id === selectedId ? '> ' : heading ? '  ' : '  ';
+    return truncateToWidth(`${prefix}${row.text}`, safeWidth);
+  });
+}
+
+export function dashboardText(snapshot: DashboardSnapshot, width = 80): string {
+  return renderDashboard(snapshot, width).join('\n');
+}
+
+class DashboardComponent {
+  private selectedId?: string;
+
+  constructor(
+    private readonly snapshot: DashboardSnapshot,
+    private readonly close: () => void,
+    private readonly renderRequested: () => void,
+  ) {
+    this.selectedId = dashboardRows(snapshot).find(row => !row.id.startsWith('section-'))?.id;
+  }
+
+  private move(offset: number): void {
+    const selectable = dashboardRows(this.snapshot).filter(row => !row.id.startsWith('section-'));
+    if (selectable.length === 0) return;
+    const current = selectable.findIndex(row => row.id === this.selectedId);
+    const next = current < 0 ? 0 : Math.max(0, Math.min(selectable.length - 1, current + offset));
+    this.selectedId = selectable[next]?.id;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape)) { this.close(); return; }
+    if (matchesKey(data, Key.up)) this.move(-1);
+    else if (matchesKey(data, Key.down)) this.move(1);
+    else return;
+    this.renderRequested();
+  }
+
+  render(width: number): string[] { return renderDashboard(this.snapshot, width, this.selectedId); }
+  invalidate(): void {}
+}
+
+export async function openTeamDashboard(context: ExtensionContext, snapshot: DashboardSnapshot): Promise<void> {
+  if (!context.hasUI || context.mode !== 'tui') {
+    context.ui.notify(dashboardText(snapshot), 'info');
+    return;
+  }
+  await context.ui.custom<void>((tui, _theme, _keybindings, done) =>
+    new DashboardComponent(snapshot, () => done(undefined), () => tui.requestRender()));
+}