ac-teams 0.0.13 → 0.0.15

package/docs/operations.md

@@ -31,6 +31,36 @@ 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.
+
+`someAvg10` and `fullAvg10` cover ten-second trends; `fullAvg60` covers a sixty-second trend. 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). Low headroom alone does not prescribe sequential work.
+
+Memory contention warns when `fullAvg60 >= 5` or `fullAvg10 >= 10`. Full pressure measures time when all non-idle work is stalled on memory. Partial pressure (`someAvg10`) remains informational; occupied swap alone does not trigger a pressure warning.
+
+These thresholds are advisory defaults, not measured limits for optimal concurrency. Consider reducing concurrency if contention is slowing progress.
+
+Starting members reserve count slots synchronously, but may not yet consume their full memory. Concurrent launch results warn about earlier starts.
+
+Choose concurrency using resource readings and observed progress. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-teams",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "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 in host headroom.`);
+    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

@@ -13,7 +13,7 @@ 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,10 +48,11 @@ 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();
+  const cachedLabels = createMemberLabels();
   function memberLabels(): Record<string, string> {
     try {
-      const members = coordinator?.store.state.members ?? readState(child ? dirname(environment[0]!) : join(teamsHome(), teamId(context!))).members;
-      return Object.fromEntries(Object.values(members).map(member => [member.id, memberName(member)]));
+      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));
@@ -196,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[] = [];
@@ -206,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 {
@@ -217,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);
@@ -279,7 +280,7 @@ 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 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 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. Choose concurrency using resource readings and observed progress, not low headroom alone. If contention slows progress, 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.",

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;
+  /** Linux PSI percentages: partial ten-second pressure and full ten-/sixty-second pressure. */
+  memoryPressure: { someAvg10: number; fullAvg10: number; fullAvg60: 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%. This is low headroom, not a per-member capacity estimate.");
+      }
+    } catch { /* Missing or unreadable metrics remain explicitly unavailable. */ }
+    try {
+      const text = read("/proc/pressure/memory");
+      const avg = (kind: string, window: 10 | 60) => {
+        const match = text.match(new RegExp(`^${kind} .*?\\bavg${window}=(\\d+(?:\\.\\d+)?) `, "m"));
+        return match ? Number(match[1]) : NaN;
+      };
+      const someAvg10 = avg("some", 10), fullAvg10 = avg("full", 10), fullAvg60 = avg("full", 60);
+      if ([someAvg10, fullAvg10, fullAvg60].every(value => Number.isFinite(value) && value >= 0 && value <= 100) && fullAvg10 <= someAvg10) {
+        result.memoryPressure = { someAvg10, fullAvg10, fullAvg60 };
+        if (fullAvg60 >= 5 || fullAvg10 >= 10) result.warnings.push(`Significant memory contention detected (full avg10: ${fullAvg10}%, full avg60: ${fullAvg60}%). Consider reducing concurrency if progress is slowing.`);
+      }
+    } 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/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;

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>;