ac-teams 0.0.1 → 0.0.3

package/src/schemas.ts

@@ -1,10 +1,12 @@
 import { Type } from "typebox";
 import { Value } from "typebox/value";
+import { taskLabelMaxLength, taskLabelPattern, memberNameMaxLength, memberNamePattern } from "./types.ts";
 
 const id = Type.String({ minLength: 1, maxLength: 128 });
 const text = Type.String({ minLength: 1, maxLength: 16000 });
 export const AgentSchema = Type.Object({
   action: Type.Union(["launch", "list", "status", "stop", "resume", "limits", "cleanup"].map(v => Type.Literal(v))),
+  name: Type.Optional(Type.String({ minLength: 1, maxLength: memberNameMaxLength, pattern: memberNamePattern.source, description: "Required on launch: a unique descriptive one- or two-word lowercase name, e.g. parser or code-review. Retained on resume." })),
   id: Type.Optional(id), brief: Type.Optional(text), cwd: Type.Optional(Type.String({ minLength: 1, maxLength: 4096 })),
   model: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
   thinking: Type.Optional(Type.Union(["off", "minimal", "low", "medium", "high", "xhigh"].map(v => Type.Literal(v)))),
@@ -17,6 +19,7 @@ export const TaskSchema = Type.Object({
   offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
   action: Type.Union(["create", "list", "read", "edit", "claim", "start", "release", "complete", "reopen"].map(v => Type.Literal(v))),
   id: Type.Optional(id), title: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+  label: Type.Optional(Type.String({ minLength: 1, maxLength: taskLabelMaxLength, pattern: taskLabelPattern.source, description: "A concise 1–3-word task label. Defaults to title only when title satisfies this limit." })),
   description: Type.Optional(Type.String({ maxLength: 16000 })),
   dependencies: Type.Optional(Type.Array(id, { maxItems: 100, uniqueItems: true })),
 }, { additionalProperties: false });
@@ -26,7 +29,30 @@ export const MessageSchema = Type.Object({
   text: Type.Optional(text), query: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
   after: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
 }, { additionalProperties: false });
+const UserActionSchema = Type.Object({
+  action: Type.Union([Type.Literal("task_request"), Type.Literal("feedback"), Type.Literal("resume")]),
+  id: Type.Optional(id), text: Type.Optional(text),
+  model: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+  thinking: AgentSchema.properties.thinking,
+}, { additionalProperties: false });
+const ContextUsageSchema = Type.Object({
+  tokens: Type.Union([Type.Null(), Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER })]),
+  contextWindow: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+  percent: Type.Union([Type.Null(), Type.Number({ minimum: 0 })]),
+}, { additionalProperties: false });
+const EventSchema = Type.Object({
+  type: Type.Union(["agent_start", "agent_settled", "activity", "summary", "model_error", "telemetry"].map(v => Type.Literal(v))),
+  text: Type.Optional(Type.String({ maxLength: 2000 })),
+  model: Type.Optional(Type.String({ maxLength: 256 })),
+  modelName: Type.Optional(Type.String({ maxLength: 256 })),
+  contextUsage: Type.Optional(Type.Union([Type.Null(), ContextUsageSchema])),
+}, { additionalProperties: false });
 export function validate(operation: string, value: unknown): void {
-  const schema = operation === "agent" ? AgentSchema : operation === "task" ? TaskSchema : operation === "message" ? MessageSchema : undefined;
+  const schema = operation === "agent" ? AgentSchema : operation === "task" ? TaskSchema : operation === "message" ? MessageSchema : operation === "ui" ? UserActionSchema : operation === "event" ? EventSchema : undefined;
   if (!schema || !Value.Check(schema, value)) throw new Error(`Invalid ${operation} request`);
+  if (operation === "agent") {
+    const args = value as { action: string; name?: string };
+    if (args.action === "launch" && !args.name) throw new Error("A descriptive teammate name is required on launch");
+    if (args.action !== "launch" && args.name !== undefined) throw new Error("A teammate name can only be set on launch");
+  }
 }

package/src/store.ts

@@ -2,9 +2,12 @@ import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdi
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { isDescendant, isLive } from "./types.ts";
+import { stripVTControlCharacters } from "node:util";
+import { isDescendant, isLive, memberNamePattern, memberNameMaxLength, taskLabelMaxLength, taskLabelPattern } from "./types.ts";
 import type { TeamState, TaskArgs, MessageArgs, Task, TaskView, Message, Worktree } from "./types.ts";
 
+// UI envelopes add task context after the public 16,000-character input limit.
+const maxMessageText = 17000;
 function code(error: unknown): string | undefined { return (error as NodeJS.ErrnoException)?.code; }
 function requireValue(ok: unknown, message: string): asserts ok { if (!ok) throw new Error(message); }
 function text(value: unknown, max = 16000): value is string { return typeof value === "string" && value.trim().length > 0 && value.length <= max; }
