pi-gang 0.1.0

package/src/gang/members.ts

@@ -0,0 +1,124 @@
+import { randomUUID } from "crypto";
+import type { PaneDetails } from "./tmux.ts";
+
+/** The superintendent every member reports to. */
+export const ORCHESTRATOR = "superintendent";
+
+/** A spawned gang member. */
+export interface Member {
+  role: string;
+  task: string;
+  index: number;
+  paneId: string;
+  runId: string;
+  spawnedAt: number;
+  thinkingLevel?: string;
+  reportedDoneAt?: number;
+  lastReportText?: string;
+}
+
+export interface MemberRuntimeSnapshot {
+  member: Member;
+  paneExists: boolean;
+  paneDead: boolean;
+  processAlive: boolean;
+  currentCommand?: string;
+  reportedDone: boolean;
+  state: "running" | "reported_done" | "pane_dead" | "pane_missing";
+  reapable: boolean;
+}
+
+export function computeMemberRuntimeSnapshot(member: Member, pane?: PaneDetails): MemberRuntimeSnapshot {
+  const paneExists = !!pane;
+  const paneDead = pane?.dead ?? false;
+  const reportedDone = typeof member.reportedDoneAt === "number";
+  const state = !paneExists
+    ? "pane_missing"
+    : paneDead
+      ? "pane_dead"
+      : reportedDone
+        ? "reported_done"
+        : "running";
+  return {
+    member,
+    paneExists,
+    paneDead,
+    processAlive: paneExists && !paneDead,
+    currentCommand: pane?.currentCommand,
+    reportedDone,
+    state,
+    reapable: state !== "running",
+  };
+}
+
+/**
+ * The 5 env vars pi-intercom reads at child startup (index.ts readChildOrchestratorMetadata):
+ * presence name comes from pi's --name flag, but these unlock the contact_supervisor tool and
+ * tell the member who its supervisor is.
+ */
+export function buildMemberEnv(opts: { role: string; runId: string; index: number; orchestrator?: string }): Record<string, string> {
+  return {
+    PI_SUBAGENT_INTERCOM_SESSION_NAME: opts.role,
+    PI_SUBAGENT_ORCHESTRATOR_TARGET: opts.orchestrator ?? ORCHESTRATOR,
+    PI_SUBAGENT_RUN_ID: opts.runId,
+    PI_SUBAGENT_CHILD_AGENT: opts.role,
+    PI_SUBAGENT_CHILD_INDEX: String(opts.index),
+  };
+}
+
+/** A role must be a safe token: valid tmux session name, shell-safe, addressable on the bus. */
+export function isValidRole(role: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9_-]{0,31}$/.test(role);
+}
+
+/** Tracks the members one superintendent session has spawned. One runId per superintendent process. */
+export class Roster {
+  readonly runId = randomUUID();
+  private members: Member[] = [];
+  private counter = 0;
+
+  nextIndex(): number {
+    return this.counter++;
+  }
+
+  add(member: Member): void {
+    this.members.push(member);
+  }
+
+  hasRole(role: string): boolean {
+    return this.members.some((member) => member.role === role);
+  }
+
+  findByRole(role: string): Member | undefined {
+    return this.members.find((member) => member.role === role);
+  }
+
+  markReportedDone(role: string, reportedDoneAt = Date.now(), text?: string): boolean {
+    const member = this.findByRole(role);
+    if (!member) return false;
+    member.reportedDoneAt = reportedDoneAt;
+    if (typeof text === "string" && text.trim()) member.lastReportText = text.trim();
+    return true;
+  }
+
+  list(): Member[] {
+    return [...this.members];
+  }
+
+  removeByRoles(roles: Set<string>): number {
+    const before = this.members.length;
+    this.members = this.members.filter((member) => !roles.has(member.role));
+    return before - this.members.length;
+  }
+
+  /** Drop members whose pane is gone/dead; returns how many were removed. */
+  prune(alivePaneIds: Set<string>): number {
+    const before = this.members.length;
+    this.members = this.members.filter((m) => alivePaneIds.has(m.paneId));
+    return before - this.members.length;
+  }
+
+  clear(): void {
+    this.members = [];
+  }
+}

package/src/gang/tmux.ts

@@ -0,0 +1,151 @@
+import { existsSync } from "fs";
+
+/** The dedicated tmux session that hosts all members. Watch with: tmux attach -t gang */
+export const GANG_SESSION = "gang";
+
+/** Prefer Homebrew tmux (the user's), fall back to PATH. Override with GANG_TMUX_BIN. */
+export const TMUX_BIN =
+  process.env.GANG_TMUX_BIN ||
+  (existsSync("/opt/homebrew/bin/tmux") ? "/opt/homebrew/bin/tmux" : "tmux");
+
+/** `-e KEY=VAL` flags that set the spawned pane's environment. */
+export function envFlags(env: Record<string, string>): string[] {
+  return Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+}
+
+export function hasSessionArgs(session = GANG_SESSION): string[] {
+  return ["has-session", "-t", session];
+}
+
+export function newSessionArgs(session = GANG_SESSION): string[] {
+  return ["new-session", "-d", "-s", session, "-x", "220", "-y", "50"];
+}
+
+/**
+ * Split a new pane and print its pane id (`-P -F '#{pane_id}'`). `target` is what to split: a session
+ * (e.g. `gang`) or a specific pane id (e.g. pi's own `$TMUX_PANE`, to split alongside the caller).
+ * Without a target, tmux splits whatever window is *currently active* — so always pass one to be
+ * deterministic. `detached` adds `-d` so the new pane doesn't steal focus (keeps you driving pi).
+ */
+export function splitArgs(opts: { target?: string; cwd: string; env: Record<string, string>; command: string; detached?: boolean }): string[] {
+  const target = opts.target ? ["-t", opts.target] : [];
+  return [
+    "split-window",
+    ...target,
+    ...(opts.detached ? ["-d"] : []),
+    "-P",
+    "-F",
+    "#{pane_id}",
+    "-c",
+    opts.cwd,
+    ...envFlags(opts.env),
+    opts.command,
+  ];
+}
+
+/** Keep a member's pane visible after its pi process exits (so you can read the final state). */
+export function remainOnExitArgs(paneId: string): string[] {
+  return ["set-option", "-p", "-t", paneId, "remain-on-exit", "on"];
+}
+
+/** Re-tile so every member pane stays visible as the gang grows. Target a session or a pane's window. */
+export function tiledLayoutArgs(target: string = GANG_SESSION): string[] {
+  return ["select-layout", "-t", target, "tiled"];
+}
+
+/** Focus a member's pane (Phase 5 GUI click-to-focus). */
+export function selectPaneArgs(paneId: string): string[] {
+  return ["select-pane", "-t", paneId];
+}
+
+/** List every pane in the session with its dead flag: lines of `#{pane_id} #{pane_dead}`. */
+export function listPanesArgs(session = GANG_SESSION): string[] {
+  return ["list-panes", "-t", session, "-F", "#{pane_id} #{pane_dead}"];
+}
+
+/** List every pane in the session with lightweight live diagnostics. */
+export function listDetailedPanesArgs(session = GANG_SESSION): string[] {
+  return ["list-panes", "-t", session, "-F", "#{pane_id}\t#{pane_dead}\t#{pane_current_command}\t#{pane_pid}"];
+}
+
+/** Server-wide pane list (`-a`) — for in-tmux mode, where members live in the user's own windows. */
+export function listAllPanesArgs(): string[] {
+  return ["list-panes", "-a", "-F", "#{pane_id} #{pane_dead}"];
+}
+
+/** Server-wide pane list with lightweight live diagnostics. */
+export function listAllDetailedPanesArgs(): string[] {
+  return ["list-panes", "-a", "-F", "#{pane_id}\t#{pane_dead}\t#{pane_current_command}\t#{pane_pid}"];
+}
+
+/** Reap one finished pane (a member whose pi process exited but remain-on-exit kept it). */
+export function killPaneArgs(paneId: string): string[] {
+  return ["kill-pane", "-t", paneId];
+}
+
+/** Nuke the whole gang session — stops every member, running or not. */
+export function killSessionArgs(session = GANG_SESSION): string[] {
+  return ["kill-session", "-t", session];
+}
+
+export interface PaneState {
+  paneId: string;
+  dead: boolean;
+}
+
+export interface PaneDetails extends PaneState {
+  currentCommand?: string;
+  pid?: number;
+}
+
+/** Parse `list-panes -F '#{pane_id} #{pane_dead}'` output. `pane_dead` is 1 for a finished pane. */
+export function parsePaneList(stdout: string): PaneState[] {
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [paneId, dead] = line.split(/\s+/);
+      return { paneId, dead: dead === "1" };
+    });
+}
+
+/** Parse tab-separated `list-panes` diagnostics. */
+export function parseDetailedPaneList(stdout: string): PaneDetails[] {
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [paneId, dead, currentCommand, pid] = line.split("\t");
+      return {
+        paneId,
+        dead: dead === "1",
+        currentCommand: currentCommand || undefined,
+        pid: pid ? Number(pid) : undefined,
+      };
+    });
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The shell-command tmux runs in the member's pane. Task is passed via @file (no shell quoting of
+ * task text). --no-extensions + explicit -e load exactly intercom+gang, regardless of install state.
+ */
+export function memberCommand(opts: { role: string; taskFile: string; intercomIndex: string; gangIndex: string; thinkingLevel?: string }): string {
+  return [
+    "pi",
+    "--name",
+    opts.role,
+    ...(opts.thinkingLevel ? ["--thinking", opts.thinkingLevel] : []),
+    "--no-extensions",
+    "-e",
+    shellQuote(opts.intercomIndex),
+    "-e",
+    shellQuote(opts.gangIndex),
+    `@${shellQuote(opts.taskFile)}`,
+  ].join(" ");
+}

