ac-teams 0.0.6 → 0.0.8

package/README.md

@@ -4,7 +4,7 @@ Persistent agent teams for [Pi](https://github.com/earendil-works/pi): shared ta
 
 ## Install
 
-Requires Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`. Interactive teams also require `tmux` on `PATH`. Tested with Pi 1.4.0.
+Requires Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`. Interactive teams also require `tmux` on `PATH`. Tested with Pi 1.4.0 and 1.5.0.
 
 ```sh
 pi install npm:ac-teams@0.0.4
@@ -28,13 +28,13 @@ 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.
 
 ## Know the boundaries
 
-- Members share your filesystem access. All members can read all team messages, including direct messages.
+- Members share your filesystem access unless launched with [enforced access](docs/access.md), an opt-in Docker sandbox that needs Docker and a locally built member image. All members can read all team messages, including direct messages.
 - Limits cover only `team_agent`, not other delegation tools. Use separate worktrees for concurrent writers.
 - Stop retains tasks, sessions, and worktrees. Worktree deletion is explicit and requires clean, integrated work.
 - Exit confirmation needs Pi's `session_before_exit` hook, which installed Pi 1.4.0 lacks. Without it, shutdown cleans up but cannot ask first. Signals always bypass confirmation.
@@ -45,6 +45,7 @@ See the [operations guide](docs/operations.md) for recovery guarantees, storage,
 
 - [Usage](docs/usage.md): tool actions, task rules, messages, and companion tools
 - [Operations](docs/operations.md): limits, stop/resume, worktrees, and security
+- [Enforced access](docs/access.md): Docker-enforced read/write grants, outbound proxy and destination policy, and setup
 - [Development](docs/development.md): source setup, verification, and publishing
 - [Implementation history](docs/implementation-plan.md): design decisions and prior art
 

package/docs/access.md

@@ -0,0 +1,103 @@
+# Enforce member access
+
+By default, members are ordinary unsandboxed Pi processes with your full user permissions. Enforced access is opt-in: ac-teams runs the member's whole Pi process, including its shell, extensions, and subprocesses, in a Docker container that sees only the directories you grant. If enforcement is unavailable, the launch fails; ac-teams never falls back to an unsandboxed member.
+
+## Request access
+
+`team_agent` launch accepts `access`:
+
+```json
+{ "action": "launch", "name": "reviewer", "brief": "...", "access": { "read": ["."] } }
+{ "action": "launch", "name": "parser", "brief": "...", "cwd": "/repo/parser", "access": { "read": ["/repo/docs", "/repo/lib"], "write": ["."] } }
+```
+
+- Paths are directories, absolute or relative to the member's `cwd`. Write implies read. The `cwd` must be inside a grant.
+- `network.allow` limits outbound destinations: `host`, or `*.host` for its subdomains, each optionally `:port`; without a port, an entry allows ports 80 and 443. `[]` allows only the model provider. Omit `allow` for any public destination. Omitting `network` keeps the requester's network access; from an unsandboxed requester that is any public destination.
+- Omitting `access` inherits the requesting member's access. From an unsandboxed requester, it launches an unsandboxed member, as before.
+- Members can only narrow access: a sandboxed member cannot grant a path outside its own access, give write where it has read, allow a destination its own allowlist does not, or launch or resume an unsandboxed member. Access is fixed at launch; resume keeps it.
+- Refused grants: `/`, your home directory or its parents, `/tmp`, `/run`, anything under `/proc`, `/dev`, or `/sys`, and anything containing or inside `~/.pi/agent` or `~/.pi/ac-teams`. They would expose host service sockets, credentials, transcripts, or coordinator state.
+- Grants must be canonical paths with no symlinks, and cannot contain commas, which Docker's mount syntax cannot escape.
+- Docker resolves mount paths when a container starts, so a sandboxed writer could swap a granted path for a symlink just before another member starts. ac-teams holds each grant open from before the container is created, and after the container starts, before any member code runs, compares every mounted grant with the directory it holds; any difference removes the container. A writer of `/repo` and a reader of `/repo/src` can therefore run together. Runtime, transcript, and socket mounts are not compared this way, so none may sit strictly inside another live member's writable grant, across all teams. This protects against sandboxed members only; your own processes, Main, and unsandboxed members can change any path and are trusted.
+- Sandboxed members cannot create or clean up worktrees, send user team actions (`/teams` feedback, task requests, resume), or open other members' terminals; use Main.
+
+Before launching, check `sandbox` in `team_agent` `list` or `limits`: `{ "available": true, "backend": "docker" }`, or `available: false` with a `reason`. Every member receives `AC_TEAMS_ACCESS`: `{"enforced":true,"read":[...],"write":[...],"network":{"allow":[...]}}` (no `allow` means any public destination), or `{"enforced":false}`. `team_agent status` reports the coordinator's authoritative `access`.
+
+## Write grants and untrusted output
+
+A write grant lets the member change those live files, including Git metadata such as hooks and config, Pi project resources, and build scripts. Treat the result like any untrusted contribution: review changes before you run them, commit them, or start Git or Pi in those directories. Running changed code later outside the sandbox is your choice, not a sandbox escape.
+
+## What an enforced member can reach
+
+| Resource | Enforced member |
+| --- | --- |
+| Granted directories | Mounted at the same paths, read-only or read-write |
+| Rest of the host filesystem | Not mounted. The container's system files come from the member image |
+| Pi runtime | Read-only: the ac-teams package and these entries from your Pi agent directory: `npm`, `extensions`, `themes`, `skills`, `prompts`, `AGENTS.md`, `keybindings.json`, `acstack.json`, `models-store.json`. They run as trusted code inside the container and are not secret-free by design: the member can read your installed package code and lockfile, custom extension source, and global instructions. Keep secrets out of them. Your real `auth.json`, sessions, and caches are not mounted |
+| Web search settings | A copy of your `web-search.json` (including any search API keys) with the proxy set |
+| Trust decisions | A filtered `trust.json` with only the entries for the member's `cwd` and its parents |
+| Settings | A copy of your Pi `settings.json`, including its package list and device ID, so do not store secrets there |
+| Scratch | Private `/tmp` (512 MiB), home (256 MiB), and Pi agent directory (64 MiB), discarded at exit |
+| Network | Outbound HTTP and HTTPS through the parent's proxy only (below); no direct network |
+| Processes | Private process namespace; host processes are invisible |
+| Team | The coordinator socket for team tools, and the member's own transcript directory |
+| Environment | A fixed minimal set; host variables, including credentials, are not inherited |
+
+Any Unix socket inside a granted directory remains reachable, so grant narrow directories.
+
+Containers run as your user with all capabilities dropped, `no-new-privileges`, a read-only root filesystem, `--network none`, no published ports, no restart policy, no Docker socket, and logging disabled. Before starting a container, ac-teams inspects its effective configuration and refuses to start it on any difference in network, ports, privileges, capabilities, security options, namespaces, devices, mounts, image volumes, user, limits, or restart policy. Docker reports bind sources unresolved, so symlink swaps are caught by re-resolving sources instead. It checks network and ports again after start.
+
+## Outbound access goes through the parent's proxy
+
+Containers have no network interface except loopback. A bridge inside the container exposes a proxy owned by the root Pi process on `127.0.0.1:3128`, and members get `HTTP_PROXY`, `HTTPS_PROXY`, their lowercase forms, `NO_PROXY` for loopback, and `NODE_USE_ENV_PROXY=1`. Pi, Node, curl, and other clients that honour these variables reach the web; ac-teams also points pi-web-access and billion-context at the proxy through their own settings. Clients that ignore proxy settings have no network at all; there is no transparent capture of other protocols.
+
+The proxy:
+
+- Handles HTTPS through `CONNECT` and plain HTTP requests, without following redirects; each new request is checked again
+- Resolves names itself and refuses a destination if any resolved address is not global unicast: loopback, private, CGNAT (including Tailscale), link-local and cloud metadata, documentation, multicast, IPv4-mapped and translated forms, and every address of this host, even public ones. It connects to the address it checked, so DNS cannot change in between
+- Applies the member's `network.allow` list, if any, but always allows the selected model provider's endpoint so Pi can run
+- Is reachable only from that member's container, through its own socket
+- Accepts at most 256 open connections per member, so one member cannot exhaust Main's file descriptors
+
+A destination allowlist does not keep data private: an allowed host, including the model provider, receives whatever the member sends it.
+
+## Model credentials
+
+The member gets an `auth.json` with only its selected provider's current OAuth access token and expiry: no refresh token and no other providers. Main's Pi refreshes the token and rewrites the member's copy when it changes. The member can use, or leak, that token until it expires, and spend your quota with it; it cannot mint new tokens. Switching to another provider inside the member fails, because no other credential is present. A member with a `network.allow` list keeps its provider: its children and its resumes must use the same provider, so the always-allowed provider endpoint cannot widen its network access. The file is removed when the member exits; if Main's Pi is killed, it stays until that team is opened again and its orphans are cleaned up.
+
+Supported: OAuth `anthropic` and `openai` models at their default endpoints, tested with Pi 1.4.0 and 1.5.0. Other providers, API-key credentials, or a changed credential shape fail the launch.
+
+## Resource limits
+
+Each member container is capped at 2 GiB of memory (no swap) and 1024 processes. ac-teams allows at most as many enforced members at once, across all teams on the host, as fit in 75% of host memory at that cap (5 on a 15 GiB host). It counts created and running member containers after creating a new one, so concurrent launches cannot both pass. This bounds the sum of container caps; it does not limit Main, unsandboxed members, or other host processes. CPU is not capped.
+
+A new enforced member takes about 20 seconds to start, because Pi compiles TypeScript extensions into an empty cache.
+
+## Set up Docker
+
+Enforced access needs a running Docker daemon your user can use, and the member image for your Pi version. Using Docker means trusting the Docker daemon, which runs as root; membership in the `docker` group is equivalent to root access on the host.
+
+When the image is missing, `team_agent list` reports the exact build command, for example:
+
+```sh
+docker build -t ac-teams-member:1.5.0-<hash> --build-arg PI_VERSION=1.5.0 -f <ac-teams>/src/sandbox.Dockerfile <ac-teams>/src
+```
+
+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`
+- Generated member configuration (settings copy, provider access token, trust and web search copies, launch file): `~/.pi/ac-teams/agents/<member>/`, removed when the member exits
+- Member transcripts: `<Main's session directory>/ac-teams/<team>/<member>/`, normally under `~/.pi/agent/sessions/<project>/`. Pi's `/resume` lists only top-level sessions, so member transcripts appear in `/teams`, not `/resume`
+
+## Known limits
+
+- Tools outside the mounted runtime, such as the ACStack CLI at `~/.claude/acstack/bin/acstack`, need explicit read grants for their directory and any symlink target. Grant those narrow directories, never `~/.claude`, which holds credentials.
+- Interactive members run in the team's tmux pane through `docker start --attach`, on the container's own terminal.
+- Linux only. [Development](development.md#enforced-access-verification) records what has been verified.
+
+[Back to README](../README.md)

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