samagotchi 0.103.0 → 0.104.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c4a19357a9f5c94b3c76052abc018a034968ad8baf3520d50ace0ab581943b6
-  data.tar.gz: ec637848fd8dc33b292d836618753699bc8159962c6051d7b9b669beb31eb50f
+  metadata.gz: f4a794e9e201d233ca72705b62746997d6ef702804e18ad8a5bb1f85851ed454
+  data.tar.gz: 341e3b0cfcbc4367faed3782d600b2d934395eef7623499619f018b1984a06db
 SHA512:
-  metadata.gz: 5ca1a63b9c68e9b18b21fb2f2bf6503eb3cec3368e10410c4efce78dc5a853e842fc8ddd74bb5387d21f6b0d38c69f4abdb58a5320bf5c9e8272232ebf56234c
-  data.tar.gz: 7c86172b9193fc68c5c639989573c17f99af9621d118624684ace1483628a01cde8e609c2438368c297e534043fb86a165e94511e34dfd880171d77f2a75eb57
+  metadata.gz: 20bdcd9c915786fe5698401079a36e676ace823d4e42625c5b75fd2472d9990b342f1cc9c23e2a609bffee3b57df88c4fb9b6c927cdf0e182c1f7966fc5fde37
+  data.tar.gz: 64d05e8f627bb8c628e3510681b7acf1de4c37995175333614094d00333f66b1de28d91a6b2819f005e4d1e5150c8ffd189f6c9e2379044b89268188086231e6

data/CHANGELOG.md