@@ -49,28 +52,44 @@ function taskView(state: TeamState, task: Task): TaskView {
 }
 
 function migrate(state: unknown): boolean {
-  if (!object(state) || state.version !== 1) return false;
+  if (!object(state) || (state.version !== 1 && state.version !== 2)) return false;
   requireValue(object(state.tasks), "Invalid legacy state tasks");
+  let number = 0;
   for (const task of Object.values(state.tasks)) {
-    requireValue(object(task) && typeof task.status === "string" && ["pending", "claimed", "completed"].includes(task.status), "Invalid legacy task status");
-    requireValue(task.status === "pending" ? task.owner === undefined : typeof task.owner === "string", "Invalid legacy task owner");
-    if (task.status === "pending") task.status = "todo";
-    else if (task.status === "claimed") task.status = "in_progress";
-    else task.status = "done";
+    requireValue(object(task) && text(task.title, 500), "Invalid legacy task");
+    if (state.version === 1) {
+      requireValue(typeof task.status === "string" && ["pending", "claimed", "completed"].includes(task.status), "Invalid legacy task status");
+      requireValue(task.status === "pending" ? task.owner === undefined : typeof task.owner === "string", "Invalid legacy task owner");
+      if (task.status === "pending") task.status = "todo";
+      else if (task.status === "claimed") task.status = "in_progress";
+      else task.status = "done";
+    }
+    task.number = ++number;
+    task.label = stripVTControlCharacters(task.title).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").trim().split(/\s+/).slice(0, 3).join(" ").slice(0, taskLabelMaxLength).trim() || "Task";
   }
-  state.version = 2;
+  state.version = 3;
   return true;
 }
 
 function validate(state: unknown): asserts state is TeamState {
   requireValue(object(state), "Invalid state snapshot");
   id(state.id);
-  requireValue(state.version === 2 && text(state.root) && integer(state.limit, 1) && integer(state.depth) && object(state.members) && object(state.tasks) && Array.isArray(state.messages), "Invalid state snapshot schema");
+  requireValue(state.version === 3 && text(state.root) && integer(state.limit, 1) && integer(state.depth) && object(state.members) && object(state.tasks) && Array.isArray(state.messages), "Invalid state snapshot schema");
   const members = state.members;
+  const names = new Set<string>(["main", "root", ...Object.keys(members)]);
   for (const [key, member] of Object.entries(members)) {
     requireValue(object(member) && member.id === key && text(key) && integer(member.depth) && text(member.token) && text(member.cwd) && ["starting", "busy", "idle", "stopping", "stopped", "interrupted"].includes(String(member.status)) && integer(member.notified), "Invalid state member");
+    if (member.name !== undefined) {
+      requireValue(text(member.name, memberNameMaxLength) && memberNamePattern.test(member.name) && !names.has(member.name), "Invalid or duplicate teammate name");
+      names.add(member.name);
+    }
     requireValue(member.parent === undefined || (text(member.parent) && Object.hasOwn(members, member.parent)), "Invalid member parent");
-    for (const field of ["identity", "sessionId", "sessionFile", "error"]) requireValue(member[field] === undefined || typeof member[field] === "string", "Invalid member field");
+    for (const field of ["identity", "sessionId", "sessionFile", "error", "model", "modelName", "thinking", "activity", "summary"]) requireValue(member[field] === undefined || typeof member[field] === "string", "Invalid member field");
+    if (member.contextUsage !== undefined) {
+      const usage = member.contextUsage;
+      requireValue(object(usage) && integer(usage.contextWindow, 1) && (usage.tokens === null || integer(usage.tokens)) && (usage.percent === null || typeof usage.percent === "number" && Number.isFinite(usage.percent) && usage.percent >= 0), "Invalid member context usage");
+    }
+    requireValue(member.terminal === undefined || typeof member.terminal === "boolean", "Invalid member terminal flag");
     requireValue(member.pid === undefined || integer(member.pid, 1), "Invalid member PID");
     requireValue(member.worktree === undefined || validateWorktree(member.worktree), "Invalid member worktree");
     const seen = new Set<string>([key]);
@@ -83,10 +102,15 @@ function validate(state: unknown): asserts state is TeamState {
   requireValue(Object.hasOwn(members, state.root), "Invalid root member");
   const tasks = state.tasks;
   const edges: Record<string, string[]> = {};
+  const taskNumbers = new Set<number>();
   for (const [key, task] of Object.entries(tasks)) {
     requireValue(object(task) && task.id === key && text(key) && integer(task.revision, 1) && text(task.title, 500) && text(task.description) && typeof task.status === "string" && ["todo", "in_progress", "done"].includes(task.status) && Array.isArray(task.dependencies), "Invalid state task");
+    requireValue(integer(task.number, 1) && !taskNumbers.has(task.number) && text(task.label, taskLabelMaxLength) && taskLabelPattern.test(task.label), "Invalid task number or label");
+    taskNumbers.add(task.number);
+    requireValue(task.completedAt === undefined || integer(task.completedAt), "Invalid task completion time");
     requireValue(task.dependencies.every(dep => typeof dep === "string" && dep !== key && Object.hasOwn(tasks, dep)) && new Set(task.dependencies).size === task.dependencies.length, "Invalid task dependencies");
     requireValue(task.owner === undefined || (typeof task.owner === "string" && Object.hasOwn(members, task.owner)), "Invalid task owner");
+    requireValue(task.creator === undefined || (typeof task.creator === "string" && Object.hasOwn(members, task.creator)), "Invalid task creator");
     requireValue(task.status !== "in_progress" || task.owner !== undefined, "In-progress task requires an owner");
     requireValue(task.status === "todo" || task.dependencies.every(dep => (tasks[dep] as Record<string, unknown>).status === "done"), "Active or done task has unfinished dependencies");
     edges[key] = task.dependencies;
@@ -104,7 +128,7 @@ function validate(state: unknown): asserts state is TeamState {
   let last = 0;
   const messageIds = new Set<string>();
   for (const message of state.messages) {
-    requireValue(object(message) && integer(message.seq, last + 1) && text(message.id) && !messageIds.has(message.id) && typeof message.from === "string" && Object.hasOwn(members, message.from) && Array.isArray(message.recipients) && message.recipients.every(recipient => typeof recipient === "string" && Object.hasOwn(members, recipient)) && new Set(message.recipients).size === message.recipients.length && text(message.text) && typeof message.time === "string" && Number.isFinite(Date.parse(message.time)), "Invalid state message");
+    requireValue(object(message) && integer(message.seq, last + 1) && text(message.id) && !messageIds.has(message.id) && typeof message.from === "string" && Object.hasOwn(members, message.from) && Array.isArray(message.recipients) && message.recipients.every(recipient => typeof recipient === "string" && Object.hasOwn(members, recipient)) && new Set(message.recipients).size === message.recipients.length && text(message.text, maxMessageText) && typeof message.time === "string" && Number.isFinite(Date.parse(message.time)), "Invalid state message");
     last = message.seq; messageIds.add(message.id);
   }
 }
@@ -233,7 +257,10 @@ export class Store {
     return this.update(state => {
       if (args.action === "create") {
         requireValue(text(args.title, 500) && text(args.description), "Task requires a title (max 500) and description (max 16000)");
-        const task: Task = { id: randomUUID(), revision: 1, title: args.title, description: args.description, dependencies: args.dependencies === undefined ? [] : structuredClone(args.dependencies), status: "todo" };
+        const label = args.label ?? args.title;
+        requireValue(text(label, taskLabelMaxLength) && taskLabelPattern.test(label), "Task requires a 1–3-word label (max 60 characters); a concise title can serve as the label");
+        const number = Object.values(state.tasks).reduce((max, task) => Math.max(max, task.number), 0) + 1;
+        const task: Task = { id: randomUUID(), number, label, revision: 1, creator: actor, title: args.title, description: args.description, dependencies: args.dependencies === undefined ? [] : structuredClone(args.dependencies), status: "todo" };
         state.tasks[task.id] = task;
         return taskView(state, task);
       }
@@ -244,6 +271,7 @@ export class Store {
         requireValue(task.status === "todo", "Only to-do tasks can be edited");
         requireValue(!task.owner || task.owner === actor, "Only the owner can edit a reserved task");
         if (args.title !== undefined) task.title = args.title;
+        if (args.label !== undefined) task.label = args.label;
         if (args.description !== undefined) task.description = args.description;
         if (args.dependencies !== undefined) task.dependencies = structuredClone(args.dependencies);
       } else if (args.action === "claim") {
@@ -261,6 +289,7 @@ export class Store {
         requireValue(task.status === "in_progress", "Only in-progress tasks can be completed; start it first");
         requireValue(args.acceptance === true, "Completion requires acceptance=true after checking acceptance criteria");
         task.status = "done";
+        task.completedAt = Date.now();
       } else if (args.action === "release") {
         requireValue(task.owner, "Task has no owner to release");
         const interrupted = ["interrupted", "stopped"].includes(state.members[task.owner].status);
@@ -273,16 +302,18 @@ export class Store {
         const dependents = Object.values(state.tasks).filter(other => other.dependencies.includes(task.id) && other.status !== "todo");
         requireValue(dependents.length === 0, `Cannot reopen task with active or done dependents: ${dependents.map(t => t.id).join(", ")}`);
         task.status = "todo";
+        delete task.completedAt;
       } else throw new Error("Unknown task action");
       task.revision++;
       return taskView(state, task);
     });
   }
 
-  message(actor: string, args: MessageArgs): Message | Message[] {
+  message(actor: string, args: MessageArgs, enveloped = false): Message | Message[] {
     requireValue(!this.closed && Object.hasOwn(this.state.members, actor), "Unknown actor or closed store");
     if (args.action === "send") return this.update(state => {
-      requireValue(text(args.text), "Message text must be nonempty and at most 16000 characters");
+      const limit = enveloped ? maxMessageText : 16000;
+      requireValue(text(args.text, limit), `Message text must be nonempty and at most ${limit} characters`);
       const recipients = args.recipients === undefined ? Object.values(state.members).filter(member => member.id !== actor && isLive(member)).map(member => member.id) : args.recipients;
       requireValue(Array.isArray(recipients) && (args.recipients === undefined || recipients.length > 0) && new Set(recipients).size === recipients.length && recipients.every(recipient => typeof recipient === "string" && Object.hasOwn(state.members, recipient) && isLive(state.members[recipient])), "Recipients must be unique live member IDs");
       const message = { seq: (state.messages.at(-1)?.seq ?? 0) + 1, id: randomUUID(), from: actor, recipients: [...recipients], text: args.text, time: new Date().toISOString() };

package/src/task-summary.ts

@@ -0,0 +1,34 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { cleanText } from "./render.ts";
+import { taskName, type TaskView } from "./types.ts";
+
+export function summaryTasks(tasks: TaskView[]): TaskView[] {
+  const dependents = new Map<string, number>();
+  for (const task of tasks) {
+    if (task.status !== "done") for (const id of task.blockedBy) dependents.set(id, (dependents.get(id) ?? 0) + 1);
+  }
+  const rank = (task: TaskView) => task.status === "in_progress" ? 0
+    : task.status === "done" ? 3 : task.blockedBy.length ? 2 : dependents.has(task.id) ? 1 : 4;
+  return tasks.filter(task => rank(task) < 4).sort((a, b) => rank(a) - rank(b)
+    || (a.status === "done" && b.status === "done" ? (b.completedAt ?? -1) - (a.completedAt ?? -1) || b.number - a.number
+      : (dependents.get(b.id) ?? 0) - (dependents.get(a.id) ?? 0) || a.number - b.number)).slice(0, 5);
+}
+
+export function renderTaskSummary(tasks: TaskView[], theme: Theme, width: number): string[] {
+  if (!tasks.length) return [];
+  const byId = new Map(tasks.map(task => [task.id, task]));
+  const visible = summaryTasks(tasks);
+  const rows = visible.map((task, index) => {
+    const status = task.status === "done" ? "done" : task.status === "in_progress" ? "working" : task.blockedBy.length ? "blocked" : "ready";
+    const color = status === "done" ? "success" : status === "working" ? "accent" : status === "blocked" ? "error" : "muted";
+    const marker = status === "done" ? "✓" : status === "working" ? "●" : status === "blocked" ? "⊘" : "○";
+    const blockers = task.blockedBy.length ? ` by ${task.blockedBy.map(id => `#${byId.get(id)?.number ?? "?"}`).join(", ")}` : "";
+    const name = cleanText(taskName(task)).replaceAll("\n", " ");
+    return theme.fg("dim", index === visible.length - 1 ? "└─ " : "├─ ")
+      + theme.fg(color, marker) + " " + theme.fg(status === "done" ? "dim" : "text", name)
+      + theme.fg(color, ` · ${status}${blockers}`);
+  });
+  return [theme.fg("muted", `Tasks ${tasks.filter(task => task.status === "done").length}/${tasks.length} done`), ...rows]
+    .map(row => truncateToWidth(row, width));
+}

package/src/telemetry.ts

@@ -0,0 +1,19 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Member, Telemetry } from "./types.ts";
+
+export function readTelemetry(ctx: ExtensionContext): Telemetry {
+  const usage = ctx.getContextUsage();
+  return { type: "telemetry", model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
+    modelName: ctx.model?.name ?? ctx.model?.id,
+    contextUsage: usage ? { tokens: usage.tokens, contextWindow: usage.contextWindow, percent: usage.percent } : null };
+}
+
+export function modelContext(member: Pick<Member, "model" | "modelName" | "contextUsage">): string {
+  const model = member.modelName || member.model?.slice(member.model.indexOf("/") + 1) || "Model unknown";
+  const usage = member.contextUsage;
+  const count = (value: number) => value >= 1000 ? `${(value / 1000).toFixed(1).replace(/\.0$/, "")}k` : String(value);
+  const context = !usage ? "context unknown" : usage.tokens === null || usage.percent === null
+    ? `context unknown / ${count(usage.contextWindow)}`
+    : `${count(usage.tokens)} / ${count(usage.contextWindow)} (${usage.percent.toFixed(1).replace(/\.0$/, "")}%)`;
+  return `${model} · ${context}`;
+}

package/src/terminal-agent.ts

@@ -0,0 +1,110 @@
+import { execFile } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { unlinkSync, writeFileSync } from "node:fs";
+import { promisify } from "node:util";
+import { processAlive, processIdentity } from "./store.ts";
+
+const exec = promisify(execFile);
+const quote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+export async function tmux(socket: string, args: string[], timeout = 5000): Promise<string> {
+  const env = { ...process.env };
+  delete env.TMUX; delete env.TMUX_PANE;
+  const result = await exec("tmux", ["-S", socket, ...args], { env, timeout, maxBuffer: 65536 });
+  return result.stdout.trim();
+}
+interface Options {
+  id: string; dir: string; cwd: string; args: string[]; env: NodeJS.ProcessEnv; command?: string;
+  request: (type: string, fields?: Record<string, unknown>, timeout?: number) => Promise<unknown>;
+}
+/** One native Pi process in a team-private tmux server; never recreates its transcript. */
+export class TerminalAgent extends EventEmitter {
+  readonly process: { pid?: number } = {};
+  readonly socket: string;
+  readonly exited: Promise<void>;
+  private resolveExit!: () => void;
+  private identity?: string;
+  private timer?: NodeJS.Timeout;
+  private closed = false;
+  private stopPromise?: Promise<void>;
+  private files: string[] = [];
+  private options: Options;
+  constructor(options: Options) {
+    super();
+    this.options = options;
+    this.socket = join(options.dir, "t.sock");
+    this.exited = new Promise(resolve => { this.resolveExit = resolve; });
+  }
+  async start(): Promise<void> {
+    const base = join(this.options.dir, `.terminal-${randomUUID()}`);
+    const config = base + ".conf", script = base + ".sh";
+    try {
+      // Credentials travel in a private file, never in tmux's command-line arguments.
+      writeFileSync(config, "set -g status off\nset -g prefix None\nset -s extended-keys always\nbind-key -n C-S-Left detach-client\n", { flag: "wx", mode: 0o600 });
+      this.files.push(config);
+      const exports = Object.entries(this.options.env)
+        .filter(([key, value]) => key.startsWith("AC_TEAMS_") && value !== undefined)
+        .map(([key, value]) => `export ${key}=${quote(value!)}`);
+      const command = this.options.command ?? process.env.AC_TEAMS_PI ?? "pi";
+      writeFileSync(script, [...exports,
+        "exec " + [command, ...this.options.args].map(quote).join(" "), ""].join("\n"), { flag: "wx", mode: 0o600 });
+      this.files.push(script);
+      const pid = Number(await tmux(this.socket, ["-f", config, "new-session", "-d", "-s", this.options.id,
+        "-c", this.options.cwd, "-x", String(process.stdout.columns || 120), "-y", String(process.stdout.rows || 40),
+        "-P", "-F", "#{pane_pid}", "--", "/bin/sh", script]));
+      if (!Number.isSafeInteger(pid) || pid < 1) throw new Error("tmux did not return a native member PID");
+      this.process.pid = pid;
+      this.identity = processIdentity(pid);
+      if (!this.identity) throw new Error("Native Pi exited during terminal startup");
+      this.timer = setInterval(() => {
+        try { if (!processAlive(pid, this.identity)) void this.finish(); }
+        catch (error) { clearInterval(this.timer); this.emit("failure", error); }
+      }, 250);
+    } catch (error) {
+      await tmux(this.socket, ["kill-session", "-t", this.options.id]).catch(() => {});
+      await this.finish();
+      throw error;
+    }
+  }
+  request(type: string, fields: Record<string, unknown> = {}, timeout = 10000): Promise<unknown> {
+    return this.options.request(type, fields, timeout);
+  }
+  private async finish(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    clearInterval(this.timer);
+    await tmux(this.socket, ["kill-session", "-t", this.options.id]).catch(() => {});
+    for (const file of this.files) {
+      try { unlinkSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") this.emit("failure", error); }
+    }
+    this.files = [];
+    this.emit("exit");
+    this.resolveExit();
+  }
+  private async wait(ms: number): Promise<boolean> {
+    let timer: NodeJS.Timeout | undefined;
+    const result = await Promise.race([this.exited.then(() => true), new Promise<false>(resolve => { timer = setTimeout(() => resolve(false), ms); })]);
+    clearTimeout(timer);
+    return result;
+  }
+  private signal(signal: NodeJS.Signals): void {
+    const pid = this.process.pid;
+    if (!pid || !this.identity) throw new Error("Cannot verify native Pi ownership; refusing to signal");
+    if (processAlive(pid, this.identity)) process.kill(pid, signal);
+  }
+  stop(): Promise<void> { this.stopPromise ??= this.stopOnce(); return this.stopPromise; }
+  private async stopOnce(): Promise<void> {
+    if (this.closed) { await this.exited; return; }
+    await this.request("abort", {}, 1000).catch(() => {});
+    await this.request("shutdown", {}, 1000).catch(() => {});
+    if (await this.wait(4000)) return;
+    this.emit("forced", "SIGHUP");
+    await tmux(this.socket, ["kill-session", "-t", this.options.id]).catch(() => {});
+    if (await this.wait(1000)) return;
+    this.emit("forced", "SIGTERM"); this.signal("SIGTERM");
+    if (await this.wait(2000)) return;
+    this.emit("forced", "SIGKILL"); this.signal("SIGKILL");
+    if (!(await this.wait(2000))) throw new Error("Owned native Pi did not exit after SIGKILL");
+  }
+}

package/src/terminal-ui.ts

@@ -0,0 +1,174 @@
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { CustomEditor, getSettingsListTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, renderFakeCursor, truncateToWidth, visibleWidth, SettingsList, type EditorComponent, type Focusable } from "@earendil-works/pi-tui";
+import { cleanText } from "./render.ts";
+import { isLive, taskName, memberName } from "./types.ts";
+import { saveDisplaySettings, type DisplaySettings } from "./config.ts";
+import { modelContext, readTelemetry } from "./telemetry.ts";
+import { renderTaskSummary } from "./task-summary.ts";
+import type { PanelHost } from "./ui-types.ts";
+
+const exec = promisify(execFile);
+export async function visitMember(ctx: ExtensionContext, host: PanelHost, socket: string, id: string): Promise<void> {
+  if (ctx.mode !== "tui") throw new Error("Live sessions require an interactive terminal");
+  if (id === host.self) return;
+  const member = (await host.snapshot()).members.find(member => member.id === id);
+  if (!member || !isLive(member)) throw new Error(`Member ${id} is stopped or unavailable; resume it from /teams`);
+  if (id !== "root" && !member.terminal) throw new Error("This member has no live terminal (it was launched headlessly)");
+  if (host.self !== "root") {
+    await exec("tmux", ["-S", socket, ...(id === "root" ? ["detach-client", "-s", host.self] : ["switch-client", "-t", id])], { timeout: 5000, maxBuffer: 65536 });
+    return;
+  }
+  const code = await ctx.ui.custom<number>((tui, _theme, _keys, done) => {
+    tui.stop();
+    process.stdout.write("\x1b[2J\x1b[H");
+    const env = { ...process.env }; delete env.TMUX; delete env.TMUX_PANE;
+    const child = spawn("tmux", ["-S", socket, "attach-session", "-t", id], { stdio: "inherit", env });
+    let restored = false;
+    const restore = (code: number) => {
+      if (restored) return;
+      restored = true; tui.start(); tui.requestRender(true); done(code);
+    };
+    child.once("error", () => restore(1));
+    child.once("exit", code => restore(code ?? 1));
+    return { render: () => [], invalidate() {}, dispose() { if (!restored) child.kill(); } };
+  });
+  if (code !== 0) throw new Error("Could not attach the live terminal; Main was restored");
+}
+
+export async function showDisplayConfig(ctx: ExtensionContext, settings: DisplaySettings): Promise<void> {
+  await ctx.ui.custom<void>((tui, theme, _keys, done) => {
+    const list = new SettingsList([
+      { id: "tasks", label: "Task summary", currentValue: settings.tasks ? "On" : "Off", values: ["On", "Off"] },
+      { id: "agents", label: "Agent selector", currentValue: settings.agents ? "On" : "Off", values: ["On", "Off"] },
+    ], 4, getSettingsListTheme(), (id, value) => {
+      if (id !== "tasks" && id !== "agents") return;
+      try {
+        const next = { ...settings, [id]: value === "On" };
+        saveDisplaySettings(next);
+        Object.assign(settings, next);
+      } catch (error) {
+        list.updateValue(id, settings[id] ? "On" : "Off");
+        ctx.ui.notify(cleanText(String(error)), "error");
+      }
+    }, () => done());
+    return {
+      render(width) {
+        const inner = Math.max(1, width - 4);
+        const rows = [theme.fg("accent", theme.bold("Teams display · global")), theme.fg("dim", "Saves immediately for this and future sessions."), "", ...list.render(inner)];
+        return ["╭" + "─".repeat(Math.max(0, width - 2)) + "╮", ...rows.map(line => {
+          const text = truncateToWidth(line, inner);
+          return "│ " + text + " ".repeat(Math.max(0, inner - visibleWidth(text))) + " │";
+        }), "╰" + "─".repeat(Math.max(0, width - 2)) + "╯"].map(line => truncateToWidth(line, width));
+      },
+      invalidate() { list.invalidate(); },
+      handleInput(input) { list.handleInput(input === " " ? "\r" : input); tui.requestRender(); },
+    };
+  }, { overlay: true, overlayOptions: { width: 64, minWidth: 30, anchor: "center" } });
+}
+
+export function installTeamFooter(_pi: ExtensionAPI, ctx: ExtensionContext, host: PanelHost, display: DisplaySettings): () => void {
+  let members: Awaited<ReturnType<PanelHost["snapshot"]>>["members"] = [];
+  let tasks: Awaited<ReturnType<PanelHost["snapshot"]>>["tasks"] = [];
+  let selected: string | undefined, start = 0;
+  let editor: (EditorComponent & Partial<Focusable> & { isShowingAutocomplete?(): boolean }) | undefined;
+  let redraw = () => {};
+  let disposed = false;
+  let timer: NodeJS.Timeout | undefined;
+  const ids = () => ["root", ...members.filter(member => member.id !== "root").map(member => member.id)];
+  const slots = () => members.filter(member => member.id !== "root").length > 4 ? 3 : 4;
+  const reveal = () => {
+    if (selected === undefined || selected === "root") return;
+    const index = ids().indexOf(selected) - 1;
+    if (index < start) start = index;
+    if (index >= start + slots()) start = index - slots() + 1;
+    start = Math.max(0, start);
+  };
+  async function refresh() {
+    try {
+      if (!display.tasks && !display.agents) {
+        ctx.ui.setStatus("ac-teams", undefined);
+        redraw();
+        return;
+      }
+      const next = await host.snapshot();
+      if (disposed) return;
+      members = next.members; tasks = next.tasks;
+      const count = ids().length;
+      ctx.ui.setStatus("ac-teams", `Teams ${[
+        ...(display.agents ? [`${count} ${count === 1 ? "agent" : "agents"}`, `${members.filter(member => member.status === "busy").length} working`] : []),
+        ...(display.tasks ? [`${tasks.filter(task => task.status === "done").length}/${tasks.length} tasks done`] : []),
+      ].join(" · ")}`);
+      if (selected && !ids().includes(selected)) { selected = undefined; if (editor) editor.focused = true; }
+      start = Math.min(start, Math.max(0, ids().length - 1 - slots()));
+      reveal(); redraw();
+    } catch { /* The next refresh retries; explicit commands report connection errors. */ }
+    finally { if (!disposed) timer = setTimeout(() => void refresh(), 1000); }
+  }
+  void refresh();
+  ctx.ui.setWidget("ac-teams-tasks", (_tui, theme) => ({
+    render: width => display.tasks ? renderTaskSummary(tasks, theme, width) : [],
+    invalidate() {},
+  }), { placement: "aboveEditor" });
+  ctx.ui.setWidget("ac-teams-agents", (tui, theme) => {
+    redraw = () => tui.requestRender();
+    return {
+      render(width) {
+        if (!display.agents && selected !== undefined) { selected = undefined; if (editor) editor.focused = true; }
+        const row = (id: string) => {
+          const member = members.find(member => member.id === id);
+          const assigned = tasks.find(task => task.owner === id && task.status === "in_progress") ?? tasks.find(task => task.owner === id && task.status !== "done");
+          const status = member?.status === "busy" ? "working" : member?.status ?? "idle";
+          const metrics = id === host.self ? readTelemetry(ctx) : member ?? {};
+          const title = id === "root" ? "main" : memberName(member ?? { id });
+          const description = `${title}  ${id === "root" ? "" : status + " · "}${modelContext(metrics)}${assigned ? ` · ${taskName(assigned)}` : ""}${member?.error || member?.activity ? ` · ${member.error || member.activity}` : ""}`;
+          return theme.fg(selected === id || host.self === id ? "accent" : "muted", `${selected === id ? ">" : " "} ${host.self === id ? "●" : "○"} ${cleanText(description).replaceAll("\n", " ")}`);
+        };
+        const peers = ids().slice(1);
+        return (display.agents ? [row("root"), ...peers.slice(start, start + slots()).map(row),
+          ...(peers.length > 4 ? [theme.fg("dim", `  ↑ ${start} above · ↓ ${Math.max(0, peers.length - start - slots())} below`)] : [])] : []
+        ).map(line => truncateToWidth(line, width));
+      },
+      invalidate() {},
+    };
+  }, { placement: "belowEditor" });
+  const previousEditor = ctx.ui.getEditorComponent();
+  const teamEditor: NonNullable<typeof previousEditor> = (tui, theme, keys) => {
+    const current: NonNullable<typeof editor> = previousEditor?.(tui, theme, keys) ?? new CustomEditor(tui, theme, keys);
+    // Decorate the instance so custom editor methods and Pi's app-control wiring survive.
+    const render = current.render.bind(current), handleInput = current.handleInput.bind(current);
+    current.render = (width: number) => {
+      const lines = render(width);
+      return disposed || selected === undefined ? lines : lines.map(line => line.replace(renderFakeCursor(" "), " "));
+    };
+    current.handleInput = (input: string) => {
+      if (disposed) { handleInput(input); return; }
+      if (!display.agents) { selected = undefined; current.focused = true; handleInput(input); return; }
+      if (selected !== undefined) {
+        const destinations = ids(), index = destinations.indexOf(selected);
+        if (matchesKey(input, "down")) selected = destinations[Math.min(destinations.length - 1, index + 1)];
+        else if (matchesKey(input, "up")) selected = index <= 0 ? undefined : destinations[index - 1];
+        else if (matchesKey(input, "escape")) selected = undefined;
+        else if (matchesKey(input, "enter")) {
+          const id = selected; selected = undefined;
+          void host.visit(id).catch(error => ctx.ui.notify(cleanText(String(error)), "error"));
+        } else { selected = undefined; handleInput(input); }
+        current.focused = selected === undefined; reveal(); redraw(); return;
+      }
+      if (matchesKey(input, "down") && !current.getText() && !current.isShowingAutocomplete?.()) {
+        selected = "root"; start = 0; current.focused = false; redraw(); return;
+      }
+      handleInput(input);
+    };
+    editor = current;
+    return current;
+  };
+  ctx.ui.setEditorComponent(teamEditor);
+  return () => {
+    disposed = true; clearTimeout(timer);
+    ctx.ui.setWidget("ac-teams-tasks", undefined); ctx.ui.setWidget("ac-teams-agents", undefined);
+    ctx.ui.setStatus("ac-teams", undefined);
+    if (ctx.ui.getEditorComponent() === teamEditor) ctx.ui.setEditorComponent(previousEditor);
+  };
+}

package/src/types.ts

@@ -5,8 +5,20 @@ export interface Worktree {
   base: string;
   target?: string;
 }
+export interface ContextUsage {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+}
+export interface Telemetry {
+  type: "telemetry";
+  model?: string;
+  modelName?: string;
+  contextUsage: ContextUsage | null;
+}
 export interface Member {
   id: string;
+  name?: string;
   parent?: string;
   depth: number;
   token: string;
@@ -19,15 +31,32 @@ export interface Member {
   notified: number;
   worktree?: Worktree;
   error?: string;
+  model?: string;
+  modelName?: string;
+  contextUsage?: ContextUsage;
+  thinking?: string;
+  activity?: string;
+  summary?: string;
+  terminal?: boolean;
 }
+export const memberNameMaxLength = 40;
+export const memberNamePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)?(?![\s\S])/;
+export function memberName(member: Pick<Member, "id" | "name">): string { return member.id === "root" ? "Main" : member.name ?? member.id; }
+export const taskLabelMaxLength = 60;
+export const taskLabelPattern = /^[^\s\x00-\x1f\x7f-\x9f]+(?: [^\s\x00-\x1f\x7f-\x9f]+){0,2}(?![\s\S])/;
+export function taskName(task: Pick<Task, "number" | "label">): string { return `#${task.number} ${task.label}`; }
 export interface Task {
   id: string;
+  number: number;
+  label: string;
   revision: number;
   title: string;
   description: string;
   dependencies: string[];
   status: "todo" | "in_progress" | "done";
+  completedAt?: number;
   owner?: string;
+  creator?: string;
 }
 export interface TaskView extends Task {
   blockedBy: string[];
@@ -41,7 +70,7 @@ export interface Message {
   time: string;
 }
 export interface TeamState {
-  version: 2;
+  version: 3;
   id: string;
   root: string;
   limit: number;
@@ -58,6 +87,7 @@ export interface TaskArgs {
   limit?: number;
   id?: string;
   title?: string;
+  label?: string;
   description?: string;
   dependencies?: string[];
 }
@@ -72,6 +102,7 @@ export interface MessageArgs {
 export interface AgentArgs {
   action: "launch" | "list" | "status" | "stop" | "resume" | "limits" | "cleanup";
   id?: string;
+  name?: string;
   brief?: string;
   cwd?: string;
   model?: string;
@@ -82,8 +113,15 @@ export interface AgentArgs {
   limit?: number;
   depth?: number;
 }
-export type Operation = "agent" | "task" | "message" | "join" | "ack";
-export function isLive(member: Member): boolean {
+export interface UserAction {
+  action: "task_request" | "feedback" | "resume";
+  id?: string;
+  text?: string;
+  model?: string;
+  thinking?: string;
+}
+export type Operation = "agent" | "task" | "message" | "join" | "ack" | "event" | "control_result" | "ui";
+export function isLive(member: Pick<Member, "status">): boolean {
   return ["starting", "busy", "idle", "stopping"].includes(member.status);
 }
 export function isDescendant(state: TeamState, id: string, ancestor: string): boolean {