ac-teams 0.0.7 → 0.0.9

package/docs/design/session-roles/main-session.yaml

@@ -0,0 +1,34 @@
+id: main-session
+name: Main session
+summary: >-
+  A Pi session the user started, joined to a team, or promoted. Every main
+  session controls every member and other main sessions, shares the team's
+  tasks and messages, and belongs to one team at a time.
+kind: component
+channels: [cli]
+relationships:
+  - id: user-drives-main
+    from: user
+    to: main-session
+    direction: one-way
+    label: Promotes, joins, and leaves through /teams in
+  - id: main-uses-coordinator
+    from: main-session
+    to: coordinator
+    direction: one-way
+    label: Hosts as owner, or connects to as a client
+  - id: main-writes-transcript
+    from: main-session
+    to: transcripts
+    direction: one-way
+    label: Writes its conversation and team entry to
+  - id: guard-reads-main
+    from: read-guard
+    to: main-session
+    direction: one-way
+    label: Finds no member role in
+  - id: coordinator-launches-main
+    from: coordinator
+    to: main-session
+    direction: one-way
+    label: Relaunches promoted members as

package/docs/design/session-roles/member.yaml

@@ -0,0 +1,28 @@
+id: member
+name: Member
+summary: >-
+  An agent-launched Pi process with ACSTACK_AGENT_ROLE=member and AC_TEAMS_*
+  variables. It controls only its descendants, and its transcript stays under
+  ac-teams/<team>/<member>/ until promotion.
+kind: component
+relationships:
+  - id: coordinator-runs-member
+    from: coordinator
+    to: member
+    direction: one-way
+    label: Launches, stops, and resumes
+  - id: member-uses-coordinator
+    from: member
+    to: coordinator
+    direction: one-way
+    label: Calls team tools through
+  - id: member-writes-transcript
+    from: member
+    to: transcripts
+    direction: one-way
+    label: Writes its conversation to
+  - id: guard-reads-member
+    from: read-guard
+    to: member
+    direction: one-way
+    label: Reads ACSTACK_AGENT_ROLE=member in

package/docs/design/session-roles/read-guard.yaml

@@ -0,0 +1,17 @@
+id: read-guard
+name: ACStack read guard
+summary: >-
+  ACStack's large-read hook. It blocks a large untargeted read once in main
+  agents only, and reads ACSTACK_AGENT_ROLE on every call to decide.
+kind: external-system
+relationships:
+  - id: guard-reads-member
+    from: read-guard
+    to: member
+    direction: one-way
+    label: Reads ACSTACK_AGENT_ROLE=member in
+  - id: guard-reads-main
+    from: read-guard
+    to: main-session
+    direction: one-way
+    label: Finds no member role in

package/docs/design/session-roles/team-store.yaml

@@ -0,0 +1,13 @@
+id: team-store
+name: Team store
+summary: >-
+  Private team state under ~/.pi/ac-teams/teams/<team>/: members with their
+  role, tasks, messages, owner.lock, and each main session's connection
+  token. Sandboxed members cannot read it.
+kind: store
+relationships:
+  - id: coordinator-writes-store
+    from: coordinator
+    to: team-store
+    direction: one-way
+    label: Holds owner.lock and records roles in

package/docs/design/session-roles/transcripts.yaml

@@ -0,0 +1,23 @@
+id: transcripts
+name: Pi transcripts
+summary: >-
+  Standard Pi session files. Main sessions sit at the top level of the
+  project's session folder, where /resume finds them. Members sit under
+  ac-teams/<team>/<member>/, where only /teams finds them.
+kind: store
+relationships:
+  - id: main-writes-transcript
+    from: main-session
+    to: transcripts
+    direction: one-way
+    label: Writes its conversation and team entry to
+  - id: member-writes-transcript
+    from: member
+    to: transcripts
+    direction: one-way
+    label: Writes its conversation to
+  - id: coordinator-moves-transcript
+    from: coordinator
+    to: transcripts
+    direction: one-way
+    label: Moves promoted transcripts within