@@ -8,6 +8,58 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.104.0] - 2026-10-23
+
+### Added
+
+- Remote attach: `chi --remote NAME --attach ID` (and `--resume ID`, `-p TEXT`, or `--dir DIR` for a new session
+  there, that machine's absolute path) runs the attached TUI on another machine's session, through its chi web:
+  the same lines and exit codes, every printed command spelled with `--remote NAME`, `@path` images from this
+  machine, a "(reconnecting…)" / "(reconnected)" line for about a minute of reconnects, and the version line naming
+  both machines. `--non-interactive`, `--verbose`, `--no-shared`, `--memory`, `--mute` and
+  `--append-system-prompt` stay this machine's (exit 2). `--dir` without `--remote` exits 2. `/exit`,
+  `/exit --delete`, `/archive`, `/stats` and `/recap` work through a remote as here, the status row counts the
+  session's delegates there, and a join shows the steps' durations and a failed turn's line from that machine's
+  saved records. See [docs/cli.md](docs/cli.md#remote-sessions).
+- Participants (experimental: identity only, the review itself comes in a later release): `chi share ID --name NAME
+  [--agent] [--expires 3d]` invites someone, or an agent, to review a session through chi web on the LAN with a link
+  of their own, printed once with a QR code (chi keeps only a digest of its token). `chi share ls [ID]` lists
+  participants and `chi share revoke ID [P] | --all` ends links; all three work through `--remote`. A link works for 7
+  days (1 hour to 30 days), until it is revoked, or until the session is archived or deleted. For now it opens a page
+  with the session's title and status; every other route answers it 403, and another session 404. chi web refuses to
+  start when another user can read its grants store. Through `--remote`, a revoked, expired or participant's token
+  gets its own message instead of "the token was refused". See [docs/cli.md](docs/cli.md#participants).
+- The bundle test kit (experimental) waits with `wait_for(what) { … }`, which raises
+  `Samagotchi::Testing::Waiting::TimedOut` naming what it waited for (and, with `seen:`, what it last saw), plus
+  `join!` and `pop!` with the same message. Every helper deadline is multiplied by `SPEC_TIME_SCALE` (default 1).
+  See [docs/plugins.md](docs/plugins.md#testing-a-bundle-experimental).
+
+### Changed
+
+- The bundle test kit's `wait_until!` is renamed `wait_for`, with no alias: a bundle spec that calls
+  `wait_until!` changes the name (same arguments).
+
+### Fixed
+
+- `chi --attach ID` (and `--resume ID`, and `chi --remote NAME --attach ID`) right after `/exit`, while the leaving
+  worker still writes its recap, waits for it with `(waiting for the session to finish its recap…)` (up to
+  `recap.timeout` plus 5 s) and then attaches, instead of failing "did not start its Bridge in time". A Ctrl-C while
+  an attach connects exits 130 without a backtrace.
+- `/queue TEXT` (or `/cut TEXT`) with no turn running says `(nothing is running: sent now)` in the REPL and the
+  attached terminal, instead of sending without a word.
+- The ctx % no longer dips at the start of each turn on a chat host (`api: openai` / `anthropic`): the turn's first
+  estimate, made before the host counts anything, left out the tool schemas; it now uses the last count's chars per
+  token.
+- Attached terminal: a command typed right after the text `/unqueue` put back in the input (`/unqueue` again,
+  `/queue TEXT`) runs as the command, with the text kept in the input, instead of going out joined to the text as
+  one prompt.
+- `chi --remote NAME sessions stop` waits up to 10 s there for the worker to let go, as `chi sessions stop` does
+  here (chi web waited 2 s, so a slow worker read "still shutting down" more often); the page's Stop still waits 2 s.
+- The terminal's status line, cut to the terminal's width, ends at a word with `…` instead of mid-word (in a pipe
+  too).
+
+Update with `chi update`.
+
 ## [0.103.0] - 2026-10-23
 
 ### Added
@@ -3892,7 +3944,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.103.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.104.0...HEAD
+[0.104.0]: https://github.com/dm1try/samagotchi/compare/v0.103.0...v0.104.0
 [0.103.0]: https://github.com/dm1try/samagotchi/compare/v0.102.0...v0.103.0
 [0.102.0]: https://github.com/dm1try/samagotchi/compare/v0.101.0...v0.102.0
 [0.101.0]: https://github.com/dm1try/samagotchi/compare/v0.100.1...v0.101.0

data/bin/chi

@@ -52,6 +52,8 @@ SUBCOMMANDS = {
   "send" => ["samagotchi/send_command", "SendCommand"],
   # answer the question a session waits on, then wait (--question, --option)
   "answer" => ["samagotchi/answer_command", "AnswerCommand"],
+  # invite participants to review a session, list them, revoke them
+  "share" => ["samagotchi/share_command", "ShareCommand"],
   # find a model server and write config.yml (--model, --name)
   "bootstrap" => ["samagotchi/bootstrap_command", "BootstrapCommand"],
   # bring an installed chi up to date
@@ -69,7 +71,10 @@ SUBCOMMANDS = {
 }.freeze
 # chi --remote NAME <command> (or CHI_REMOTE=NAME): the session commands
 # against another machine's chi web; what runs here only is refused (exit 2).
-# chi remote, --version and --help run here as always.
+# chi remote, --version and --help run here as always. Run flags under a
+# remote (--attach, --resume, -p, --dir: a session there in this terminal)
+# are parsed below and go to RemoteAttachCommand before this machine's
+# checks; the local-only ones are refused here.
 require "samagotchi/session_access/dispatch"
 begin
   remote_run = Samagotchi::SessionAccess::Dispatch.from(ARGV)
@@ -78,7 +83,12 @@ rescue Samagotchi::SessionAccess::Dispatch::Usage => e
   exit 2
 end
 ARGV.replace(remote_run.argv)
-exit remote_run.run(SUBCOMMANDS) if remote_run.remote? && !remote_run.here?
+remote_attach = remote_run.remote? && !remote_run.here? && remote_run.run_flags?
+if remote_attach && (refusal = remote_run.refusal)
+  warn "Error: #{refusal}"
+  exit 2
+end
+exit remote_run.run(SUBCOMMANDS) if remote_run.remote? && !remote_run.here? && !remote_attach
 
 if (path, klass = SUBCOMMANDS[ARGV[0]])
   require path
@@ -152,6 +162,29 @@ Samagotchi::Config.reload!(cli_overrides: cli_overrides) unless cli_overrides.em
 require "samagotchi/log"
 Samagotchi::Log.configure(level: options[:verbose] ? :debug : nil, mirror: options[:verbose])
 
+# chi --remote NAME --attach ID (--resume ID, --dir DIR, -p TEXT): the
+# attached TUI on that machine's session. Nothing below runs: it checks
+# this machine's sessions, memories and files.
+if remote_attach
+  unless ARGV.empty?
+    warn "Error: unknown command #{ARGV.first} (see chi --help)"
+    exit 1
+  end
+  require "samagotchi/remote_attach_command"
+  begin
+    entry = Samagotchi::Remotes.find(Samagotchi::Remotes.check_name!(remote_run.remote))
+  rescue Samagotchi::Remotes::Invalid => e
+    warn "Error: #{e.message}"
+    exit 2
+  end
+  exit Samagotchi::RemoteAttachCommand.new(options, access: Samagotchi::SessionAccess::Remote.new(entry)).run
+end
+# --dir names a folder on a remote; here the session starts in this one.
+if options[:dir]
+  warn "Error: --dir goes with --remote; cd there instead"
+  exit 2
+end
+
 # `chi web`: its flags (--port, --open, --web-view…) went through the parser above.
 options[:web] = true if web
 
@@ -340,6 +373,10 @@ if launch == :attached
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
     exit 1
+  rescue Interrupt
+    # Ctrl-C while it connects (a wait for a leaving worker, a late Bridge):
+    # no backtrace.
+    exit Samagotchi::CLI::Exit::INTERRUPTED
   end
   exit Samagotchi::TerminalUI::AttachLauncher.exit_status(ended)
 end

data/docs/architecture.md

@@ -469,7 +469,8 @@ Every route goes through `Bridge#dispatch`: an id other than the bridge's own se
 The per-session port is OS-assigned (bound to `0`) and published to a `bridge.json` sidecar
 for client discovery. `chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
 (503 `not_live` when the worker is not running; full history of any session is served by
-`GET /api/sessions/:id/output`). Resume/ring-buffer state is **in-memory**, per worker: a cursor from
+`GET /api/sessions/:id/output`), as a byte pipe for the owner: `App#proxy_stream_body` gives `ProxyStreamBody` the
+request principal's frame filter (`App#stream_filter`, nil for the owner, the only principal today). Resume/ring-buffer state is **in-memory**, per worker: a cursor from
 an earlier worker gets the `reset` snapshot, not a replay.
 
 **Session hub.** The cross-session layer (which sessions exist, who owns them, what changed)
@@ -510,35 +511,46 @@ chi web (the remote-sessions plan; `SessionAccess::Contract` says which commands
 cover most of it; `Web::SessionAccessRoutes` (`web/session_access_routes.rb`, in `App`'s `ROUTES`) adds the rest, each
 calling the `SessionAccess::Local` operation of the same name, so a remote backend maps 1:1 onto them. Every one is
 token-gated like the rest (LAN mode: `Authorization: Bearer`), and one that takes an id is a `:session` route (an id
-that isn't one, or no such session: 404 `not_found`). How a request flows end to end, which checks run where and the trust
+that isn't one, or no such session: 404 `not_found`). Every `ROUTES` row also names who may use it, checked against
+the request's `Web::Principal` (`App#principal_for`): `owner`, or `participant` for a route a participant may use too.
+A participant (a `Web::Grants` token for one session) may use three: `GET /`, `GET /api/info` and `GET /api/sessions/:id`,
+each answered as theirs; every other route is `owner` (Permission below, and the participants routes in
+[internals/participants.md](internals/participants.md)); `spec/web/principal_spec.rb` fails on a row without one. How a request flows end to end, which checks run where and the trust
 model: [internals/remote-sessions.md](internals/remote-sessions.md).
 
-| Route | Body / params | Answer | Refusals |
-|---|---|---|---|
-| `GET /api/sessions/resolve?id=` | an id or a unique prefix | 200 `{id}` | 404 `not_found`; 400 `ambiguous_id` with `ids` |
-| `GET /api/sessions/summaries` | `dir` (a folder: its project; none: every project), `cwd`, `live=1`, `archived=1`, `tests=0`, `sort`, `order`, `limit` | 200: the rows `chi sessions list` prints (`SessionManager.session_summaries`: `status`, `live`, `busy`, `owner`, `recap`, `ctx_pct`, `waiting`, `waiting_id`, `title`, `preview`, …) | 400 `invalid_dir`, `invalid_cwd` |
-| `POST /api/sessions` (more fields) | `toolkit`, `tools`, `no_tools`, `parent_answers`; `client_id` (`cli:send`/`cli:answer`: the first line is checked as chi send checks it); `check_vision: true` (images follow) | 201 adds `model_warning` and `parent_answers_warning` (a level looser than config.yml's, capped) | 400 `invalid_toolkit`, `invalid_parent_answers`, `invalid_continues` (beside `continues`); 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
-| `POST /api/sessions/:id/turn` (more fields) | `client_id` as above; `check_vision: true` with `images` | as before | 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
-| `POST /api/sessions/:id/wait/prepare` | `question_id` (absent: the pending one; `null`: none), `turn`, `created`, `busy` (+ `queue`) | 200 `{session_id, cursor, baseline: {messages, question_id, last_turn}, own_turn, known_turn, running, live, settled, last_turn_id}` (`WaitStart`) | 409 `busy`, `waiting` (`SendCommand::Busy`'s words, and its fields: `question`, `parent_strategy`) |
-| `POST /api/sessions/:id/wait` | `cursor`, `baseline`, `turn`, `queued`, `ended_before`, `owner_grace`, `timeout` (capped at 30 s) | 200: `ReplyWait::Result`'s fields (`status`: `done`, `waiting_for_answer`, `no_reply`, `error`, `stopped`, `worker_gone`, or `timeout`: ask again; `text`, `file`, `question` as `PendingQuestion#to_file`, `outcome`, `limit`, `error_kind`, `retryable`, `cancel_reason`, `stopped_by`, `kept_steps`, `turn_id`, `origin`; never the session) and `parent_strategy` `{name, allowed, origin}` (`ParentReport.strategy_for`, this server's config.yml) | 400 `invalid_wait`; 503 `server_stopping` |
-| `POST /api/sessions/:id/notes` | `text`, `source` (default `cli`, never `broadcast`) | 200 `{status: queued \| waits, session_id, queued}` (`NoteDelivery`) | 409 `owned_by_tui` (`status: refused`); 400 `note_rejected`, `missing_fields`, `invalid_source` |
-| `POST /api/sessions/:id/context` (more bodies) | `{name, push: true, why, hint}` or `{name, cmd, every, why, hint}` beside the page's `{url, why, hint}`; `added_by` `cli`/`agent` (else `web`) | 201 `{status: attached, name}` | 400 `invalid_source`; 409 `exists` |
-| `POST /api/sessions/:id/context/:name/push` | `text`, `summary`, `wake`, `hint` (a source's JSON output, checked the same way) | 200 `{status: pushed, name, before, revision, changed}` | 404 `not_found`; 409 `not_push`; 400 `invalid_text` |
-| `DELETE /api/sessions/:id/context/:name?own=1` | | 200 `{status: detached}`: the session's own only | 409 `project_source` (chi context rm's words); 404 |
-| `POST /api/sessions/:id/stop` | | 200 `{status: stopped, session_id, released}`: `released`, whether the worker let go within `STOP_WAIT_SECONDS` (2 s) | 409 `owned_by_tui` |
-| `DELETE /api/sessions/:id?force=` | `force=true` stops a live worker first (the page sends it) | as before | 409 `worker_running` without it |
-| `GET /api/sessions/:id?brief=1` | | 200 `{brief, session: {id, status (the file's), title, display_title, project_root, working_directory, model_name, model_typed, parent_answers, owner}, pending_question}` (the file's; no messages): `Remote#show` | 404 |
-| `POST /api/sessions/:id/turn` (its 202) | | the ack with `via`: `bridge` or `file` (the input file: a remote `chi send --wait` follows that turn) | |
-| `GET /api/sessions/:id/context?full=1`, `…/context/:name?full=1` | | each row with `source` (`Source#to_h`, its command too; the page's rows never carry one), `snapshot` (`Snapshot#to_h`, no text) and `shadowed`, shadowed project sources included | |
-| `POST /api/sessions/:id/wake` | `wait` (seconds, default and most 10: `WAKE_MAX_WAIT`) | 200 `{session_id, woke, worker: {epoch, started_at, version, features}, model_name, default_model, parent_strategy, installed}`: the live worker as is (`woke: false`), else resumed and its Bridge waited for (`Local#wake`); `default_model` and `installed` are this machine's | 409 `owned_by_tui`, `scratch` (`LaunchMode::SCRATCH_LEFTOVER`); 504 `worker_timeout` (`LaunchMode::BRIDGE_LATE`); 400 `invalid_wait`; 404 |
-| `GET /api/sessions/:id/worker` | | 200 `{session_id, live, stopped, owner: worker \| tui \| null, worker: {epoch, started_at, version, features} \| null, parent_strategy}` (`Local#worker`; never starts one) | 404 |
-| `POST /api/sessions/:id/turn` (`no_interrupt`) | `no_interrupt: true`: the turn runs with the raised iteration limit (`SessionManager.deliver_turn(no_interrupt:)`, to the Bridge or the input file) | as before | |
-| `POST /api/sessions/:id/command` (its 501) | | | 501 `not_supported` for a builtin the worker lacks adds `command` (`"/title"`) and `message` |
+| Route | Permission | Body / params | Answer | Refusals |
+|---|---|---|---|---|
+| `GET /api/sessions/resolve?id=` | owner | an id or a unique prefix | 200 `{id}` | 404 `not_found`; 400 `ambiguous_id` with `ids` |
+| `GET /api/sessions/summaries` | owner | `dir` (a folder: its project; none: every project), `cwd`, `live=1`, `archived=1`, `tests=0`, `sort`, `order`, `limit` | 200: the rows `chi sessions list` prints (`SessionManager.session_summaries`: `status`, `live`, `busy`, `owner`, `recap`, `ctx_pct`, `waiting`, `waiting_id`, `title`, `preview`, …) | 400 `invalid_dir`, `invalid_cwd` |
+| `POST /api/sessions` (more fields) | owner | `toolkit`, `tools`, `no_tools`, `parent_answers`; `client_id` (`cli:send`/`cli:answer`: the first line is checked as chi send checks it); `check_vision: true` (images follow) | 201 adds `model_warning` and `parent_answers_warning` (a level looser than config.yml's, capped) | 400 `invalid_toolkit`, `invalid_parent_answers`, `invalid_continues` (beside `continues`); 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
+| `POST /api/sessions/:id/turn` (more fields) | owner | `client_id` as above; `check_vision: true` with `images` | as before | 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
+| `POST /api/sessions/:id/wait/prepare` | owner | `question_id` (absent: the pending one; `null`: none), `turn`, `created`, `busy` (+ `queue`) | 200 `{session_id, cursor, baseline: {messages, question_id, last_turn}, own_turn, known_turn, running, live, settled, last_turn_id}` (`WaitStart`) | 409 `busy`, `waiting` (`SendCommand::Busy`'s words, and its fields: `question`, `parent_strategy`) |
+| `POST /api/sessions/:id/wait` | owner | `cursor`, `baseline`, `turn`, `queued`, `ended_before`, `owner_grace`, `timeout` (capped at 30 s) | 200: `ReplyWait::Result`'s fields (`status`: `done`, `waiting_for_answer`, `no_reply`, `error`, `stopped`, `worker_gone`, or `timeout`: ask again; `text`, `file`, `question` as `PendingQuestion#to_file`, `outcome`, `limit`, `error_kind`, `retryable`, `cancel_reason`, `stopped_by`, `kept_steps`, `turn_id`, `origin`; never the session) and `parent_strategy` `{name, allowed, origin}` (`ParentReport.strategy_for`, this server's config.yml) | 400 `invalid_wait`; 503 `server_stopping` |
+| `POST /api/sessions/:id/notes` | owner | `text`, `source` (default `cli`, never `broadcast`) | 200 `{status: queued \| waits, session_id, queued}` (`NoteDelivery`) | 409 `owned_by_tui` (`status: refused`); 400 `note_rejected`, `missing_fields`, `invalid_source` |
+| `POST /api/sessions/:id/context` (more bodies) | owner | `{name, push: true, why, hint}` or `{name, cmd, every, why, hint}` beside the page's `{url, why, hint}`; `added_by` `cli`/`agent` (else `web`) | 201 `{status: attached, name}` | 400 `invalid_source`; 409 `exists` |
+| `POST /api/sessions/:id/context/:name/push` | owner | `text`, `summary`, `wake`, `hint` (a source's JSON output, checked the same way) | 200 `{status: pushed, name, before, revision, changed}` | 404 `not_found`; 409 `not_push`; 400 `invalid_text` |
+| `DELETE /api/sessions/:id/context/:name?own=1` | owner | | 200 `{status: detached}`: the session's own only | 409 `project_source` (chi context rm's words); 404 |
+| `POST /api/sessions/:id/stop` | owner | `wait?` (seconds, capped at `SessionManager::STOP_WAIT`, 10: `chi --remote NAME sessions stop` sends it) | 200 `{status: stopped, session_id, released}`: `released`, whether the worker let go within the wait (without one `STOP_WAIT_SECONDS`, 2 s: the page's Stop) | 409 `owned_by_tui` |
+| `DELETE /api/sessions/:id?force=` | owner | `force=true` stops a live worker first (the page sends it) | as before | 409 `worker_running` without it |
+| `GET /api/sessions/:id?brief=1` | participant (theirs: title, status, participants) | | 200 `{brief, session: {id, status (the file's), title, display_title, project_root, working_directory, model_name, model_typed, parent_answers, owner}, pending_question}` (the file's; no messages): `Remote#show` | 404 |
+| `POST /api/sessions/:id/turn` (its 202) | owner | | the ack with `via`: `bridge` or `file` (the input file: a remote `chi send --wait` follows that turn) | |
+| `GET /api/sessions/:id/context?full=1`, `…/context/:name?full=1` | owner | | each row with `source` (`Source#to_h`, its command too; the page's rows never carry one), `snapshot` (`Snapshot#to_h`, no text) and `shadowed`, shadowed project sources included | |
+| `POST /api/sessions/:id/wake` | owner | `wait` (seconds, default and most 10: `WAKE_MAX_WAIT`) | 200 `{session_id, woke, worker: {epoch, started_at, version, features}, model_name, default_model, parent_strategy, installed}`: the live worker as is (`woke: false`), else resumed and its Bridge waited for (`Local#wake`); `default_model` and `installed` are this machine's | 409 `owned_by_tui`, `scratch` (`LaunchMode::SCRATCH_LEFTOVER`); 504 `worker_timeout` (`LaunchMode::BRIDGE_LATE`); 400 `invalid_wait`; 404 |
+| `GET /api/sessions/:id/worker` | owner | | 200 `{session_id, live, stopped, owner: worker \| tui \| null, worker: {epoch, started_at, version, features} \| null, default_model, parent_strategy}` (`Local#worker`; never starts one; `default_model` is this machine's) | 404 |
+| `POST /api/sessions/:id/exit` | owner | `client_id` (passed on only when it is an attached TUI's, `tui:…`; any other is dropped), `delete` | 200 the worker's `{status: exiting, session_id, discard}` (`BridgeClient#request_exit`; never wakes one) | 409 `held` with the worker's `{status, reason, tasks, hint}`; 503 `not_live`; 501 `not_supported`; 504 `worker_timeout` |
+| `POST /api/sessions/:id/recap` | owner | | 200 the worker's `{enabled, saved, request, min_user_turns, session_off}` (`BridgeClient#request_recap`) | 503, 501, 504 as every relay |
+| `GET /api/sessions/:id/stats` | owner | | 200 `{session_id, metrics}`: the worker's stats, its state's metrics for a worker from before the stats route | 503 `not_live`; 504 `worker_timeout`; 502 `bridge_error` |
+| `GET /api/sessions/:id/children/counts` | owner | | 200 `{running, waiting, unreported}` (`ChildrenStatus.counts`, the delegates' files here) | 404 |
+| `GET /api/sessions/:id/turns/:turn_id/records` | owner | | 200 `{tool_records: […], turn_record: {…} \| null}` (`SessionMetrics.saved_tool_records` / `saved_turn_record`, as saved) | 400 `invalid_turn_id`; 404 |
+| `POST /api/sessions/:id/turn` (`no_interrupt`) | owner | `no_interrupt: true`: the turn runs with the raised iteration limit (`SessionManager.deliver_turn(no_interrupt:)`, to the Bridge or the input file) | as before | |
+| `POST /api/sessions/:id/command` (its 501) | owner | | | 501 `not_supported` for a builtin the worker lacks adds `command` (`"/title"`) and `message` |
+| `GET`/`POST`/`DELETE /api/sessions/:id/participants`, `GET`/`DELETE /api/participants` | owner | `chi share`'s (`name`, `kind`, `ttl`; `?id=p_…`) | the grants, never a token but POST's own once ([internals/participants.md](internals/participants.md)) | 400 `invalid_participant`; 404 |
 
 `GET /api/info` names the feature `session_commands` (`SessionAccessRoutes::FEATURE`): `SessionAccess::Remote` asks it
 once before its first request, and a chi web without it (or `serve_static`'s 404 for a path no route takes) is "remote NAME runs chi X, too
 old for this command through --remote: update chi there (chi update)". The feature `remote_attach`
-(`SessionAccessRoutes::ATTACH_FEATURE`) names the wake and worker routes a remote attached TUI needs.
+(`SessionAccessRoutes::ATTACH_FEATURE`) names the routes a remote attached TUI needs: wake, worker, exit, recap, stats,
+children counts and a turn's records. Their refusals carry `{error, detail, message}`.
 
 `POST …/answer` passes on `client_id` only when it is chi answer's (`cli:answer`), so the worker holds the answer to
 its `guardrails.parent_answers`; any other is dropped, so a forwarded id can only tighten. The worker's 403

data/docs/cli.md

@@ -22,7 +22,9 @@
 - `chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one takes it at its next step; `--cut` asks it to cut long thinking for it; `--queue` runs it as a turn of its own after the running one, and `--queue --wait` waits for that turn's own answer); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead (`--new --continues ID|last:ID` the next link of that session's chain, see [Session chains](sessions.md#session-chains)), and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending — to an idle session whose last turn already ended, that ended turn's reply or end comes back; `--wait --turn T ID` with no message waits for exactly turn T, whether running, queued or last ended; `--format json` includes its `turn_id` when known, for waiting again after exit 3 or 4; exit 3 a question waits, its options on stderr; exit 4 `--timeout` passed with the turn still running; see [Starting a session](sessions.md#starting-a-session))
 - `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). What a parent may pick follows `guardrails.parent_answers`, or the session's own `parent_answers` when stricter (`soft`, the default: a deny, a plain answer, Continue and "Allow once"; `standard`: no allow; `hard`: no Continue either), never a wider scope or an allow on chi's own config; a refused pick exits 1 with what to answer instead (a convention, not a security boundary; see [Guardrails](guardrails.md#answers-from-a-parent-agent))
 - `chi remote add NAME URL [--token-file F | --token-stdin]`, `chi remote ls`, `chi remote rm NAME` — the other machines whose chi web the session commands reach with `--remote NAME` (see [Remote sessions](#remote-sessions))
-- `chi --remote NAME send|answer|note|context|sessions …` (or `CHI_REMOTE=NAME`) — those commands on that machine's sessions, through its chi web (see [Remote sessions](#remote-sessions))
+- `chi share ID --name NAME [--agent] [--expires 3d]`, `chi share ls [ID]`, `chi share revoke ID [P] | --all` — invite a participant to review a session through chi web on the LAN (a link of their own, 7 days), list them, revoke them (see [Participants](#participants))
+- `chi --remote NAME send|answer|note|context|sessions|share …` (or `CHI_REMOTE=NAME`) — those commands on that machine's sessions, through its chi web (see [Remote sessions](#remote-sessions))
+- `chi --remote NAME --attach ID` (`--resume ID`, `--dir DIR [-p TEXT]`) — the attached TUI on a session of that machine (see [Remote sessions](#remote-sessions))
 - `chi memory ls [--scope project|system] [--format text|json]` — the memories of both scopes (this folder's project first), one row each: scope, name, size, date, `from <bundle>`, the index description and its model overlays; `chi memory rm NAME [--scope project|system]` removes one as `memory_write` with `remove: true` does: its file and model overlays go to the bundle trash (the line names the dir; `chi bundle trash` lists and empties it) and its index line is dropped. NAME in both scopes without `--scope` exits 2 naming both; a missing NAME or a bundle's memory (`chi bundle uninstall` removes it) exits 1 (see [Memory: Listing and removing from the shell](memory.md#listing-and-removing-from-the-shell))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
@@ -280,7 +282,8 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--shared` | Run the session (new, or `--resume`'s) in a background worker and attach to it: the default, and the way to get it when `session.shared` is off. See [Sharing a session](#sharing-a-session). |
 | `--no-shared` | Run the plain in-process REPL for this run. |
 | `--attach SESSION_ID` | Attach to a session's worker, waking one if it has exited. |
-| `--remote NAME` | Before a session command (`chi --remote studio send …`): run it against that remote's sessions, through its chi web; beats `CHI_REMOTE`. Commands and flags that run on this machine only exit 2. See [Remote sessions](#remote-sessions). |
+| `--remote NAME` | Before a session command (`chi --remote studio send …`) or the run flags (`chi --remote studio --attach ID`, `--resume ID`, `--dir DIR -p TEXT`): run it against that remote's sessions, through its chi web; beats `CHI_REMOTE`. Commands and flags that run on this machine only exit 2. See [Remote sessions](#remote-sessions). |
+| `--dir DIR` | With `--remote`: a new session's folder on that machine, its absolute path (required for a new session there). Without `--remote` it exits 2: cd there instead. |
 | `--model NAME` | Use this model for the run (overrides the configured default and a resumed session's model). |
 | `--thinking LEVEL` | This session's own thinking level: `off`, `low`, `medium` or `high`, saved in the session and first in the order (`default` unsets it). On `--resume` or `--attach` it is set at once, through a `/thinking` on an attached worker. With `chi web` it is instead the default for the sessions its workers run, below a session's own (as env `SAMAGOTCHI_THINKING_LEVEL` is). See "Thinking" in configuration.md. |
 | `--toolkit NAME`, `--tool NAME`, `--no-tool NAME` | A new session's toolkit, the tools its prompts declare: `full` (every built-in), `lean`, `child`, one of config's `toolkit.kits` or a bundle's (without `--toolkit`: config's `toolkit.default`), with tools declared on top of it (`--tool`) or left out (`--no-tool`); both repeatable, a comma list too. Saved in the session as given; a respawned worker, a fork and a continue keep it. Ignored with `--attach`/`--resume` (one line, as `--memory`); `/toolkit` changes it. Not on `chi web` (config's `toolkit.default` covers its sessions). See [Toolkits](configuration.md#toolkits). |
@@ -750,12 +753,14 @@ REPL alike:
   with images works the same way: it waits for the turn's end, and the lines
   sent after it still go in at the next step.
   At the open prompt (no turn running) `/cut TEXT` and `/queue TEXT` run TEXT
-  as a normal prompt.
+  as a normal prompt, and the terminals say so: `(nothing is running: sent now)`.
 - `/unqueue` (attached terminal) takes back the newest line this terminal
   queued that hasn't started: `removed: <its first 60 characters>`, and its text
   goes back into the input to change and send again (not over typed text: then
   it is in the input history, ↑; not with input from a pipe; its images don't
-  come back), then the one before it on the next `/unqueue`; `(nothing queued: …)` when none waits,
+  come back), then the one before it on the next `/unqueue`. A command typed
+  after that text without clearing it (`fix it/unqueue`, `fix it/queue more`)
+  runs as the command, and the text stays in the input. `(nothing queued: …)` when none waits,
   `(not removed: it already started)` when its turn won the race, `(not removed:
   it is already gone)` when another client removed it. Other terminals that
   showed it say `(a queued message was removed)`; the web drops its bubble. A
@@ -1189,10 +1194,9 @@ CHI_REMOTE=studio chi context push claude-outbox ab12 < answer.json
   list|stop|restart|archive|unarchive|delete`. The rest runs on this machine
   only and exits 2 with `chi <command> runs on this machine only: run it on
   <remote>`: `context refresh|mute|unmute` and `--project`, `sessions
-  stats|prune|clean`, `broadcast`, the machine's own commands (`bundle`,
-  `memory`, `update`, …) and a session in this terminal (`--attach`, `-p`,
-  `--resume`: remote attach comes later). `chi remote`, `--version` and
-  `--help` always run here.
+  stats|prune|clean`, `broadcast` and the machine's own commands (`bundle`,
+  `memory`, `update`, …). `chi remote`, `--version` and `--help` always run
+  here.
 - `send --new` needs `--dir`, that machine's absolute path (no folder of this
   one is guessed); `--toolkit`, `--set` and `--parent-answers` are checked
   against that machine's config and bundles. `sessions list` lists every
@@ -1208,18 +1212,88 @@ CHI_REMOTE=studio chi context push claude-outbox ab12 < answer.json
   `--timeout`; exit codes are the same. The commands chi prints for what to
   do next work as pasted: they carry `--remote NAME` (`chi --remote studio
   answer ab12 --question q1 --option N`, `chi --remote studio send --wait …`),
-  under `CHI_REMOTE` too. What runs on this machine only isn't offered:
-  where chi says `chi --attach ID` here it names that machine's chi web
-  (`chi web on studio shows it`), and `sessions stop` names no `chi
-  --resume`.
+  under `CHI_REMOTE` too, an attach as well (`chi --remote studio --attach
+  ab12 shows it`, `sessions stop`'s `chi --remote studio --resume ab12`).
 - A remote that can't be reached names itself and why (`chi send: remote
   studio (http://192.168.1.29:4567): connection refused`, exit 1; with
   `--format json` an `error` object).
 - Plain http, the same as the phone's: use it on your home network.
 
+A session there in this terminal (the attached TUI, through that machine's
+chi web; its worker stays there):
+
+```sh
+chi --remote studio --attach ab12                      # attach (wakes its worker if it exited)
+chi --remote studio --resume ab12 -p "go on"           # resume there, run one turn, stay attached
+chi --remote studio --dir /Users/me/app -p "hi"        # a new session there (--dir required), one turn, stay
+```
+
+- The same TUI and exit codes (0 detached, 3 a question left waiting with
+  input from a pipe, 1 otherwise), every printed command with `--remote
+  studio`. Prompts, session commands, `/model`, `!cmd` (a shell command **on
+  that machine**, under its guardrails), `/queue`, `/cut`, `/unqueue`,
+  `/detach`, `/exit`, `/exit --delete`, `/archive`, `/stats` and `/recap` work
+  as here, on that machine's session (`/exit --delete` deletes it there).
+  The status row's children segment counts its delegates there, and a join
+  shows the steps' durations and a failed turn's line from its saved records
+  there. A chi web too old for one of them says so in one line ("remote
+  studio runs chi X, too old for this command through --remote: update chi
+  there").
+- A new session needs `--dir`, that machine's absolute path; `--model`,
+  `--thinking`, `--llm-context*`, `--toolkit`, `--tool`, `--no-tool`, `--set`
+  and `--parent-answers` are checked there (exit 2 for a bad one). With
+  `--attach`/`--resume` they work as here (`--model`, `--thinking`,
+  `--llm-context*` change the session; the others are named as ignored).
+  `--non-interactive` (use `chi --remote studio send --new --dir D -m TEXT
+  --wait`), `--verbose`, `--no-shared`, `--memory`, `--mute` and
+  `--append-system-prompt` run on this machine only (exit 2).
+- `@path` images are this machine's files (read and downscaled here, then
+  uploaded); Tab completes `/` commands and `@path`, not memory names. The
+  prompt history (↑) and `no_interrupt` / `no_default_input` are this
+  terminal's.
+- When chi web can't be reached the TUI says "(lost the connection to
+  studio; reconnecting…)" and tries for about a minute, then "(reconnected)";
+  what it missed is replayed or resynced. A prompt typed meanwhile is usually
+  accepted there and runs when a worker reads it. A worker that went away
+  (not stopped) is woken again. The end is worded by why: "The session was
+  stopped on studio. Resume it with: chi --remote studio --resume ab12", the
+  token refused, chi web unreachable, the worker gone, the session deleted.
+- The version line names both machines: the worker older than what studio
+  has installed (`chi --remote studio sessions restart ab12`), this terminal
+  older than studio (`chi update` here).
+
 How it works inside (`SessionAccess`, chi web's routes, where each check runs):
 [internals/remote-sessions.md](internals/remote-sessions.md).
 
+### Participants
+
+A session's owner can invite **participants**, people or agents, to review it through chi web on the LAN
+(`web.host: lan`), each with a link of their own that reaches that one session:
+
+```sh
+chi share 3f9a1c2e --name Alex
+# p_7c01d2aa  Alex (human, reviewer) · session 3f9a1c2e · expires 2026-10-30 14:02
+# http://192.168.1.29:4567/?token=chp_…#s=3f9a1c2e-…
+# (shown once: chi keeps only its digest; chi share revoke 3f9a1c2e p_7c01d2aa ends it)
+chi share ls                    # every session's participants (--format json; never a token)
+chi share revoke 3f9a1c2e       # every link to that session; add a participant id for one
+chi share revoke --all          # every link to every session
+```
+
+- The link is printed once (with a QR code at a terminal): chi keeps only a digest of its token. Send it to the
+  participant; opening it sets their browser's cookie, as the owner's LAN link does. `--agent` marks an agent
+  participant, which uses the token as `Authorization: Bearer` (e.g. `chi --remote` with that token).
+- It works for 7 days (`--expires Nh` or `Nd`, 1 hour to 30 days), until it is revoked, or until the session is
+  archived or deleted. A revoked or expired link shows "This review link has expired or was revoked."
+- For now a participant sees a page with the session's title and status; comments and the review itself come in
+  a later chi. They can't reach anything else: every other route answers them 403, another session 404.
+- `chi --remote studio share …` invites on studio: the link names studio's LAN address. Locally, the link names
+  this machine's chi web; without one on the LAN, chi says the link opens on this machine only.
+- The owner's own token and the `chi web --new-token` rotation are separate: rotating it ends no participant's link.
+
+How it works inside (grants, the gate, the routes, the audit trail):
+[internals/participants.md](internals/participants.md).
+
 ## Runtime Model Switch (Assist Mode)
 
 In interactive assist mode, you can switch the request model without restarting:

data/docs/guardrails.md

@@ -595,7 +595,8 @@ only by the user: these change a model's system prompt for later sessions (see
 [Model notes](memory.md#model-notes); a shell command reaches them only under
 `shell-touches-chi`'s text heuristic); and answering chi's
 questions around `chi answer`: `chi --attach` or `chi -p` with stdin from a
-pipe, a here-string or a file, not `/dev/null` (`chi-answer-piped`), and `curl`/`wget` to a
+pipe, a here-string or a file, not `/dev/null` (`chi-answer-piped`, which also sees
+`chi --remote NAME --attach|--resume|-p` and `CHI_REMOTE=NAME chi …`), and `curl`/`wget` to a
 session's `/answer` route (`chi-answer-http`), both once or for the session, and only by the
 user (a parent agent allowing one would answer as the user).
 `chi answer` itself isn't asked about. It denies writes into `.git/hooks`.

data/docs/internals/context-telemetry.md

@@ -12,8 +12,12 @@ resumed session's line already names):
 
 Both loops do this, before each request (`ContextStatus`, one per turn). The
 chat loop's estimate counts the conversation's text and tool calls, not the
-tool schemas it sends, until the host's first count (its `usage`). The event
-carries a `status` string using this prefix:
+tool schemas it sends, until the host's first count (its `usage`). So that a
+turn's first request doesn't dip below the last turn's count (the schemas are
+thousands of tokens), the loop keeps the last counted request's chars per token
+(`ContextStatus#counted_chars_per_token`, on `KernelLoop` / `ChatLoop`) and the
+next turn's estimate before its first count uses it instead of
+`context.chars_per_token`. The event carries a `status` string using this prefix:
 
 `CONTEXT_STATUS ...`
 

data/docs/internals/engine.md

@@ -518,7 +518,10 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:answer_display` | after the after_turn hooks (observers only, not the sink) | `{display, refs?}` (display a string, or nil; refs the count of the answer's refs, only when a hook attached some) |
 
 The boundary events (`:turn_started`, `:turn_completed`, `:turn_canceled`, `:turn_failed`) also carry `origin`
-when the turn was queued with one.
+when the turn was queued with one: `{client_id:, enqueued_id:}`, plus `author:` when someone other than the session's
+owner wrote it (its input file's `author`, stamped by chi web from the request's `Web::Principal`). An owner's turn
+has no `author` anywhere: not in its input file, its origin or the session. `GuardrailWiring#begin_turn` gets the
+origin, and `#turn_author` reads its author for the gate's checks.
 
 ### Hook points (not events)
 

data/docs/internals/participants.md

@@ -0,0 +1,137 @@
+# Participants: identity and routes
+
+A session's owner can invite **participants** to review it: people, or agents, who reach that one session through
+chi web with a link of their own. This page is the identity layer (the shared-sessions plan's P2): grants, the gate,
+the routes a participant reaches, and what is written where. A participant can't send a turn yet (P3), and their page
+shows only the session's title and status until the full participant UI lands (P4). The code and docs say
+"participants" and "review", never "shared": `session.shared` already means "attached by default".
+
+Until `web.public_url` lands, participants are a **LAN** feature (`web.host: lan`): a loopback peer is always the
+owner, and a reverse proxy on the same machine would make every visitor loopback.
+
+## Grants
+
+A grant (`Web::Grants`, `lib/samagotchi/web/grants.rb`) binds **one random token** to **one session**, **one
+participant** and **one role**, until it expires or is revoked.
+
+- **Token.** `chp_` + 43 URL-safe characters (32 random bytes, as the owner's `Web::Token`). The prefix lets the gate
+  look up only participant tokens, and a leaked one is recognisable. It is shown **once**, in the link chi share or
+  `POST …/participants` prints; chi keeps only its **SHA-256 digest**. Lookup digests the presented token and
+  compares it with every grant's digest (`Rack::Utils.secure_compare`).
+- **Participant.** The grant's `id`, `p_<8 hex>`, names the participant: a turn they send will be authored
+  `"p:<id>"` (`Grant#author`, `Principal#author`; P3). `kind` is `human` or `agent` (D11: an agent uses the same
+  token, as a Bearer header; there is no agent UI). `role` is `reviewer`, the only one in v1. `name` is cleaned to
+  one line of at most 64 characters with no brackets (`Grants.clean_name`), so it can't forge P3's
+  `[Review contribution from …]` header.
+- **Lifetime (D8).** 7 days by default (`chi share --expires Nh|Nd`, 1 hour to 30 days). Revoked by the owner
+  (`chi share revoke`, `DELETE …/participants`), and by an **archive** (the session and its delegates) or a
+  **delete** (`SessionManager.archive_session` / `delete_session` → `Participants.end_sessions`). A session pruned by
+  retention, or archived or deleted by a process that didn't revoke, is caught by the gate: a live grant whose session
+  file is gone or archived is revoked on sight (`revoked_by: gone | archive`). Unarchiving doesn't restore a grant.
+  An ended grant stays in the store for 30 days, so its token answers `token_revoked` / `token_expired` rather than a
+  bare 401; then it goes.
+- **Store.** `$XDG_STATE_HOME/samagotchi/web-grants/grants.json`, next to `web-token`: the file 0600, in its own 0700
+  folder, written whole (`AtomicFile`) under a lock file (`grants.lock`) since chi web and a local `chi share` both
+  write it. Readers follow its mtime (a `chi share revoke` in another process takes effect at chi web's next request).
+  `last_used_at` is written at most once a minute per grant. **chi web refuses to start** when that folder or file can
+  be read by another user, or isn't this user's (`Grants.check_permissions!`, one message naming the `chmod`). Only
+  those two are checked: the state dir above is often 0755, and that's fine. Never point `XDG_STATE_HOME` at a
+  shared folder.
+- Rotating the owner token (`chi web --new-token`) never touches grants; `chi share revoke --all` ends them all.
+
+## The gate
+
+`App#principal_for` resolves every request to a `Web::Principal`:
+
+1. A loopback peer, or a chi web not on the LAN: the **owner** (unchanged).
+2. The owner's token (Bearer, then the cookie; `?token=` on the page's trade): the **owner**. Checked first, so the
+   owner's requests never touch the grants store (measured: no change to an owner route's time).
+3. A `chp_` token whose grant is active: a **participant** (`Principal.new(kind: :participant, grant:)`).
+4. Anything else: nil. `#token_gate` answers an ended grant's token **401 `token_revoked`** or **401
+   `token_expired`** (the page: "This review link has expired or was revoked. Ask the session's owner for a new
+   one."), any other **401 `unauthorized`** as before.
+
+The `?token=` trade sets the `chi_token` cookie to the token that was presented, the owner's or the participant's
+(one at a time per browser: a participant link opened in the owner's browser replaces the owner's cookie there).
+
+Then `#route`, for each matching `ROUTES` row:
+
+1. A participant on a `/api/sessions/:id…` route whose id isn't their grant's session gets **404 `not_found`**, the
+   same answer as a session that doesn't exist, before the permission check: they can't learn which sessions exist.
+2. A route whose permission the principal lacks (`Principal#permits?`) gets **403 `not_permitted`**, worded for the
+   role: "a participant can't do that: only the session's owner can".
+
+`spec/web/participant_gate_spec.rb` walks `ROUTES`: every `:owner` row answers a participant 403, and every session
+row answers another session's id 404, so a new route is covered without a new example.
+
+## What a participant reaches (P2)
+
+| Route | Permission | A participant gets |
+|---|---|---|
+| `GET /` | participant | the participant page (server-rendered, no script): "Alex's review", the session's title and status, "Comments open soon", the participants' names. Never the owner's page, where every route would refuse them. |
+| `GET /api/info` | participant | `{app, version, features}` (what `SessionAccess::Remote`'s check needs); not `pid`, `cwd`, `lan`, `installed` |
+| `GET /api/sessions/:id` | participant | their session only, whatever the query (`brief`, `cards`, `tail`, `timing`): `{session: {id, title, status, participants: [{id, name, kind, role}]}}` (the active ones). `title` is the session's own title, or "an untitled session": never `display_title`'s fallback, the first prompt's opening words |
+
+Everything else is `:owner`, `POST …/turn` included (P3 opens it). Static assets (`/app.js`, …) are served to any
+principal past the gate: they are the public frontend.
+
+**Streams.** No stream route is a participant's yet (`App#stream_filter` raises for one, until P4's filter). The
+seam for ending them is in place: `App#stream_running(principal)` is the proxy's running check (asked every
+`BridgeClient::STREAM_POLL`), and for a participant it is false once the grant is revoked or expired, so P4's
+participant streams close within a poll of a revoke, including one made by `chi share revoke` in another process.
+
+## The owner's routes
+
+| Route | Body / params | Answer | Refusals |
+|---|---|---|---|
+| `GET /api/sessions/:id/participants` | | 200 `{participants: [grant]}`, every state | |
+| `GET /api/participants` | | 200 `{participants: [grant]}`, every session's | |
+| `POST /api/sessions/:id/participants` | `name`, `kind` (`human`/`agent`), `ttl` (seconds) | 201 `{participant: grant, token, link, lan}`: the token and the link once; `link` names this chi web's LAN address (`http://IP:PORT/?token=…#s=<id>`), `lan` false when it has none | 400 `invalid_participant` (name, kind, ttl, an archived session); 404 |
+| `DELETE /api/sessions/:id/participants[?id=p_…]` | | 200 `{revoked: [grant]}`: one participant, or the session's | 400 `invalid_participant` |
+| `DELETE /api/participants` | | 200 `{revoked: [grant]}`: every session's | |
+
+A grant here is `Grant#public_h`: `id, session_id, kind, name, role, created_at, expires_at, revoked_at, revoked_by,
+last_used_at, state` (`active | revoked | expired`). Never the token or its digest.
+
+`chi share` (docs/cli.md) uses them through `--remote`, and `SessionAccess::Local`'s same-named operations here
+(`participants`, `invite`, `revoke_participants`; `ParticipantView`, `Invitation`). A local invite's link names
+the local chi web's LAN address when one runs (its `GET /api/info`), else `127.0.0.1` with a line saying it opens on
+this machine only.
+
+## Files in the session dir
+
+Neither is in the session JSON (chi web never saves that, and a worker would overwrite a field it added), and
+neither is copied to a continue, a fork or a delegate (a continue starts with no participants). A session nobody was
+invited to has neither: its files stay byte for byte as they were.
+
+- **`participants.json`** (0600, `Participants.write`): `{participants: [{id, kind, name, role, added_at,
+  expires_at, removed_at}]}`, rewritten by whoever changes a grant (chi web, `chi share`). Never a token or a digest.
+  The worker reads it with `Participants.read` (P3a's system-prompt line, `ctx`).
+- **`participants.jsonl`** (0600, append-only, `Participants.log`): one JSON line per event, with `at`: `issued`
+  (participant, name, kind, role, expires_at), `revoked` (participant, by), `expired` (the first refused use after the
+  expiry, once per chi web), `peer` (the first use and each new peer address since chi web started: ip, user agent),
+  `refused` (method, path, reason; at most once a minute per route). It goes with the session (retention, delete).
+
+## Errors through `--remote`
+
+Each condition has one message, owned by its `SessionAccess` class and built from the remote's label
+(`Remote.access_error`, keyed by chi web's error code, for any route):
+
+| Code | Class | Message |
+|---|---|---|
+| 401 `token_revoked` | `TokenRevoked` (an `AuthRefused`) | `this review link was revoked by the session's owner` |
+| 401 `token_expired` | `TokenExpired` (an `AuthRefused`) | `this review link expired: ask the session's owner for a new one` |
+| 403 `not_permitted` | `NotPermitted` | `this token is a participant's: only the session's owner can do that` |
+| 429 `too_many_turns` | `TooManyTurns` (P3b) | `this participant has too many turns waiting: wait for one to finish` |
+| 429 `cap_reached` | `CapReached` (P3b) | `this participant's spending cap is reached: ask the session's owner to raise it` |
+
+A 401 `unauthorized` stays `AuthRefused`'s "the token was refused".
+
+## Invariants
+
+- The owner is a loopback peer or the owner's token; nothing else. A participant token never widens to the owner.
+- A participant reaches one session, through the `:participant` rows only; another session is a 404.
+- No token is written anywhere: the grants store has digests, the sidecar and the audit trail have neither.
+- Owner sessions are unchanged: no sidecar, no audit file, no key in the session JSON until a grant exists.
+- P2 lets no participant reach `POST …/turn`, `/command`, `/answer` or a stream. P3 adds the turn, with the author
+  stamped from the principal (never the body), and the worker's review boundary.