samagotchi 0.103.0 → 0.104.0

data/docs/internals/remote-sessions.md

@@ -1,7 +1,8 @@
 # Remote sessions
 
 `chi --remote NAME <command>` (or `CHI_REMOTE=NAME`) runs chi's session commands (`send`, `answer`, `note`, a
-session's `context`, `sessions list/stop/restart/archive/unarchive/delete`) against another machine's sessions. The
+session's `context`, `sessions list/stop/restart/archive/unarchive/delete`) against another machine's sessions, and
+`chi --remote NAME --attach ID` (`--resume ID`, `--dir DIR`, `-p TEXT`) runs the attached TUI on one of them. The
 sessions, workers, memories and code stay on that machine; this one only sends requests and prints the answers.
 User-facing behaviour is in [cli.md](../cli.md#remote-sessions). This page is the code's shape, for changing it.
 
@@ -44,8 +45,14 @@ subcommand:
 - `here?`: `chi remote …` (`ALWAYS_HERE`), and a bare `--version` / `-h` / `--help`, run locally as usual.
 - `#run`: an unknown command exits 1. `#refusal` is the single local-only message, `chi <words> runs on this machine
   only: run it on <remote>` (exit 2). `<words>` comes from `Contract`: a `MACHINE` command, an unlisted command, a
-  `:local_only` command, subcommand or long flag, or a run flag (`RUN_FLAGS`: `--attach`, `--resume`, `-p`,
-  `--shared`, `--no-shared`; with no command at all it reads "(a session in this terminal)").
+  `:local_only` command, subcommand or long flag, or a run flag `Contract::RUN` lists local-only (`chi --verbose`;
+  `--non-interactive` adds "(chi --remote NAME send --new --dir D -m TEXT --wait runs one turn there)"). A flag's
+  value (`-p TEXT`, `--model NAME`: `RunOptions.value_switches`) is never read as a flag.
+- **Run flags** (`#run_flags?`: no subcommand, the first word a flag or nothing) don't go to `#run`: bin/chi refuses
+  the local-only ones, parses the rest with `RunOptions.parse` (the one run-flag parser) and, before any of its own
+  checks (`Session.resolve_id`, the scratch check, `--memory`, `--append-system-prompt`, `Toolkit.from_flags`, …: all
+  this machine's), runs `RemoteAttachCommand.new(options, access: Remote.new(entry)).run`. A word left over exits 1.
+  Without a remote, `--dir` exits 2 ("--dir goes with --remote; cd there instead").
 - Otherwise it calls `Remotes.find`, then `Samagotchi.const_get(klass).new(argv, access: Remote.new(entry)).run`.
   `Remotes::Invalid` (including `NotFound`) exits 2. A `RemoteFailed` that escapes the command prints
   `chi <cmd>: <message>` and exits 1.
@@ -59,6 +66,14 @@ reads bin/chi's `SUBCOMMANDS` and each command's `FLAGS`. It fails when a subcom
 command, or a flag of a supported command is missing from both lists, or when the table lists something that doesn't
 exist. **A new session command or flag fails that spec until you choose one.**
 
+`Contract::RUN` does the same for bin/chi's run flags (`RunOptions.switches`): `SUPPORTED` (`--attach`, `--resume`,
+`-p`, `--shared`, `--model`, `--thinking`, `--llm-context*`, `--toolkit`, `--tool`, `--no-tool`, `--set`,
+`--parent-answers`, `--no-interrupt`, `--no-default-input`, `--dir`, `--help`, `--version`) or `LOCAL_ONLY`
+(`--no-shared`, `--non-interactive` and `--verbose`: the in-process REPL, P4-D4; `--memory`, `--mute`,
+`--append-system-prompt`: this machine's memories and files, P4-D2/D3; `chi web`'s flags; `--profile`). A config
+registry flag (`--recap-base-url` …) is this machine's config: `LOCAL_ONLY` without being listed
+(`Contract.run_status`). The contract spec fails on a run flag in neither.
+
 ## One request, end to end
 
 `chi --remote studio send ab12 -m "fix it" --wait`:
@@ -117,9 +132,20 @@ the session commands*. Keep that table in step with `SessionAccessRoutes`.
   refused" (also: no answer within 5 s, a read timeout, can't find host, host unreachable, TLS, a broken connection).
   `ParentWait#run` catches `RemoteFailed` so that `--format json` still prints its error object. Dispatch catches it for
   the other commands.
-- **Auth.** `Remote.auth_failure`: a 401 → "the token was refused (… chi remote add NAME URL --token-file FILE)". A 403
+- **Auth.** `Remote.access_error`, keyed by chi web's error code on any route: a 401 `unauthorized` → "the token was
+  refused (… chi remote add NAME URL --token-file FILE)"; a participant's token's own conditions (401 `token_revoked`,
+  `token_expired`, 403 `not_permitted`, P3b's 429 `too_many_turns`, `cap_reached`) → one class and message each
+  ([participants.md](participants.md#errors-through---remote)). A 403
   `forbidden` (the Host check) → "chi web answers its LAN IP only: use the LAN IP <ip>, not a hostname", with the IP
   taken from the 403's detail. `chi remote add` uses the same words through `Remote.info_problem`.
+- **A remote attach.** Before the loop runs (resolve, create, wake, the feature check) every failure is
+  `AttachLauncher::Error` or the command's own line, exit 1 (`BadRequest`: exit 2): the wake's 409 `owned_by_tui`
+  is `OwnedByTUI` (its message is the one `chi --attach` prints here too: `AttachLauncher.connect` now uses it), its
+  409 `scratch` and 504 `worker_timeout` are `Refused` with `LaunchMode::SCRATCH_LEFTOVER` / `BRIDGE_LATE`'s words
+  (`Remote#attach_wake`). Once the loop runs, `WebBridgeClient` turns every `RemoteFailed` into `Unreachable`
+  (an `IOError`), so the loop's rescues catch it and `AttachedLoop#worker_down` prints its message as is ("could not
+  send the prompt (remote studio (http://…): the token was refused …)"); the stream's end is worded by its reason
+  (*Remote attach*, below). A refused token is `AuthRefused < RemoteFailed`, so rediscovery can tell it apart.
 - **Version skew.** The check is by feature, not by version: `/api/info`'s `features` must include `session_commands`
   (`SessionAccessRoutes::FEATURE`, mirrored as `Remote::FEATURE` so chi web needn't be loaded). If it's missing,
   `RemoteTooOld` says "remote NAME runs chi X, too old for this command through --remote: update chi there (chi
@@ -149,14 +175,30 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
 | `context`'s default session (`SAMAGOTCHI_PARENT_SESSION`, `ContextCommand#inside_session`) | client | no default: ids are required (`added_by` still reads it) |
 | A context URL's provider (`ContextProviders.resolve`) | client's bundles | server's bundles (`Remote#context_add_url`) |
 | UI-only slash commands (`SessionCommands.ui_only_entry`), `--image` ingest, note text (`SessionInbox.checked_text`), push text (`ContextSources.parse_output`) | client | client too (the server checks note and push text again) |
+| A remote attach's `--attach`/`--resume` id (`Session.resolve_id`), the leftover scratch check, the "open in a chi REPL" refusal | client (bin/chi, `AttachLauncher.connect`) | server: `Remote#resolve`, then `POST …/wake`'s 409s |
+| A new attached session's `--toolkit`, `--set`, `--thinking`, `--llm-context*`, `--parent-answers`, `--model` | client (bin/chi) | server: `POST /api/sessions` with `idle: true` and `SetupWords`; its warnings printed as `send --new` prints them |
+| The status row's default model, the newest chi for the version line, what a parent may pick (exit 3) | client | server: the wake's `default_model`, `installed`, `parent_strategy` (the last read again from `GET …/worker` at report time) |
+| `@path` images (ingest, convert, downscale) | client, into the session's `images/` | client, into a scratch dir, then uploaded (`POST …/images`) |
+| Prompt history (↑), the `no_interrupt` / `no_default_input` baselines, Tab's `@path` | client | client (this terminal's; `history: false` on every POST); no memory-name completion remotely (P4-D11) |
 
 ## Trust model
 
 - **The token is the owner.** In LAN mode (`web.host: lan`) every non-loopback request needs the `Web::Token` access
-  token, as the `chi_token` cookie or `Authorization: Bearer` (`App#token_gate`). Passing the gate grants everything,
-  because no route checks roles (`local_viewer?` only hides `editor_url`). This runs over plain http, which is fine on
-  a home LAN, the same as the phone page. A loopback chi web without LAN mode needs no token
+  token, as the `chi_token` cookie or `Authorization: Bearer` (`App#token_gate`). This runs over plain http, which is
+  fine on a home LAN, the same as the phone page. A loopback chi web without LAN mode needs no token
   (`Remotes::Entry#token` is nil, and no header is sent).
+- **Every request has a principal.** `App#principal_for` resolves who a request is, as a `Web::Principal`
+  (`web/principal.rb`): `Principal::OWNER` for a peer the gate doesn't ask (no LAN mode, or a loopback peer) and for
+  the access token; a participant for a live grant's `chp_` token; nil (a 401) for anyone else (`token_revoked` /
+  `token_expired` for an ended grant's). `#token_gate` uses it, and `#route` keeps it in the request's env
+  (`App#principal(req)`), so a handler reads the principal and never trusts the body for it. Each `ROUTES` row names
+  who may use it (its permission column, `:owner` or `:participant`; `Principal#permits?`; any other answers 403
+  `not_permitted`). The owner passes every route (`local_viewer?` only hides `editor_url`). A participant, a
+  `Web::Grants` token for one session, reaches only the `:participant` rows, and another session's id is a 404
+  ([participants.md](participants.md)). A turn's author comes from the principal
+  (`Principal#author`, nil for the owner) and rides with the turn (`SessionManager.deliver_turn(author:)` →
+  `BridgeClient#post_turn` → `Bridge#handle_post_turn` → the input file, the fallback's too → the turn's `origin`);
+  an owner's turn carries none, so its input file and session are byte for byte as before.
 - **The token at rest.** `remotes.yml` is written through `AtomicFile.write(perm: 0o600)`. `Entry#inspect` / `#to_s`
   redact the token. `chi remote ls` never prints it (JSON shows `token: true|false`). `HTTPTransport#inspect` and
   `Remote#inspect` show only the label.
@@ -166,6 +208,12 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
 - **`client_id` only tightens.** `handle_question_answer` forwards `client_id` only when it is `ClientId::CLI_ANSWER`
   and drops any other value, so a remote answer is held to the parent rules and can't pass for the user's own. On
   create and turn, a `cli:send` / `cli:answer` id adds checks (`CLI_SEND_IDS`) and never removes any.
+- **A remote attach's `client_id`** (`tui:<pid>@<host>`, P4-D6) is forwarded as given on `/turn` and `/command`, as
+  the page's is: the token is the owner. Only the cli ids (`cli:send`, `cli:answer`) add checks there; a parent
+  agent driving the TUI from a pipe answers as `cli:answer`, held to that machine's `guardrails.parent_answers`.
+  `POST …/exit` passes on only a `tui:` id: any other is dropped, so the worker counts every stream as a UI, which
+  only keeps it up. `POST …/wake` spawns a worker, which `/turn` already did. `!cmd` typed in a remote TUI runs on that machine, under
+  its guardrails.
 - **Context push is an inbound path.** A remote `context push` writes text that can wake a session. It carries the same
   trust as a local `chi context push` on that machine, the owner's token ([guardrails.md](../guardrails.md)). A remote
   `context add --cmd` runs its command on the session's machine.
@@ -197,20 +245,43 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
   (`spec/support/web_server.rb`) followed through a `WebBridgeClient` (join, a turn, a restart, a stop). It runs
   over loopback, so chi web's token gate is skipped there; `spec/web/lan_auth_spec.rb` covers the gate on the
   stream, wake and worker routes.
-- By hand: the smoke-run skill (`.claude/skills/smoke-run`, kept in the checkout, not in git) covers chi web.
-  It has no remote recipe yet. The real lane is laptop → Studio over the LAN: `chi remote add`, `send --new --wait`,
+- The remote TUI: `spec/terminal_ui/remote_link_spec.rb` (rediscovery reasons, the wake on a reconnect, images, the
+  join's reads, `HANDLED_COMMANDS` covering every attached terminal command), `spec/terminal_ui/attached_loop_remote_spec.rb`
+  (the loop's `--remote` lines, `/exit`, `/exit --delete`, `/archive`, `/stats`, `/recap`, a join with that machine's
+  saved records, `Unreachable` mid-session, the reasons' and reconnect lines),
+  `spec/terminal_ui/remote_connector_spec.rb`, `spec/remote_attach_command_spec.rb`,
+  `spec/session_access/remote_attach_spec.rb` (wake, worker, feature check through `RackTransport`), and bin/chi's
+  branch in `spec/session_access_dispatch_spec.rb`.
+- By hand: the smoke-run skill (`.claude/skills/smoke-run`, kept in the checkout, not in git) covers chi web; its
+  cli-tui recipe has remote attach on one machine (two isolated envs, `chi remote add self http://<LAN IP>:PORT`, the
+  terminal's commands through chi web). The real lane is laptop → Studio over the LAN: `chi remote add`, `send --new --wait`,
   an exit-3 `answer`, `context push`, `note`, then `CHI_REMOTE=studio sh scripts/pair <id>` from the laptop's Claude.
 
-## Remote attach (the plumbing)
+## Remote attach
+
+`chi --remote NAME --attach ID`: the attached TUI (`AttachedLoop`) on a session of another machine. The TUI still
+talks to a worker's Bridge interface; chi web relays each request to that Bridge on loopback.
 
-What a remote attached TUI (`chi --remote NAME --attach ID`, not wired yet) will run on. The TUI still talks to a
-worker's Bridge interface; chi web relays each request to that Bridge on loopback.
+```
+bin/chi ── RunOptions.parse ── a remote, run flags ──> RemoteAttachCommand ── AttachLauncher.run(connector: RemoteConnector)
+                                                                                        │ POST …/wake
+                                                         AttachedLoop.new(link: RemoteLink) ── link.client: WebBridgeClient
+                                                                                        │ one-shots and the stream
+                                                                       chi web (that machine) ── the worker's Bridge
+```
+
+### The plumbing
 
 **chi web's routes** (tabled in [architecture.md](../architecture.md)): `POST …/wake` (`Local#wake`: the live worker
 as is, else `SessionManager.resume_session` and `BridgeClient.wait_for`, at most `WAKE_MAX_WAIT` 10 s, the attach's
-`BRIDGE_WAIT` here; a leftover scratch session is refused in `LaunchMode::SCRATCH_LEFTOVER`'s words, a late Bridge
-in `LaunchMode::BRIDGE_LATE`'s) and `GET …/worker` (`Local#worker`: live, the stop marker, the owner; it never starts
-one), both answering the worker as `{epoch, started_at, version, features}`; `POST …/turn` takes `no_interrupt`
+`BRIDGE_WAIT` here, after waiting for a worker still leaving to let go of its lock, `OwnerLock.await_release`: its
+recap on leave's timeout plus 5 s; a leftover scratch session is refused in `LaunchMode::SCRATCH_LEFTOVER`'s words, a late Bridge
+in `LaunchMode::BRIDGE_LATE`'s) and `GET …/worker` (`Local#worker`: live, the stop marker, the owner, `leaving` and `leave_seconds` when its worker
+is leaving, `WorkerState#leaving?`; it never starts one; it also names that machine's `default_model`), both answering the worker as `{epoch, started_at, version,
+features}`; `POST …/exit` (the worker's exit, `client_id` passed on only when it is a `tui:` one), `POST …/recap`,
+`GET …/stats` (the stats, else an older worker's state metrics), `GET …/children/counts` (`ChildrenStatus.counts`)
+and `GET …/turns/:turn_id/records` (`SessionMetrics`' saved tool records and turn record), every refusal with
+`{error, detail, message}`; `POST …/turn` takes `no_interrupt`
 (`SessionManager.deliver_turn(no_interrupt:)`, to the Bridge or into the input file); `POST …/command`'s 501 for a
 builtin the worker lacks names it (`command`). `/api/info`'s feature `remote_attach`
 (`SessionAccessRoutes::ATTACH_FEATURE`, mirrored as `Remote::ATTACH_FEATURE`) says a chi web has them.
@@ -221,10 +292,11 @@ builtin the worker lacks names it (`command`). `/api/info`'s feature `remote_att
 
 **`SessionAccess::WebBridgeClient`** (`session_access/web_bridge_client.rb`, built by `Remote#attach_client(id,
 worker:)` from a wake's or worker read's `worker`): `post_turn` (`no_interrupt`, `history: false`), `post_command`,
-`answer`, `dismiss_question`, `dequeue`, `cancel`, `follow`, `connect_stream`, `session_id`, `worker_key`, `port`
-(nil). One-shots go through `Remote#route_request` (the server check, the auth and missing-route mapping), a new
-connection each, with a 45 s read timeout (chi web's 30 s Bridge read plus its wait for a waking Bridge; 75 s for
-answer and dismiss, which chi web sends twice on a 408). Every reply goes through **one status mapper**,
+`answer`, `dismiss_question`, `dequeue`, `cancel`, `request_exit`, `request_recap`, `stats`, `children_counts`,
+`turn_records`, `follow`, `connect_stream`, `session_id`, `worker_key`, `port` (nil). One-shots go through
+`Remote#route_request` (the server check, the auth and missing-route mapping), a new connection each, with a 45 s
+read timeout (chi web's 30 s Bridge read plus its wait for a waking Bridge; 75 s for answer and dismiss, which chi web
+sends twice on a 408; 5 s, `JOIN_READ_TIMEOUT`, for the join's reads: the children counts and a turn's records, L9). Every reply goes through **one status mapper**,
 `WebBridgeClient::Mapping.response(route, reply, …)`:
 
 | chi web's answer | What the loop gets |
@@ -253,21 +325,72 @@ passes none):
   sidecar before it ends the open streams: the reconnect finds no sidecar, chi web waits for the next worker's
   (`await_bridge_port`) and proxies the cursor to it. A sidecar still naming the dead port would get an empty 200
   (the proxy's connects refused), and the stream would move by rediscovery (`worker_changed`, then a `snapshot`).
-- `announce_retries:` `stream_retrying` once a reconnect fails, `stream_resumed` at the next frame.
+- `announce_retries:` `stream_retrying` once a reconnect fails and rediscovery neither moved the stream nor ended it
+  (a stop prints its stopped line alone), `stream_resumed` once a stream answers again (a replay may bring no frame).
 
 `EventStream` compares a rediscovered client's key with the key it last followed, not with the client object's, so a
 rediscovery that updates the same client in place is a move. Rediscovery may give a reason with its answer
 (`[nil, reason]` while it retries, `[:gone, reason]` to stop, `AttachLink#live_worker`'s shape), and `stream_closed`
-carries the last one (`unreachable` without). `LocalLink#live_worker` gives `stopped` for a stopped session, but
-`AttachedLoop#live_worker` passes only the client on, so the local closing line is unchanged.
+carries the last one (`unreachable` without). `AttachedLoop#live_worker` passes the link's pair on; on this machine
+the closing line reads `stopped` as `unreachable`, the words it always had.
+
+### The remote TUI
+
+- **`RemoteAttachCommand`** (`remote_attach_command.rb`) takes RunOptions' parsed options: `LaunchMode.attached_conflict`
+  (exit 1, the same words); `--attach`/`--resume` resolved there (`Remote#resolve`); without them a new session,
+  which needs `--dir`, that machine's absolute path (exit 2, before anything is asked): `Remote#create` with
+  `NewSession(idle: true)` and the setup flags as typed (`SetupWords`), its warnings printed as `send --new` prints
+  them, its `-p` sent once attached. An existing session prints the ignored-flags line (`--dir` among them) and gets
+  `--model`/`--llm-context*`/`--thinking` as first commands, as here. `Remote#require_feature!("remote_attach")` comes
+  first (without it, `Remote.too_old_message`). Then `AttachLauncher.run(connector: RemoteConnector)` and
+  `AttachLauncher.exit_status`.
+- **`RemoteConnector`** (`terminal_ui/remote_connector.rb`): `#connect` is `Remote#attach_worker` (a worker there
+  still leaving prints `LaunchMode::RECAP_WAIT`, as a local attach does, and the wake's read timeout grows by its
+  `leave_seconds`), then `Remote#attach_wake` (`POST …/wake`, `WakeReply`) and the `RemoteLink`; `#client_id` is `tui:<pid>@<short hostname>` (P4-D6).
+- **`RemoteLink`** (`terminal_ui/remote_link.rb`), the `AttachLink`:
+  - `client`: one `WebBridgeClient` for the attach; `switched(event)` keeps it (its key the event's epoch) and reads
+    the new worker's features (`GET …/worker`).
+  - `live_worker`: `Remote#attach_worker` (`WorkerReply`) with a reason (M5): `stopped` and `unknown_session` (gone),
+    `auth_failed` (`AuthRefused`) and `too_old` (`RemoteTooOld`) end at once; `unreachable` (a transport
+    `RemoteFailed`) and `worker_gone` (chi web answers, no live worker, not stopped) retry through
+    `RECONNECT_DELAYS` (about a minute, P4-D5). A worker gone for `WAKE_AFTER` (3 s, so a restart's new worker isn't
+    raced) is woken once per outage with `POST …/wake` (P4-D9). `failure` keeps the last message for the closing line.
+  - `queues?`/`unqueues?`: the worker's `features`. `ingest_images`: `ImageStore.ingest` into a scratch dir here, then
+    `Remote#upload_images`; `close` (`AttachLauncher.run`'s `ensure`) removes the dir.
+  - `installed_version`: the wake's (that machine's). `default_model_name`: the wake's, then the one `GET …/worker`
+    names after a worker change (the loop forgets its copy on `worker_changed`). `parent_strategy`: `GET …/worker`'s,
+    read at report time (L4), the wake's when that fails.
+  - `completions`: `@path` (this machine's files: images are ingested here), no memory names (P4-D11).
+  - `via`: `Remote#invocation`, so every printed command reads `chi --remote NAME …` (`ChiInvocation#attach` and
+    `#resume` have their remote forms; `shows`/`open_it` name the attach too).
+  - The terminal's own commands through chi web: `/exit` is `WebBridgeClient#request_exit` (`POST …/exit`, this
+    TUI's `tui:` id); `/exit --delete` adds `Remote#delete(id, force: true)` and `/archive` `Remote#archive` once the
+    worker answered (their refusals the classes `SessionManager` raises here, a transport failure `Unreachable`);
+    `/stats` is `GET …/stats` and `/recap` `POST …/recap`. A failure the loop shows in its own words through a
+    remote: "(no metrics: …)", "(no recap: …)", the exit lines' "could not ask the worker to stop: …". A chi web
+    with `remote_attach` but without one of these routes (`serve_static`'s 404) reads as `RemoteTooOld`, so the line
+    carries `Remote.too_old_message`'s words.
+  - The join's reads swallow every failure (a debug log line): `saved_tool_records` / `saved_turn_record` are one
+    `GET …/turns/:turn_id/records` per join (the second call takes what the first read) and give `[]` / nil;
+    `children_counts` gives `Counts.none`.
+  - `HANDLED_COMMANDS` must list every `local: true` command shown in the attached TUI (`remote_link_spec`), so a new
+    terminal command can't silently fall through remotely.
+- **The loop's lines.** `stream_retrying` → "(lost the connection to NAME; reconnecting…)", `stream_resumed` →
+  "(reconnected)". `stream_closed`, by reason: "The session was stopped on NAME. Resume it with: chi --remote NAME
+  --resume ID"; "Lost the session: <the auth or too-old words>"; "Lost the connection to NAME (connection refused).
+  Re-attach with: chi --remote NAME --attach ID"; "The session's worker on NAME is gone. Resume it with: …"; "The
+  session is gone from NAME (deleted)." A restart is one "chi> the session's worker restarted on chi X" (the epoch's
+  `worker_changed`, then the new Bridge's `reset`). The version line across machines (P4-D10,
+  `VersionLines.across_machines`): "chi> the session's worker runs chi W; NAME has I installed: chi --remote NAME
+  sessions restart ID" and "chi> this terminal runs chi T (NAME has I): chi update here".
 
 ## Extension points (not built yet)
 
-- **Remote attach.** `--attach`, `-p` and `--resume` are refused today (`Dispatch::RUN_FLAGS`). The seams it plugs into
-  are in place:
+- **Remote attach** is built (*Remote attach*, above); its seams, for another kind of link:
   - `TerminalUI::AttachLink` (terminal_ui/attach_link.rb): what `AttachedLoop` knows about *where* the session is,
     beside its client: `live_worker` (`[client, nil]`, `[nil, nil]`, `[:gone, reason]`) and `switched(event)` for
-    the stream's rediscovery and a restart; `queues?` / `unqueues?`; `stats_metrics`; `ingest_images`; the saved
+    the stream's rediscovery and a restart; `queues?` / `unqueues?`; `stats_metrics` (may raise `IOError`: the loop
+    shows a remote's message); `ingest_images`; the saved
     records and `children_counts`; `delete_session`, `archive_session`; `installed_version`, `default_model_name`,
     `parent_strategy`; `completions` (Tab's `@path` and `#memory`); `reconnect_delays`; and `via`, the
     `ChiInvocation` every printed command is spelled with. `LocalLink` is this machine's; `AttachedLoop.new` makes
@@ -285,8 +408,7 @@ carries the last one (`unreachable` without). `LocalLink#live_worker` gives `sto
     branch can take the parsed options before bin/chi's local checks; `LaunchMode.attached_conflict` and
     `LaunchMode::SCRATCH_LEFTOVER` / `BRIDGE_LATE` are the words both would print.
 
-  The plumbing below (*Remote attach*) is built; `RemoteLink`, the connector and bin/chi's branch are not. chi web
-  still has no route for exit, recap, stats or a turn's saved records.
+  An https chi web (a pod behind a proxy) needs TLS and chunked decoding in `StreamRequest`.
 - **Shared sessions (guests, roles).** The only access point is `App#token_gate`: one token, the owner's. Roles would
   attach there and to the routes. The claude-peer / codex-peer inbox leg (chi → this machine's Claude or Codex) would
   need a relay through chi web.
@@ -296,6 +418,10 @@ carries the last one (`unreachable` without). `LocalLink#live_worker` gives `sto
 
 ## Known gaps
 
+- A prompt typed while a remote stream reconnects is usually accepted (chi web's `/turn` resumes the worker, else
+  writes an input file) where a local one fails "could not send the prompt". A POST whose reply is lost reads as
+  "could not send", yet ran: sending it again runs it twice (no idempotency key yet).
+
 - Through a remote the pair scripts (`bundles/{claude,codex}-peer/scripts/pair`) detect `CHI_REMOTE` or `--remote` in
   `CHI` the way Dispatch does, and attach only `*-outbox`: chi there can't reach this machine's Claude socket or Codex
   thread, so chi's replies reach Claude only when relayed.

data/docs/plugins.md

@@ -1207,7 +1207,13 @@ bundle.shutdown
 - **More:** `bundle.plugin` (the instance `register` ran on, for its own methods), `bundle.declarations` (the
   `chi.*` calls `register` made, in order, as made), `bundle.namespace`, `bundle.hook_names(event)`,
   `bundle.run_inits`, `sandbox.write_memory(name, text, scope:)` / `memory_dir`, `sandbox.fake_executable(name,
-  body)` (first on `PATH`), `wait_until { }`.
+  body)` (first on `PATH`).
+- **Waiting:** `wait_for(what, timeout: 5, seen: nil) { … }` polls the block until it is truthy and returns that
+  value, or raises `Samagotchi::Testing::Waiting::TimedOut` ("timed out after 5 s waiting for <what>", plus
+  `; last saw: <value>` from the `seen:` callable). `join!(thread, what)` and `pop!(queue, what)` are
+  `Thread#join` and `Queue#pop` with that deadline and message; `wait_until { }` returns the block's last value
+  instead of raising, for a wait whose timeout is fine; `process_gone?(pid)`. Every deadline is multiplied by
+  `SPEC_TIME_SCALE` (default 1, at least 1; chi's CI sets 2), so a slow runner gets headroom.
 - **Model notes:** `sandbox.model_notes_for(model_id, small: nil, cwd: nil)` lists the model notes chi would load
   into the prompt for a bare model id (`deepseek/deepseek-v4.1-flash`, no host prefix), from the sandbox's
   memories (an installed bundle's included), matched as chi matches them: each `models:` glob against the id and

data/docs/sessions.md

@@ -17,10 +17,12 @@ Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/s
 
 A session is deleted if **expired by age OR overflow by count** (unless `keep_status` or the live-owner guard: a session a worker or `chi` still has open is never pruned). A session's `status` is its turn state (`idle`/`running`), not whether a worker is alive. Orphan dirs without a `*.json` are never deleted, except skeleton-only ones (see *Empty sessions*). Deletion removes both `*.json` and sidecar dir atomically. Set both `DAYS=0` and `MAX=0` to retain forever.
 
-**Worker idle exit:** a background worker (plain `chi`, Web UI sessions) exits after `SAMAGOTCHI_SESSION_IDLE_EXIT_MINUTES` (`session.idle_exit_minutes`, default `30`, `0`=never) with no turn running or queued, no client on its stream (an open web tab or attached terminal keeps it), no reminder registered, no background task it watches for a [finish wake](internals/background-tasks.md#finish-wake) still running or waiting for its wake turn (with `session.task_wakes: wake`; not one whose turn you stopped) and no continue offer (the step-limit question) waiting for an answer. It removes `bridge.json` and frees `owner.lock`; the next prompt or `--attach` wakes a new worker (`WorkerIdleExit`, `SessionManager.run_session_loop`). A client can also ask the worker to exit right away (Bridge `POST /session/:id/exit`; `/exit` in an attached terminal does, `/detach` doesn't): the same rules apply without the timeout (even with `0`), and the asker's own stream doesn't count. The reply names what keeps it up (for background tasks, which ones and how to stop them). The session's status stays as it was, not `stopped`. With `"restart": true` (a worker whose sidecar lists the `restart` feature) the worker hands the session to a new worker on the newest chi installed: it leaves, then starts its successor once its lock is free, keeping even an empty session and writing no recap. Clients' streams don't hold a restart (a web tab and an attached terminal reconnect to the new worker); what would be lost does: a turn running or queued, a continue offer, a question or approval waiting, reminders, a `/btw` (or another anytime command) still running, a delegate's approval relay open or settled in the last 10 minutes, and background tasks this conversation started that still run (`WorkerIdleExit#hold_for_restart`; 409 `held` with `reason`). What lives only in the worker's memory goes: the event history a late client replays, the kept `/btw` answers, a plugin's in-memory state.
+**Worker idle exit:** a background worker (plain `chi`, Web UI sessions) exits after `SAMAGOTCHI_SESSION_IDLE_EXIT_MINUTES` (`session.idle_exit_minutes`, default `30`, `0`=never) with no turn running or queued, no client on its stream (an open web tab or attached terminal keeps it), no reminder registered, no background task it watches for a [finish wake](internals/background-tasks.md#finish-wake) still running or waiting for its wake turn (with `session.task_wakes: wake`; not one whose turn you stopped) and no continue offer (the step-limit question) waiting for an answer. It removes `bridge.json` and frees `owner.lock`; the next prompt or `--attach` wakes a new worker (`WorkerIdleExit`, `SessionManager.run_session_loop`). As its Bridge stops, the worker marks the lock leaving (`OwnerLock#mark_leaving`: `leaving_at`, and `leave_wait`, its `recap.timeout`), since it keeps the lock while it writes the recap on leave: an `--attach` or `--resume` meanwhile (here, or a remote one through chi web's wake) prints `(waiting for the session to finish its recap…)` (`LaunchMode::RECAP_WAIT`) and waits for the release, up to that budget plus `OwnerLock::LEAVE_MARGIN` (5 s), before starting the new worker (`OwnerLock.await_release`). A lock held by a worker that isn't leaving (a live one, a stuck one) is left as before. A client can also ask the worker to exit right away (Bridge `POST /session/:id/exit`; `/exit` in an attached terminal does, `/detach` doesn't): the same rules apply without the timeout (even with `0`), and the asker's own stream doesn't count. The reply names what keeps it up (for background tasks, which ones and how to stop them). The session's status stays as it was, not `stopped`. With `"restart": true` (a worker whose sidecar lists the `restart` feature) the worker hands the session to a new worker on the newest chi installed: it leaves, then starts its successor once its lock is free, keeping even an empty session and writing no recap. Clients' streams don't hold a restart (a web tab and an attached terminal reconnect to the new worker); what would be lost does: a turn running or queued, a continue offer, a question or approval waiting, reminders, a `/btw` (or another anytime command) still running, a delegate's approval relay open or settled in the last 10 minutes, and background tasks this conversation started that still run (`WorkerIdleExit#hold_for_restart`; 409 `held` with `reason`). What lives only in the worker's memory goes: the event history a late client replays, the kept `/btw` answers, a plugin's in-memory state.
 
 **Empty sessions:** a session nothing happened in is deleted when it is left, so `chi` → `/exit` leaves no trace. Empty means: no messages, no turn tried (a failed turn leaves a `last_prompt` and keeps it), no memory used, no pending question, nothing in `input/`, `notes/` or `images/`, nothing in its dir beyond the worker's skeleton, mode `assist`, and the default model. A session on another model (`/model`, `--model`) counts as prepared and stays (`SessionManager.discardable?`). The worker checks as it idle-exits or leaves on a client's request and deletes it once its lock is free, checking again first. The attached `/exit` then says `Detached; the session is empty: it will be discarded if nothing arrives before its worker stops.` (a note or prompt landing first keeps it). The REPL (`--no-shared`) does the same at `/exit` or Ctrl-D. The retention sweep catches those killed first: empty sessions over an hour old with no live owner, whatever `DAYS`/`MAX`, and skeleton-only dirs with no `*.json`. `session.keep_empty: true` (env `SAMAGOTCHI_SESSION_KEEP_EMPTY`) turns all of it off.
 
+**Participants:** a session its owner invited participants to review (`chi share`, see [CLI: Participants](cli.md#participants)) has two more files in its dir, neither in the session JSON: `participants.json` (0600), who is or was invited (`{participants: [{id, kind, name, role, added_at, expires_at, removed_at}]}`, never a token), which chi web and `chi share` write and the worker reads (`Participants.read`); and `participants.jsonl` (0600, append-only), the audit trail (grants issued, revoked and expired, each new peer, refused routes). A session nobody was invited to has neither. A continue, a fork or a delegate starts with no participants. Archiving or deleting the session revokes its links. See [internals/participants.md](internals/participants.md).
+
 **Attached by default:** plain `chi` and `chi --resume ID` run their session in a background worker and attach to it (`session.shared`, default `true`; env `SAMAGOTCHI_SESSION_SHARED`). The worker runs in the session's `working_directory`, so `!commands` and tools see the directory the session was started in. `session.shared: false` keeps the in-process REPL, `--no-shared` does for one run; a session the REPL has open can't be attached ("close it there first"). See [CLI: Sharing a session](cli.md#sharing-a-session).
 
 **Which chi a worker runs:** a new or woken worker runs the newest chi installed for this Ruby (`gem 'samagotchi', '>= 0.a'`, prereleases count), whoever starts it: a `chi web` or terminal still on an older chi starts it on the newest one, so a stale process doesn't spread old code. A worker already running keeps its version until it is restarted. Should the newest install fail to load, the worker runs the starter's own version and logs `boot_fallback` (its stdio is `/dev/null`). Under `bundle exec` the worker drops Bundler's env first, so it activates the newest gem too. Two consequences: a wrapper pin (`chi _0.17.0_ web`) pins only that process, not the workers it starts; and a source checkout (`bin/chi` in a worktree, `bundle exec`) starts its workers on its own `lib/`, but a session it made that is later woken by an installed chi (`chi web`, `chi send`) runs the installed code. The names an older starter hands a newer worker (the boot line, its env keys, `input/` files, the session JSON fields and the Bridge routes sessions use on each other) are pinned in `spec/worker_contract_spec.rb`.
@@ -29,7 +31,7 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **A worker killed mid-turn:** while a turn runs, its worker keeps it on disk (`TurnCheckpoint`): the session file has the turn so far (the prompt from the turn's start, then the finished tool steps and lines merged into it) and `interrupted_turn: {id, started_at, at, iteration, enqueued_id}` (`enqueued_id`: the input the turn runs, so any process can tell which turn is running; a continue turn carries its offer turn's), written as the turn starts, at the loop's first iteration boundary and then at most every 10 s (`updated_at` moves with it). The turn's end saves the real messages without the mark. A worker that died without ending its turn (SIGKILL, a crash of the process) leaves the mark, and loses what came after its last written boundary: at most the last 10 s of steps, plus the step in flight. Each checkpoint write also saves the turn's metrics so far to `analytics.json` (tokens, speeds, timings, its finished tool calls), as the record a killed turn leaves: canceled, `cancellation_reason: worker_stopped`; the turn's own end writes over it. The next worker to start for the session (a `chi send`, `--resume`, `--attach`, the web), or a `--no-shared` REPL resuming it, settles the turn before anything else (`TurnCheckpoint.settle`, log `interrupted_turn_settled`): a note `the previous turn was cancelled (worker-stopped) after Ns` goes at the tail, the status goes idle and the mark goes; `last_turn` stays the previous turn's (a new one saved before the turn a `chi send --wait` woke the worker for would end that wait at once); the dead turn's end is recorded under its `enqueued_id` instead, in `<id>/input/settled/<enqueued_id>` (a `last_turn` record: canceled, `cancel_reason: worker_stopped`), which only a wait for that very turn reads (`chi send --queue --wait`, `chi send --wait ID --turn`, a continue's wait): it ends `canceled` with `cancel_reason: worker_stopped`, detail "its worker exited mid-turn", instead of timing out. A reply the turn wrote before its worker died is still its answer. The session shows the turn's prompt and steps with that note; the dead turn is not run again, and the model reads on its next turn that it was cut.
 
-**Stopping a worker:** `chi sessions stop ID` marks the session stopped (an empty `<id>/stopped` file, not a session.json field, which a worker saving at that moment would write over; a resume removes it), sends its worker TERM and waits (up to 10 s) until the worker has let go of `owner.lock`. A running turn is canceled over the Bridge first, with reason `session_stopped` (the turn's line ends "(session stopped)", its note says `cancelled (session-stopped)`, and a command it was running says "stopped as the session was stopped"; a bare signal to the worker makes it "stopped by a signal to chi"; an older worker takes the reason as `manual`); the TERM stops whatever still runs as a Stop with reason `signal` and saves it (a spawned worker traps TERM, HUP and INT: `WorkerSignals`; a turn not ended within 3 s, 0.5 s after a stop or a second signal, is cut and the session saved as it was), and a stopped worker still saves its kept turn, since the marker, not the saved status, says stopped. Any TERM, HUP or INT does the same to a worker outside a stop: it leaves (log `worker stop reason=signal`) and the next send wakes a new one, so a `chi --resume ID` right after spawns a fresh worker. That is also how to restart a worker still running an older chi, which the attached terminal reports when a command or a question dismiss gets a 404, and the web when an answer, a dismiss, a command or a cancel does (`501 not_supported`; `BridgeClient.stale_worker_message`). A command this chi has that the older worker doesn't (`/llm-context`, the web's `llm ctx` chip, against a 0.39.0 worker) says the same, not `not a session command` (`SessionCommands.builtin_name`); a typo keeps its `400 unknown_command`. The web's `POST /api/sessions/:id/stop` waits the same way, for 2 s. A command sent during a turn that waits for its end (`/model X`, `!cmd`; see *Typing during a turn* in [cli.md](cli.md)) and hasn't run when the worker leaves (a stop, a crash) is answered `command_ran {status: "dropped"}`, so no UI keeps showing it waiting.
+**Stopping a worker:** `chi sessions stop ID` marks the session stopped (an empty `<id>/stopped` file, not a session.json field, which a worker saving at that moment would write over; a resume removes it), sends its worker TERM and waits (up to 10 s) until the worker has let go of `owner.lock`. A running turn is canceled over the Bridge first, with reason `session_stopped` (the turn's line ends "(session stopped)", its note says `cancelled (session-stopped)`, and a command it was running says "stopped as the session was stopped"; a bare signal to the worker makes it "stopped by a signal to chi"; an older worker takes the reason as `manual`); the TERM stops whatever still runs as a Stop with reason `signal` and saves it (a spawned worker traps TERM, HUP and INT: `WorkerSignals`; a turn not ended within 3 s, 0.5 s after a stop or a second signal, is cut and the session saved as it was), and a stopped worker still saves its kept turn, since the marker, not the saved status, says stopped. Any TERM, HUP or INT does the same to a worker outside a stop: it leaves (log `worker stop reason=signal`) and the next send wakes a new one, so a `chi --resume ID` right after spawns a fresh worker. That is also how to restart a worker still running an older chi, which the attached terminal reports when a command or a question dismiss gets a 404, and the web when an answer, a dismiss, a command or a cancel does (`501 not_supported`; `BridgeClient.stale_worker_message`). A command this chi has that the older worker doesn't (`/llm-context`, the web's `llm ctx` chip, against a 0.39.0 worker) says the same, not `not a session command` (`SessionCommands.builtin_name`); a typo keeps its `400 unknown_command`. The web's `POST /api/sessions/:id/stop` waits the same way, for 2 s (the page's Stop shows the stop at once), or for the body's `wait` up to the same 10 s (`SessionManager::STOP_WAIT`): `chi --remote NAME sessions stop` sends it, so it waits as long as here. A command sent during a turn that waits for its end (`/model X`, `!cmd`; see *Typing during a turn* in [cli.md](cli.md)) and hasn't run when the worker leaves (a stop, a crash) is answered `command_ran {status: "dropped"}`, so no UI keeps showing it waiting.
 
 **Deleting a session:** `chi sessions delete ID...`, `/exit --delete` in a terminal and the Web UI's delete all go through `SessionManager.delete_session`: it resolves a unique prefix, removes `<id>.json` and the whole `<id>/` dir, and returns what it removed. A session a plain REPL has open (`owner.lock` kind `tui`) is always refused. One a worker runs is refused unless the caller asks to stop it: then it stops the worker as `chi sessions stop` does and deletes once `owner.lock` is free (`--force` on the CLI, 10 s; the web page always, 2 s; `/exit --delete` after the worker agreed to exit, 10 s). A worker that outlives the wait leaves the session in place. The web's route is `DELETE /api/sessions/:id?force=true` (the page sends `force`; without it a live worker's session is 409 `worker_running`, as the CLI without `--force`; 200 `{status: "deleted", session_id, stopped}`; 409 `owned_by_tui` or `still_stopping`; 404).
 

data/docs/sub-agent.md

@@ -164,6 +164,14 @@ An answer typed into `chi --attach` or the REPL counts as a parent's too when
 stdin isn't a terminal or an agent marker (`CLAUDECODE`, `AI_AGENT`,
 `CODEX_THREAD_ID`, `SAMAGOTCHI_PARENT_SESSION`) is set.
 
+The same holds for another machine's session in this terminal (`chi --remote
+NAME --attach ID`, `--resume ID`, `--dir DIR -p TEXT` from a pipe): the answers
+go as chi answer's and are held to that machine's `guardrails.parent_answers`;
+a question left waiting at the pipe's end is exit 3, its report read with that
+machine's parent strategy (asked again then) and its commands spelled `chi
+--remote NAME answer …`. For one turn and no terminal, use `chi --remote NAME
+send --new --dir D -m TEXT --wait` (`--non-interactive` is this machine's only).
+
 Through `chi web` (`POST /api/sessions/:id/answer`, what chi answer uses against
 another machine's sessions) the answer keeps chi answer's mark: the route passes
 on `client_id: "cli:answer"` and drops any other id, so a forwarded answer can

data/docs/testing.md

@@ -22,6 +22,9 @@ with two rules only, `no-undef` (a name used but never imported or declared: a d
 style pass: add a rule only for a bug class it would have caught. It runs in about 2 s, in CI's `npm test` job and in
 `rake release:check`; `rake lint` stays RuboCop alone (CI's rubocop job has no node). A name that is also a browser
 global (`name`, `status`, `open`…) passes even when its import is gone: give an export such a name only with care.
+It also checks `spec/e2e/` for one thing, the Playwright twin of `Samagotchi/SpecSleep`: no `page.waitForTimeout`.
+Wait for the state (a locator's `expect`, `data-phase`, an animation's end through `waitForFunction`); a pause that
+is the behaviour (a pointer's dwell) carries `// eslint-disable-line no-restricted-syntax -- why`.
 
 CI's e2e job keeps the tests, chi and the fake model on the runner but runs Chromium in Playwright's image
 (`mcr.microsoft.com/playwright:v<version>-noble`, `playwright run-server` on the host network); the tests connect
@@ -66,11 +69,68 @@ either router adds its row there; a row where a UI differs on purpose (or a foun
 `repl` override and a `note`. The Ruby side runs each row with every core command (a new one fails its
 `CORE_ROUTES` check until listed there); a row's names that core lacks stand for plugin commands.
 
-A spec that waits for something uses `wait_until(timeout:)`, or `wait_until!(what, timeout:)` where no check
-follows (stubs, helper threads: it raises "timed out after N s waiting for <what>") — never a loop with no deadline.
+## Waiting and time
+
+A spec waits *for* something and never sleeps to wait: a fixed pause is too short on a loaded runner (a parallel
+run, CI) and too long on a fast one. The contract a new spec follows:
+
+1. **Never `sleep` to wait.** Wait for the condition: `wait_for("what") { condition }`, or
+   `eventually { expect(…) }` for a value. A `sleep` that *is* the behaviour (slowness, holding a connection,
+   separating mtimes) carries `# sleep-ok: why` on its line or the line above (for a call over several lines, its
+   first line). A bounded best-effort `wait_until`
+   whose timeout is fine ("at most 0.5 s, fine to cut short") carries `# wait-ok: why`; it must not become
+   `wait_for`, which would raise where the code moves on. A `Timeout.timeout` is a wait too (use `pop!`, `join!` or
+   `wait_for`); one that only guards a call that returns by itself against a hang carries `# timeout-ok: why`.
+2. **Time logic takes seams.** Intervals, graces and deadlines in lib take `clock:` / `sleeper:` / `interval:`
+   constructor arguments, and the unit spec moves the clock itself (`SessionAccess::Remote` is the model;
+   `IdleScheduler.new(interval:)`). Real time is used only in one smoke example per class. Two sessions or inbox
+   files that must sort apart get distinct times, not a pause: `Session.new_session(now:)`, `Session#save(now:)` and
+   `SessionInbox.write_input` / `write_note` / `write_output(now:)` take `now: next_stamp` (spec/support/stamps.rb:
+   a millisecond later on each call, starting a second in the past).
+3. **What a spec starts, it stops and waits for** before teardown: `join!(thread, what)`, `with_task_dir { … }`
+   (spec/support/task_dirs.rb: a tasks' folder of its own, its tasks stopped and their exit-status recorders joined
+   with `TaskRuntime.quiesce!`), a `stop` that joins (`IdleScheduler#stop`). Never only `Thread#kill`.
+4. **"Nothing happens" is shown by counting passes** (the worker's loop rounds, spec/support/worker_loop_rounds.rb;
+   a class's ticks), not by a pause.
+5. **A wall-clock bound** only as "not the full N s", with at least 5× headroom measured on the slow (x86) laptop.
+
+The helpers are the bundle test kit's (`Samagotchi::Testing::Waiting`, [plugins.md](plugins.md#testing-a-bundle-experimental)),
+so core and bundle specs share one copy; `SpecWaiting` (spec/support/waiting.rb) includes them in every example
+group and also answers them as module calls (`SpecWaiting.pop!`, for a stubbed lib thread):
+
+- `wait_for(what, timeout: 5, interval: 0.01, seen: nil) { … }` returns the block's first truthy value, or raises
+  `Waiting::TimedOut`. `seen:` (a callable) shows what the condition last saw, since a falsy block value tells
+  nothing.
+- `join!(thread, what, timeout: 5)` and `pop!(queue, what, timeout: 5)`: `Thread#join` and `Queue#pop` with the
+  same deadline and message. A gate a stubbed lib thread waits on takes `timeout: 30`: it only ends a hang.
+- `wait_until(timeout:) { … }` returns the block's last value (falsy at the deadline): for a value the example
+  checks after, or a `wait-ok` wait.
+- `eventually(timeout: 5) { expect(…) }` (spec only) retries until the expectations hold, then re-raises the last
+  failure prefixed `still failing after 5 s:`, so the matcher's own expected/got is in the message.
+
+One formatter builds the failure text of `wait_for`, `join!` (which adds "to finish") and `pop!`:
+
+```
+timed out after 5 s waiting for task 20261023-0a1b to end
+timed out after 10.0 s (5 s × SPEC_TIME_SCALE 2) waiting for task 20261023-0a1b to end; last saw: "running"
+```
+
+**`SPEC_TIME_SCALE`** (default 1, at least 1; CI's `rspec`, `rspec-macos` and `bundles` jobs set 2) multiplies
+every helper deadline, explicit `timeout:` values included: a positive wait only gets more headroom, and a passing
+run is no slower. Set it locally to reproduce a CI timing (`SPEC_TIME_SCALE=2 bundle exec rspec FILE`). It does not
+scale the lib's own timeouts a spec passes in (`wait: 0.05`, `grace: 0.1`): those are the code's deadlines, and a
+flaky one gets a `clock:` seam instead. A helper's own spec pins the scale (stub `Waiting.time_scale`). Keep
+explicit helper timeouts at 30 or below: 60 s on CI, under the per-example limit.
+
 Every example also runs under a 120 s limit (`spec_helper`'s `around`; `integration`, `macos_build`, `warmup` and
 `recap` examples are exempt), so a hang fails its example instead of the run. `SPEC_EXAMPLE_TIMEOUT=N` changes the
-limit, `0` turns it off (a debugger session).
+limit, `0` turns it off (a debugger session). The limit is not scaled.
+
+**The cops.** `Samagotchi/SpecSleep` (an untagged `sleep` in a spec) and `Samagotchi/SilentWait` (a `wait_until`
+whose value is dropped, an example's last line included, `expect(wait_until { … }).to be(true)`, or an untagged
+`Timeout.timeout`) live in `rubocop/` and run in `rake lint`, so CI fails on them. RSpec counts `wait_for`,
+`eventually`, `join!` and `pop!` as an example's expectation (`RSpec/NoExpectationExample`), so a wait can be an
+example's last line. What the cops can't see, `script/affected-specs` hints at (`timing:`, below).
 
 ## Bundle specs: the test kit
 
@@ -140,7 +200,11 @@ words the REPL prints, pick it by a rule), then the other name matches (a spec n
 `toolkit.rb`; then one beside the file, so `plugin/context.rb` picks `spec/samagotchi/plugin/*context*` before
 `spec/guardrails/context_spec.rb`), then the specs that name a changed file's class. The default range is the merge-base with main (or origin/main) plus uncommitted and untracked files.
 The Ruby specs go to stdout; the node tests to run (`npm test` targets), "web changed: also run npm run e2e" (with `npm run lint` too when a frontend module changed) and a
-hint for a hub class (named in too many specs to list) go to stderr. Nothing printed means nothing matched.
+hint for a hub class (named in too many specs to list) go to stderr, and so do the `timing:` hints, from the lines a
+changed spec adds (`git diff -U0` against the base; an untracked spec, all its lines): a `Thread.new`, `.start`,
+`spawn` or `fork` with no `join!`, `wait_for`, `with_task_dir` or `Process.wait` added in the same file, and a
+sub-second `be < 0.x` bound ([Waiting and time](#waiting-and-time), rules 3 and 5). Nothing printed means nothing
+matched.
 
 It finds a change's own specs, not the regressions it causes elsewhere. So before committing, run the full suite
 (`bundle exec parallel_rspec -n 8 spec lib/samagotchi/bundles/*/spec`), unless your task says the coordinator runs it; the coordinator runs it at merge

data/lib/samagotchi/bridge.rb

@@ -892,6 +892,10 @@ module Samagotchi
       client_id = fetched(parsed, "client_id")
       # --no-interrupt: the turn runs with the raised iteration limit.
       no_interrupt = fetched(parsed, "no_interrupt") == true
+      # Who wrote it when it isn't the owner (chi web stamps it from the
+      # request's principal; the Bridge is loopback and trusts its caller).
+      author = fetched(parsed, "author")
+      author = nil unless author.is_a?(String) && !author.empty?
       if sid.to_s.strip.empty? || prompt.to_s.strip.empty?
         return [{ "Allow" => "POST" }, 400,
                 { error: "missing_fields", detail: "session_id and prompt are required" }]
@@ -935,7 +939,7 @@ module Samagotchi
 
         queued_behind_turn = Delivery.queue?(delivery) && !@accumulator.current_turn.nil?
         enqueue_turn(prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                     no_interrupt: no_interrupt, images: images, delivery: delivery).tap do |ok|
+                     no_interrupt: no_interrupt, images: images, delivery: delivery, author: author).tap do |ok|
           next unless ok
 
           enqueued_event = { type: :turn_enqueued, enqueued_id: enqueued_id, client_id: client_id, prompt: prompt.to_s }
@@ -1082,9 +1086,9 @@ module Samagotchi
 
     # Write a turn into this session's input dir, reusing the file IPC the
     # worker polls. Never calls run_turn across the boundary.
-    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [], delivery: nil)
+    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [], delivery: nil, author: nil)
       SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                                            no_interrupt: no_interrupt, images: images, delivery: delivery)
+                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author)
     end
 
     # ── HTTP plumbing ────────────────────────────────────────────────────────

data/lib/samagotchi/bridge_client/event_stream.rb

@@ -31,8 +31,9 @@ module Samagotchi
     # WebBridgeClient), where the client stays the same object across
     # workers: +epoch_watch+ (a frame whose id has another epoch than the
     # cursor's is a new worker: worker_changed first, the client's key
-    # updated), +announce_retries+ (stream_retrying once a reconnect fails,
-    # stream_resumed at the next frame), +idle_timeout+ (no byte, not even
+    # updated), +announce_retries+ (stream_retrying once a reconnect fails
+    # and rediscovery neither moved nor ended the stream, stream_resumed
+    # once a stream answers again), +idle_timeout+ (no byte, not even
     # the Bridge's 15 s ping, for that long: a half-open connection,
     # reconnected with the cursor).
     class EventStream
@@ -125,7 +126,8 @@ module Samagotchi
             next
           end
 
-          announce_retry
+          # Rediscovery first: a stopped session or a new worker is no
+          # retry to announce (a stop prints its line alone).
           case rediscover_worker
           when :moved
             failures = 0
@@ -133,6 +135,7 @@ module Samagotchi
             next
           when :gone then return finish(@reason || "unreachable")
           end
+          announce_retry
 
           failures += 1
           return finish(@reason || "unreachable") if failures > @reconnect_delays.size
@@ -153,6 +156,9 @@ module Samagotchi
         return :unknown_session if status == 404
         return :unreachable unless status == 200
 
+        # Back as soon as the stream answers: a replay may bring nothing
+        # (the session was quiet), and the next frame could be minutes away.
+        announce_resumed
         yielded = false
         parser = SSEParser.new
         loop do
@@ -163,7 +169,6 @@ module Samagotchi
             event = parse(frame[:data])
             next unless event
 
-            announce_resumed
             watch_epoch(frame[:id]) if @epoch_watch
             @last_event_id = frame[:id] if frame[:id]
             yielded = true

data/lib/samagotchi/bridge_client.rb

@@ -165,9 +165,12 @@ module Samagotchi
     # @param no_interrupt [Boolean] run the turn with the raised iteration limit
     # @param images [Array<Hash>] refs ({file:, name:}) to images already in
     #   the session's images/
-    def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil)
+    # @param author [String, nil] who wrote it when it isn't the session's
+    #   owner; sent only when given (SessionManager.deliver_turn)
+    def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil, author: nil)
       body = { session_id: @session_id, prompt: prompt, client_id: client_id }
       body[:no_interrupt] = true if no_interrupt
+      body[:author] = author if author
       body[:images] = images if images && !images.empty?
       body[:delivery] = delivery unless delivery.nil? || Delivery.next_step?(delivery)
       body[:deadline] = deadline

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.103.0
+version: 0.104.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files: