ac-teams 0.0.7 → 0.0.8

package/README.md

@@ -28,7 +28,7 @@ Your Pi session is the root; its child agents are members. Ask Pi to delegate a
 
 The task summary sits above the input. The agent selector sits below the input, above your existing footer, and shows descriptive names, models, and context usage. ac-teams publishes a compact team status without replacing the footer or editor supplied by other extensions. `/teams config` toggles these displays independently.
 
-From an empty editor, press Down to select the team row, then Enter to open a member. A red **Needs input** label marks a member with an open question. Ctrl+Shift+Left returns to Main without stopping the member or dismissing its question. `/teams stop` stops every descendant.
+From an empty editor, press Down to select the team row, then Enter to open a member. A red **Needs input** label marks a member with an open question. Ctrl+Shift+Left returns to Main without stopping the member or dismissing its question. `/teams stop` stops every member; main sessions keep running. `/teams join` and `/teams leave` add this session to another team or take it out.
 
 Defaults allow up to **10 live members** and **two levels of delegation**. Use the fewest useful agents.
 

package/docs/access.md

@@ -84,6 +84,10 @@ docker build -t ac-teams-member:1.5.0-<hash> --build-arg PI_VERSION=1.5.0 -f <ac
 
 The image is `node:22-bookworm-slim`, pinned by digest, with bash, curl, Git, ripgrep, CA certificates, and the same Pi version as Main. Rebuild after upgrading Pi.
 
+## Promotion drops enforcement
+
+Promoting an enforced member to a main session relaunches it outside the container with your user's access. The panel asks for confirmation first. Members always run with `ACSTACK_AGENT_ROLE=member`; main sessions run without it and without inherited `AC_TEAMS_*` variables.
+
 ## Storage
 
 - Coordinator state and settings: `~/.pi/ac-teams/teams/<team>/`, `~/.pi/ac-teams/config.json`, and `~/.pi/ac-teams/display.json`

package/docs/design/session-roles/README.md

