ac-teams 0.0.7 → 0.0.8

package/src/index.ts

@@ -9,6 +9,13 @@ import { resolveTeammate, teamsCompletions } from "./commands.ts";
 import { showTeamsPanel } from "./panel.ts";
 import { teamToolRenderers, renderTeamMessage, cleanText } from "./render.ts";
 import { 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 { teamEntryType, type TeamEntry } from "./mains.ts";
+import { isMain, memberName, taskName, type TeamState } from "./types.ts";
 import { Coordinator, assistantEvent, taskRequestGuidance } from "./coordinator.ts";
 import { Connection, isRecord } from "./connection.ts";
 import { policy, readDisplaySettings, defaultDisplaySettings } from "./config.ts";
@@ -30,21 +37,113 @@ export default function teams(pi: ExtensionAPI) {
   let disposeUI: (() => void) | undefined;
   let telemetryTimer: NodeJS.Timeout | undefined;
   let inputCount = 0;
+  /** This main session's team, from its transcript's team entry; a session with no entry leads its own team as "root". */
+  let team: TeamEntry | undefined;
+  /** Why team tools are off in this session, if they are. */
+  let disabled: string | undefined;
+  let linking: Promise<void> | undefined;
+  let linkedSession: string | undefined;
   const drafts = new Map<string, string>();
   const display = { ...defaultDisplaySettings };
-  const self = environment[1] ?? "root";
+  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 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 });
     if (connection) void connection.request("ack", { through }).catch(error => warn(String(error)));
-    else coordinator?.ack("root", through);
+    else coordinator?.ack(coordinator.self, through);
   };
