ac-teams 0.0.12 → 0.0.14

package/README.md

@@ -7,7 +7,7 @@ Persistent agent teams for [Pi](https://github.com/earendil-works/pi): shared ta
 Requires Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`. Interactive teams also require `tmux` on `PATH`. Tested with Pi 1.4.0 and 1.5.0.
 
 ```sh
-pi install npm:ac-teams@0.0.4
+pi install npm:ac-teams
 ```
 
 Restart Pi after installation. Use Pi's `/trust` command to save approval for each project directory before launching members there; headless children cannot answer the initial trust prompt.

package/docs/operations.md

@@ -31,6 +31,30 @@ pi --teams-limit 4 --teams-depth 1
 
 Other delegation tools remain outside these limits. See [companion tools](usage.md#companion-tools-add-guidance-or-terminal-management).
 
+### Check headroom before adding concurrency
+
+`team_agent list` and `limits` include a fresh `resources` advisory. Launch and teammate resume results include the sample taken before startup.
+
+It reports host available RAM, occupied swap, recent memory stalls, and live/starting member counts. Values are bytes; Linux pressure averages are percentages over the last ten seconds. Missing or invalid metrics are `null` with a warning, not zero or an all-clear.
+
+The check reads only `/proc/meminfo` and `/proc/pressure/memory` on demand. It adds no polling, process-tree scans, or subprocesses.
+
+Available RAM below 10% triggers a low-headroom warning (a heuristic, not a per-member budget). Any nonzero ten-second memory-stall average also warns. Occupied swap alone does not trigger a pressure warning.
+
+Starting members reserve count slots synchronously, but may not yet consume their full memory. Concurrent launch results warn about earlier starts.
+
+Sequence launches and recheck `list` after startup before adding more. These advisories never block a launch, change the configured ceiling, reserve RAM, or stop a member. Host figures do not account for a tighter container/cgroup limit or guarantee future capacity; other teams and non-team processes also consume resources.
+
+Idle members keep Pi and its extensions alive. Stop unneeded members to release their owned processes, then resume their saved sessions when needed.
+
+This preserves transcripts, tasks, messages, and worktrees. Extension-owned language servers and scanners can dominate memory; ac-teams does not disable them or share them across sessions.
+
+### Avoid repeated work without dropping updates
+
+The coordinator skips saves when member events leave the state unchanged or notification cursors do not advance. Real changes still use the same validated, atomic saves. Repeated model errors still deliver separate parent notifications.
+
+The footer refreshes at the same interval without fetching message history. The panel still loads messages and complete tasks. Connected sessions cache display names until the snapshot file changes; they do not retain a second copy of the history.
+
 ## Display preferences are global
 
 `/teams config` saves task-summary and agent-selector visibility to `~/.pi/ac-teams/display.json`:

package/docs/usage.md

@@ -39,7 +39,7 @@ Each team tool call uses one line with a status dot, tool name, action, and resu
 
 The `+N lines` hint shows the hidden detail count. Ctrl+O expands the full request and response JSON; mouse-enabled Pi views also support clicking the row.
 
-Team notification messages remain compact; Ctrl+O expands their labeled fields. UI state colors do not replace the underlying progress, ownership, or dependency fields.
+Tool summaries and team notification previews prefer teammate names over IDs. Message receipt IDs stay out of compact summaries. Ctrl+O expands the original request and response, including IDs. Unknown members fall back to their IDs. UI state colors do not replace the underlying progress, ownership, or dependency fields.
 
 ## Main sessions share one team
 
@@ -159,7 +159,11 @@ Example `team_message` arguments:
 {"action":"send","recipients":["root"],"text":"Parser review complete. No edits; two malformed-input cases need tests."}
 ```
 
-Omit `recipients` to notify all other live members. Explicit sets must contain unique live member IDs; an invalid set rejects the whole send. All team members can read the full history, including direct messages.
+Use exact teammate names (such as `"oom-review"`) or member IDs in `recipients`; IDs remain valid. Omit `recipients` to notify all other live members.
+
+Each recipient must resolve to a different live member. An unknown name, a stopped member, or two entries for the same member rejects the whole send.
+
+Receipts and stored history retain resolved IDs. All team members can read the full history, including direct messages.
 
 ```json
 {"action":"history","after":0,"limit":20}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-teams",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Small, persistent teams for Pi",
   "type": "module",
   "license": "MIT",

package/src/coordinator.ts

@@ -1,6 +1,6 @@
 import { createServer, type Server, type Socket } from "node:net";
 import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { isDeepStrictEqual, promisify } from "node:util";
 import { chmodSync, closeSync, constants, copyFileSync, existsSync, fstatSync, mkdirSync, openSync, lstatSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
@@ -12,6 +12,7 @@ import { Egress, egressPort, providerRoutes, type Credentials } from "./egress.t
 import { Store, processAlive, processIdentity } from "./store.ts";
 import { stateRoot } from "./config.ts";
 import { RpcAgent } from "./rpc-agent.ts";
+import { hostResources, type HostResources } from "./resources.ts";
 import { TerminalAgent, tmux } from "./terminal-agent.ts";
 import { authentic, isRecord, readLines, send } from "./connection.ts";
 import { validate } from "./schemas.ts";
@@ -52,6 +53,8 @@ export interface CoordinatorOptions {
   interactive?: boolean; model?: string; thinking?: string;
   /** Version of the running Pi; members use the image built for it. Defaults to the `pi` on PATH. */
   piVersion?: string;
+  /** Test hook: samples host headroom without depending on the test machine's load. */
+  resources?: () => HostResources;
   /** Test hook: provider token refresh interval (default one minute). */
   refreshMs?: number;
   /** Test hook: runs after a member container passes all checks and before it starts. */
@@ -270,21 +273,22 @@ export class Coordinator {
     const event = value as { type: string; active?: boolean; text?: string; model?: string; modelName?: string; contextUsage?: ContextUsage | null };
     const member = this.store.state.members[actor];
     if (!member || !isLive(member) || (member.status === "stopping" && event.type !== "model_error")) return;
-    this.store.update(next => {
-      const current = next.members[actor];
-      if (event.type === "blocked") { if (event.active) current.needsInput = true; else delete current.needsInput; }
-      else if (event.type === "telemetry") {
-        current.model = event.model ?? current.model;
-        current.modelName = event.modelName;
-        current.contextUsage = event.contextUsage ?? undefined;
-      }
-      else if (event.type === "agent_start") { current.status = "busy"; current.activity = "Working"; delete current.error; delete current.summary; }
-      else if (event.type === "agent_settled") { delete current.needsInput; current.status = "idle"; current.activity = current.error ? "Model request failed" : current.summary || "Available for follow-up"; }
-      else if (event.type === "activity") current.activity = event.text;
-      else if (event.type === "summary") current.summary = event.text?.slice(0, 500);
-      else if (event.type === "model_error") current.error = event.text || "Model request failed";
-    });
-    this.publishStatus();
+    const current = { ...member };
+    if (event.type === "blocked") { if (event.active) current.needsInput = true; else delete current.needsInput; }
+    else if (event.type === "telemetry") {
+      current.model = event.model ?? current.model;
+      current.modelName = event.modelName;
+      current.contextUsage = event.contextUsage ?? undefined;
+    }
+    else if (event.type === "agent_start") { current.status = "busy"; current.activity = "Working"; delete current.error; delete current.summary; }
+    else if (event.type === "agent_settled") { delete current.needsInput; current.status = "idle"; current.activity = current.error ? "Model request failed" : current.summary || "Available for follow-up"; }
+    else if (event.type === "activity") current.activity = event.text;
+    else if (event.type === "summary") current.summary = event.text?.slice(0, 500);
+    else if (event.type === "model_error") current.error = event.text || "Model request failed";
+    if (!isDeepStrictEqual(member, current)) {
+      this.store.update(next => { next.members[actor] = structuredClone(current); });
+      this.publishStatus();
+    }
     if (event.type === "model_error" && !isMain(member) && member.status !== "stopping") {
       const recipient = member.parent && isLive(this.store.state.members[member.parent]) ? member.parent : this.self;
       this.store.message(actor, { action: "send", recipients: [recipient], text: `Member ${actor} model error: ${event.text || "Model request failed"}` });
@@ -347,10 +351,20 @@ export class Coordinator {
   }
   /** Live members this coordinator runs; main sessions run in their own terminals and never count. */
   live(): Member[] { return Object.values(this.store.state.members).filter(member => !isMain(member) && isLive(member)); }
+  private resources() {
+    const sample = (this.options.resources ?? hostResources)();
+    const live = this.live();
+    const startingMembers = live.filter(member => member.status === "starting").length;
+    const warnings = [...sample.warnings];
+    if (startingMembers) warnings.push(`${startingMembers} teammate(s) still starting; their full memory cost is not yet reflected. Sequence launches and recheck team_agent list after startup.`);
+    return { ...sample, liveMembers: live.length, startingMembers, warnings };
+  }
   ack(id: string, through: number): void {
     const last = this.store.state.messages.at(-1)?.seq ?? 0;
     if (!Number.isSafeInteger(through) || through < 0 || through > last) throw new Error("Invalid notification cursor");
-    this.store.update(state => { state.members[id].notified = Math.max(state.members[id].notified, through); });
+    if (this.closed) throw new Error("Team is stopping");
+    if (through <= this.store.state.members[id].notified) return;
+    this.store.update(state => { state.members[id].notified = through; });
   }
   private notify(id: string): void {
     if (this.closed || this.notices.has(id)) return;
@@ -388,12 +402,12 @@ export class Coordinator {
   }
   private async agent(actor: string, args: AgentArgs, authorizedLimit: boolean): Promise<unknown> {
     const state = this.store.state;
-    if (args.action === "list") return { team: state.id, limit: state.limit, depth: state.depth, sandbox: this.sandboxStatus(), lastMessage: state.messages.at(-1)?.seq ?? 0, members: Object.values(state.members).map(member => this.publicMember(member)) };
+    if (args.action === "list") return { team: state.id, limit: state.limit, depth: state.depth, sandbox: this.sandboxStatus(), resources: this.resources(), lastMessage: state.messages.at(-1)?.seq ?? 0, members: Object.values(state.members).map(member => this.publicMember(member)) };
     if (args.action === "limits") {
       if (!isMain(state.members[actor])) throw new Error("Only a main session can change team limits");
       if ((args.limit ?? state.limit) > 10 && !authorizedLimit) throw new Error("A ceiling above 10 requires explicit user confirmation or --teams-limit");
       this.store.update(next => { next.limit = args.limit ?? next.limit; next.depth = args.depth ?? next.depth; });
-      return { limit: this.store.state.limit, depth: this.store.state.depth, sandbox: this.sandboxStatus() };
+      return { limit: this.store.state.limit, depth: this.store.state.depth, sandbox: this.sandboxStatus(), resources: this.resources() };
     }
     if (args.action === "launch" || args.action === "resume") {
       const launch = this.launch(actor, args);
@@ -455,6 +469,8 @@ export class Coordinator {
     const locked = resumed ? resumed.provider : parent.access?.network.allow ? parent.provider : undefined;
     if (access?.network.allow && locked && provider !== locked) throw new Error(`A member with restricted network access can only use ${locked} models`);
     const member: Member = resumed ? { ...resumed, token: randomUUID(), status: "starting", error: undefined, contextUsage: undefined, modelName: undefined, handover: undefined } : { id, name: args.name, role: "member", parent: actor, depth, token: randomUUID(), cwd, status: "starting", notified: 0, access, provider: access ? provider : undefined };
+    const resources = this.resources();
+    for (const warning of resources.warnings) this.options.warning(warning);
     // Reserve synchronously before the first await so concurrent launches cannot oversubscribe.
     this.store.update(next => { next.members[id] = member; });
     this.publishStatus();
@@ -531,7 +547,7 @@ export class Coordinator {
       this.store.update(next => { if (next.members[id].status === "starting") next.members[id].status = prompt ? "busy" : "idle"; });
       this.publishStatus();
       if (prompt) await agent.request("prompt", { message: args.brief, streamingBehavior: "followUp" });
-      return this.publicMember(this.store.state.members[id]);
+      return { ...this.publicMember(this.store.state.members[id]), resources };
     } catch (error) {
       clearTimeout(timer); this.ready.delete(id);
       if (agent) await agent.stop();

package/src/index.ts

@@ -7,13 +7,13 @@ import { installTeamFooter, visitMember, showDisplayConfig } from "./terminal-ui
 import { readTelemetry } from "./telemetry.ts";
 import { resolveTeammate, teamsCompletions } from "./commands.ts";
 import { showTeamsPanel } from "./panel.ts";
-import { teamToolRenderers, renderTeamMessage, cleanText } from "./render.ts";
-import { join } from "node:path";
+import { teamToolRenderers, teamMessageRenderer, cleanText } from "./render.ts";
+import { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { promisify } from "node:util";
-import { readState, teamsHome } from "./store.ts";
+import { createMemberLabels, readState, teamsHome } from "./store.ts";
 import { teamEntryType, type TeamEntry } from "./mains.ts";
 import { isMain, memberName, taskName, type TeamState } from "./types.ts";
 import { Coordinator, assistantEvent, taskRequestGuidance } from "./coordinator.ts";
@@ -48,7 +48,14 @@ export default function teams(pi: ExtensionAPI) {
   const teamTools = ["team_agent", "team_task", "team_message"];
   const memberId = () => child ? environment[1]! : team?.member ?? "root";
   const teamId = (ctx: ExtensionContext) => team?.team ?? ctx.sessionManager.getSessionId();
-  pi.registerMessageRenderer("ac-teams", renderTeamMessage);
+  const cachedLabels = createMemberLabels();
+  function memberLabels(): Record<string, string> {
+    try {
+      if (coordinator) return Object.fromEntries(Object.values(coordinator.store.state.members).map(member => [member.id, memberName(member)]));
+      return cachedLabels(child ? dirname(environment[0]!) : join(teamsHome(), teamId(context!)));
+    } catch { return { root: "Main" }; } // A transcript can render before its team is available.
+  }
+  pi.registerMessageRenderer("ac-teams", teamMessageRenderer(memberLabels));
   const warn = (message: string) => context?.ui.notify(message, "warning");
   const notify = (through: number, messages: Message[] = []) => {
     pi.sendMessage({ customType: "ac-teams", content: `New team messages through sequence ${through}. Read team_message history after your last cursor. Reply only with useful updates, not acknowledgements.`, display: true, details: { through, messages } }, { deliverAs: "followUp", triggerTurn: true });
@@ -190,7 +197,7 @@ export default function teams(pi: ExtensionAPI) {
     }
     return coordinator!.handle(coordinator!.self, operation, args, authorized);
   }
-  async function snapshot(ctx: ExtensionContext): Promise<TeamSnapshot> {
+  async function snapshot(ctx: ExtensionContext, includeMessages = true): Promise<TeamSnapshot> {
     if (!child && !opening && !connection) return { members: [{ id: "root", cwd: ctx.cwd, depth: 0, status: ctx.isIdle() ? "idle" : "busy", notified: 0, needsInput: inputCount > 0 }], tasks: [], messages: [], limit: 10, depth: 2 };
     const status = await handle("agent", { action: "list" }, ctx) as Pick<TeamSnapshot, "members" | "limit" | "depth"> & { lastMessage: number };
     const tasks: TaskView[] = [];
@@ -200,7 +207,7 @@ export default function teams(pi: ExtensionAPI) {
       tasks.push(...page.tasks); total = page.total;
       if (!page.tasks.length) break;
     } while (tasks.length < total);
-    const messages = await handle("message", { action: "history", after: Math.max(0, status.lastMessage - 100), limit: 100 }, ctx) as Message[];
+    const messages = includeMessages ? await handle("message", { action: "history", after: Math.max(0, status.lastMessage - 100), limit: 100 }, ctx) as Message[] : [];
     return { members: status.members, limit: status.limit, depth: status.depth, tasks, messages };
   }
   function host(ctx: ExtensionContext): PanelHost {
@@ -211,7 +218,7 @@ export default function teams(pi: ExtensionAPI) {
       return await coordinator!.handle(coordinator!.self, "ui", value) as string;
     };
     const api: PanelHost = {
-      self: memberId(), child, drafts, snapshot: () => snapshot(ctx),
+      self: memberId(), child, drafts, snapshot: includeMessages => snapshot(ctx, includeMessages),
       visit: async id => {
         if (id === memberId()) return;
         if (!child) await link(ctx);
@@ -273,13 +280,13 @@ export default function teams(pi: ExtensionAPI) {
     if (change) report(ctx, change);
   });
   function output(data: unknown) { return { content: [{ type: "text" as const, text: JSON.stringify(data) }], details: data }; }
-  const guidance = "Team launches use real long-lived Pi sessions. Idle members count against the shared ceiling. Use stable member/task IDs; query status and history instead of acknowledging notifications. Limits cover only ac-teams, not other launchers or shell commands.";
+  const guidance = "Team launches use real long-lived Pi sessions. Idle members count against the shared ceiling and retain their processes and extensions. Check team_agent list resources before adding concurrency; teammate launch/resume results include pre-launch host headroom. Resource warnings are advisory, not a memory reservation or capacity guarantee. Sequence launches while members are starting or memory is pressured; stop unneeded idle members and resume their saved sessions later. Use teammate names for messaging and stable IDs for member control and tasks; query status and history instead of acknowledging notifications. Limits cover only ac-teams, not other launchers or shell commands.";
   const taskTrackingGuidance = "Before delegating a deliverable through team_agent, create or reuse a team_task and include its ID in the member's brief. Use one shared task list for your own work and delegated work; do not create one task per teammate by default. Quick lookups and brief second opinions need no separate task unless their results need coordination or follow-up.";
   pi.registerTool({
     name: "team_agent", label: "Team agent", description: "Launch/resume Pi members, list/status, stop owned subtrees, change root limits, and explicitly clean stopped worktrees. Create or reuse team_task entries for delegated deliverables; quick lookups need no task unless results need coordination or follow-up.",
     promptGuidelines: [guidance, taskTrackingGuidance, "Delegation needs the user's authorization. Give each new member a unique descriptive name (one or two lowercase words, hyphenated if two), plus a bounded brief. Names remain stable on resume. Avoid concurrent writers in the same cwd. Worktrees are opt-in."],
     parameters: AgentSchema,
-    ...teamToolRenderers("team_agent"),
+    ...teamToolRenderers("team_agent", memberLabels),
     async execute(_id, args, _signal, _update, ctx) { return output(await handle("agent", args, ctx)); },
   });
   pi.registerTool({
@@ -294,7 +301,7 @@ export default function teams(pi: ExtensionAPI) {
       "team_task start refuses another owner's task or unfinished dependencies. Complete requires ownership, in-progress work, and acceptance=true. Release clears ownership, returns in-progress work to todo, and leaves done work done. Reopen is explicit and cannot invalidate active or done dependents.",
     ],
     parameters: TaskSchema,
-    ...teamToolRenderers("team_task"),
+    ...teamToolRenderers("team_task", memberLabels),
     async execute(_id, args, _signal, _update, ctx) {
       const data = await handle("task", args, ctx) as TaskView | { tasks: TaskView[]; total: number };
       const compact = (task: TaskView) => ({ id: task.id, number: task.number, label: task.label, title: task.title, status: task.status, owner: task.owner, revision: task.revision, dependencies: task.dependencies, blockedBy: task.blockedBy });
@@ -303,10 +310,10 @@ export default function teams(pi: ExtensionAPI) {
     },
   });
   pi.registerTool({
-    name: "team_message", label: "Team message", description: "Send a persistent direct/team message or read cursor-paged history. Send returns a receipt; history and search return full messages. New messages queue a compact follow-up notification for each recipient.",
+    name: "team_message", label: "Team message", description: "Send a persistent direct/team message to teammate names or IDs, or read cursor-paged history. Send returns a receipt with resolved IDs; history and search return full messages. New messages queue a compact follow-up notification for each recipient.",
     promptGuidelines: ["Do not poll team_message history while waiting for replies; notifications trigger a follow-up turn. On notification, read team_message history after your last read cursor and advance it through the returned messages. An empty result means no newer messages, not that a teammate has finished."],
     parameters: MessageSchema,
-    ...teamToolRenderers("team_message"),
+    ...teamToolRenderers("team_message", memberLabels),
     async execute(_id, args, _signal, _update, ctx) {
       const result = await handle("message", args, ctx);
       if (args.action === "send") {

package/src/render.ts

@@ -46,26 +46,30 @@ function entry(title: string, value: unknown, expanded: boolean, theme: Theme, e
   };
 }
 
-function preview(items: unknown[], count: string, theme: Theme): string {
-  const entries = items.slice(0, 3).map(item => toolSummary(item, theme)).filter(Boolean);
+type MemberLabels = () => Readonly<Record<string, string>>;
+const defaultLabels: MemberLabels = () => ({ root: "Main" });
+const memberLabel = (id: unknown, labels: Readonly<Record<string, string>>) => inline(typeof id === "string" && Object.hasOwn(labels, id) ? labels[id] : id);
+
+function preview(items: unknown[], count: string, theme: Theme, labels: Readonly<Record<string, string>>): string {
+  const entries = items.slice(0, 3).map(item => toolSummary(item, theme, labels)).filter(Boolean);
   if (items.length > 3) entries.push(`+${items.length - 3} more`);
   return [count, ...entries].join(" · ");
 }
 
-function toolSummary(data: unknown, theme: Theme): string {
-  if (Array.isArray(data)) return preview(data, `${data.length} messages`, theme);
+function toolSummary(data: unknown, theme: Theme, labels: Readonly<Record<string, string>>): string {
+  if (Array.isArray(data)) return preview(data, `${data.length} messages`, theme, labels);
   if (data && typeof data === "object") {
     const value = data as Record<string, unknown>;
-    if (Array.isArray(value.members)) return preview(value.members, `${value.members.length} members`, theme);
-    if (Array.isArray(value.tasks)) return preview(value.tasks, value.total === undefined ? `${value.tasks.length} tasks` : `${value.tasks.length} of ${value.total} tasks`, theme);
-    const label = value.title ?? value.name ?? value.brief ?? value.text ?? value.query ?? value.id;
+    if (Array.isArray(value.members)) return preview(value.members, `${value.members.length} members`, theme, labels);
+    if (Array.isArray(value.tasks)) return preview(value.tasks, value.total === undefined ? `${value.tasks.length} tasks` : `${value.tasks.length} of ${value.total} tasks`, theme, labels);
+    const label = value.title ?? value.name ?? value.brief ?? value.text ?? value.query ?? (Array.isArray(value.recipients) ? undefined : value.id === undefined ? undefined : memberLabel(value.id, labels));
     const status = value.status === undefined ? "" : inline(value.status);
     const color = status === "done" ? "success"
       : status === "interrupted" ? "error"
       : status === "busy" || status === "in_progress" ? "accent"
       : status === "todo" || status === "starting" || status === "stopping" ? "warning" : "muted";
     const parts = [status ? theme.fg(color, theme.bold(`[${status}]`)) : "", label === undefined ? "" : inline(label)];
-    if (Array.isArray(value.recipients)) parts.push(`to ${value.recipients.map(inline).join(", ")}`);
+    if (Array.isArray(value.recipients)) parts.push(`${value.from === undefined ? "to" : `${memberLabel(value.from, labels)} →`} ${value.recipients.map(id => memberLabel(id, labels)).join(", ")}`);
     for (const key of ["seq", "limit", "depth"]) {
       if (value[key] !== undefined) parts.push(`${key}: ${inline(value[key])}`);
     }
@@ -74,13 +78,13 @@ function toolSummary(data: unknown, theme: Theme): string {
   return data === undefined || data === null ? "" : inline(data);
 }
 
-export function teamToolRenderers(name: string): ToolRenderers {
+export function teamToolRenderers(name: string, getLabels: MemberLabels = defaultLabels): ToolRenderers {
   return {
     renderShell: "self",
     renderCall(args, theme, context) {
       if (!context.isPartial) return new Container();
       const { action, ...fields } = (args ?? {}) as Record<string, unknown>;
-      const request = toolSummary(fields, theme);
+      const request = toolSummary(fields, theme, getLabels());
       const text = `${theme.fg("warning", "●")} ${theme.fg("toolTitle", name)} · ${inline(action ?? "...")} → running${request ? ` · ${request}` : ""}`;
       return new TruncatedText(text, context.outputPad, 0);
     },
@@ -92,8 +96,9 @@ export function teamToolRenderers(name: string): ToolRenderers {
       if (data === undefined) {
         try { data = JSON.parse(text); } catch { data = text; }
       }
-      const outcome = context.isError ? `error · ${inline(text)}` : toolSummary(data, theme) || "done";
-      const request = toolSummary(fields, theme);
+      const labels = getLabels();
+      const outcome = context.isError ? `error · ${inline(text)}` : toolSummary(data, theme, labels) || "done";
+      const request = toolSummary(fields, theme, labels);
       const heading = `${theme.fg(context.isError ? "error" : "success", "●")} ${theme.fg("toolTitle", name)} · ${inline(action ?? "...")} → ${outcome}${request && !outcome.includes(request) ? ` · ${request}` : ""}`;
       const requestJSON = cleanText(JSON.stringify(context.args, null, 2));
       const responseJSON = cleanText(result.details === undefined ? text : JSON.stringify(result.details, null, 2));
@@ -122,10 +127,15 @@ export function teamToolRenderers(name: string): ToolRenderers {
   };
 }
 
-export const renderTeamMessage: MessageRenderer = (message, { expanded }, theme) => {
-  const details = message.details as { through?: number; messages?: { from: string; text: string; recipients: string[] }[] } | undefined;
-  const recent = details?.messages?.at(-1);
-  const name = (id: string) => id === "root" ? "Main" : id;
-  const preview = recent ? `${name(recent.from)} → ${recent.recipients.map(name).join(", ")} · ${recent.text.split("\n")[0]}` : `Updates through ${details?.through ?? "unknown"}`;
-  return entry("Team message", details ?? { content: message.content }, expanded, theme, false, preview);
-};
+export function teamMessageRenderer(getLabels: MemberLabels = defaultLabels): MessageRenderer {
+  return (message, { expanded }, theme) => {
+    const details = message.details as { through?: number; messages?: { from: string; text: string; recipients: string[] }[] } | undefined;
+    const recent = details?.messages?.at(-1);
+    const labels = getLabels();
+    const name = (id: string) => memberLabel(id, labels);
+    const preview = recent ? `${name(recent.from)} → ${recent.recipients.map(name).join(", ")} · ${recent.text.split("\n")[0]}` : `Updates through ${details?.through ?? "unknown"}`;
+    return entry("Team message", details ?? { content: message.content }, expanded, theme, false, preview);
+  };
+}
+
+export const renderTeamMessage = teamMessageRenderer();

package/src/resources.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+
+export interface HostResources {
+  scope: "host";
+  memory: { totalBytes: number; availableBytes: number; swapUsedBytes: number } | null;
+  /** Percentage of wall time stalled on memory over the last ten seconds (Linux PSI). */
+  memoryPressure: { someAvg10: number; fullAvg10: number } | null;
+  warnings: string[];
+}
+
+/** On-demand advisory only: no process walks, subprocesses, timers, or per-member budget. */
+export function hostResources(read: (path: string) => string = path => readFileSync(path, "utf8"), platform: string = process.platform): HostResources {
+  const result: HostResources = { scope: "host", memory: null, memoryPressure: null, warnings: [] };
+  if (platform === "linux") {
+    try {
+      const text = read("/proc/meminfo");
+      const bytes = (key: string) => {
+        const match = text.match(new RegExp(`^${key}:\\s+(\\d+) kB$`, "m"));
+        return match ? Number(match[1]) * 1024 : NaN;
+      };
+      const totalBytes = bytes("MemTotal"), availableBytes = bytes("MemAvailable");
+      const swapTotal = bytes("SwapTotal"), swapFree = bytes("SwapFree");
+      if ([totalBytes, availableBytes, swapTotal, swapFree].every(Number.isSafeInteger) && totalBytes > 0 && availableBytes <= totalBytes && swapFree <= swapTotal) {
+        result.memory = { totalBytes, availableBytes, swapUsedBytes: swapTotal - swapFree };
+        if (availableBytes < totalBytes * 0.1) result.warnings.push("Host available memory is below 10%. Sequence work; stop unneeded idle members and resume their saved sessions later.");
+      }
+    } catch { /* Missing or unreadable metrics remain explicitly unavailable. */ }
+    try {
+      const text = read("/proc/pressure/memory");
+      const avg = (kind: string) => {
+        const match = text.match(new RegExp(`^${kind} avg10=(\\d+(?:\\.\\d+)?) `, "m"));
+        return match ? Number(match[1]) : NaN;
+      };
+      const someAvg10 = avg("some"), fullAvg10 = avg("full");
+      if ([someAvg10, fullAvg10].every(value => Number.isFinite(value) && value >= 0 && value <= 100) && fullAvg10 <= someAvg10) {
+        result.memoryPressure = { someAvg10, fullAvg10 };
+        if (someAvg10 > 0) result.warnings.push(`Host tasks stalled on memory for ${someAvg10}% of the last ten seconds. Prefer sequential work over more teammates.`);
+      }
+    } catch { /* PSI is optional on older kernels. */ }
+  }
+  if (!result.memory) result.warnings.push("Host memory headroom is unavailable; do not assume another teammate fits.");
+  if (!result.memoryPressure) result.warnings.push("Host memory pressure is unavailable; recent stalls cannot be assessed.");
+  return result;
+}

package/src/schemas.ts

@@ -36,7 +36,7 @@ export const TaskSchema = Type.Object({
 }, { additionalProperties: false });
 export const MessageSchema = Type.Object({
   action: Type.Union(["send", "history", "search"].map(v => Type.Literal(v))),
-  recipients: Type.Optional(Type.Array(id, { minItems: 1, maxItems: 100, uniqueItems: true })),
+  recipients: Type.Optional(Type.Array(id, { minItems: 1, maxItems: 100, uniqueItems: true, description: "Exact teammate names or member IDs. Each must resolve to a different live member. Omit to notify all other live members." })),
   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 });

package/src/store.ts

@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
 import { stateRoot } from "./config.ts";
 import { validatePolicy } from "./egress.ts";
 import { stripVTControlCharacters } from "node:util";
-import { isDescendant, isLive, isMain, memberNamePattern, memberNameMaxLength, taskLabelMaxLength, taskLabelPattern } from "./types.ts";
+import { isDescendant, isLive, isMain, memberName, 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.
@@ -183,6 +183,20 @@ export function readState(dir: string): TeamState {
   } finally { closeSync(fd); }
 }
 
+/** Cache only display names, not histories; atomic snapshot replacements invalidate the cache. */
+export function createMemberLabels(): (dir: string) => Record<string, string> {
+  let key: string | undefined, labels: Record<string, string>;
+  return dir => {
+    const file = join(dir, "state.json"), stat = lstatSync(file, { bigint: true });
+    const next = `${file}:${stat.dev}:${stat.ino}:${stat.mtimeNs}:${stat.size}:${stat.mode}:${stat.uid}:${stat.nlink}`;
+    if (next !== key) {
+      labels = Object.fromEntries(Object.values(readState(dir).members).map(member => [member.id, memberName(member)]));
+      key = next;
+    }
+    return labels;
+  };
+}
+
 export class Store {
   readonly dir: string;
   state: TeamState;
@@ -360,8 +374,11 @@ export class Store {
     if (args.action === "send") return this.update(state => {
       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 members = Object.values(state.members);
+      requireValue(args.recipients === undefined || Array.isArray(args.recipients), "Recipients must be unique live member names or IDs");
+      const recipients = args.recipients === undefined ? members.filter(member => member.id !== actor && isLive(member)).map(member => member.id)
+        : args.recipients.map(recipient => typeof recipient === "string" ? members.find(member => member.id === recipient || member.name === recipient)?.id : undefined);
+      requireValue((args.recipients === undefined || recipients.length > 0) && new Set(recipients).size === recipients.length && recipients.every((recipient): recipient is string => recipient !== undefined && isLive(state.members[recipient])), "Recipients must be unique live member names or IDs");
       const message = { seq: (state.messages.at(-1)?.seq ?? 0) + 1, id: randomUUID(), from: actor, recipients: [...recipients], text: args.text, time: new Date().toISOString() };
       state.messages.push(message);
       return structuredClone(message);

package/src/terminal-ui.ts

@@ -95,7 +95,7 @@ export function installTeamFooter(_pi: ExtensionAPI, ctx: ExtensionContext, host
         redraw();
         return;
       }
-      const next = await host.snapshot();
+      const next = await host.snapshot(false);
       if (disposed) return;
       members = next.members.filter(isLive); tasks = next.tasks;
       const count = ids().length;

package/src/ui-types.ts

@@ -12,7 +12,7 @@ export interface PanelHost {
   self: string;
   /** True in a member session; false in a main session. */
   child: boolean;
-  snapshot(): Promise<TeamSnapshot>;
+  snapshot(includeMessages?: boolean): Promise<TeamSnapshot>;
   visit(id: string): Promise<void>;
   requestTask(text: string): Promise<string>;
   feedback(task: TaskView, text: string): Promise<string>;