package/docs/design/session-roles/user.yaml

@@ -0,0 +1,17 @@
+id: user
+name: User
+summary: >-
+  Starts main sessions and is the only party who can promote a member, join a
+  session to a team, or approve a sandboxed member's full access.
+kind: actor
+relationships:
+  - id: user-drives-main
+    from: user
+    to: main-session
+    direction: one-way
+    label: Promotes, joins, and leaves through /teams in
+  - id: user-uses-herdr
+    from: user
+    to: herdr
+    direction: one-way
+    label: Switches between main sessions in

package/docs/operations.md

@@ -51,6 +51,8 @@ This is snapshot-based cleanup, not OS containment. Detached or uncaptured desce
 
 The interactive panel can instead quietly resume a saved member session without inventing a new brief. Feedback then arrives through the durable team mailbox.
 
+Stopping a main session ends its Pi process; an exiting coordinator hands over first. Resuming another main session relaunches it in its own terminal.
+
 Root session switching, forking, and tree traversal are blocked while members are live. A member cannot switch away from its team binding. Stop members explicitly before replacing the root session.
 
 ### Exit confirmation needs a Pi hook
@@ -59,6 +61,12 @@ Exit confirmation requires Pi's `session_before_exit` hook. The prerequisite is
 
 With that hook, native exit asks before stopping live members; cancellation leaves them running. Without it, shutdown performs cleanup but cannot ask first. Signals bypass confirmation.
 
+### Coordinator handover
+
+The main session holding `owner.lock` runs the coordinator. Before it exits it records whether each member was busy, idle, or waiting for input, then stops the members. Another connected main session takes the lock within seconds and runs the resume pass: busy members resume and are told their process restarted during a handover, idle members resume idle, and members waiting for input resume and ask again. The same pass runs when a main session opens a team with no coordinator running.
+
+A main session that crashes is marked interrupted; any main session can resume it. Raising the member limit above 10 requires the coordinator's own session, because the confirmation prompt runs there.
+
 ### Crash recovery is best effort
 
 If the root crashes, closing its owned pipes and losing the coordinator connection makes ordinary RPC children shut down. Native members also monitor the authenticated coordinator connection and exit after it is lost. This passed SIGTERM and SIGKILL probes with native child and grandchild processes.
@@ -79,7 +87,8 @@ Each root session uses `~/.pi/ac-teams/teams/<session-id>/`:
 
 - `state.json` contains membership, policy, tasks, messages, claims, and notification cursors
 - Member transcripts live under Main's session directory in `ac-teams/<team>/<member>/`, normally `~/.pi/agent/sessions/<project>/ac-teams/...`; Pi's `/resume` lists only top-level sessions, so use `/teams` to find them
-- `owner.lock` and `coordinator.sock` coordinate the running root
+- `owner.lock` and `coordinator.sock` coordinate the main session running the coordinator; other main sessions authenticate with tokens stored in `state.json`
+- Promoted members' transcripts move to `<session folder>/` beside other top-level sessions, and their `~/.pi/ac-teams/agents/<id>` folder is removed
 - Interactive teams also own `t.sock`, the private tmux socket, and per-member terminal environment files; shutdown removes those files
 
 New members also store their descriptive names and optional model/context reports. When an existing team opens, unnamed members receive stable, collision-free names such as `teammate-1`; their IDs and sessions do not change.
@@ -88,7 +97,9 @@ State schema 3 adds stable task numbers and short labels. Opening a schema 1 or
 
 Schema 1 also migrates progress: `pending` becomes `todo`, `claimed` becomes `in_progress`, and `completed` becomes `done`. Migration writes atomically and rejects invalid snapshots without replacement. Older ac-teams code cannot reopen schema 3; stop old sessions before updating.
 