package/src/gang/ui/mission-control.ts

@@ -0,0 +1,234 @@
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import type { SessionInfo } from "../../intercom/types.js";
+import type { FeedClient, FeedEvent } from "../feed-client.js";
+
+export interface FeedItem {
+  ts: number;
+  from: string;
+  to: string;
+  text: string;
+  expectsReply?: boolean;
+}
+
+export interface MissionState {
+  members: SessionInfo[];
+  feed: FeedItem[];
+  online: boolean;
+  /** Current time for uptime/idle math; defaults to Date.now() when omitted (keeps tests deterministic). */
+  now?: number;
+  /** role → task, joined from the superintendent's Roster so each member shows what it's doing. */
+  tasks?: Record<string, string>;
+}
+
+/** Minimal theme surface so render() is unit-testable with a plain stub. */
+interface RenderTheme {
+  fg(name: string, text: string): string;
+  bold(text: string): string;
+}
+
+function statusGlyph(status: string): string {
+  if (status.startsWith("tool:")) return "◆";
+  if (status.startsWith("thinking")) return "◐";
+  if (status.startsWith("idle")) return "●";
+  return "·";
+}
+
+function statusColor(status: string): string {
+  if (status.startsWith("tool:")) return "accent";
+  if (status.startsWith("thinking")) return "warning";
+  if (status.startsWith("idle")) return "success";
+  return "muted";
+}
+
+function pad(text: string, width: number): string {
+  const gap = width - visibleWidth(text);
+  return gap > 0 ? text + " ".repeat(gap) : text;
+}
+
+function hhmm(ts: number): string {
+  const d = new Date(ts);
+  return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+/** Compact duration: 3s / 12m / 2h / 1d. */
+function fmtDur(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+/** Count members by status category for the header histogram. */
+function statusHistogram(members: SessionInfo[], theme: RenderTheme): string {
+  let tool = 0, thinking = 0, idle = 0, other = 0;
+  for (const m of members) {
+    const s = m.status || "";
+    if (s.startsWith("tool:")) tool++;
+    else if (s.startsWith("thinking")) thinking++;
+    else if (s.startsWith("idle")) idle++;
+    else other++;
+  }
+  const chip = (n: number, glyph: string, color: string) => (n ? theme.fg(color, `${glyph}${n}`) : "");
+  return [
+    chip(tool, "◆", "accent"),
+    chip(thinking, "◐", "warning"),
+    chip(idle, "●", "success"),
+    chip(other, "·", "muted"),
+  ].filter(Boolean).join(" ");
+}
+
+/** Pure renderer: state + theme + width → terminal lines. No I/O, fully testable. */
+export function renderMissionControl(state: MissionState, theme: RenderTheme, width: number): string[] {
+  const inner = Math.max(44, Math.min(width - 2, 104));
+  const content = inner - 4; // 1 border + 1 space padding each side
+  const border = (s: string) => theme.fg("accent", s);
+  const lines: string[] = [];
+
+  const row = (text = "") => {
+    const clipped = truncateToWidth(text, content, "", true);
+    return `${border("│")} ${clipped}${" ".repeat(Math.max(0, content - visibleWidth(clipped)))} ${border("│")}`;
+  };
+
+  // Title bar with right-aligned connection state.
+  const title = theme.bold("gang") + theme.fg("muted", " · mission control");
+  const live = state.online ? theme.fg("success", "● live") : theme.fg("muted", "○ offline");
+  const titleGap = Math.max(1, content - visibleWidth(title) - visibleWidth(live));
+  lines.push(border(`╭${"─".repeat(inner - 2)}╮`));
+  lines.push(row(`${title}${" ".repeat(titleGap)}${live}`));
+  lines.push(border(`├${"─".repeat(inner - 2)}┤`));
+
+  // Members. Header carries a status histogram (◆tool ◐think ●idle) right-aligned.
+  const now = state.now ?? Date.now();
+  const tasks = state.tasks ?? {};
+  const head = theme.fg("muted", `MEMBERS · ${state.members.length}`);
+  const hist = statusHistogram(state.members, theme);
+  const headGap = Math.max(2, content - visibleWidth(head) - visibleWidth(hist));
+  lines.push(row(hist ? `${head}${" ".repeat(headGap)}${hist}` : head));
+  if (state.members.length === 0) {
+    lines.push(row(theme.fg("dim", "  no members yet — gang spawn <role> <task>")));
+  } else {
+    const nameWidth = Math.min(18, Math.max(6, ...state.members.map((m) => visibleWidth(m.name || m.id.slice(0, 8)))));
+    const statusWidth = Math.min(16, Math.max(4, ...state.members.map((m) => visibleWidth(m.status || "—"))));
+    for (const m of state.members) {
+      const status = m.status || "—";
+      const name = m.name || m.id.slice(0, 8);
+      const color = statusColor(status);
+      const glyph = theme.fg(color, statusGlyph(status));
+      const shown = status.length > statusWidth ? status.slice(0, statusWidth - 1) + "…" : status;
+      const label = theme.fg(color, pad(shown, statusWidth));
+      const up = m.startedAt > 0 ? fmtDur(now - m.startedAt) : "";
+      const idle = m.lastActivity > 0 ? `·${fmtDur(now - m.lastActivity)}` : "";
+      const metrics = theme.fg("dim", pad(`${up} ${idle}`.trim(), 9));
+      const taskText = tasks[name] ? theme.fg("dim", tasks[name].replace(/\s+/g, " ")) : "";
+      lines.push(row(`${glyph} ${theme.bold(pad(name, nameWidth))}  ${label}  ${metrics}  ${taskText}`));
+    }
+  }
+  lines.push(row());
+
+  // Feed (newest first).
+  lines.push(row(theme.fg("muted", "FEED")));
+  if (state.feed.length === 0) {
+    lines.push(row(theme.fg("dim", "  waiting for messages…")));
+  } else {
+    const routeWidth = Math.min(
+      26,
+      Math.max(...state.feed.map((f) => visibleWidth(`${f.from} → ${f.to}`))),
+    );
+    for (const f of state.feed.slice(0, 12)) {
+      const route = `${theme.fg("accent", f.from)} ${theme.fg("dim", "→")} ${theme.fg("warning", f.to)}`;
+      const routePadded = route + " ".repeat(Math.max(0, routeWidth - visibleWidth(`${f.from} → ${f.to}`)));
+      const flag = f.expectsReply ? theme.fg("warning", " (awaiting reply)") : "";
+      const time = theme.fg("dim", hhmm(f.ts));
+      const text = f.text.replace(/\s+/g, " ");
+      lines.push(row(`${time}  ${routePadded}  ${theme.fg("text", text)}${flag}`));
+    }
+  }
+
+  lines.push(border(`├${"─".repeat(inner - 2)}┤`));
+  lines.push(row(theme.fg("dim", "esc  close")));
+  lines.push(border(`╰${"─".repeat(inner - 2)}╯`));
+  return lines;
+}
+
+export class MissionControlOverlay implements Component {
+  private members = new Map<string, SessionInfo>();
+  private feed: FeedItem[] = [];
+  private online = false;
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: Theme,
+    private readonly keybindings: KeybindingsManager,
+    feed: FeedClient,
+    private readonly done: () => void,
+    private readonly getTasks: () => Record<string, string> = () => ({}),
+  ) {
+    feed.on("status", (s: string) => {
+      this.online = s === "up";
+      this.tui.requestRender();
+    });
+    feed.on("event", (ev: FeedEvent) => {
+      this.apply(ev);
+      this.tui.requestRender();
+    });
+  }
+
+  private apply(ev: FeedEvent): void {
+    switch (ev.type) {
+      case "snapshot":
+        this.members.clear();
+        for (const s of (ev.sessions as SessionInfo[]) ?? []) this.members.set(s.id, s);
+        // Buffer is oldest→newest; overlay renders feed[0] as newest, so reverse.
+        this.feed = ((ev.feed as Array<Record<string, unknown>>) ?? [])
+          .map((m) => ({
+            ts: (m.ts as number) ?? Date.now(),
+            from: m.from as string,
+            to: m.to as string,
+            text: (m.text as string) ?? "",
+            expectsReply: m.expectsReply as boolean | undefined,
+          }))
+          .reverse();
+        break;
+      case "session_joined":
+      case "presence_update": {
+        const s = ev.session as SessionInfo;
+        if (s) this.members.set(s.id, s);
+        break;
+      }
+      case "session_left":
+        this.members.delete(ev.sessionId as string);
+        break;
+      case "message":
+        this.feed.unshift({
+          ts: (ev.ts as number) ?? Date.now(),
+          from: ev.from as string,
+          to: ev.to as string,
+          text: (ev.text as string) ?? "",
+          expectsReply: ev.expectsReply as boolean | undefined,
+        });
+        this.feed = this.feed.slice(0, 50);
+        break;
+    }
+  }
+
+  invalidate(): void {}
+
+  handleInput(data: string): void {
+    if (this.keybindings.matches(data, "tui.select.cancel")) {
+      this.done();
+    }
+  }
+
+  render(width: number): string[] {
+    return renderMissionControl(
+      { members: [...this.members.values()], feed: this.feed, online: this.online, now: Date.now(), tasks: this.getTasks() },
+      this.theme,
+      width,
+    );
+  }
+}