ac-teams 0.0.6 → 0.0.8

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

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

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

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

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

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

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

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

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

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

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

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

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

package/docs/development.md

@@ -48,6 +48,24 @@ Terminal UI checks used real native Pi processes in an isolated full-size Herdr
 - Task summary above the input, agent selector below status, native subcommand/name autocomplete, and same-PID/session opening by name or ID
 - Pi-reported model display names and changing context estimates in the live selector
 
+### Enforced access verification
+
+Checks on 2026-11-02, Ubuntu 24.04, kernel 6.8, Docker 29.9.2 (rootful, default AppArmor and seccomp), Pi 1.4.0, member image `ac-teams-member:1.4.0-<hash>`:
+
+- `test/sandbox.test.ts` with real containers for RPC and native (tmux) members: grants enforced read-only and read-write; host files, other transcripts, team state, the real `auth.json`, the Docker socket, and the tmux socket unreachable; only the selected provider's access token is present, without a refresh token, and a token change reaches the container in place; public HTTP and HTTPS work through the proxy with curl and Node; this host's addresses (including its public IP and Tailscale address), the Docker bridge, and cloud metadata are refused; no direct network, UDP, or host Unix socket; the start gate cannot be replayed; no capabilities, `NoNewPrivs`, private PIDs, read-only root, written files owned by the user; nested narrower launch works and escalation is refused; the native member's terminal is the container's own pty, and TIOCSTI did not inject; containers and member credentials are removed on close
+- A grant swapped for a symlink between the checks and start is caught before any member code runs, and the container is removed; a writer of a repo and a reader of its subdirectory run together; resume gets a new gated container
+- A refused second owner leaves live containers alone; after the coordinator is killed, the next owner removes the orphaned container; the enforced-member cap counts other teams' containers
+- A real OpenAI OAuth member with the full installed extension set (billion-context active, ACStack, pi-web-access) answered through the proxy, ran curl (200), `web_search`, and `fetch_content` on a public documentation page; a member with `network.allow: []` still reached the model while curl to a public site failed; no refresh token or other provider in the container; network `none`, no ports, and no host listener changes
+
+Anthropic, later on 2026-11-02 (Pi 1.4.0 for the first two checks; Pi 1.5.0 with member image `ac-teams-member:1.5.0-<hash>` for the third and for a full `npm test` rerun, 118 pass):
+
+- A `claude-haiku-4-5` member with the full installed extension set ran curl (200), `web_search`, and `fetch_content`; with `network.allow: []` it still reached the model while curl failed; no refresh token or other provider in the container; network `none`, no ports
+- A real Pi Main loading this branch from an isolated agent directory (access tokens only, no refresh tokens) launched an enforced Anthropic member with `network.allow: []` through Main's own credential code: the sandbox was available, the launch succeeded, and the member answered `curl=000`; no host listener changes and no leftover containers or member files
+
+On the final tree with Pi 1.5.0, the OpenAI full-extension and `network.allow: []` runs passed again: curl 200, `web_search` and `fetch_content` ok, then curl `000` with the model still reachable. `npm test` passed 119 tests, and the Docker suite passed 10.
+
+Not verified: an Anthropic Main session, because Main's own Anthropic request was refused as out of extra usage while the member's Haiku requests succeeded.
+
 Not verified on macOS, Windows, or network filesystems. The package is Linux-only because safe process identity uses `/proc`. No web dashboard, workflow DSL, daemon, or automatic merging is included.
 
 ## Stage releases for npm approval

package/docs/operations.md

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

package/docs/usage.md

@@ -1,6 +1,6 @@
 # Use ac-teams
 