-  async function root(ctx: ExtensionContext): Promise<Coordinator> {
+  function disable(reason: string) {
+    disabled = reason;
+    pi.setActiveTools(pi.getActiveTools().filter(name => !teamTools.includes(name)));
+  }
+  function enable() {
+    disabled = undefined;
+    pi.setActiveTools([...new Set([...pi.getActiveTools(), ...teamTools])]);
+  }
+  function remember(entry: TeamEntry) {
+    team = entry;
+    pi.appendEntry(teamEntryType, entry);
+  }
+  /** Runs a native command sent by the coordinator: members get these from their parent, main sessions from other mains. */
+  function onCommand(ctx: ExtensionContext, link: Connection) {
+    return (command: { id: string; command: string; args: Record<string, unknown> }) => {
+      void (async () => {
+        let data: unknown = {}, error: string | undefined;
+        try {
+          if (command.command === "get_state") data = { sessionId: ctx.sessionManager.getSessionId(), sessionFile: ctx.sessionManager.getSessionFile(), model: ctx.model ? { id: ctx.model.id, provider: ctx.model.provider, name: ctx.model.name } : undefined, contextUsage: readTelemetry(ctx).contextUsage, isStreaming: !ctx.isIdle() };
+          else if (command.command === "prompt") {
+            if (typeof command.args.message !== "string" || !command.args.message.trim() || command.args.message.length > 16000) throw new Error("Invalid native prompt");
+            pi.sendUserMessage(command.args.message, { deliverAs: "followUp" });
+          } else if (command.command === "abort") ctx.abort();
+          else if (command.command !== "shutdown") throw new Error("Unsupported native command");
+        } catch (failure) { error = String(failure).slice(0, 2000); }
+        try { await link.request("control_result", { id: command.id, data, error }); }
+        catch { return; }
+        if (command.command === "shutdown" && !error) { exiting = true; ctx.shutdown(); }
+      })();
+    };
+  }
+  /** Connects to a running coordinator as a main-session client; false when none is listening. */
+  async function connectMain(ctx: ExtensionContext): Promise<boolean> {
+    const dir = join(teamsHome(), teamId(ctx)), socket = join(dir, "coordinator.sock");
+    if (!existsSync(socket)) return false;
+    const record = readState(dir).members[memberId()];
+    if (!isMain(record)) throw new Error("This session is no longer a main session of its team; use /teams join");
+    const link = new Connection(socket, record.id, record.token);
+    try { await link.open(); } catch { return false; }
+    link.on("notice", (through, messages) => notify(through, messages));
+    link.on("command", onCommand(ctx, link));
+    link.on("disconnect", () => {
+      if (connection !== link) return;
+      connection = undefined;
+      if (!exiting) void takeover(ctx);
+    });
+    try { await link.request("join", { sessionId: ctx.sessionManager.getSessionId(), sessionFile: ctx.sessionManager.getSessionFile(), tools: pi.getAllTools().map(tool => tool.name), trusted: ctx.isProjectTrusted() }); }
+    catch (error) { link.close(); throw error; }
+    connection = link; linkedSession = ctx.sessionManager.getSessionId();
+    if (!team) remember({ team: teamId(ctx), member: record.id });
+    return true;
+  }
+  /** The coordinator owner went away: one main session takes the owner lock, the rest reconnect to it. */
+  async function takeover(ctx: ExtensionContext) {
+    warn("The team coordinator stopped; taking over or reconnecting");
+    for (let attempt = 0; attempt < 40 && !exiting; attempt++) {
+      await new Promise(resolve => setTimeout(resolve, 250 + Math.random() * 250));
+      try {
+        await link(ctx);
+        warn(coordinator ? "This session now runs the team coordinator" : "Reconnected to the team coordinator");
+        return;
+      } catch { /* The new owner may still be starting. */ }
+    }
+    if (!exiting) warn("Could not reach or take over the team coordinator; team tools will retry on next use");
+  }
+  /** Makes this session an owner or client of its team's coordinator. */
+  async function link(ctx: ExtensionContext): Promise<void> {
+    if (child) { if (!connection) throw new Error("Team coordinator is not connected"); return; }
+    if (exiting) throw new Error("Team is stopping");
+    if (disabled) throw new Error(disabled);
+    if (connection || coordinator) return;
+    linking ??= (async () => {
+      if (await connectMain(ctx)) return;
+      try { await root(ctx); }
+      catch (error) {
+        // Another main session won the owner lock first; join it as a client.
+        if (String(error).includes("live owner lock") && await connectMain(ctx)) return;
+        throw error;
+      }
+    })().finally(() => { linking = undefined; });
+    return linking;
+  }
+  async function root(ctx: ExtensionContext, join?: { id: string; member: string }): Promise<Coordinator> {
     if (exiting) throw new Error("Team is stopping");
     context = ctx;
     opening ??= Coordinator.open({
-      id: ctx.sessionManager.getSessionId(), cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile(), sessionDir: ctx.sessionManager.getSessionDir(),
+      id: join?.id ?? teamId(ctx), self: join?.member ?? memberId(), join: join !== undefined, sessionId: ctx.sessionManager.getSessionId(),
+      shutdown: () => { exiting = true; ctx.shutdown(); },
+      cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile(), sessionDir: ctx.sessionManager.getSessionDir(),
       ...policy(ctx.cwd, pi.getFlag("teams-project-config") === true, { limit: pi.getFlag("teams-limit") as string | undefined, depth: pi.getFlag("teams-depth") as string | undefined }),
       extension: fileURLToPath(import.meta.url), notice: notify, warning: warn, piVersion: VERSION,
       status: (kind, active) => pi.events.emit(`herdr:${kind}`, { active, source: "ac-teams" }),
@@ -62,9 +161,10 @@ export default function teams(pi: ExtensionAPI) {
       },
       interactive: ctx.mode === "tui", model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined, thinking: pi.getThinkingLevel(),
     }).then(value => {
-      coordinator = value;
-      if (ctx.isIdle?.() === false) value.recordEvent("root", { type: "agent_start" });
-      if (inputCount > 0) value.recordEvent("root", { type: "blocked", active: true });
+      coordinator = value; linkedSession = ctx.sessionManager.getSessionId();
+      if (!team) remember({ team: value.store.state.id, member: value.self });
+      if (ctx.isIdle?.() === false) value.recordEvent(value.self, { type: "agent_start" });
+      if (inputCount > 0) value.recordEvent(value.self, { type: "blocked", active: true });
       return value;
     }, error => { opening = undefined; throw error; });
     return opening;
@@ -80,19 +180,18 @@ export default function teams(pi: ExtensionAPI) {
       }
       args = agent;
     }
-    if (child) {
-      if (!connection) throw new Error("Team coordinator is not connected");
-      return connection.request(operation, args);
-    }
+    await link(ctx);
+    // shortcut: client main sessions cannot approve a ceiling above 10, only the owner can; add a confirmation relay if needed.
+    if (connection) return connection.request(operation, args);
     let authorized = false;
     if (operation === "agent" && (args as AgentArgs).action === "limits" && ((args as AgentArgs).limit ?? 0) > 10) {
       if (!ctx.hasUI || !await ctx.ui.confirm("Raise team ceiling?", `Allow up to ${(args as AgentArgs).limit} live Pi members, including idle members? This increases possible model costs.`)) throw new Error("Ceiling increase was not explicitly approved");
       authorized = true;
     }
-    return (await root(ctx)).handle("root", operation, args, authorized);
+    return coordinator!.handle(coordinator!.self, operation, args, authorized);
   }
   async function snapshot(ctx: ExtensionContext): Promise<TeamSnapshot> {
-    if (!child && !opening) 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 };
+    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[] = [];
     let total = 0;