-Only the root writes state. Mutations validate a copy, flush a temporary snapshot, atomically rename it, and flush the directory before returning success. An exclusive process-identity lock prevents concurrent owners. Private team directories use 0700; state files and the authenticated Unix socket use 0600. Uncertain locks fail closed.
+State schema 4 adds a role to each record: `main` or `member`. Opening a schema 3 team makes the root record a main session and every other record a member. A record without a role has left the team. A promotion records each step, so a failure rolls the member back to a stopped member with its original transcript path.
+
+Only the coordinator writes state. Mutations validate a copy, flush a temporary snapshot, atomically rename it, and flush the directory before returning success. An exclusive process-identity lock prevents concurrent owners. Private team directories use 0700; state files and the authenticated Unix socket use 0600. Uncertain locks fail closed.
 
 This is a small-team store: each mutation rewrites the snapshot, and search scans local history. There is no database, compaction, retention policy, automatic deletion, or deduplication of repeated mutation requests. Inspect state before retrying an ambiguous failed request.
 

package/docs/usage.md

@@ -1,6 +1,6 @@
 # Use ac-teams
 
-ac-teams provides three tools without prescribing a workflow. Your Pi session is the root; its child agents are members. The root opens coordination state on the first team request.
+ac-teams provides three tools with lightweight guidance for tracking delegated work. Your Pi session is a main session; the agents it launches are members. The first main session opens coordination state on the first team request. See [main sessions](#main-sessions-share-one-team) for adding more.
 
 | Tool | Actions | Main rule |
 | --- | --- | --- |
@@ -8,7 +8,7 @@ ac-teams provides three tools without prescribing a workflow. Your Pi session is
 | `team_task` | `create`, `list`, `read`, `edit`, `claim`, `start`, `release`, `complete`, `reopen` | Claim reserves work; dependencies gate starting, not ownership |
 | `team_message` | `send`, `history`, `search` | Recipients select who receives notification, not who can read |
 
-In interactive Pi, `/teams` or `/teams panel` opens the team panel. `/teams teammate <name-or-id>` opens a live teammate directly; autocomplete suggests subcommands and teammate names. You can also enter an exact teammate ID. The older `/teams open <id>` form remains supported. Headless roots retain the status listing. `/teams stop` stops every descendant. See [operations](operations.md) for limits, recovery, and worktree cleanup.
+In interactive Pi, `/teams` or `/teams panel` opens the team panel. `/teams teammate <name-or-id>` opens a live teammate directly; autocomplete suggests subcommands and teammate names. You can also enter an exact teammate ID. The older `/teams open <id>` form remains supported. Headless roots retain the status listing. `/teams stop` stops every member; main sessions keep running. `/teams join` and `/teams leave` change which team this session belongs to. See [operations](operations.md) for limits, recovery, and worktree cleanup.
 
 ## Navigate without stopping members
 
@@ -38,6 +38,17 @@ The `+N lines` hint shows the hidden detail count. Ctrl+O expands the full reque
 
 Team notification messages remain compact; Ctrl+O expands their labeled fields. UI state colors do not replace the underlying progress, ownership, or dependency fields.
 
+## Main sessions share one team
+
+A team can have several main sessions, each a top-level Pi session a person drives. Members are the agents they launch. Every main session controls every member and can stop or resume other main sessions; a member controls only its own descendants and never a main session.
+
+- **Promote:** On the panel's Teammates tab, `P` stops a member and relaunches it as a main session. It keeps its session ID and history, its transcript moves to the normal Pi session folder so `/resume` lists it, and it stays in the team. Under Herdr it opens in a new tab of the workspace for its worktree; otherwise it runs in its own tmux server and ac-teams prints the attach command. A member with enforced access asks first, because the promoted session runs without the container.
+- **Join:** `/teams join` lists the teams in this project and adds this session to the chosen one as a main session, then posts a summary of open tasks, owners, and recent messages. It refuses a session already in that team, or one already in a team with other members.
+- **Leave:** `/teams leave` returns this session's in-progress tasks to `todo`, clears their ownership, and drops its main-session role; its record keeps its history. The last main session cannot leave while members are live.
+- **Resume:** A session remembers its team in its transcript. Resuming it reconnects to the team; if no coordinator is running, ac-teams offers to run it here. Declining turns the team tools off for this session.
+
+One main session runs the coordinator; the others connect to it. When that session exits, another main session takes over automatically and resumes the members that were working. See [operations](operations.md#coordinator-handover).
+
 ## Show tasks and configure the displays
 
 The task summary sits above the input editor; the agent selector sits below the editor. The task summary shows completed/total counts and up to five numbered task labels, ordered by:
@@ -57,12 +68,27 @@ Hiding a display does not stop agents, change tasks, or disable `/teams`. With t
 
 ## Give members bounded assignments
 
-Example `team_agent` arguments:
+Before delegating a deliverable, create or reuse a shared task and include its ID in the member's brief. Track independently owned outcomes, not every agent, tool call, or procedural step. For example:
+
+- A fix and an independently owned test assignment need separate tasks.
+- A diagnosis others need for follow-up needs a task, even if the investigation is read-only.
+- A quick lookup, clarification, or brief second opinion can skip a task unless its result needs coordination or follow-up.
+- Running tests as part of a fix usually belongs to the fix's existing task.
+
+Review the current task list and relevant details first. Reuse an existing task when it covers the assignment. If none does, create one with acceptance criteria. Example `team_task` arguments:
+
+```json
+{"action":"create","label":"Parser review","title":"Review parser errors and malformed input","description":"Read-only review of src/parser.ts. Acceptance: report concrete malformed-input failures with reproduction steps, or report that none were found."}
+```
+
+Put the returned task UUID in the brief in place of `<task-id>`. Example `team_agent` arguments:
 
 ```json
-{"action":"launch","name":"parser-review","brief":"Review src/parser.ts. Read only; do not delegate or edit. Send findings to root through team_message."}
+{"action":"launch","name":"parser-review","brief":"Task <task-id>: claim and start it, then review src/parser.ts. Read only; do not delegate or edit. Send findings to root through team_message. Complete the task after checking its acceptance criteria, or report blockers."}
 ```
 
+These are prompt guidelines, not launch requirements. ac-teams neither creates tasks automatically nor blocks launches without tasks.
+
 Every launch needs a unique descriptive `name`: one or two lowercase words, hyphenated if two, at most 40 characters. For example, `parser-review` or `research`. `main`, `root`, and names matching an existing member's ID are reserved. Names remain stable across stop/resume; IDs remain the API references.
 
 `cwd` defaults to the requesting member's directory. `model` (`provider/model`) and `thinking` default to that member's current selection. An explicit override wins. Native Pi selects the model; provider/account rejections remain visible in member status and notify the parent. There is no automatic model retry.
@@ -75,11 +101,7 @@ Children can delegate through the same coordinator, subject to depth and capacit
 
 ## Track progress separately from ownership
 
-Example `team_task` arguments:
-
-```json
-{"action":"create","label":"Parser review","title":"Review parser errors and malformed input","description":"Check malformed input and report concrete failures; no edits."}
-```
+Task owners claim and start their work, then complete it after checking acceptance criteria or report blockers. Claiming reserves a task; starting also requires its dependencies to be done.
 
 Each task has a stable team-local `number` and a 1–3-word `label` (at most 60 characters). The graph and list show `#3 Parser review`; details retain the full title, description, and UUID.
 

package/package.json

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

package/src/commands.ts

@@ -3,7 +3,7 @@ import { memberName, type Member } from "./types.ts";
 import { cleanText } from "./render.ts";
 
 type NamedMember = Pick<Member, "id" | "name" | "status">;
-const actions = ["panel", "teammate", "config", "back", "stop", "status"];
+const actions = ["panel", "teammate", "config", "back", "stop", "status", "join", "leave"];
 
 export function resolveTeammate(members: NamedMember[], value: string): string | undefined {
   const key = value === "main" ? "root" : value;