-ac-teams provides three tools without prescribing a workflow. Your Pi session is the root; its child agents are members. The root opens coordination state on the first team request.
+ac-teams provides three tools without prescribing a workflow. Your Pi session is a main session; the agents it launches are members. The first main session opens coordination state on the first team request. See [main sessions](#main-sessions-share-one-team) for adding more.
 
 | Tool | Actions | Main rule |
 | --- | --- | --- |
@@ -8,7 +8,7 @@ ac-teams provides three tools without prescribing a workflow. Your Pi session is
 | `team_task` | `create`, `list`, `read`, `edit`, `claim`, `start`, `release`, `complete`, `reopen` | Claim reserves work; dependencies gate starting, not ownership |
 | `team_message` | `send`, `history`, `search` | Recipients select who receives notification, not who can read |
 
-In interactive Pi, `/teams` or `/teams panel` opens the team panel. `/teams teammate <name-or-id>` opens a live teammate directly; autocomplete suggests subcommands and teammate names. You can also enter an exact teammate ID. The older `/teams open <id>` form remains supported. Headless roots retain the status listing. `/teams stop` stops every descendant. See [operations](operations.md) for limits, recovery, and worktree cleanup.
+In interactive Pi, `/teams` or `/teams panel` opens the team panel. `/teams teammate <name-or-id>` opens a live teammate directly; autocomplete suggests subcommands and teammate names. You can also enter an exact teammate ID. The older `/teams open <id>` form remains supported. Headless roots retain the status listing. `/teams stop` stops every member; main sessions keep running. `/teams join` and `/teams leave` change which team this session belongs to. See [operations](operations.md) for limits, recovery, and worktree cleanup.
 
 ## Navigate without stopping members
 
@@ -38,6 +38,17 @@ The `+N lines` hint shows the hidden detail count. Ctrl+O expands the full reque
 
 Team notification messages remain compact; Ctrl+O expands their labeled fields. UI state colors do not replace the underlying progress, ownership, or dependency fields.
 
+## Main sessions share one team
+
+A team can have several main sessions, each a top-level Pi session a person drives. Members are the agents they launch. Every main session controls every member and can stop or resume other main sessions; a member controls only its own descendants and never a main session.
+
+- **Promote:** On the panel's Teammates tab, `P` stops a member and relaunches it as a main session. It keeps its session ID and history, its transcript moves to the normal Pi session folder so `/resume` lists it, and it stays in the team. Under Herdr it opens in a new tab of the workspace for its worktree; otherwise it runs in its own tmux server and ac-teams prints the attach command. A member with enforced access asks first, because the promoted session runs without the container.
+- **Join:** `/teams join` lists the teams in this project and adds this session to the chosen one as a main session, then posts a summary of open tasks, owners, and recent messages. It refuses a session already in that team, or one already in a team with other members.
+- **Leave:** `/teams leave` returns this session's in-progress tasks to `todo`, clears their ownership, and drops its main-session role; its record keeps its history. The last main session cannot leave while members are live.
+- **Resume:** A session remembers its team in its transcript. Resuming it reconnects to the team; if no coordinator is running, ac-teams offers to run it here. Declining turns the team tools off for this session.
+
+One main session runs the coordinator; the others connect to it. When that session exits, another main session takes over automatically and resumes the members that were working. See [operations](operations.md#coordinator-handover).
+
 ## Show tasks and configure the displays
 
 The task summary sits above the input editor; the agent selector sits below the editor. The task summary shows completed/total counts and up to five numbered task labels, ordered by:
@@ -133,6 +144,6 @@ Messages survive crashes; exactly-once delivery or model execution does not. Avo
 
 ac-teams works alone. ACStack adds planning, review, and shipping skills; Herdr adds terminal tabs, panes, and visible root sessions. These are companion capabilities, not automatic integrations. ac-teams does not open a Herdr pane for each member. Interactive members use a team-private tmux server and open in the current terminal when selected; headless roots use RPC members.
 
-Other delegation tools can coexist. ac-teams warns when `Agent`, `SubagentWorkflow`, or `subagent` is active, but does not disable them. Its limits cover only members launched through `team_agent`. Use Pi's resource settings to disable other launchers if you want one team authority. Shell access and same-user extensions are not sandboxed.
+Other delegation tools can coexist. ac-teams warns when `Agent`, `SubagentWorkflow`, or `subagent` is active, but does not disable them. Its limits cover only members launched through `team_agent`. Use Pi's resource settings to disable other launchers if you want one team authority. Shell access and same-user extensions are not sandboxed unless a member is launched with [enforced access](access.md).
 
 [Back to README](../README.md)

package/package.json

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

package/src/access.ts

@@ -0,0 +1,175 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir, totalmem } from "node:os";
+import { stateRoot } from "./config.ts";
+import { assertNetworkNarrower, validatePolicy, type NetworkPolicy } from "./egress.ts";
+import { dirname, join, resolve } from "node:path";
+
+/** Canonical directory grants; write implies read. Undefined access means an unsandboxed member. */
+export interface Access { read: string[]; write: string[]; network: NetworkPolicy }
+export interface AccessRequest { read?: string[]; write?: string[]; network?: NetworkPolicy }
+export interface SandboxStatus { available: boolean; backend: "docker"; reason?: string }
+
+export const within = (path: string, root: string) => path === root || path.startsWith(root === "/" ? "/" : root + "/");
+const inside = (path: string, roots: string[]) => roots.some(root => within(path, root));
+export const readable = (access: Access, path: string) => inside(path, [...access.read, ...access.write]);
+export const writable = (access: Access, path: string) => inside(path, access.write);
+
+/** Pi's agent directory and ac-teams state hold credentials, transcripts, and coordinator tokens. */
+export const privateRoots = () => [resolve(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent")), stateRoot()];
+
+export function resolveAccess(request: AccessRequest, base: string): Access {
+  const canonical = (paths: string[] = []) => [...new Set(paths.map(path => {
+    let real: string;
+    try { real = realpathSync(resolve(base, path)); } catch { throw new Error(`Access path does not exist: ${path}`); }
+    if (!statSync(real).isDirectory()) throw new Error(`Access path must be a directory: ${path}`);
+    // A symlink in the path would be re-resolved by Docker at start; a sandboxed writer could have planted or could swap it.
+    if (real !== resolve(base, path)) throw new Error(`Access paths must be canonical, without symlinks: ${path} resolves to ${real}`);
+    // Docker's --mount syntax has no escaping, so a comma would inject mount options.
+    if (/[,\n]/.test(real)) throw new Error(`Access paths cannot contain commas or newlines: ${real}`);
+    // These would replace the sandbox's private /proc, /dev, /tmp, or home, or expose host sockets and credentials.
+    for (const unsafe of ["/proc", "/dev", "/sys", "/run"]) if (within(real, unsafe)) throw new Error(`Access to ${real} is not allowed`);
+    for (const covered of ["/tmp", "/run", "/var/run", homedir()]) if (within(covered, real)) throw new Error(`Access to ${real} would expose ${covered}; grant a narrower directory`);
+    for (const root of privateRoots()) if (within(real, root) || within(root, real)) throw new Error(`Access to ${real} would expose private Pi or ac-teams state in ${root}`);
+    return real;
+  }))].sort();
+  const write = canonical(request.write);
+  return { read: canonical(request.read).filter(path => !inside(path, write)), write, network: validatePolicy(request.network ?? {}) };
+}
+
+/** Throws unless child grants are the same as or narrower than the actor's; an unsandboxed actor may grant anything. */
+export function assertNarrower(actor: Access | undefined, child: Access | undefined): void {
+  if (!actor) return;
+  if (!child) throw new Error("A sandboxed member cannot launch or resume an unsandboxed member");
+  for (const path of child.write) if (!writable(actor, path)) throw new Error(`Write access to ${path} exceeds the requesting member's access`);
+  for (const path of child.read) if (!readable(actor, path)) throw new Error(`Read access to ${path} exceeds the requesting member's access`);
+  assertNetworkNarrower(actor.network, child.network);
+}
+
+/** Host paths a member mounts, and the subset it can write. */
+export interface MountSet { sources: string[]; writes: string[] }
+/** Grants are identity-checked at start, so only a member's other mounts count as sources; its writable grants are its writes. */
+export const mountSet = (mounts: { source: string; rw: boolean }[], grants: string[]): MountSet => ({
+  sources: mounts.filter(mount => !grants.includes(mount.source)).map(mount => mount.source),
+  writes: mounts.filter(mount => mount.rw && grants.includes(mount.source)).map(mount => mount.source) });
+/**
+ * Docker resolves bind sources when a container starts. A sandboxed writer can replace any entry strictly below its
+ * writable directory, so no member may mount a path strictly inside another live member's writable directory, in either
+ * direction. Equal paths are safe: a writer cannot replace its own mount point. A member's own non-grant mounts (runtime,
+ * bridge) must not sit inside its own writable directory either, or it could swap them before its next start.
+ */
+export function assertStableGrants(mine: MountSet, others: MountSet[]): void {
+  const below = (set: MountSet, writer: MountSet) => set.sources.find(path => writer.writes.some(root => path !== root && within(path, root)));
+  for (const other of [...others, mine]) {
+    const path = below(mine, other) ?? below(other, mine);
+    if (path) throw new Error(`Mount ${path} lies strictly inside a sandboxed member's writable directory; grant that directory or a path outside it`);
+  }
+}
+
+/** Pi agent-directory entries members need: installed packages, extensions, themes, skills, prompts, and settings Pi reads at startup. */
+export const agentRuntime = ["npm", "extensions", "themes", "skills", "prompts", "AGENTS.md", "keybindings.json", "acstack.json", "models-store.json"];
+export const generatedAgentFiles = ["settings.json", "auth.json", "trust.json", "web-search.json"];
+
+export function packageRoot(file: string): string {
+  for (let dir = dirname(realpathSync(file)); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    if (dir === dirname(dir)) throw new Error(`No package root for ${file}`);
+  }
+}
+
+// Container memory caps; the aggregate guard keeps the sum of caps within 75% of host RAM.
+// shortcut: fixed per-member cap, add a setting if real workloads need more.
+export const memberMemory = 2 * 1024 ** 3;
+export const memberPids = 1024;
+export const maxSandboxed = () => Math.max(1, Math.floor(totalmem() * 0.75 / memberMemory));
+
+const dockerfile = new URL("./sandbox.Dockerfile", import.meta.url);
+/** Image tag tied to the host Pi version and this Dockerfile, so members run the same Pi as Main. */
+export function memberImage(piVersion: string): { tag: string; build: string } {
+  const hash = createHash("sha256").update(readFileSync(dockerfile)).digest("hex").slice(0, 12);
+  const tag = `ac-teams-member:${piVersion}-${hash}`, file = dockerfile.pathname;
+  return { tag, build: `docker build -t ${tag} --build-arg PI_VERSION=${piVersion} -f ${file} ${dirname(file)}` };
+}
+
+export function sandboxStatus(image: { tag: string; build: string }, docker = "docker"): SandboxStatus {
+  const status = (reason?: string): SandboxStatus => ({ available: !reason, backend: "docker", ...(reason ? { reason } : {}) });
+  if (process.platform !== "linux") return status("Enforced access requires Linux");
+  const probe = spawnSync(docker, ["image", "inspect", "--format", "{{json .Config.Volumes}}", image.tag], { encoding: "utf8", timeout: 10000 });
+  if (probe.error) return status(`Docker is unavailable: ${probe.error.message}`);
+  if (probe.status !== 0) return status(/No such image/i.test(probe.stderr) ? `Member image ${image.tag} is missing; build it with: ${image.build}` : `Docker cannot be used: ${probe.stderr.trim().slice(0, 300)}`);
+  if (!["null", "{}"].includes(probe.stdout.trim())) return status(`Member image ${image.tag} declares volumes; rebuild it from the shipped Dockerfile`);
+  return status();
+}
+
+export interface SandboxPlan {
+  name: string; labels: Record<string, string>; image: string; access: Access; cwd: string; home: string; terminal: boolean;
+  agentDir: string; configDir: string; sessionDir: string; coordinatorSocket: string; egressSocket: string;
+  runtime: string[]; launch: string; bridge: string;
+}
+export interface Mount { source: string; target: string; readonly: boolean }
+/** Every host path a member container sees. Nothing else on the host is mounted. */
+export function sandboxMounts(plan: SandboxPlan): Mount[] {
+  const mounts: Mount[] = [
+    ...plan.access.read.map(path => ({ source: path, target: path, readonly: true })),
+    ...plan.access.write.map(path => ({ source: path, target: path, readonly: false })),
+    // Runtime code stays read-only even inside a writable grant, because unsandboxed processes load it too.
+    ...plan.runtime.map(path => ({ source: path, target: path, readonly: true })),
+    ...agentRuntime.map(name => join(plan.agentDir, name)).filter(path => existsSync(path)).map(path => ({ source: path, target: path, readonly: true })),
+    ...generatedAgentFiles.map(name => ({ source: join(plan.configDir, name), target: join(plan.agentDir, name), readonly: true })),
+    { source: plan.launch, target: plan.launch, readonly: true },
+    { source: plan.sessionDir, target: plan.sessionDir, readonly: false },
+    { source: plan.coordinatorSocket, target: plan.coordinatorSocket, readonly: false },
+    { source: plan.egressSocket, target: plan.egressSocket, readonly: false },
+  ];
+  return mounts;
+}
+
+export function dockerCreateArgs(plan: SandboxPlan): string[] {
+  const uid = process.getuid!(), gid = process.getgid!();
+  const args = ["create", "--name", plan.name, "--interactive", ...(plan.terminal ? ["--tty"] : []), "--init",
+    "--network", "none", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--read-only", "--restart", "no",
+    "--user", `${uid}:${gid}`, "--memory", String(memberMemory), "--memory-swap", String(memberMemory), "--pids-limit", String(memberPids),
+    "--log-driver", "none", "--hostname", "ac-teams",
+    "--tmpfs", "/tmp:rw,nosuid,nodev,size=512m", "--tmpfs", `${plan.home}:rw,nosuid,nodev,size=256m,uid=${uid},gid=${gid},mode=0700`,
+    // Pi writes lock files and caches in its agent directory; this private scratch copy hides the real one.
+    "--tmpfs", `${plan.agentDir}:rw,nosuid,nodev,size=64m,uid=${uid},gid=${gid},mode=0700`];
+  for (const [key, value] of Object.entries(plan.labels)) args.push("--label", `${key}=${value}`);
+  // Other coordinators use this to tell grants (identity-checked at start) from runtime mounts.
+  args.push("--label", `ac-teams.grants=${JSON.stringify([...plan.access.read, ...plan.access.write])}`);
+  for (const mount of sandboxMounts(plan)) args.push("--mount", `type=bind,source=${mount.source},target=${mount.target}${mount.readonly ? ",readonly" : ""}`);
+  args.push("--env", "PATH=/usr/local/bin:/usr/bin:/bin", "--env", `HOME=${plan.home}`, "--env", "TMPDIR=/tmp",
+    "--workdir", plan.cwd, plan.image, "node", plan.bridge, plan.launch);
+  return args;
+}
+
+/** Checks docker inspect output against the policy; any problem means the container must not start. */
+export function containerProblems(inspect: any, plan: SandboxPlan, started = false): string[] {
+  const problems: string[] = [], host = inspect?.HostConfig ?? {}, config = inspect?.Config ?? {};
+  const expect = (ok: boolean, problem: string) => { if (!ok) problems.push(problem); };
+  expect(host.NetworkMode === "none", `network mode ${host.NetworkMode}`);
+  expect(!Object.keys(host.PortBindings ?? {}).length && !host.PublishAllPorts && !Object.keys(config.ExposedPorts ?? {}).length, "ports are published or exposed");
+  expect(host.Privileged === false, "privileged");
+  expect(JSON.stringify(host.CapDrop) === '["ALL"]' && !(host.CapAdd ?? []).length, "capabilities are not all dropped");
+  const security: string[] = host.SecurityOpt ?? [];
+  expect(security.length > 0 && security.every(option => /^no-new-privileges(:true)?$/.test(option)), "security options differ from no-new-privileges");
+  expect(host.ReadonlyRootfs === true, "root filesystem is writable");
+  expect(["no", ""].includes(host.RestartPolicy?.Name ?? ""), "restart policy is set");
+  expect(host.LogConfig?.Type === "none", "container logging is enabled");
+  expect(!host.PidMode && ["", "private"].includes(host.IpcMode ?? "") && !host.UTSMode && !host.UsernsMode && !host.CgroupnsMode?.startsWith?.("host"), "host namespaces are shared");
+  expect(!(host.Devices ?? []).length && !(host.DeviceRequests ?? []).length && !(host.GroupAdd ?? []).length && !(host.VolumesFrom ?? []).length, "devices, groups, or volumes-from are added");
+  expect(host.Memory === memberMemory && host.PidsLimit === memberPids, "resource limits are missing");
+  expect(config.User === `${process.getuid!()}:${process.getgid!()}`, `user ${config.User}`);
+  expect(!Object.keys(config.Volumes ?? {}).length, "the image declares volumes");
+  const allowed = new Map(sandboxMounts(plan).map(mount => [mount.target, mount]));
+  const mounts: any[] = inspect?.Mounts ?? [];
+  expect(mounts.length === allowed.size, `expected ${allowed.size} mounts, found ${mounts.length}`);
+  for (const mount of mounts) {
+    const wanted = allowed.get(mount.Destination);
+    expect(mount.Type === "bind" && !!wanted && mount.Source === wanted.source && mount.RW === !wanted.readonly, `unexpected mount ${mount.Type} ${mount.Source} -> ${mount.Destination}`);
+    expect(!/docker\.sock$/.test(mount.Source ?? ""), "the Docker socket is mounted");
+  }
+  expect(JSON.stringify(Object.keys(host.Tmpfs ?? {}).sort()) === JSON.stringify(["/tmp", plan.home, plan.agentDir].sort()), "unexpected tmpfs mounts");
+  if (started) expect(inspect?.NetworkSettings && !Object.keys(inspect.NetworkSettings.Ports ?? {}).length, "ports are bound after start");
+  return problems;
+}

package/src/commands.ts

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