@@ -107,30 +206,35 @@ export default function teams(pi: ExtensionAPI) {
   function host(ctx: ExtensionContext): PanelHost {
     const userAction = async (args: UserAction): Promise<string> => {
       const value = { ...args, model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined, thinking: pi.getThinkingLevel() };
-      if (child) {
-        if (!connection) throw new Error("Team coordinator is not connected");
-        return await connection.request("ui", value) as string;
-      }
-      return await (await root(ctx)).handle("root", "ui", value) as string;
+      await link(ctx);
+      if (connection) return await connection.request("ui", value) as string;
+      return await coordinator!.handle(coordinator!.self, "ui", value) as string;
     };
     const api: PanelHost = {
-      self, drafts, snapshot: () => snapshot(ctx),
+      self: memberId(), child, drafts, snapshot: () => snapshot(ctx),
       visit: async id => {
-        if (id === self) return;
-        const socket = child ? process.env.AC_TEAMS_TERMINAL_SOCKET : join((await root(ctx)).store.dir, "t.sock");
+        if (id === memberId()) return;
+        if (!child) await link(ctx);
+        const socket = child ? process.env.AC_TEAMS_TERMINAL_SOCKET : join(teamsHome(), teamId(ctx), "t.sock");
         if (!socket) throw new Error("This member has no live terminal transport");
         await visitMember(ctx, api, socket, id);
       },
       requestTask: text => userAction({ action: "task_request", text }),
       feedback: (task, text) => userAction({ action: "feedback", id: task.id, text }),
       resume: async id => { await userAction({ action: "resume", id }); },
+      promote: async id => {
+        const member = (await snapshot(ctx)).members.find(member => member.id === id);
+        const confirmed = member?.access ? await ctx.ui.confirm("Promote a sandboxed member?", `${memberName(member)} will leave its sandbox and run as a main session with your full access.`) : false;
+        if (member?.access && !confirmed) return;
+        ctx.ui.notify(await userAction({ action: "promote", id, confirmed }), "info");
+      },
     };
     return api;
   }
   function report(ctx: ExtensionContext, event: { type: string; text?: string; active?: boolean }) {
     if (exiting) return;
-    if (child && ctx.mode === "tui") void connection?.request("event", event).catch(error => warn(cleanText(String(error))));
-    else if (!child) coordinator?.recordEvent("root", event);
+    if (connection && (!child || ctx.mode === "tui")) void connection.request("event", event).catch(error => warn(cleanText(String(error))));
+    else coordinator?.recordEvent(coordinator.self, event);
   }
   function startTelemetry(ctx: ExtensionContext) {
     clearInterval(telemetryTimer);
@@ -141,8 +245,8 @@ export default function teams(pi: ExtensionAPI) {
       try {
         const event = readTelemetry(ctx), encoded = JSON.stringify(event);
         if (encoded === previous) return;
-        if (child) await connection?.request("event", event);
-        else coordinator?.recordEvent("root", event);
+        if (connection) await connection.request("event", event);
+        else coordinator?.recordEvent(coordinator.self, event);
         previous = encoded;
       } catch (error) { if (!exiting) warn(cleanText(String(error))); }
       finally { pending = false; }
@@ -157,8 +261,8 @@ export default function teams(pi: ExtensionAPI) {
     inputCount = Math.max(0, inputCount + (data.active ? 1 : -1));
     if (context) {
       const event = { type: "blocked", active: inputCount > 0 };
-      if (child) void connection?.request("event", event).catch(error => warn(cleanText(String(error))));
-      else coordinator?.recordEvent("root", event);
+      if (connection) void connection.request("event", event).catch(error => warn(cleanText(String(error))));
+      else coordinator?.recordEvent(coordinator.self, event);
     }
   });
   pi.on("agent_start", (_event, ctx) => report(ctx, { type: "agent_start" }));
@@ -196,34 +300,104 @@ export default function teams(pi: ExtensionAPI) {
     disposeUI?.(); disposeUI = undefined;
     connection?.close(); connection = undefined;
     if (opening) await (await opening).close();
-    coordinator = undefined; opening = undefined;
+    coordinator = undefined; opening = undefined; linkedSession = undefined;
+  }
+  /** A resumed main session reconnects to its team, or offers to run the coordinator and resume the team's members. */
+  async function rejoin(ctx: ExtensionContext) {
+    try {
+      if (await connectMain(ctx)) return;
+      const dir = join(teamsHome(), teamId(ctx));
+      if (!existsSync(join(dir, "state.json"))) return;
+      const state = readState(dir);
+      if (!isMain(state.members[memberId()])) { disable("This session is no longer a main session of its team; use /teams join"); return; }
+      const others = Object.values(state.members).filter(member => member.id !== memberId() && member.role);
+      if (!ctx.hasUI || !others.length) return;
+      if (await ctx.ui.confirm("Run the team coordinator?", `This is a main session of a team with ${others.length} other member(s), and no coordinator is running. Run it here and resume the members that were working?`)) await link(ctx);
+      else disable("You declined to run the team coordinator; team tools are off in this session. Resume the session again to take over.");
+    } catch (error) { warn(cleanText(String(error))); }
+  }
+  async function repository(cwd: string): Promise<string> {
+    try { return (await promisify(execFile)("git", ["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], { timeout: 5000 })).stdout.trim(); }
+    catch { return cwd; }
+  }
+  /** /teams join: adds this session to another team in the same project as a main session. */
+  async function joinTeam(ctx: ExtensionContext) {
+    if (child) throw new Error("A member cannot join another team");
+    if (!ctx.hasUI) throw new Error("/teams join requires an interactive session");
+    const sessionId = ctx.sessionManager.getSessionId(), home = teamsHome();
+    const current = existsSync(join(home, teamId(ctx), "state.json")) ? readState(join(home, teamId(ctx))) : undefined;
+    if (current && Object.values(current.members).some(member => member.id !== memberId() && member.role)) throw new Error("This session is already in a team with other members; use /teams leave first");
+    const repo = await repository(ctx.cwd), teams: TeamState[] = [];
+    for (const name of existsSync(home) ? readdirSync(home) : []) {
+      try {
+        const state = readState(join(home, name)), main = Object.values(state.members).find(isMain);
+        if (state.id !== current?.id && main && await repository(main.cwd) === repo) teams.push(state);
+      } catch { /* Unreadable or foreign team folders are not offered. */ }
+    }
+    if (!teams.length) { ctx.ui.notify("No other teams in this project", "info"); return; }
+    const describe = (state: TeamState) => {
+      const members = Object.values(state.members);
+      return `${members.filter(isMain).map(memberName).join(", ")} · ${members.filter(member => member.role === "member").length} member(s) · ${Object.values(state.tasks).filter(task => task.status !== "done").length} open task(s) · ${state.id.slice(0, 8)}`;
+    };
+    const labels = teams.map(describe), choice = await ctx.ui.select("Join which team?", labels);
+    const chosen = teams[labels.indexOf(choice ?? "")];
+    if (!chosen) return;
+    if (Object.values(chosen.members).some(member => member.sessionId === sessionId)) throw new Error("This session is already in that team");
+    await close(); exiting = false; enable();
+    const dir = join(home, chosen.id), probe = new Connection(join(dir, "coordinator.sock"), "join", chosen.key);
+    let running = false;
+    try { await probe.open(); running = true; } catch { /* No coordinator: this session runs it. */ }
+    if (running) {
+      try {
+        const added = await probe.request("add_main", { sessionId, sessionFile: ctx.sessionManager.getSessionFile(), cwd: ctx.cwd }) as { id: string };
+        remember({ team: chosen.id, member: added.id });
+      } finally { probe.close(); }
+      if (!await connectMain(ctx)) throw new Error("The team coordinator stopped while joining; resume this session to retry");
+    } else {
+      const member = randomUUID().slice(0, 16);
+      await root(ctx, { id: chosen.id, member });
+      remember({ team: chosen.id, member });
+    }
+    const state = readState(dir), name = (id?: string) => id ? memberName(state.members[id] ?? { id }) : "unowned";
+    const open = Object.values(state.tasks).filter(task => task.status !== "done");
+    const recent = state.messages.slice(-5);
+    pi.sendMessage({ customType: "ac-teams", display: true, details: { through: state.messages.at(-1)?.seq ?? 0, messages: recent }, content: [
+      `Joined team ${state.id} as ${name(team!.member)}, a main session.`,
+      open.length ? `Open tasks:\n${open.map(task => `- ${taskName(task)} (${task.status}, ${name(task.owner)})`).join("\n")}` : "No open tasks.",
+      recent.length ? `Recent messages:\n${recent.map(message => `- ${name(message.from)}: ${message.text.split("\n")[0].slice(0, 200)}`).join("\n")}` : "No messages yet.",
+    ].join("\n\n") }, { triggerTurn: false });
+  }
+  /** /teams leave: hands this session's work back and drops its main-session role. */
+  async function leaveTeam(ctx: ExtensionContext) {
+    if (child) throw new Error("A member cannot leave its team; its parent stops it");
+    await link(ctx);
+    const left = { team: teamId(ctx), member: memberId(), left: true };
+    const result = connection ? await connection.request("ui", { action: "leave" }) : await coordinator!.handle(coordinator!.self, "ui", { action: "leave" });
+    pi.appendEntry(teamEntryType, left);
+    team = undefined;
+    await close(); exiting = false;
+    disable("This session left its team; use /teams join to join one");
+    ctx.ui.notify(String(result), "info");
   }
   pi.on("session_start", async (_event, ctx) => {
-    if (!child && coordinator && coordinator.store.state.id !== ctx.sessionManager.getSessionId()) { await close(); drafts.clear(); }
+    if (!child && linkedSession && linkedSession !== ctx.sessionManager.getSessionId()) { await close(); drafts.clear(); }
     context = ctx; exiting = false; inputCount = 0;
     if (child) {
       if (environment.some(value => !value)) throw new Error("Incomplete AC_TEAMS membership environment; refusing independent-root fallback");
-      connection = new Connection(environment[0]!, environment[1]!, environment[2]!);
-      connection.on("notice", (through, messages) => notify(through, messages));
-      connection.on("disconnect", () => { warn("Team coordinator disconnected; this member is shutting down"); ctx.abort(); ctx.shutdown(); });
-      connection.on("command", (command: { id: string; command: string; args: Record<string, unknown> }) => {
-        void (async () => {
-          let data: unknown = {}, error: string | undefined;
-          try {
-            if (command.command === "get_state") data = { sessionId: ctx.sessionManager.getSessionId(), sessionFile: ctx.sessionManager.getSessionFile(), model: ctx.model ? { id: ctx.model.id, provider: ctx.model.provider, name: ctx.model.name } : undefined, contextUsage: readTelemetry(ctx).contextUsage, isStreaming: !ctx.isIdle() };
-            else if (command.command === "prompt") {
-              if (typeof command.args.message !== "string" || !command.args.message.trim() || command.args.message.length > 16000) throw new Error("Invalid native prompt");
-              pi.sendUserMessage(command.args.message, { deliverAs: "followUp" });
-            } else if (command.command === "abort") ctx.abort();
-            else if (command.command !== "shutdown") throw new Error("Unsupported native command");
-          } catch (failure) { error = String(failure).slice(0, 2000); }
-          try { await connection?.request("control_result", { id: command.id, data, error }); }
-          catch { return; }
-          if (command.command === "shutdown" && !error) ctx.shutdown();
-        })();
-      });
-      await connection.open();
-      await connection.request("join", { sessionId: ctx.sessionManager.getSessionId(), sessionFile: ctx.sessionManager.getSessionFile(), tools: pi.getAllTools().map(tool => tool.name), trusted: ctx.isProjectTrusted() });
+      const link = new Connection(environment[0]!, environment[1]!, environment[2]!);
+      connection = link;
+      link.on("notice", (through, messages) => notify(through, messages));
+      link.on("disconnect", () => { warn("Team coordinator disconnected; this member is shutting down"); ctx.abort(); ctx.shutdown(); });
+      link.on("command", onCommand(ctx, link));
+      await link.open();
+      await link.request("join", { sessionId: ctx.sessionManager.getSessionId(), sessionFile: ctx.sessionManager.getSessionFile(), tools: pi.getAllTools().map(tool => tool.name), trusted: ctx.isProjectTrusted() });
+    } else if (!linkedSession) {
+      const entry = ctx.sessionManager.getEntries().filter(entry => entry.type === "custom" && entry.customType === teamEntryType).at(-1);
+      const data = entry?.type === "custom" ? entry.data as TeamEntry : undefined;
+      team = data && !data.left ? { team: data.team, member: data.member } : undefined;
+      disabled = undefined;
+      if (data?.left) disable("This session left its team; use /teams join to join one");
+      else if (team) await rejoin(ctx);
     }
     startTelemetry(ctx);
     if (!warned) {
@@ -241,7 +415,7 @@ export default function teams(pi: ExtensionAPI) {
   });
   pi.on("session_shutdown", close);
   const switchGuard = () => {
-    if (child || coordinator?.live().length) {
+    if (child || coordinator?.live().length || connection) {
       warn("Stop team members before switching/forking/traversing sessions (team_agent stop, or /teams stop)");
       return { cancel: true as const };
     }
@@ -262,12 +436,12 @@ export default function teams(pi: ExtensionAPI) {
     handler: async ctx => { if (ctx.mode === "tui") await host(ctx).visit("root"); },
   });
   pi.registerCommand("teams", {
-    description: "Team panel; /teams teammate <name-or-id>, config, back, stop, or status",
+    description: "Team panel; /teams teammate <name-or-id>, config, back, stop, status, join, or leave",
     async getArgumentCompletions(prefix) {
       if (!prefix.includes(" ")) return teamsCompletions(prefix, []);
       if (!context) return null;
       try {
-        const members = child || opening ? (await handle("agent", { action: "list" }, context) as Pick<TeamSnapshot, "members">).members : [{ id: "root", status: "idle" as const }];
+        const members = child || opening || connection ? (await handle("agent", { action: "list" }, context) as Pick<TeamSnapshot, "members">).members : [{ id: "root", status: "idle" as const }];
         return teamsCompletions(prefix, members);
       } catch { return null; }
     },
@@ -279,13 +453,20 @@ export default function teams(pi: ExtensionAPI) {
         catch (error) { ctx.ui.notify(cleanText(String(error)), "error"); }
         return;
       }
+      if (args.trim() === "join" || args.trim() === "leave") {
+        try { await (args.trim() === "join" ? joinTeam(ctx) : leaveTeam(ctx)); }
+        catch (error) { ctx.ui.notify(cleanText(String(error instanceof Error ? error.message : error)), "error"); }
+        return;
+      }
       if (args.trim() === "stop") {
         if (child) throw new Error("A member can only stop its descendants using team_agent");
-        const team = await root(ctx);
-        for (const member of [...team.live()].sort((a, b) => b.depth - a.depth)) await team.stopTree(member.id);
+        await link(ctx);
+        // Main sessions keep running; /teams stop stops members only.
+        const { members } = await handle("agent", { action: "list" }, ctx) as Pick<TeamSnapshot, "members">;
+        for (const member of members.filter(member => member.role === "member" && !member.parent && ["starting", "busy", "idle"].includes(member.status))) await handle("agent", { action: "stop", id: member.id }, ctx);
       }
       if (ctx.mode === "tui" && args.trim() !== "stop" && args.trim() !== "status") {
-        if (!child) await root(ctx);
+        if (!child) await link(ctx);
         const api = host(ctx);
         if (args.trim() === "back") await api.visit("root");
         else if (/^(teammate|open)\s+/.test(args.trim())) {
@@ -296,7 +477,7 @@ export default function teams(pi: ExtensionAPI) {
           else ctx.ui.notify(`Unknown teammate: ${cleanText(value)}. Use autocomplete or /teams panel.`, "error");
         }
         else if (!args.trim() || args.trim() === "panel") await showTeamsPanel(ctx, api);
-        else ctx.ui.notify("Usage: /teams [panel|teammate <name-or-id>|config|back|stop|status]", "info");
+        else ctx.ui.notify("Usage: /teams [panel|teammate <name-or-id>|config|back|stop|status|join|leave]", "info");
       } else {
         const status = await handle("agent", { action: "list" }, ctx);
         ctx.ui.notify(JSON.stringify(status, null, 2), "info");

package/src/mains.ts

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+/** Pi custom entry in a main session's transcript: which team it belongs to. Holds no secrets. */
+export const teamEntryType = "ac-teams-team";
+export interface TeamEntry { team: string; member: string; left?: boolean }
+export const handoverPrompt = "Your process was restarted during a coordinator handover. Check your last steps and continue your current task.";
+
+/** A main session's environment: no member identity, member role, or member Herdr opt-out. */
+export function mainEnv(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const clean: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined || key === "ACSTACK_AGENT_ROLE" || key.startsWith("AC_TEAMS_") || (key === "HERDR_ENV" && value === "0") || key === "TMUX" || key === "TMUX_PANE") continue;
+    clean[key] = value;
+  }
+  return clean;
+}
+
+export interface MainLaunch { id: string; name: string; cwd: string; command: string[]; env: Record<string, string>; socket: string }
+/**
+ * Opens a main session where the user can switch to it: its own Herdr tab in the workspace for its worktree, or else a
+ * tmux session on a socket of its own, so the coordinator owner's tmux kill-server cannot reach it. Returns a user notice.
+ */
+export async function launchMain(spec: MainLaunch): Promise<string> {
+  if (spec.env.HERDR_ENV === "1") {
+    const herdr = async (...args: string[]) => JSON.parse((await exec("herdr", args, { env: spec.env, timeout: 10000, maxBuffer: 4 * 1024 * 1024 })).stdout);
+    const workspaces = (await herdr("workspace", "list")).result?.workspaces as { workspace_id: string; worktree?: { checkout_path?: string } }[] | undefined;
+    const workspace = workspaces?.find(entry => entry.worktree?.checkout_path === spec.cwd);
+    const created = workspace
+      ? await herdr("tab", "create", "--workspace", workspace.workspace_id, "--cwd", spec.cwd, "--label", spec.name, "--focus")
+      : await herdr("workspace", "create", "--cwd", spec.cwd, "--label", spec.name, "--focus");
+    const pane = created.result?.root_pane?.pane_id;
+    if (typeof pane !== "string") throw new Error("Herdr did not report the new tab's pane");
+    // Herdr types the command into the pane's shell, so each word is quoted for it.
+    await exec("herdr", ["pane", "run", pane, spec.command.map(word => `'${word.replaceAll("'", "'\\''")}'`).join(" ")], { env: spec.env, timeout: 10000 });
+    return `${spec.name} opened in its own Herdr tab`;
+  }
+  await exec("tmux", ["-S", spec.socket, "new-session", "-d", "-s", spec.id, "-c", spec.cwd, "--", ...spec.command], { env: spec.env, timeout: 10000 });
+  return `${spec.name} runs in tmux; attach with: tmux -S ${spec.socket} attach -t ${spec.id}`;
+}

package/src/panel.ts

@@ -93,7 +93,9 @@ export async function showTeamsPanel(ctx: ExtensionContext, host: PanelHost): Pr
       try {
         const member = snapshot.members.find(member => member.id === id);
         if (member && ["stopped", "interrupted"].includes(member.status)) await host.resume(id);
-        done(id);
+        // Main sessions run in their own terminals; resuming one opens it there.
+        if (member?.role === "main" && id !== host.self) receipt = `${name(id)} runs in its own terminal`;
+        else done(id);
       } catch (error) { receipt = `Could not open ${name(id)}: ${clean(String(error))}`; }
       finally { opening = false; refresh(); }
     }
@@ -237,6 +239,7 @@ export async function showTeamsPanel(ctx: ExtensionContext, host: PanelHost): Pr
         heading("Message with full context"), "Open the native Pi session to read its conversation and type your message there.", "",
         fg("accent", member && ["stopped", "interrupted"].includes(member.status) ? "Enter  Resume and open" : "Enter  Open full session"),
         fg("muted", "No separate message composer."),
+        ...(!host.child && member?.role === "member" ? ["", fg("accent", "P  Promote to main session"), fg("muted", "Stops it and reopens its transcript as a main session in its own terminal.")] : []),
       ], width);
     }
 
@@ -294,6 +297,11 @@ export async function showTeamsPanel(ctx: ExtensionContext, host: PanelHost): Pr
         } else if (data.toLowerCase() === "g" && tab === 0 && !detail) { graph = !graph; scroll = 0; }
         else if (data.toLowerCase() === "n") begin("new");
         else if (data.toLowerCase() === "c" && tab === 0) begin("feedback");
+        else if (data.toLowerCase() === "p" && tab === 1 && !host.child) {
+          const id = memberIds()[memberIndex];
+          if (snapshot.members.find(member => member.id === id)?.role !== "member") receipt = "Only a member can be promoted.";
+          else { done(undefined); void host.promote(id).catch(error => ctx.ui.notify(`Promotion failed: ${clean(String(error))}`, "error")); return; }
+        }
         else if (matchesKey(data, "enter") || data.toLowerCase() === "o") {
           if (tab === 1 || data.toLowerCase() === "o") {
             const id = tab === 1 ? memberIds()[memberIndex] : tab === 0 ? selectedTask()?.owner : events[eventIndex]?.from;

package/src/schemas.ts

@@ -37,8 +37,8 @@ export const MessageSchema = Type.Object({
   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),
+  action: Type.Union([Type.Literal("task_request"), Type.Literal("feedback"), Type.Literal("resume"), Type.Literal("promote"), Type.Literal("leave")]),
+  id: Type.Optional(id), text: Type.Optional(text), confirmed: Type.Optional(Type.Boolean()),
   model: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
   thinking: AgentSchema.properties.thinking,
 }, { 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, memberNamePattern, memberNameMaxLength, taskLabelMaxLength, taskLabelPattern } from "./types.ts";
+import { isDescendant, isLive, isMain, 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.
@@ -54,7 +54,18 @@ function taskView(state: TeamState, task: Task): TaskView {
 }
 
 function migrate(state: unknown): boolean {
-  if (!object(state) || (state.version !== 1 && state.version !== 2)) return false;
+  if (!object(state) || ![1, 2, 3].includes(state.version as number)) return false;
+  if (state.version !== 3) migrateTasks(state);
+  // Schema 4: roles replace the special root ID; the creator's record becomes a main session.
+  const root = state.root ?? "root";
+  requireValue(object(state.members) && typeof root === "string" && Object.hasOwn(state.members, root), "Invalid legacy root member");
+  for (const [key, member] of Object.entries(state.members)) if (object(member)) member.role = key === root ? "main" : "member";
+  delete state.root;
+  state.key = randomUUID();
+  state.version = 4;
+  return true;
+}
+function migrateTasks(state: Record<string, unknown>): void {
   requireValue(object(state.tasks), "Invalid legacy state tasks");
   let number = 0;
   for (const task of Object.values(state.tasks)) {
@@ -69,14 +80,12 @@ function migrate(state: unknown): boolean {
     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 = 3;
-  return true;
 }
 
 function validate(state: unknown): asserts state is TeamState {
   requireValue(object(state), "Invalid state snapshot");
   id(state.id);
-  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");
+  requireValue(state.version === 4 && text(state.key) && 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)) {
@@ -91,6 +100,10 @@ function validate(state: unknown): asserts state is TeamState {
       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.role === undefined || member.role === "main" || member.role === "member", "Invalid member role");
+    requireValue(member.role !== "main" || member.parent === undefined, "A main session has no parent");
+    requireValue(member.handover === undefined || ["busy", "idle", "input"].includes(String(member.handover)), "Invalid member handover state");
+    requireValue(member.promotion === undefined || (object(member.promotion) && ["stopped", "moved", "role", "entry"].includes(String(member.promotion.step)) && text(member.promotion.sessionFile)), "Invalid member promotion");
     requireValue(member.terminal === undefined || typeof member.terminal === "boolean", "Invalid member terminal flag");
     requireValue(member.needsInput === undefined || typeof member.needsInput === "boolean", "Invalid member input flag");
     requireValue(member.pid === undefined || integer(member.pid, 1), "Invalid member PID");
@@ -105,7 +118,6 @@ function validate(state: unknown): asserts state is TeamState {
       parent = (members[parent] as Record<string, unknown>).parent;
     }
   }
-  requireValue(Object.hasOwn(members, state.root), "Invalid root member");
   const tasks = state.tasks;
   const edges: Record<string, string[]> = {};
   const taskNumbers = new Set<number>();
@@ -156,13 +168,24 @@ function privateFile(path: string, flags: number): number {
   } catch (error) { closeSync(fd); throw error; }
 }
 
+export const teamsHome = () => join(stateRoot(), "teams");
+/** Reads a team snapshot without taking ownership, for sessions that connect to its coordinator as clients. */
+export function readState(dir: string): TeamState {
+  const fd = privateFile(join(dir, "state.json"), constants.O_RDONLY);
+  try {
+    const stored: unknown = JSON.parse(readFileSync(fd, "utf8"));
+    migrate(stored); validate(stored);
+    return stored;
+  } finally { closeSync(fd); }
+}
+
 export class Store {
   readonly dir: string;
   state: TeamState;
   private lock?: number;
   private closed = false;
 
-  constructor(initial: TeamState, home = join(stateRoot(), "teams")) {
+  constructor(initial: TeamState, home = teamsHome()) {
     validate(initial);
     this.dir = join(resolve(home), initial.id);
     this.state = structuredClone(initial);
@@ -299,12 +322,12 @@ export class Store {
       } else if (args.action === "release") {
         requireValue(task.owner, "Task has no owner to release");
         const interrupted = ["interrupted", "stopped"].includes(state.members[task.owner].status);
-        requireValue(task.owner === actor || (interrupted && (actor === state.root || isDescendant(state, task.owner, actor))), "Only the owner can release this task; ancestors may release interrupted descendants");
+        requireValue(task.owner === actor || (interrupted && (isMain(state.members[actor]) || isDescendant(state, task.owner, actor))), "Only the owner can release this task; ancestors may release interrupted descendants");
         if (task.status === "in_progress") task.status = "todo";
         delete task.owner;
       } else if (args.action === "reopen") {
         requireValue(task.status === "done", "Only done tasks can be reopened");
-        requireValue(!task.owner || task.owner === actor || actor === state.root, "Only the owner or root can reopen an owned task");
+        requireValue(!task.owner || task.owner === actor || isMain(state.members[actor]), "Only the owner or a main session can reopen an owned task");
         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";

package/src/terminal-agent.ts

@@ -44,7 +44,7 @@ export class TerminalAgent extends EventEmitter {
       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_") || key === "HERDR_ENV") && value !== undefined)
+        .filter(([key, value]) => (key.startsWith("AC_TEAMS_") || key === "HERDR_ENV" || key === "ACSTACK_AGENT_ROLE") && value !== undefined)
         .map(([key, value]) => `export ${key}=${quote(value!)}`);
       const command = this.options.command ?? process.env.AC_TEAMS_PI ?? "pi";
       writeFileSync(script, [...exports,