samagotchi 0.102.0 → 0.103.0

data/docs/sessions.md

@@ -31,7 +31,7 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **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.
 
-**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 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` (200 `{status: "deleted", session_id, stopped}`; 409 `owned_by_tui` or `still_stopping`; 404).
+**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).
 
 <a id="archiving-a-session"></a>**Archiving a session:** `chi sessions archive ID...`, `/archive` in a terminal and the Web UI's `archive` go through `SessionManager.archive_session`: it writes `<id>/archived` (`{"archived_at": …}`; not a session.json field, which every save rewrites) for the session and its delegated children. `Session.list` leaves archived sessions out unless `include_archived:`, and everything built on it follows: `chi sessions list` (`--archived` shows them, `[archived]`), the summaries (`--live`, json/tsv, the desktop panel, the agent's `list_sessions`) and the retention prune, which neither deletes nor counts them against `max_count`. `children_of` (max_children, `delegate_result`) still sees them, and `--resume`/`--attach ID`, `chi send`/`chi note ID` reach them as before. Refused: a turn running in the session or in one of its children (naming the child; 409 `busy` on the web), a prompt queued in `input/` (it would run on the next resume) or a live worker's step-limit question still open, in it or a child (409 `busy` too), a plain REPL owning it (`owned_by_tui`), a `chi scratch` session (`scratch`). A live idle worker is stopped first, and the marker is written even if it is still shutting down. Input a human typed brings a session back (`{"unarchived_at": …}`): a prompt from the web, an attached or plain terminal or `chi send` (origin `web:*`, `tui:*`, `cli:send`, none), steering merged into a running turn, a `/continue` answer or a question answered (the step-limit question too); a delegate's follow-up, a plugin's turn, a reminder, the idle recap, a note and just opening it don't. A child's input brings only the child back. The retention sweep ages an unarchived session from when it was unarchived, so unarchiving an old session doesn't let the next sweep take it. `/archive` leaves the session first, as `/exit` does, then archives it: in an attached terminal the worker is asked to exit (one that stays up for another UI is stopped by the archive; a running turn, a queued prompt or an open step-limit question refuses it), and an empty session is discarded instead; `chi scratch` refuses it. Typed while a turn runs, `/archive` waits for the turn's end (an attached terminal for the commands queued behind it too) and then archives. `chi sessions unarchive ID...` and the web's `unarchive` bring back the whole family. Web routes: `POST /api/sessions/:id/archive` (200 `{status, session_id, archived, stopped, discarded}`, ids) and `POST /api/sessions/:id/unarchive` (200 `{status, session_id, unarchived}`). The session hub and `GET /api/sessions` keep archived sessions, `archived: true` in their summaries: the page leaves them out of the strip, its count and the list at render, and "include archived" by the all-sessions search shows them, dimmed with an `archived` badge. The info bar marks a session whose live worker runs an older chi than the newest installed (`worker_version` in its summary): `chi 0.18.1 · Restart`, which asks to confirm and calls `POST /api/sessions/:id/restart` (a refusal's reason shows in a toast); a worker from before restarts shows `chi sessions stop ID` instead. The info bar reads `continue → · archive · stop · delete` (`unarchive` on an archived one; no `continue →` on a link continued already, see *Session chains*); archiving the open session stays on it, with an Undo toast.
 
@@ -152,11 +152,18 @@ system message marked `kind: turn_note` (the UIs don't show it; they showed the
   the provider (cyber). …]` when the provider refused it.
 
 After you drop or undrop an item of the working set between turns (`/working-set drop KEY`, the web list's
-`drop`; [cli.md](cli.md#the-working-set)), the next turn starts with one line about it (`kind: working_set`,
+`drop`; [cli.md](cli.md#the-working-set)), or pin or unpin one under a strategy with the forget layer, the next turn
+starts with one line about it (`kind: working_set`,
 escaped like a context note; the UIs don't show it): `[WORKING SET: since your last turn the user dropped
 lib/cart.rb from your context: you are sent a stub instead of its outputs; read it again only if the task needs
 it.]`. Every op since the last turn joins that one line, and an undrop before the next turn takes its drop off it.
-The drop itself is saved on the entries (`edits`, kind `drop`), so `--resume`, rollbacks and forks keep it.
+An add (`/working-set add KEY`) asks the model in that line to load the item first (`the user added lib/tax.rb to
+your context: before anything else, load it with read "/abs/lib/tax.rb"`); an unadd before the next turn takes it
+off.
+The drop itself is saved on the entries (`edits`, kind `drop`), so `--resume`, rollbacks and forks keep it. A pin is
+the session file's `working_set_pins` (`[{"kind": "file", "key": "/abs/path"}]`, `[]` for none; kinds `file`,
+`memory`, `url`), not an edit: a respawned worker reads it, a continue and a fork (`ctx.sessions.fork`) copy it as
+they copy the toolkit, and a delegate child starts without. A rollback leaves it (it is not in the conversation).
 
 When the context window fills past 40% (then 60%, 80%), the native loop leaves a similar line (`kind: context`):
 `[CONTEXT: about 55% of the context window is in use (estimated; bucket=40plus). context moderate — prefer targeted
@@ -187,7 +194,7 @@ pbpaste | chi send 3fa2                             # the clipboard is the messa
 
 - With both stdin and `-m`, stdin is context: each line becomes a `> ` quote (as web annotations quote a selection), then a blank line, then the message. With only one, it goes in as is. A terminal on stdin is ignored. Both empty is a usage error; over 16 KiB is refused, never cut.
 - It goes through the same path as the web composer (`SessionManager.deliver_turn`): the worker's Bridge when it is up, so every attached UI shows it as your message (client id `cli:send`, shown like any user message); the input file when the worker is on its way out. During a running turn it is merged into that turn at the next step, like a message typed then, and cuts nothing. `--cut` asks for a cut, as `/cut TEXT` in a terminal does: a generation that has streamed only thinking for `steer.cut_after` seconds (per host/model: `steer_cut_after`) is cut (now, or once its thinking passes that), and the step starts again with the message. To an idle session `--cut` sends normally. `--cut --wait` into a running turn is refused like any `--wait` there (`busy: a turn is running`). `--queue` (not with `--cut`, a usage error) keeps the message for after the running turn: it runs as a turn of its own then (as `/queue TEXT` does), and a plain message sent after it still goes in at the running turn's next step. To an idle session it runs at once (it still goes as a queue, so a turn another client starts first never takes it as a steer). A worker older than queueing would steer it instead, so it is refused (to an idle session too) (`refused: this session's worker predates queueing, …; restart it`, exit 1) and nothing is sent; `chi sessions restart ID` and send again.
-- A session with no worker gets one started (like `--attach` or the web composer). A session open in a plain REPL (`--no-shared`) refuses it. Only sessions on this machine: Bridges listen on 127.0.0.1.
+- A session with no worker gets one started (like `--attach` or the web composer). A session open in a plain REPL (`--no-shared`) refuses it. Bridges listen on 127.0.0.1: another machine's sessions are reached through its chi web, `chi --remote NAME send …` ([Remote sessions](cli.md#remote-sessions)).
 - Fire and forget: it returns once the message is queued and never prints the answer; that shows in whatever is attached. A guardrail "ask" waits for a UI to answer it, so with nothing attached the turn stalls there until one attaches (`chi --attach ID`).
 - `--image PATH` (repeatable, up to 20) sends images with the message, as the web composer's chips do. Each file is read once before anything is sent (bmp, tiff and heic converted to png, large ones downscaled, as for `@path`); a missing file or one that isn't an image stops the send (exit 1; with `--wait --format json`, an `error` line) and nothing is sent; more than 20 is a usage error (exit 2). Each session gets its own copy in `<session>/images/`. Text is still required (`-m` or stdin; context alone counts), also with `--wait`. The session's model must see images: one known not to (the host's model list says text-only, `vision: false` in `models:` or `hosts:`, a native llama.cpp without a vision model) is refused before anything is sent, with the reason (`<id>  refused: gemma can't take images (…); send text only or switch the model (/model)`); the other sessions of the same send still get it, and the exit is 1. With `--new` nothing is started. When chi can't tell (a native host whose `/props` doesn't answer, a list that doesn't say), the message is sent as before and a text-only model fails the turn in the session. A running turn doesn't take images mid-turn: the message runs as the next turn, and the line says `(runs after the current turn)`. With `--new` the session starts idle with the message as its preview, then the message goes in as its first turn once its worker is up (`<id>  started with 1 image`); if the worker doesn't come up in 5 s the session is kept, with its id on the `failed:` line.
 - A session command runs as the command, as typed in a terminal: `chi send -m "/model qwen" 3fa2` switches the model (`sent as a session command`), and the model never sees the line. What counts is what the session's worker knows (the built-ins, `!cmd`, its bundles' commands); an unknown `/word` (`/usr/bin/env is missing`) goes in as a message. A UI-only command (`/stats`, `/exit`, `/recap`, …) is refused instead: the worker doesn't run it, so the line would reach the model as a prompt (`<id>  refused: /stats is a terminal and web command; use chi sessions stats <id8>`; exit 1, and nothing is sent). With `--new` a line starting with `/` or `!` starts the session idle and goes to its worker once it is up, which decides. With `--wait` a command has no reply to wait for: exit 0 at once, `<id>  sent as a session command: no reply to wait for …` on stderr (`{"status":"command",…,"detail":…}` with `--format json`); its output shows where the session is open.
@@ -243,7 +250,7 @@ A session can **continue** an earlier one: "the next run of the same routine" (a
 - **Its open delegates move to the new link** instead: each direct delegate that is running, waiting for an answer, has a live worker or a reply its parent wasn't given, or has such a delegate below it (checked again after the recap wait, so one delegated meanwhile moves too). It moves with its own delegates, stays unarchived, and from then on is the new link's: its card folds under the new link, its reports ring the new link (an idle one runs a wake turn for them, as for its own delegates), `delegate_result` and the `⑂` chip count it there, and what its parent was already told (`delegates.json`) and any report still waiting come along, so nothing is reported twice. A moved delegate gets a context note from `session chain`, `Your parent session is now 4b7e9a01 (…), the next link of its session chain: …`, as its system prompt keeps naming the parent it started with. The move writes `<child>/parent.json` (`{parent_id, from, at}`) beside the child's session file, never the file itself, so a live child worker saving its own copy changes nothing; every reader applies it (a later move overwrites it; it is never removed). A continue is **refused for an open delegate that can't move** (`SessionContinue::Refused`, naming it): one whose live worker runs an older chi (`older chi worker 0.46.1; restart it`: `chi sessions restart <id>`, or stop it) or that is open in a chi REPL (close it there). An older `chi web` or CLI still running shows a moved delegate under the archived link until it is restarted.
 - **If the continue fails part-way:** a new link that fails to start gives its moved delegates back before it is deleted (each gets a note saying so; its worker is stopped first, if one started, and a worker that won't stop is reported, the link left), with any report one of them rang it with meanwhile; the previous link, back in the lists, is woken for reports waiting. A continue that dies in the middle leaves a `move.json` in the new link's folder: the new link's next worker finishes that move (only the delegates it names, and without a second note to one already told) as it starts. Until the new link's own worker holds it, a ring from a moved delegate doesn't start another (a `starting` marker in its folder, which that worker removes; a stale one, over 60 s old or from a process that is gone, is ignored). An open delegate below an archived delegate refuses the continue (`under archived …`): unarchive that one, or archive this one.
 - **Refused too:** a link that is continued already (naming the link that continues it; continue that one, or `last:<id>`), a previous link whose folder is gone, and one whose model's host can't run it when no default model is configured to fall back to. A refusal starts nothing and archives nothing; a new link that fails to start puts back what was archived. Every refusal that can be known up front (the archive's ones included) comes before the recap wait. One continue of a session runs at a time (a lock in its folder; other chains don't wait), so a double click finds the first one's link and is refused, while a `last:<id>` continue that waited follows the chain to its new end.
-- **Web:** `POST /api/sessions` takes `continues: "<id, prefix or last:id>"`, with `idle: true` (a new link waiting for its first message, previewed by the previous link's, or `preview`) or a `prompt`, and `model` (or `model_name`) for the new link's model, but not `dir`, `llm_context` or `thinking` (400 `invalid_continues`: the previous link's are taken). 201 is the new session's summary, `continues` set, with `moved`: the ids of the delegates that moved to it (`[]` for none), and `model_warning`: the default-model fallback's warning, then any about the model id, joined by `; ` (`null` for none), and `opener`: the previous link's first typed message, in full, when that link continues one itself (`null` otherwise: a chain's first link's first message is its task); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a given model whose host config.yml doesn't have (or a fallback with no default model); 409 `continued` with `next_id` (the link that continues it already, which the page opens instead), `open_children` with `ids` (open delegates that can't move), `folder_gone`, `busy`, `scratch` or `owned_by_tui`. Every session summary carries `continues`.
+- **Web:** `POST /api/sessions` takes `continues: "<id, prefix or last:id>"`, with `idle: true` (a new link waiting for its first message, previewed by the previous link's, or `preview`) or a `prompt`, and `model` (or `model_name`) for the new link's model, but not `dir`, `llm_context`, `thinking`, `settings`, `toolkit`, `tools`, `no_tools` or `parent_answers` (400 `invalid_continues`: the previous link's are taken). 201 is the new session's summary, `continues` set, with `moved`: the ids of the delegates that moved to it (`[]` for none), and `model_warning`: the default-model fallback's warning, then any about the model id, joined by `; ` (`null` for none), and `opener`: the previous link's first typed message, in full, when that link continues one itself (`null` otherwise: a chain's first link's first message is its task); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a given model whose host config.yml doesn't have (or a fallback with no default model); 409 `continued` with `next_id` (the link that continues it already, which the page opens instead), `open_children` with `ids` (open delegates that can't move), `folder_gone`, `busy`, `scratch` or `owned_by_tui`. Every session summary carries `continues`.
 - **The page:** the info bar's `continue →` continues the open session (`continues: <id>, idle: true`; it reads `continuing…` through the recap wait) and opens the new link with an opener in the composer, not sent (a draft written in this session stays instead; one carried over from another session or the start page gives way to the opener, and the toast's **Restore draft** brings it back): the previous link's own first typed message when that link continues one (the 201's `opener`; a `!shell` line isn't taken), else `Continue where we left off.`. So whatever you sent on the last link comes back on the next one, and editing it once changes it for every later link; the previous link is archived, a toast says so (`Continued 3fa2c1d0 in 4b7e9a01; 3fa2c1d0 is archived; 1 open delegate moved`), and a moved delegate's card folds under the new link. When the previous link's model's host is gone the link starts on the default model and the toast carries the server's `model_warning` too, and then stays until closed. A fresh link (one with no turn yet, however it was made: `continue →`, `chi send --new --continues`, a reload) shows the model picker in its composer with the link's model, until its first turn starts (a failed or canceled first turn ends it too); a pick runs `/model <name>` in the link (a command bubble; the info bar follows) and changes neither the start page's remembered model nor its Recent list, and a Send right after it waits for the `/model` to be taken. A link a chi REPL owns, or one continued already, shows none. A link continued already has no `continue →`: its `→` link goes to the next link (a stale page's continue answered 409 `continued` opens `next_id`). A continue refused for open delegates that can't move shows a toast that names each one (its preview and what the server says to do: `older chi worker 0.46.1; restart it`, `open in a chi REPL; close it there`), each a link to its page; any other refusal shows the server's words. The info bar of a link carries `← 2026-10-08` (the previous link's day) and, on an earlier link, `2026-10-10 →`, each a link with its id, its full start (`2026-10-10 14:32`) and its preview in the tooltip; a neighbour that started on the open link's own day shows its time instead (`← 09:12`, `14:32 →`). A link made by `continue →` inherits the previous link's preview (and its title, if it has one) when it is created, so its card keeps its chain's title whatever opener it is sent, and its top bar and browser tab show its card's title. A link whose title is the opener and nothing else (a `chi send --new --continues` link whose first message is `Continue where we left off.`) shows its chain's first link's title instead, on its card, in the popover and in its info bar's title line, display only (its messages and data keep the opener; its own title when the first link is gone). The lists fold a chain into the card of its latest listed link, whatever the earlier links' archived state (typing in an archived link brings it back, folded there still), their delegates with them: the card's `↩ #N` chip (`#N of M` when later links aren't listed; its tooltip `Session chain: link N of M`) opens a popover of the other links, newest first (`#N`, its date, with its time (`2026-10-17 14:32`) when another link of the chain started the same day, its own title when it differs from the card's (a link inherits its chain's, so mostly it doesn't), else its recap's first sentence, else its preview, `archived`), a click opens one; the chip shows a live dot or `waiting` for a link that has a worker or waits on the user, and a waiting link puts its chain's card first. All sessions folds nothing while a search is typed or "include archived" is on: every link is a card of its own then, its chip `#N of M`, with its own delegates folded in, so a search finds an earlier link and its delegates.
 - **CLI:** `chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT]` (see *Starting a session*).
 - **Which link:** an id, a unique prefix, or `last:<id or prefix>`, the latest link of the chain that session is in. It walks the links that still exist: a deleted link in the middle (`chi sessions delete`, the retention sweep of an unarchived one) ends the walk before it, so `last:` of an earlier link then names that earlier link, and continuing it starts a second line beside the links after the gap; name a link after the gap instead. A trigger names the chain this way: `chi send` to an archived link would bring it back (a human's input), not continue the chain.

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.
 
+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
+only be held to the parent rules, never pass for the user's own. The worker's
+refusal (403 `parent_answer_refused`) comes back as it said it. A parent's
+`/continue yes` and a loosening `/parent-answers` sent through `chi web`'s create
+and turn routes are refused there too, held to that machine's config.yml.
+
 The worker checks it again with its own config.yml. The guardrails settings
 have no environment variables, and a worker drops any `SAMAGOTCHI_GUARDRAILS_*`
 it inherits; but a parent that sets `XDG_CONFIG_HOME` picks which config.yml a

data/lib/samagotchi/answer_command.rb

@@ -10,6 +10,7 @@ require_relative "guardrails/parent_policy"
 require_relative "cli/command"
 require_relative "cli/flags"
 require_relative "cli/parent_wait"
+require_relative "session_access/local"
 
 module Samagotchi
   # `chi answer`: answer the question a session's worker waits on (exit 3
@@ -68,11 +69,14 @@ module Samagotchi
       f.value "--format"
     end
 
-    def initialize(argv, stdout: $stdout, stderr: $stderr, state_dir: nil)
+    # @param access [SessionAccess::Local, nil] where the sessions are;
+    #   default this machine's, in +state_dir+
+    def initialize(argv, stdout: $stdout, stderr: $stderr, state_dir: nil, access: nil)
       @argv = argv.dup
       @stdout = stdout
       @stderr = stderr
       @state_dir = state_dir || Session.default_state_dir
+      @access = access || SessionAccess::Local.new(state_dir: @state_dir)
     end
 
     private
@@ -106,23 +110,23 @@ module Samagotchi
     def run_parsed(options)
       id = resolve(options[:id]) or return 1
       qid = options[:question].strip
-      session = Session.load(id, state_dir: @state_dir)
+      session = @access.show(id)
       pending = session.pending_question
       # Taken before the answer goes in, with the question answered as the
       # one already reported: the file keeps it until the turn thread
-      # wakes, and it must not come back as exit 3.
-      cursor = ReplyWait.newest_reply(id, state_dir: @state_dir)
-      baseline = ReplyWait.baseline_of(session, question_id: qid)
-      # The turn the answer is about: the one asking (running), or the one
+      # wakes, and it must not come back as exit 3. Its own_turn is the
+      # turn the answer is about: the one asking (running), or the one
       # whose continue offer stands. Its own reply is the answer's, not a
       # turn queued behind it; nil (an older worker): the next reply.
-      turn = ReplyWait.own_turn(session, session_dir: Session.session_dir(id, state_dir: @state_dir))
+      start = @access.prepare_wait(id, session: session, question_id: qid)
 
       if pending && pending.id.to_s == qid
         return failure(not_dismissable(pending)) if options[:dismiss] && ParentReport.continue?(pending)
 
         selected = selection(pending, options) or return @selection_status
-        refusal = parent_refusal(pending, selected, session)
+        # Remotely the worker's check alone (chi web passes chi answer's
+        # client_id on, and its 403 says why).
+        refusal = parent_refusal(pending, selected, session) unless @access.remote?
         return failure(refusal) if refusal
 
         posted = post(id, qid, selected, options)
@@ -134,7 +138,7 @@ module Samagotchi
       end
       # Answered here, or no longer open (answered elsewhere, or a newer
       # question): what comes next either way.
-      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout], turn: turn)
+      wait_for_reply(id, cursor: start.cursor, baseline: start.baseline, timeout: options[:timeout], turn: start.own_turn)
     end
 
     # The labels to send. A number is an option's place (1-based); an
@@ -163,6 +167,8 @@ module Samagotchi
     # with this process's config.yml tightened by the session file's own
     # parent_answers, and the question's own tags). A deny, text alone or a
     # dismissal always passes. The worker checks it again with its own.
+    # Machine-local (this machine's config.yml): remotely skipped here; the
+    # server forwards CLI_ANSWER and the worker's check refuses (P2).
     def parent_refusal(pending, selected, session)
       offered = Array(pending.options).map(&:to_s)
       indices = selected.map { |label| offered.index(label) }
@@ -177,23 +183,18 @@ module Samagotchi
         "(--option Stop --text WHY stops it)"
     end
 
-    # Post the answer (or the dismissal) to the live worker's Bridge.
+    # Post the answer (or the dismissal) to the live worker (its Bridge,
+    # through SessionAccess), marked as chi answer's.
     # @return [Integer, nil] an exit status when it didn't go in; nil to
     #   wait (it went in, or the question was no longer open: 409)
     def post(id, qid, selected, options)
-      client = BridgeClient.discover(id, session_dir: Session.session_dir(id, state_dir: @state_dir))
-      return failure(worker_gone(id)) unless client
-
-      reply = nil
-      2.times do
-        reply = if options[:dismiss]
-                  client.dismiss_question(id: qid)
-                else
-                  client.answer(id: qid, selected: selected, freeform: options[:text],
-                                client_id: ClientId::CLI_ANSWER)
-                end
-        break unless reply.status == 408
-      end
+      reply = if options[:dismiss]
+                @access.dismiss(id, question_id: qid)
+              else
+                @access.answer(id, question_id: qid, selected: selected, freeform: options[:text],
+                                   client_id: ClientId::CLI_ANSWER)
+              end
+      return failure(worker_gone(id)) unless reply
 
       case reply.status
       when 200 then nil
@@ -209,7 +210,7 @@ module Samagotchi
         return failure(worker_gone(id)) if reply.json&.dig("error") == "unknown_session"
 
         cant = options[:dismiss] ? "dismiss a question" : "take an answer"
-        failure(BridgeClient.stale_worker_message(id, cant: cant))
+        failure(BridgeClient.stale_worker_message(id, cant: cant, via: @access.invocation))
       else failure("the worker answered #{reply.status}: #{reply.json&.dig("detail") || reply.body}")
       end
     rescue Errno::ETIMEDOUT
@@ -229,7 +230,8 @@ module Samagotchi
     end
 
     def worker_gone(id)
-      "the worker is gone and the question with it; send the task again: chi send --wait -m \"…\" #{id}"
+      "the worker is gone and the question with it; send the task again: " \
+        "#{@access.invocation.command("send --wait -m \"…\" #{id}")}"
     end
 
     # @return [Integer] 1, after the line

data/lib/samagotchi/bridge.rb

@@ -172,6 +172,9 @@ module Samagotchi
       # One a worker that died left is not open.
       @pending_card.clear
       @pending_card_handle = @engine.subscribe(observer: @pending_card)
+      # #stop and #close_intake wake the acceptor through it: closing the
+      # listen socket doesn't cut a select on it short on Linux.
+      @wake_reader, @wake_writer = IO.pipe
       @accept_thread = Thread.new { accept_loop }
       @accept_thread.report_on_exception = false
       write_sidecar
@@ -198,12 +201,17 @@ module Samagotchi
       rescue StandardError
         nil
       end
+      wake_acceptor
     end
 
     # Stop the acceptor, release the socket and remove the sidecar, so clients
     # don't have to find it stale. Does not stop the owning turn. Joins the
     # acceptor thread so the process can exit cleanly (Ruby waits for a thread
     # blocked in IO.select at VM shutdown). Safe to call again.
+    #
+    # The sidecar goes before the open streams close: a client that
+    # reconnects as its stream ends (chi web's proxy, an attached TUI) then
+    # finds no worker, or the next one, never this one's dead port.
     def stop
       @mutex.synchronize { @stopped = true }
       begin
@@ -211,6 +219,7 @@ module Samagotchi
       rescue StandardError
         nil
       end
+      wake_acceptor
       @capture_handle&.unsubscribe
       @accumulator_handle&.unsubscribe
       @engine.running_turn_messages = nil
@@ -220,13 +229,14 @@ module Samagotchi
       # A turn post killed between its enqueue and its reply looks failed to
       # the web, which then queues the prompt again from the input file.
       await_answers(REQUEST_GRACE_SECONDS)
+      remove_sidecar
       @connection_threads.each { |t| t.kill rescue nil }
       @connection_threads.clear
       # Its relay watchers (RelayWatcher) end with it.
       watchers = @mutex.synchronize { (@relay_watchers || []).tap { @relay_watchers = [] } }
       watchers.each { |thread| thread.kill.join(RELAY_WATCHER_JOIN_SECONDS) }
       @accept_thread&.join(2)
-      remove_sidecar
+      [@wake_reader, @wake_writer].each { |io| io&.close rescue nil }
       nil
     end
 
@@ -360,17 +370,25 @@ module Samagotchi
       end
     end
 
+    # #stop or #close_intake: the acceptor's select returns now.
+    def wake_acceptor
+      @wake_writer&.write_nonblock(".", exception: false)
+    rescue IOError
+      nil # closed by an earlier #stop
+    end
+
     def accept_loop
       loop do
         break if stopped? || @server.closed?
 
         begin
-          rs, = IO.select([@server], nil, nil, 0.5)
+          rs, = IO.select([@server, @wake_reader], nil, nil, 0.5)
         rescue IOError
           break
         end
 
         next unless rs
+        break if rs.include?(@wake_reader)
 
         client =
           begin
@@ -1264,9 +1282,11 @@ module Samagotchi
 
     def write_sidecar
       # version: the chi this worker runs (chi update and the web's badge
-      # report older ones); features: what a client may ask of it.
+      # report older ones); features: what a client may ask of it; epoch:
+      # this worker's, as its event ids carry it.
       WorkerSidecar.new(port: @port, bind: @bind, session_id: @session_id, started_at: Time.now.iso8601(3),
-                        version: Samagotchi::VERSION, input_format: @input_format, features: FEATURES).write(session_dir)
+                        version: Samagotchi::VERSION, input_format: @input_format, features: FEATURES,
+                        epoch: @epoch).write(session_dir)
     rescue StandardError => e
       Log.warn(:bridge, "sidecar_write_failed", echo: "Bridge: failed to write #{WorkerSidecar::FILE}: #{e.class}: #{e.message}", error: e.class.name)
     end

data/lib/samagotchi/bridge_client/event_stream.rb

@@ -19,11 +19,22 @@ module Samagotchi
     # it without that event.
     #
     # With +rediscover+, a failed connection first looks for the session's
-    # live worker (its sidecar): a new one (a restart) is followed from its
-    # snapshot, announced by a synthetic `{"type" => "worker_changed",
-    # "port" => ...}` first, since its event ids start over. (A new worker
-    # on the old one's port is the plain reconnect: its Bridge can't replay
-    # the old ids and sends a reset.)
+    # live worker (its sidecar): a new one (a restart: a client with another
+    # BridgeClient#worker_key) is followed from its snapshot, announced by a
+    # synthetic `{"type" => "worker_changed", "port" => ...}` first, since its
+    # event ids start over. (A new worker on the old one's port is the plain
+    # reconnect: its Bridge can't replay the old ids and sends a reset.)
+    # Rediscovery may also give a reason ([nil, reason] while it retries,
+    # [:gone, reason] to stop): the stream_closed event carries the last one.
+    #
+    # Off by default, for a stream through chi web (SessionAccess::
+    # 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
+    # the Bridge's 15 s ping, for that long: a half-open connection,
+    # reconnected with the cursor).
     class EventStream
       DEFAULT_RECONNECT_DELAYS = [0.1, 0.25, 0.5, 1.0, 2.0].freeze
       # Long enough for a restarted worker to boot (its Engine, the plugins).
@@ -40,12 +51,26 @@ module Samagotchi
       # @param reconnect_delays [Array<Float>] sleeps between failed attempts;
       #   one more failure than there are delays gives up
       # @param rediscover [#call, nil] → a BridgeClient for the session's live
-      #   worker now, nil when there is none yet, or :gone to give up now
+      #   worker now, nil when there is none yet, or :gone to give up now;
+      #   or AttachLink#live_worker's pair, [one of those, a reason]
+      # @param epoch_watch [Boolean] see the class comment; the client takes
+      #   worker_key= then
+      # @param announce_retries [Boolean] see the class comment
+      # @param idle_timeout [Float, nil] seconds; nil: a quiet stream is
+      #   never cut (a Bridge on this machine)
       # @yieldparam event [Hash] string-keyed event
       def initialize(client, snapshot: true, client_id: nil, reconnect_delays: DEFAULT_RECONNECT_DELAYS, rediscover: nil,
-                     &on_event)
+                     epoch_watch: false, announce_retries: false, idle_timeout: nil, &on_event)
         @client = client
+        # The worker followed: a client that keeps its object across
+        # workers (epoch_watch) changes its key, not itself.
+        @worker_key = client.worker_key
         @rediscover = rediscover
+        @epoch_watch = epoch_watch
+        @announce_retries = announce_retries
+        @idle_timeout = idle_timeout
+        @retrying = false
+        @reason = nil
         params = []
         params << %w[snapshot 1] if snapshot
         params << ["client_id", client_id] if client_id
@@ -96,18 +121,21 @@ module Samagotchi
 
           if outcome == :events
             failures = 0
+            @reason = nil
             next
           end
 
+          announce_retry
           case rediscover_worker
           when :moved
             failures = 0
+            @reason = nil
             next
-          when :gone then return finish("unreachable")
+          when :gone then return finish(@reason || "unreachable")
           end
 
           failures += 1
-          return finish("unreachable") if failures > @reconnect_delays.size
+          return finish(@reason || "unreachable") if failures > @reconnect_delays.size
 
           sleep(@reconnect_delays[failures - 1])
         end
@@ -128,11 +156,15 @@ module Samagotchi
         yielded = false
         parser = SSEParser.new
         loop do
+          raise Errno::ETIMEDOUT if @idle_timeout && !sock.wait_readable(@idle_timeout)
+
           chunk = sock.readpartial(4096)
           parser.feed(chunk) do |frame|
             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
             @on_event.call(event)
@@ -172,18 +204,55 @@ module Samagotchi
       def rediscover_worker
         return nil unless @rediscover
 
-        found = @rediscover.call
+        found, reason = @rediscover.call
+        @reason = reason if reason
         return :gone if found == :gone
-        return nil if found.nil? || found.port == @client.port
+        return nil if found.nil? || found.worker_key == @worker_key
 
         @client = found
         @last_event_id = nil
-        @on_event.call({ "type" => "worker_changed", "port" => found.port }) unless closed?
+        moved(found.port, found.worker_key)
         :moved
       rescue StandardError
         nil
       end
 
+      # The frame +id+'s epoch (EventId: "<seq>-<epoch>") differs from the
+      # cursor's: a new worker answers the old cursor (its Bridge sends a
+      # reset next, or this is it). Announced before the frame.
+      def watch_epoch(id)
+        epoch = id.to_s[/-(\w+)\z/, 1]
+        cursor = @last_event_id.to_s[/-(\w+)\z/, 1]
+        return if epoch.nil? || cursor.nil? || epoch == cursor
+
+        @client.worker_key = epoch
+        moved(nil, epoch)
+      end
+
+      # Following another worker now: its key, and the worker_changed event
+      # (with its epoch for a stream through chi web).
+      def moved(port, key)
+        @worker_key = key
+        event = { "type" => "worker_changed", "port" => port }
+        event["epoch"] = key if @epoch_watch
+        @on_event.call(event) unless closed?
+      end
+
+      # A reconnect failed: said once, until a frame comes again.
+      def announce_retry
+        return if !@announce_retries || @retrying || closed?
+
+        @retrying = true
+        @on_event.call({ "type" => "stream_retrying" })
+      end
+
+      def announce_resumed
+        return unless @retrying
+
+        @retrying = false
+        @on_event.call({ "type" => "stream_resumed" })
+      end
+
       def finish(reason)
         @on_event.call({ "type" => "stream_closed", "reason" => reason }) unless closed?
       end

data/lib/samagotchi/bridge_client/stream_request.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Samagotchi
+  class BridgeClient
+    # The GET that opens an event stream, written by hand over a TCPSocket,
+    # and its response headers read up to the body: BridgeClient's stream
+    # (the worker's Bridge, `/session/:id/stream`), and any other server that
+    # serves the same SSE body at its own path with its own extra headers.
+    # TLS would plug in here.
+    module StreamRequest
+      # A reply's status line; its code is group 1 (BridgeClient::STATUS_LINE).
+      STATUS_LINE = %r{\AHTTP/1\.[01] (\d{3})}
+
+      module_function
+
+      # Open the stream and read past the response headers.
+      # @param host [String]
+      # @param port [Integer]
+      # @param path [String] the request path with its query
+      # @param last_event_id [String, nil] the reconnect cursor
+      # @param headers [Hash{String => String}] extra request headers, after
+      #   Last-Event-ID
+      # @param timeout [Float, nil] give up when the headers aren't all in by then
+      # @return [Array(TCPSocket, Integer, Hash), nil] the socket positioned
+      #   at the body, the HTTP status and the response headers (names in
+      #   lower case), or nil when the server can't be reached
+      def open(host:, port:, path:, last_event_id: nil, headers: {}, timeout: nil)
+        sock = TCPSocket.new(host, port)
+        sock.write(request(host: host, port: port, path: path, last_event_id: last_event_id, headers: headers))
+        deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
+        status = header_line(sock, deadline).to_s[STATUS_LINE, 1].to_i
+        received = {}
+        while (line = header_line(sock, deadline))
+          break if line.strip.empty?
+
+          name, value = line.split(":", 2)
+          received[name.strip.downcase] = value.to_s.strip if value
+        end
+        [sock, status, received]
+      rescue SystemCallError, SocketError, IOError
+        sock&.close rescue nil
+        nil
+      end
+
+      # The request's bytes.
+      # @return [String]
+      def request(host:, port:, path:, last_event_id: nil, headers: {})
+        lei = last_event_id.to_s.strip
+        last_event_line = lei.empty? ? "" : "Last-Event-ID: #{lei}\r\n"
+        extra = headers.map { |name, value| "#{name}: #{value}\r\n" }.join
+        "GET #{path} HTTP/1.1\r\nHost: #{host}:#{port}\r\nAccept: text/event-stream\r\n#{last_event_line}#{extra}" \
+          "Connection: keep-alive\r\n\r\n"
+      end
+
+      # One line of the response headers, or nil at EOF; raises
+      # Errno::ETIMEDOUT once +deadline+ (monotonic, nil: none) has passed. A
+      # line read in pieces, so a server that stops mid-line can't hold it.
+      def header_line(sock, deadline)
+        return sock.gets unless deadline
+
+        line = +""
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Errno::ETIMEDOUT unless remaining.positive? && sock.wait_readable(remaining)
+
+          char = sock.getc
+          return line.empty? ? nil : line if char.nil?
+
+          line << char
+          return line if char == "\n"
+        end
+      end
+    end
+  end
+end