@@ -0,0 +1,343 @@
+# Session roles - promotion, joining, and several main sessions
+
+A team can have several main sessions. The user can promote a member into a main session or join an existing session to a team. Identity, transcript discovery, membership, coordinator ownership, and permission authority stay separate, and ACSTACK\_AGENT\_ROLE tells hooks which processes are main.
+
+<!-- Generated from the entry YAML and its element files; regenerate with design-doc --markdown -->
+
+```mermaid
+flowchart TD
+    element_user["User<br/>actor"]
+    element_main-session["Main session<br/>component · cli"]
+    element_member["Member<br/>component"]
+    element_coordinator["Coordinator<br/>component"]
+    element_team-store["Team store<br/>store"]
+    element_transcripts["Pi transcripts<br/>store"]
+    element_herdr["Herdr<br/>external-system"]
+    element_read-guard["ACStack read guard<br/>external-system"]
+    element_user -->|"Promotes, joins, and leaves through /teams in"| element_main-session
+    element_user -->|"Switches between main sessions in"| element_herdr
+    element_main-session -->|"Hosts as owner, or connects to as a client"| element_coordinator
+    element_main-session -->|"Writes its conversation and team entry to"| element_transcripts
+    element_read-guard -->|"Finds no member role in"| element_main-session
+    element_coordinator -->|"Relaunches promoted members as"| element_main-session
+    element_coordinator -->|"Launches, stops, and resumes"| element_member
+    element_member -->|"Calls team tools through"| element_coordinator
+    element_member -->|"Writes its conversation to"| element_transcripts
+    element_read-guard -->|"Reads ACSTACK_AGENT_ROLE=member in"| element_member
+    element_coordinator -->|"Holds owner.lock and records roles in"| element_team-store
+    element_coordinator -->|"Moves promoted transcripts within"| element_transcripts
+    element_coordinator -->|"Opens main-session tabs through"| element_herdr
+```
+
+## Session roles: promotion, joining, and several main sessions
+
+Status: draft for review. Implements nothing yet. Resolves the design questions in [issue #19](https://github.com/ac8318740/ac-teams/issues/19).
+
+A team can have several **main sessions**. A main session is a Pi session the user created, joined to a team, or promoted. Every other team process is a **member**. The user can promote a member to a main session from the TUI, or join an existing session to a team with `/teams join`. ac-teams marks every member process with `ACSTACK_AGENT_ROLE=member`, so ACStack's large-read guard applies only to main sessions.
+
+### Review questions
+
+1. Does promotion by relaunch feel seamless enough, given that a promoted session moves to its own Herdr tab?
+2. Does it look right that every main session can control every member and other main sessions? That matches what an unsandboxed session can already do through its shell.
+3. Is the takeover after the owner exits (automatic, with a notice) the right default?
+4. Are the changes and tests at the end complete enough to start implementation?
+
+### Trade-offs to judge
+
+- **Relaunch, not live handover.** Promotion stops the member process and reopens its transcript in a new process. The member loses its in-flight turn, but its role, sandbox, token, and environment change cleanly.
+- **No coordinator daemon.** The coordinator stays inside whichever main session holds `owner.lock`. When the owner exits, members stop and the next owner resumes them automatically. The cost is a pause and at most one redone turn per busy member.
+- **Wide main-session authority.** Any main session can stop work started by another. ac-teams does not try to guard against this, because an unsandboxed session can already stop processes through the shell or Herdr.
+
+## Definitions
+
+These five properties are independent. A change to one never changes another.
+
+| Property | Defined by | Changes when |
+|---|---|---|
+| Identity | Pi session id in the transcript header | Never |
+| Discovery | Where the transcript file lives | Promotion moves it to the top-level session folder |
+| Membership | A member record in the team store | Join adds one; leave clears its role |
+| Coordinator ownership | Holder of `owner.lock` | The owner exits and another main session takes it |
+| Authority | The record's `role`: `main` or `member` | Only promotion, join, or leave, all user actions |
+
+### What the coordinator does
+
+The coordinator is ac-teams' in-process server. Today it runs inside Main. In this design, it runs inside whichever main session holds `owner.lock`. In practice it:
+
+- **Runs member processes.** Starts each member's Pi, either headless or in tmux, optionally inside a Docker sandbox. It also stops and resumes members, and stops them all when its host session exits
+- **Answers team tools.** Every `team_agent`, `team_task`, and `team_message` call from any session arrives over `coordinator.sock` and is applied here, so concurrent edits are serialized
+- **Keeps team state.** Writes members, tasks, and messages to the team store
+- **Delivers notifications.** Tells each session when new team messages arrive
+- **Enforces rules.** Checks authority, depth and member limits, and sandbox grants, and brokers provider credentials for sandboxed members
+
+This design keeps all of that. It adds role checks, connections from main sessions it did not launch, promotion, joining, leaving, and ownership takeover.
+
+The team id stays the session id of the session that created the team, even after that session leaves or hands over ownership.
+
+### Main-agent signal
+
+- The coordinator sets `ACSTACK_AGENT_ROLE=member` on every member process, next to `AC_TEAMS_MEMBER`. That includes the terminal-launch script, which today only passes `AC_TEAMS_*` and `HERDR_ENV`
+- A hook treats the session as main when the variable is absent or `main`, and as not main for any other value
+- Anything a member starts inherits the variable and counts as not main
+- Promotion and every main-session launch must remove `ACSTACK_AGENT_ROLE`, every `AC_TEAMS_*` variable, and `HERDR_ENV=0`. Tests must cover this
+- ACStack reads the variable on every tool call. It detects Claude Code and Codex subagents from `agent_id` in their hook payloads instead. That detection belongs to ACStack, not ac-teams
+- Role grants no permission by itself
+
+## User flows
+
+### Promote a member
+
+1. The user opens a teammate from the agent selector or `/teams` and chooses **Promote to main**
+2. If the member is sandboxed, a confirmation states that the session will run with the user's full access. Declining cancels
+3. The coordinator stops the member, waiting for its process to exit as `stop` does today
+4. The coordinator moves the transcript from `ac-teams/<team>/<member>/` to the project's top-level session folder. It removes the member's config at `~/.pi/ac-teams/agents/<id>` and sets the member's role to `main` without a parent. The member's children stay its descendants
+5. The coordinator writes the session's team entry: a Pi custom entry holding the team id and member id, with no secrets
+6. The coordinator relaunches `pi --session <moved file>` with a clean environment:
+    - With Herdr, in a new tab in the workspace for the session's worktree, creating the workspace if needed. The tab gets focus and the session's name
+    - Without Herdr, in a tmux session on a per-main-session socket that the owner's `kill-server` cannot reach. The user's screen stays attached, and ac-teams prints the reattach command
+7. The new process reads its team entry, connects to the coordinator with a main-session token from the team store, and appears in `/resume`
+
+### Join an existing session to a team
+
+1. The user runs `/teams join` in an ordinary Pi session
+2. ac-teams lists this project's teams. The user picks one
+3. ac-teams refuses if the session already belongs to a team with members, or if its session id is already in the chosen team
+4. The coordinator adds a member record with role `main` and writes the team entry
+5. The session receives a short summary of open tasks, owners, and recent messages, with its message cursor at the latest message. It claims or creates work with the normal team tools
+
+### Several main sessions
+
+- Each main session holds one connection to the coordinator. The owner hosts it in-process; the others connect over `coordinator.sock`
+- Every main session sits at depth 0. Any main session can launch, stop, resume, and clean up any member, and stop or resume another main session
+- Stopping a main session asks it to shut down through its connection. Resuming one relaunches its transcript, as in step 6 of promotion
+- Members keep today's rule: they control only their descendants and never a main session
+- Tasks and messages stay shared. Ownership and revision checks still serialize concurrent edits, because one coordinator applies them all
+
+### Leave a team
+
+`/teams leave` returns the session's in-progress tasks to todo and clears their ownership. The member record keeps its history but loses its role, so its descendants stay under the other main sessions. The team entry records the departure, so a later `/resume` does not rejoin. Leaving is refused while the session is the only main session and members are still live.
+
+## Recovery
+
+- **The owner exits while another main session runs.** Before stopping members, the owner records each one's state (busy, idle, or needs input) in the team store. Today, `Coordinator.open` discards that state. A connected main session then takes `owner.lock`, opens the coordinator, and runs the resume pass below. Every main session gets a notice naming the new owner
+- **No main session is running when the owner exits.** Members stay stopped with their recorded state. The next main session that opens the team runs the same resume pass
+- **A promoted session is resumed with no coordinator running.** The extension reads its team entry at startup and offers to take ownership. Accepting opens the coordinator and runs the resume pass. Declining runs the session without team tools
+
+### Resume pass
+
+| Recorded state | Action |
+|---|---|
+| Busy | Resume and send: "Your process was restarted during a coordinator handover. Check your last steps and continue your current task." |
+| Idle | Resume and leave idle |
+| Needs input | Resume and show **Needs input** again |
+
+Pi saves each completed message, so a busy member loses only the reply it was generating and redoes that turn. A command killed mid-run may have half finished. The message tells the member to check before it continues, which reduces that risk but does not remove it, the same as stopping a member today.
+- **A main session crashes.** Its record stays. The coordinator marks it interrupted, and any main session can resume it
+- **Promotion fails partway.** Each step is recorded in the team store before the next starts. On failure, the coordinator rolls back to a stopped member with its original transcript path, and the member can be retried or resumed
+
+## Security boundaries
+
+- Only the user can promote, join, or leave. These actions have no agent-tool form
+- Promoting a sandboxed member is an explicit escalation, approved in the confirmation step. Without approval, nothing changes
+- Main-session tokens live in the private team store, which sandboxed members cannot read. A member therefore cannot impersonate a main session over the socket
+- Descendant non-escalation stays as it is: a member cannot grant its descendants more access than it has
+- Provider credentials for sandboxed members come from the current owner's Pi login. After a takeover, the new owner brokers them under the same OS user
+
+## Changes needed before implementation
+
+- **Team store schema 4.** Add `role` to members and migrate `root` to a main record. Replace `actor === "root"` checks with role checks. Store each main session's token
+- **Coordinator.**
+    - Accept connections from main sessions that were not launched by the coordinator
+    - Add promote, join, leave, and the stop and resume of main sessions
+    - Add ownership takeover, and recompute descendant depths after a promotion
+- **Launch environment.** Set `ACSTACK_AGENT_ROLE=member` for every member, including the terminal script's variable filter. Strip it on main-session launches
+- **Extension.** Read the team entry at `session_start`. Add `/teams join`, `/teams leave`, and the **Promote to main** action. Open Herdr tabs, or use the tmux fallback
+- **Docs.** Update `docs/usage.md`, `docs/operations.md`, and `docs/access.md`
+
+## Tests needed
+
+- A launched member has `ACSTACK_AGENT_ROLE=member`, in both RPC and terminal modes
+- A promoted session's environment has no `ACSTACK_AGENT_ROLE` and no `AC_TEAMS_*` variables
+- Promotion keeps the session id, moves the file, updates the stored path, and writes the team entry. Pi's session listing then includes the session
+- A sandboxed promotion is refused without confirmation and runs unsandboxed after it
+- Joining refuses a duplicate session id, and refuses a session that leads another team with members
+- A main session can stop and resume members and other main sessions. A member cannot act on a main session
+- When the owner exits, another main session takes the lock. Busy members resume with the continue message, idle members stay idle, and members that needed input show **Needs input** again
+- When no main session is running, the next one to open the team runs the same resume pass
+- Resuming a promoted transcript with no coordinator offers takeover, and declining leaves team tools off
+- Leaving returns in-progress tasks to todo and keeps descendants manageable
+- A promotion interrupted after each step rolls back to a resumable member
+- Schema 3 teams migrate to schema 4 with root as a main record
+
+
+## User
+
+*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.*
+
+- Identity: `user`
+- Kind: actor
+- Channels: none
+- Source: [user.yaml](user.yaml)
+
+
+
+## Main session
+
+*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.*
+
+- Identity: `main-session`
+- Kind: component
+- Channels: cli
+- Source: [main-session.yaml](main-session.yaml)
+
+## Main-agent signal
+
+- Requirement: ACStack's large-read guard applies only to main agents. A main agent is a session the user created or promoted, never one an agent created. The signal must reach in-process Pi hooks and shell hooks, and must change when a member is promoted.
+- Design response: The coordinator sets ACSTACK\_AGENT\_ROLE=member on every member process, next to AC\_TEAMS\_MEMBER. Absent or "main" means main; any other value means not main. Children of a member inherit it. Promotion always relaunches the transcript in a new process without ACSTACK\_AGENT\_ROLE or any AC\_TEAMS\_\* variable, so a live process never needs to change its role. Main status grants no permissions.
+- Applies to: coordinator, member, main-session, read-guard
+
+## Separate identity, discovery, membership, and authority
+
+- Requirement: Issue \#19 forbids tying session identity or permission authority to picker visibility, storage location, or a single main session.
+- Design response: Identity is the Pi session id. Discovery is where the transcript file lives. Membership and role are records in the team store. Ownership is whoever holds owner.lock. Authority comes from the member's role in the team store, which only explicit user actions change. Moving a file or taking the lock changes nothing else.
+- Applies to: main-session, member, coordinator, team-store, transcripts
+
+## Duplicate prevention
+
+- Requirement: A session must not appear twice in a team, run as two processes, or belong to two teams.
+- Design response: The team store keys members by member id and refuses a second record with the same Pi session id. The coordinator accepts one live connection per member and keeps the existing pid and identity check before any launch or relaunch. A session in a team with members cannot join another team.
+- Applies to: coordinator, team-store, main-session
+
+## Recovery without the original owner
+
+- Requirement: The team must carry on when the owner exits, and a promoted session resumed later must find its team again.
+- Design response: When the owner exits, another connected main session takes owner.lock and resumes members by their recorded state: busy members get a message to check their last steps and continue, idle members stay idle, and open questions reappear. A main session resumed from /resume reads its team entry, then connects to the live coordinator or offers to take ownership.
+- Applies to: main-session, coordinator, team-store, member
+
+## Member
+
+*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/&\#60;team&\#62;/&\#60;member&\#62;/ until promotion.*
+
+- Identity: `member`
+- Kind: component
+- Channels: none
+- Source: [member.yaml](member.yaml)
+
+## Main-agent signal
+
+- Requirement: ACStack's large-read guard applies only to main agents. A main agent is a session the user created or promoted, never one an agent created. The signal must reach in-process Pi hooks and shell hooks, and must change when a member is promoted.
+- Design response: The coordinator sets ACSTACK\_AGENT\_ROLE=member on every member process, next to AC\_TEAMS\_MEMBER. Absent or "main" means main; any other value means not main. Children of a member inherit it. Promotion always relaunches the transcript in a new process without ACSTACK\_AGENT\_ROLE or any AC\_TEAMS\_\* variable, so a live process never needs to change its role. Main status grants no permissions.
+- Applies to: coordinator, member, main-session, read-guard
+
+## Separate identity, discovery, membership, and authority
+
+- Requirement: Issue \#19 forbids tying session identity or permission authority to picker visibility, storage location, or a single main session.
+- Design response: Identity is the Pi session id. Discovery is where the transcript file lives. Membership and role are records in the team store. Ownership is whoever holds owner.lock. Authority comes from the member's role in the team store, which only explicit user actions change. Moving a file or taking the lock changes nothing else.
+- Applies to: main-session, member, coordinator, team-store, transcripts
+
+## Recovery without the original owner
+
+- Requirement: The team must carry on when the owner exits, and a promoted session resumed later must find its team again.
+- Design response: When the owner exits, another connected main session takes owner.lock and resumes members by their recorded state: busy members get a message to check their last steps and continue, idle members stay idle, and open questions reappear. A main session resumed from /resume reads its team entry, then connects to the live coordinator or offers to take ownership.
+- Applies to: main-session, coordinator, team-store, member
+
+## Coordinator
+
+*The team's single referee, running inside whichever main session holds owner.lock. It starts and stops member processes, answers every team\_agent, team\_task, and team\_message call, delivers message notifications, checks who may do what, and runs promotion, joining, and takeover.*
+
+- Identity: `coordinator`
+- Kind: component
+- Channels: none
+- Source: [coordinator.yaml](coordinator.yaml)
+
+## Main-agent signal
+
+- Requirement: ACStack's large-read guard applies only to main agents. A main agent is a session the user created or promoted, never one an agent created. The signal must reach in-process Pi hooks and shell hooks, and must change when a member is promoted.
+- Design response: The coordinator sets ACSTACK\_AGENT\_ROLE=member on every member process, next to AC\_TEAMS\_MEMBER. Absent or "main" means main; any other value means not main. Children of a member inherit it. Promotion always relaunches the transcript in a new process without ACSTACK\_AGENT\_ROLE or any AC\_TEAMS\_\* variable, so a live process never needs to change its role. Main status grants no permissions.
+- Applies to: coordinator, member, main-session, read-guard
+
+## Separate identity, discovery, membership, and authority
+
+- Requirement: Issue \#19 forbids tying session identity or permission authority to picker visibility, storage location, or a single main session.
+- Design response: Identity is the Pi session id. Discovery is where the transcript file lives. Membership and role are records in the team store. Ownership is whoever holds owner.lock. Authority comes from the member's role in the team store, which only explicit user actions change. Moving a file or taking the lock changes nothing else.
+- Applies to: main-session, member, coordinator, team-store, transcripts
+
+## Duplicate prevention
+
+- Requirement: A session must not appear twice in a team, run as two processes, or belong to two teams.
+- Design response: The team store keys members by member id and refuses a second record with the same Pi session id. The coordinator accepts one live connection per member and keeps the existing pid and identity check before any launch or relaunch. A session in a team with members cannot join another team.
+- Applies to: coordinator, team-store, main-session
+
+## Recovery without the original owner
+
+- Requirement: The team must carry on when the owner exits, and a promoted session resumed later must find its team again.
+- Design response: When the owner exits, another connected main session takes owner.lock and resumes members by their recorded state: busy members get a message to check their last steps and continue, idle members stay idle, and open questions reappear. A main session resumed from /resume reads its team entry, then connects to the live coordinator or offers to take ownership.
+- Applies to: main-session, coordinator, team-store, member
+
+## Team store
+
+*Private team state under \~/.pi/ac-teams/teams/&\#60;team&\#62;/: members with their role, tasks, messages, owner.lock, and each main session's connection token. Sandboxed members cannot read it.*
+
+- Identity: `team-store`
+- Kind: store
+- Channels: none
+- Source: [team-store.yaml](team-store.yaml)
+
+## Separate identity, discovery, membership, and authority
+
+- Requirement: Issue \#19 forbids tying session identity or permission authority to picker visibility, storage location, or a single main session.
+- Design response: Identity is the Pi session id. Discovery is where the transcript file lives. Membership and role are records in the team store. Ownership is whoever holds owner.lock. Authority comes from the member's role in the team store, which only explicit user actions change. Moving a file or taking the lock changes nothing else.
+- Applies to: main-session, member, coordinator, team-store, transcripts
+
+## Duplicate prevention
+
+- Requirement: A session must not appear twice in a team, run as two processes, or belong to two teams.
+- Design response: The team store keys members by member id and refuses a second record with the same Pi session id. The coordinator accepts one live connection per member and keeps the existing pid and identity check before any launch or relaunch. A session in a team with members cannot join another team.
+- Applies to: coordinator, team-store, main-session
+
+## Recovery without the original owner
+
+- Requirement: The team must carry on when the owner exits, and a promoted session resumed later must find its team again.
+- Design response: When the owner exits, another connected main session takes owner.lock and resumes members by their recorded state: busy members get a message to check their last steps and continue, idle members stay idle, and open questions reappear. A main session resumed from /resume reads its team entry, then connects to the live coordinator or offers to take ownership.
+- Applies to: main-session, coordinator, team-store, member
+
+## Pi transcripts
+
+*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/&\#60;team&\#62;/&\#60;member&\#62;/, where only /teams finds them.*
+
+- Identity: `transcripts`
+- Kind: store
+- Channels: none
+- Source: [transcripts.yaml](transcripts.yaml)
+
+## Separate identity, discovery, membership, and authority
+
+- Requirement: Issue \#19 forbids tying session identity or permission authority to picker visibility, storage location, or a single main session.
+- Design response: Identity is the Pi session id. Discovery is where the transcript file lives. Membership and role are records in the team store. Ownership is whoever holds owner.lock. Authority comes from the member's role in the team store, which only explicit user actions change. Moving a file or taking the lock changes nothing else.
+- Applies to: main-session, member, coordinator, team-store, transcripts
+
+## Herdr
+
+*Optional terminal workspace manager. When present, each main session gets its own tab in the workspace for its worktree.*
+
+- Identity: `herdr`
+- Kind: external-system
+- Channels: none
+- Source: [herdr.yaml](herdr.yaml)
+
+
+
+## ACStack read guard
+
+*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.*
+
+- Identity: `read-guard`
+- Kind: external-system
+- Channels: none
+- Source: [read-guard.yaml](read-guard.yaml)
+
+## Main-agent signal
+
+- Requirement: ACStack's large-read guard applies only to main agents. A main agent is a session the user created or promoted, never one an agent created. The signal must reach in-process Pi hooks and shell hooks, and must change when a member is promoted.
+- Design response: The coordinator sets ACSTACK\_AGENT\_ROLE=member on every member process, next to AC\_TEAMS\_MEMBER. Absent or "main" means main; any other value means not main. Children of a member inherit it. Promotion always relaunches the transcript in a new process without ACSTACK\_AGENT\_ROLE or any AC\_TEAMS\_\* variable, so a live process never needs to change its role. Main status grants no permissions.
+- Applies to: coordinator, member, main-session, read-guard

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

@@ -0,0 +1,44 @@
+id: coordinator
+name: Coordinator
+summary: >-
+  The team's single referee, running inside whichever main session holds
+  owner.lock. It starts and stops member processes, answers every team_agent,
+  team_task, and team_message call, delivers message notifications, checks
+  who may do what, and runs promotion, joining, and takeover.
+kind: component
+relationships:
+  - id: main-uses-coordinator
+    from: main-session
+    to: coordinator
+    direction: one-way
+    label: Hosts as owner, or connects to as a client
+  - id: member-uses-coordinator
+    from: member
+    to: coordinator
+    direction: one-way
+    label: Calls team tools through
+  - id: coordinator-runs-member
+    from: coordinator
+    to: member
+    direction: one-way
+    label: Launches, stops, and resumes
+  - id: coordinator-launches-main
+    from: coordinator
+    to: main-session
+    direction: one-way
+    label: Relaunches promoted members as
+  - id: coordinator-writes-store
+    from: coordinator
+    to: team-store
+    direction: one-way
+    label: Holds owner.lock and records roles in
+  - id: coordinator-moves-transcript
+    from: coordinator
+    to: transcripts
+    direction: one-way
+    label: Moves promoted transcripts within
+  - id: coordinator-opens-tabs
+    from: coordinator
+    to: herdr
+    direction: one-way
+    label: Opens main-session tabs through

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

@@ -0,0 +1,70 @@
+id: session-roles
+name: Session roles - promotion, joining, and several main sessions
+summary: >-
+  A team can have several main sessions. The user can promote a member into a
+  main session or join an existing session to a team. Identity, transcript
+  discovery, membership, coordinator ownership, and permission authority stay
+  separate, and ACSTACK_AGENT_ROLE tells hooks which processes are main.
+detail: journey.md
+elements:
+  - user.yaml
+  - main-session.yaml
+  - member.yaml
+  - coordinator.yaml
+  - team-store.yaml
+  - transcripts.yaml
+  - herdr.yaml
+  - read-guard.yaml
+concerns:
+  - id: main-signal
+    name: Main-agent signal
+    elements: [coordinator, member, main-session, read-guard]
+    requirement: >-
+      ACStack's large-read guard applies only to main agents. A main agent is
+      a session the user created or promoted, never one an agent created. The
+      signal must reach in-process Pi hooks and shell hooks, and must change
+      when a member is promoted.
+    response: >-
+      The coordinator sets ACSTACK_AGENT_ROLE=member on every member process,
+      next to AC_TEAMS_MEMBER. Absent or "main" means main; any other value
+      means not main. Children of a member inherit it. Promotion always
+      relaunches the transcript in a new process without ACSTACK_AGENT_ROLE
+      or any AC_TEAMS_* variable, so a live process never needs to change its
+      role. Main status grants no permissions.
+  - id: separate-axes
+    name: Separate identity, discovery, membership, and authority
+    elements: [main-session, member, coordinator, team-store, transcripts]
+    requirement: >-
+      Issue #19 forbids tying session identity or permission authority to
+      picker visibility, storage location, or a single main session.
+    response: >-
+      Identity is the Pi session id. Discovery is where the transcript file
+      lives. Membership and role are records in the team store. Ownership is
+      whoever holds owner.lock. Authority comes from the member's role in the
+      team store, which only explicit user actions change. Moving a file or
+      taking the lock changes nothing else.
+  - id: duplicate-prevention
+    name: Duplicate prevention
+    elements: [coordinator, team-store, main-session]
+    requirement: >-
+      A session must not appear twice in a team, run as two processes, or
+      belong to two teams.
+    response: >-
+      The team store keys members by member id and refuses a second record
+      with the same Pi session id. The coordinator accepts one live
+      connection per member and keeps the existing pid and identity check
+      before any launch or relaunch. A session in a team with members cannot
+      join another team.
+  - id: recovery
+    name: Recovery without the original owner
+    elements: [main-session, coordinator, team-store, member]
+    requirement: >-
+      The team must carry on when the owner exits, and a promoted session
+      resumed later must find its team again.
+    response: >-
+      When the owner exits, another connected main session takes owner.lock
+      and resumes members by their recorded state: busy members get a message
+      to check their last steps and continue, idle members stay idle, and open
+      questions reappear. A main session resumed
+      from /resume reads its team entry, then connects to the live
+      coordinator or offers to take ownership.

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

@@ -0,0 +1,17 @@
+id: herdr
+name: Herdr
+summary: >-
+  Optional terminal workspace manager. When present, each main session gets
+  its own tab in the workspace for its worktree.
+kind: external-system
+relationships:
+  - id: user-uses-herdr
+    from: user
+    to: herdr
+    direction: one-way
+    label: Switches between main sessions in
+  - id: coordinator-opens-tabs
+    from: coordinator
+    to: herdr
+    direction: one-way
+    label: Opens main-session tabs through

package/docs/design/session-roles/journey.md

@@ -0,0 +1,139 @@
+## Session roles: promotion, joining, and several main sessions
+
+Status: draft for review. Implements nothing yet. Resolves the design questions in [issue #19](https://github.com/ac8318740/ac-teams/issues/19).
+
+A team can have several **main sessions**. A main session is a Pi session the user created, joined to a team, or promoted. Every other team process is a **member**. The user can promote a member to a main session from the TUI, or join an existing session to a team with `/teams join`. ac-teams marks every member process with `ACSTACK_AGENT_ROLE=member`, so ACStack's large-read guard applies only to main sessions.
+
+### Review questions
+
+1. Does promotion by relaunch feel seamless enough, given that a promoted session moves to its own Herdr tab?
+2. Does it look right that every main session can control every member and other main sessions? That matches what an unsandboxed session can already do through its shell.
+3. Is the takeover after the owner exits (automatic, with a notice) the right default?
+4. Are the changes and tests at the end complete enough to start implementation?
+
+### Trade-offs to judge
+
+- **Relaunch, not live handover.** Promotion stops the member process and reopens its transcript in a new process. The member loses its in-flight turn, but its role, sandbox, token, and environment change cleanly.
+- **No coordinator daemon.** The coordinator stays inside whichever main session holds `owner.lock`. When the owner exits, members stop and the next owner resumes them automatically. The cost is a pause and at most one redone turn per busy member.
+- **Wide main-session authority.** Any main session can stop work started by another. ac-teams does not try to guard against this, because an unsandboxed session can already stop processes through the shell or Herdr.
+
+## Definitions
+
+These five properties are independent. A change to one never changes another.
+
+| Property | Defined by | Changes when |
+|---|---|---|
+| Identity | Pi session id in the transcript header | Never |
+| Discovery | Where the transcript file lives | Promotion moves it to the top-level session folder |
+| Membership | A member record in the team store | Join adds one; leave clears its role |
+| Coordinator ownership | Holder of `owner.lock` | The owner exits and another main session takes it |
+| Authority | The record's `role`: `main` or `member` | Only promotion, join, or leave, all user actions |
+
+### What the coordinator does
+
+The coordinator is ac-teams' in-process server. Today it runs inside Main. In this design, it runs inside whichever main session holds `owner.lock`. In practice it:
+
+- **Runs member processes.** Starts each member's Pi, either headless or in tmux, optionally inside a Docker sandbox. It also stops and resumes members, and stops them all when its host session exits
+- **Answers team tools.** Every `team_agent`, `team_task`, and `team_message` call from any session arrives over `coordinator.sock` and is applied here, so concurrent edits are serialized
+- **Keeps team state.** Writes members, tasks, and messages to the team store
+- **Delivers notifications.** Tells each session when new team messages arrive
+- **Enforces rules.** Checks authority, depth and member limits, and sandbox grants, and brokers provider credentials for sandboxed members
+
+This design keeps all of that. It adds role checks, connections from main sessions it did not launch, promotion, joining, leaving, and ownership takeover.
+
+The team id stays the session id of the session that created the team, even after that session leaves or hands over ownership.
+
+### Main-agent signal
+
+- The coordinator sets `ACSTACK_AGENT_ROLE=member` on every member process, next to `AC_TEAMS_MEMBER`. That includes the terminal-launch script, which today only passes `AC_TEAMS_*` and `HERDR_ENV`
+- A hook treats the session as main when the variable is absent or `main`, and as not main for any other value
+- Anything a member starts inherits the variable and counts as not main
+- Promotion and every main-session launch must remove `ACSTACK_AGENT_ROLE`, every `AC_TEAMS_*` variable, and `HERDR_ENV=0`. Tests must cover this
+- ACStack reads the variable on every tool call. It detects Claude Code and Codex subagents from `agent_id` in their hook payloads instead. That detection belongs to ACStack, not ac-teams
+- Role grants no permission by itself
+
+## User flows
+
+### Promote a member
+
+1. The user opens a teammate from the agent selector or `/teams` and chooses **Promote to main**
+2. If the member is sandboxed, a confirmation states that the session will run with the user's full access. Declining cancels
+3. The coordinator stops the member, waiting for its process to exit as `stop` does today
+4. The coordinator moves the transcript from `ac-teams/<team>/<member>/` to the project's top-level session folder. It removes the member's config at `~/.pi/ac-teams/agents/<id>` and sets the member's role to `main` without a parent. The member's children stay its descendants
+5. The coordinator writes the session's team entry: a Pi custom entry holding the team id and member id, with no secrets
+6. The coordinator relaunches `pi --session <moved file>` with a clean environment:
+    - With Herdr, in a new tab in the workspace for the session's worktree, creating the workspace if needed. The tab gets focus and the session's name
+    - Without Herdr, in a tmux session on a per-main-session socket that the owner's `kill-server` cannot reach. The user's screen stays attached, and ac-teams prints the reattach command
+7. The new process reads its team entry, connects to the coordinator with a main-session token from the team store, and appears in `/resume`
+
+### Join an existing session to a team
+
+1. The user runs `/teams join` in an ordinary Pi session
+2. ac-teams lists this project's teams. The user picks one
+3. ac-teams refuses if the session already belongs to a team with members, or if its session id is already in the chosen team
+4. The coordinator adds a member record with role `main` and writes the team entry
+5. The session receives a short summary of open tasks, owners, and recent messages, with its message cursor at the latest message. It claims or creates work with the normal team tools
+
+### Several main sessions
+
+- Each main session holds one connection to the coordinator. The owner hosts it in-process; the others connect over `coordinator.sock`
+- Every main session sits at depth 0. Any main session can launch, stop, resume, and clean up any member, and stop or resume another main session
+- Stopping a main session asks it to shut down through its connection. Resuming one relaunches its transcript, as in step 6 of promotion
+- Members keep today's rule: they control only their descendants and never a main session
+- Tasks and messages stay shared. Ownership and revision checks still serialize concurrent edits, because one coordinator applies them all
+
+### Leave a team
+
+`/teams leave` returns the session's in-progress tasks to todo and clears their ownership. The member record keeps its history but loses its role, so its descendants stay under the other main sessions. The team entry records the departure, so a later `/resume` does not rejoin. Leaving is refused while the session is the only main session and members are still live.
+
+## Recovery
+
+- **The owner exits while another main session runs.** Before stopping members, the owner records each one's state (busy, idle, or needs input) in the team store. Today, `Coordinator.open` discards that state. A connected main session then takes `owner.lock`, opens the coordinator, and runs the resume pass below. Every main session gets a notice naming the new owner
+- **No main session is running when the owner exits.** Members stay stopped with their recorded state. The next main session that opens the team runs the same resume pass
+- **A promoted session is resumed with no coordinator running.** The extension reads its team entry at startup and offers to take ownership. Accepting opens the coordinator and runs the resume pass. Declining runs the session without team tools
+
+### Resume pass
+
+| Recorded state | Action |
+|---|---|
+| Busy | Resume and send: "Your process was restarted during a coordinator handover. Check your last steps and continue your current task." |
+| Idle | Resume and leave idle |
+| Needs input | Resume and show **Needs input** again |
+
+Pi saves each completed message, so a busy member loses only the reply it was generating and redoes that turn. A command killed mid-run may have half finished. The message tells the member to check before it continues, which reduces that risk but does not remove it, the same as stopping a member today.
+- **A main session crashes.** Its record stays. The coordinator marks it interrupted, and any main session can resume it
+- **Promotion fails partway.** Each step is recorded in the team store before the next starts. On failure, the coordinator rolls back to a stopped member with its original transcript path, and the member can be retried or resumed
+
+## Security boundaries
+
+- Only the user can promote, join, or leave. These actions have no agent-tool form
+- Promoting a sandboxed member is an explicit escalation, approved in the confirmation step. Without approval, nothing changes
+- Main-session tokens live in the private team store, which sandboxed members cannot read. A member therefore cannot impersonate a main session over the socket
+- Descendant non-escalation stays as it is: a member cannot grant its descendants more access than it has
+- Provider credentials for sandboxed members come from the current owner's Pi login. After a takeover, the new owner brokers them under the same OS user
+
+## Changes needed before implementation
+
+- **Team store schema 4.** Add `role` to members and migrate `root` to a main record. Replace `actor === "root"` checks with role checks. Store each main session's token
+- **Coordinator.**
+    - Accept connections from main sessions that were not launched by the coordinator
+    - Add promote, join, leave, and the stop and resume of main sessions
+    - Add ownership takeover, and recompute descendant depths after a promotion
+- **Launch environment.** Set `ACSTACK_AGENT_ROLE=member` for every member, including the terminal script's variable filter. Strip it on main-session launches
+- **Extension.** Read the team entry at `session_start`. Add `/teams join`, `/teams leave`, and the **Promote to main** action. Open Herdr tabs, or use the tmux fallback
+- **Docs.** Update `docs/usage.md`, `docs/operations.md`, and `docs/access.md`
+
+## Tests needed
+
+- A launched member has `ACSTACK_AGENT_ROLE=member`, in both RPC and terminal modes
+- A promoted session's environment has no `ACSTACK_AGENT_ROLE` and no `AC_TEAMS_*` variables
+- Promotion keeps the session id, moves the file, updates the stored path, and writes the team entry. Pi's session listing then includes the session
+- A sandboxed promotion is refused without confirmation and runs unsandboxed after it
+- Joining refuses a duplicate session id, and refuses a session that leads another team with members
+- A main session can stop and resume members and other main sessions. A member cannot act on a main session
+- When the owner exits, another main session takes the lock. Busy members resume with the continue message, idle members stay idle, and members that needed input show **Needs input** again
+- When no main session is running, the next one to open the team runs the same resume pass
+- Resuming a promoted transcript with no coordinator offers takeover, and declining leaves team tools off
+- Leaving returns in-progress tasks to todo and keeps descendants manageable
+- A promotion interrupted after each step rolls back to a resumable member
+- Schema 3 teams migrate to schema 4 with root as a main record