samagotchi 0.62.0 → 0.64.0

data/docs/sessions.md

@@ -2,6 +2,8 @@
 
 Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`). Besides the messages and turn state, the JSON keeps `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
 
+**Input files:** a message for a session's worker waits in `input/<timestamp>.json` (`SessionInbox.write_input`: `prompt`, `client_id`, `enqueued_id`, and `images`, `no_interrupt` and `delivery` when they apply; `delivery` is written only for `"queue"`). While a turn runs, the worker merges them at each step boundary in name order, except a queued one or one with images: those wait for the turn's end and run one turn each, in name order, and a file after them still merges (`Worker#pending_input_drain`). A queue is sent only to a worker whose `bridge.json` names the `delivery` feature; an older one would steer it, so `SessionManager.deliver_turn` refuses it (409 `delivery_unavailable`), and any other 4xx the Bridge answers is a refusal too, never a fallback file (except a 413, a body over its size limit: that one still goes in as a file, its `delivery` kept). **Reply files:** a turn that ends with visible text leaves its reply in `output/<timestamp>.txt`, or `output/<timestamp>-<enqueued_id>.txt` when the turn ran an input file with an id (`SessionInbox.write_output`), and the session's `last_turn` keeps that `enqueued_id`; so a wait for one queued message (`chi send --queue --wait`, `ReplyWait`'s `turn:`) finds its own turn's reply or end, never another turn's. The names still sort by time, and every reader takes `*.txt`.
+
 **Retention (file-based, opt-out via env):**
 
 | Env | Default | Purpose |
@@ -23,9 +25,9 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **A worker outlives whoever started it:** a spawned worker leaves its spawner's process tree (it is forked again, in a session of its own, and reparented to init), so closing the terminal of a `chi web`, or a tool tearing down a background `chi send --wait` and its children, no longer takes the worker and its turn with it.
 
-**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}`, 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 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.
+**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 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 (so a command it was running says "stopped by the user"; only a bare signal to the worker makes it "stopped by a signal to chi"); 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. 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).
 
@@ -153,21 +155,22 @@ cancel during its thinking, it said it had never been asked.
 `chi send` is the other half of `chi note`: the text goes in as your message, the same as typing it in the attached terminal or the web composer, so a turn runs.
 
 ```sh
-chi send [-m TEXT] [--image PATH]... [--cut] (ID|PREFIX)...
+chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...
 chi send -m "is this the same bug?" 3fa2           # a message
 chi send --cut -m "stop, wrong file" 3fa2          # cut the running turn's long thinking
+chi send --queue -m "then update the docs" 3fa2    # a turn of its own after the running one
 chi send --image shot.png -m "why is this red?" 3fa2  # with an image
 pbpaste | chi send -m "is this the same bug?" 3fa2  # the clipboard quoted above the message
 pbpaste | chi send 3fa2                             # the clipboard is the message
 ```
 
 - 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`).
+- 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.
 - 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.
-- One line per session: `sent`, `sent as a session command`, `sent with 2 images`, `sent (goes in at the running turn's next step)`, with `--cut` `sent (cut in now)`, `sent (cuts in once the thinking passes 20 s)` or `sent (cutting is off; goes in at the next step)`, `sent (started its worker)`, `refused: …` or `failed: …`. Exit 0 when all were sent, 1 when any was refused, failed or not found, 2 for a usage error. There is no `--all`.
+- One line per session: `sent`, `sent as a session command`, `sent with 2 images`, `sent (goes in at the running turn's next step)`, with `--cut` `sent (cut in now)`, `sent (cuts in once the thinking passes 20 s)` or `sent (cutting is off; goes in at the next step)`, with `--queue` `sent (queued: runs after the current turn)`, `sent (the running turn had ended: it runs now)` or `sent (nothing running: it runs now)`, `sent (started its worker)`, `refused: …` or `failed: …`. Exit 0 when all were sent, 1 when any was refused, failed or not found, 2 for a usage error. There is no `--all`.
 
 The Automator action above works for messages too: swap its last line for `pbpaste | "$chi" send -m "what do you make of this?" $(print -r -- "$picked" | cut -f1)`.
 
@@ -190,10 +193,10 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
   (`SAMAGOTCHI_THINKING_LEVEL=low chi send --new …`) only reaches the worker this call spawns: when the session's
   worker is woken later (by `chi web`, a delivery) without that env, the level is gone. Use `--thinking`.
 - `--new` prints `<full id>  started` on stdout. With `--wait` that line (and the `sent` line for an existing session) goes to stderr, so stdout is exactly the answer: the reply of the turn the message started, in full. It is the worker's `output/` file, the same one `delegate` reads; a turn that ends with only tool calls and no text has none.
-- `--wait` takes one session: `--new` or one id. A session with a running turn is refused (`busy: a turn is running; wait or attach`, exit 1): the message would run after it, and its reply would come back as the answer.
+- `--wait` takes one session: `--new` or one id. A session with a running turn is refused (`busy: a turn is running; wait or attach`, exit 1): the message would merge into it, and its reply would come back as the answer. `--queue --wait` is the way in: the message runs as a turn of its own after the running one, and the wait is for that turn alone (the ack's `enqueued_id` names its reply file and its `last_turn`), so the running turn's reply and end, and a question it asks meanwhile, are not the answer (it keeps waiting through them; its `--timeout` still applies); a question its own turn asks is (exit 3). Two queued waits each get their own turn's answer. A session waiting for an answer is still refused. `--format json` adds `delivery`: `queue`, or `next_step` when the running turn ended before the message went in (it then ran at once, and the answer is still its own).
 - Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question, a guardrail approval, or the step-limit question: see [chi as a sub-agent](sub-agent.md#the-step-limit)), and the session keeps waiting: stderr gets the whole question (`waiting for an answer (approval): …`, its text, the numbered options, whether free text is allowed) and how to answer it (`chi answer ID --question QID --option N`, or `chi --attach ID`, the web); 4 `--timeout S` passed with the turn still running (it goes on; wait again); 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, or the session was stopped; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
 - `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
-- `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
+- `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. With a turn running, that turn's reply (its `interrupted_turn` mark names it), not a turn's queued behind it; with the step-limit question standing, the reply of the turn its Continue runs. With neither (or a worker whose `bridge.json` lacks `turn_ids`), the next reply of any turn. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
 - `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model, LLM context and thinking level, so `--dir`, `--model`, `--llm-context*` and `--thinking` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1.
 - The 16 KiB cap applies: `git diff | chi send --new …` on a big diff is refused; name the branch in the message instead and let the session read it.
 - A session nobody attaches to stalls at its first question or guardrail ask until someone answers it (`chi answer`, the web, `chi --attach`), and its worker stays up meanwhile: it doesn't idle-exit while a question waits (`chi sessions list` shows it as `waiting`; `chi sessions stop ID` frees it). Otherwise it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
@@ -220,7 +223,7 @@ A session can **continue** an earlier one: "the next day of the same routine" (a
 
 The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail like an `execute` result. Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `delegated by` in its info bar; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
 
-- `delegate(task, model:, session:, cwd:, wait:, timeout:)`: starts a child and, by default, waits for its reply. `wait: false` is the usual way for work that takes a while, several children side by side, or to keep talking with the user: it returns at once, the parent ends its turn or works on, and the reply comes back by itself as a *delegate report* (below), in a turn of its own if the parent is idle. The tool descriptions tell the model so, and to wait (`wait: true`, `delegate_result`) only when its turn can't go on without the reply. `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting. With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one.
+- `delegate(task, model:, session:, cwd:, wait:, timeout:)`: starts a child and, by default, waits for its reply. `wait: false` is the usual way for work that takes a while, several children side by side, or to keep talking with the user: it returns at once, the parent ends its turn or works on, and the reply comes back by itself as a *delegate report* (below), in a turn of its own if the parent is idle. The tool descriptions tell the model so, and to wait (`wait: true`, `delegate_result`) only when its turn can't go on without the reply. `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting. With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one. The wait (`wait: true`, a later `delegate_result`) and the delegate report are for the reply of the child's turn the follow-up went to: its running turn, which it merges into, or the turn of its own it runs when the child is idle (`turn` in `delegates.json`, set when the child's worker names `turn_ids`), not a newer reply of a turn queued behind it. A follow-up merged as a steer into a turn the child started at that moment (a wake, a reminder, another message) gets that turn's reply or question. A child on its first turn, or with an older worker, gives its next reply, as before.
 - `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's.
 - `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child (`timeout` as for `delegate`: 0 checks once and returns at once). The reply comes back once; a later call waits for the next one. After `wait: false` it isn't needed: the report brings the reply.
 - A wait that timed out or was canceled still gets its delegate report: neither moves the parent's cursor, so the child's reply comes as a report when its turn ends. The result says so (`chi brings its reply here by itself as a delegate report …`; with `queue`, that it joins the next step or turn) and that `delegate_result` waits again only if the turn needs the reply now. A parent that gets no reports (`session.delegate_reports: off`, a `--no-shared` REPL, `--non-interactive`) is told `delegate_result <id> waits again` instead, and `wait: false`'s result says `delegate_result waits for its reply`.

data/docs/sub-agent.md

@@ -13,17 +13,28 @@ worker keeps the turn paused. The parent answers with `chi answer`, from what it
 knows or after asking its own user, and chi goes on from there. The model gets
 the answer as its tool result, as if you had answered in the web.
 
+The other direction, chi sending a part of its work to a Claude Code session
+you already work with (to validate, as context, or with a question), is the
+[claude-peer bundle](plugins.md#the-claude-peer-bundle): Claude pairs with the
+chi session, chi's `claude_send` tool or `/claude` writes to Claude's inbox,
+and Claude's answer comes back as attached context.
+
 ## The commands
 
 ```sh
 chi send --new --wait --format json [--dir D] [--model M] [--timeout S] -m "task"
 chi send --wait --format json [--timeout S] [-m "follow-up"] ID
+chi send --queue --wait --format json [--timeout S] -m "follow-up" ID
 chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]
 chi answer ID --question QID --dismiss [--timeout S] [--format json]
 ```
 
 `chi answer` waits after answering, the same way `chi send --wait` does, so the
-next question comes back as exit 3 again. `--option` is 1-based or the label,
+next question comes back as exit 3 again. What it waits for is the answered
+turn: the turn that asked (or, for the step-limit question, the turn it
+continues), so its reply comes back, not that of a turn queued behind it.
+A worker older than this (its `bridge.json` doesn't name `turn_ids`) gets
+the session's next reply instead. `--option` is 1-based or the label,
 repeated on a multi-select question. `--text` is free text (where the question
 allows it) or the reason for a Deny. `--dismiss` leaves the question
 unanswered: the model doesn't do what it asked about and finishes its reply.
@@ -37,7 +48,7 @@ Exit codes, both commands:
 | 0 | `not_continued` | (`chi answer`) a Stop answered the step-limit question; the turn's work so far stays |
 | 3 | `question` | chi waits for an answer: `question`, `answer_with` |
 | 4 | `running` | `--timeout` passed; the turn goes on, wait again |
-| 1 | `failed`, `canceled`, `limit`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web or `chi sessions stop`; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
+| 1 | `failed`, `canceled`, `limit`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web; `session_stopped`: a session stop, `chi sessions stop` or the web's; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
 | 2 | (no JSON) | usage error, or an option the question doesn't offer |
 | 130 | `running` | Ctrl-C; the turn goes on |
 
@@ -133,8 +144,18 @@ answers from any local process.
   isn't sent: it exits 1 with the `chi answer` command for the question. The
   step-limit question is the exception: it waits between turns, so a message
   goes in, drops it and starts a new turn.
+- A follow-up to a session whose turn still runs (`busy: a turn is running`,
+  exit 1, say you waited on with `--timeout` and got exit 4) goes in with
+  `chi send --queue --wait -m "…" ID`: it runs as a turn of its own after the
+  running one, and the wait is for that turn's answer alone, never the running
+  turn's (`--format json` adds `"delivery": "queue"`). A question the running
+  turn asks meanwhile isn't yours: the wait goes on through it (until your
+  `--timeout`); one the queued turn asks comes back as exit 3. `chi answer`
+  on the running turn's question gets that turn's reply, not your queued one.
 - `chi send --wait ID` with no message waits past a question already reported
-  (the step-limit question too), until someone answers it.
+  (the step-limit question too), until someone answers it. It waits for the
+  turn running when it starts (or the one the step-limit question continues),
+  and prints that turn's reply, not a queued one's after it.
 - An answer to a question that is no longer open (you answered it in the web
   first) isn't sent; `chi answer` says so and waits for what comes next. Its
   JSON then has `"answered_here": false` (absent when the answer went in), so
@@ -181,6 +202,8 @@ Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
 Run each chi command on its own, nothing chained after it: the exit code comes
 back with the output. Talk to chi only through these commands; never call its
 Bridge or web API directly. Follow-ups in the same session:
-`chi send --wait --format json --timeout 500 -m "…" <session_id>`.
+`chi send --wait --format json --timeout 500 -m "…" <session_id>`; if that says
+`busy` (a turn still runs), add `--queue`: the follow-up runs after that turn
+and you get its own answer.
 Keep `--timeout` under your shell tool's limit (Claude Code: 600 s per call).
 ```

data/docs/testing.md

@@ -15,15 +15,24 @@ bug) or a broken spec: fix it, or disable that line with the reason (`# rubocop:
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 
-The web specs run in plain node. One that loads lit-html (`turn_view.js`, `thinking_chip.js`, `llm_context_chip.js`,
-`info_bar.js`, `lists_view.js`, `context_chips.js`, `families_view.js`, `chains.js`, `vendor/lit-html.js`) needs a DOM: `import "./dom_shim.js";` as its first import (happy-dom, a
-devDependency only, never shipped; about 0.3 s per spec file that loads it). The shim's `htmlOf(nodes)` and `canon(html)` compare markup
-without lit's marker comments. happy-dom 20 picks the wrong option of a `<select>` whose options lit inserted with
+The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_view.js`,
+`turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
+`question_cards.js`, `stream_handlers.js`, the chips, `info_bar.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
+`chains.js`, `vendor/lit-html.js`) needs a DOM: `import "./dom_shim.js";` as its first import (happy-dom, a devDependency only,
+never shipped; about 0.3 s per spec file that loads it; lit reads `document` as it loads). The shim's `markupOf(template)`,
+`htmlOf(nodes)` and `canon(html)` compare markup without lit's marker comments; the DOM writes text with only `&`, `<`, `>`
+escaped (a `"` in text stays `"`) and an attribute with `&` and `"` escaped. happy-dom 20 picks the wrong option of a `<select>` whose options lit inserted with
 `?selected`: read the option marked `selected` (`option[selected]`), not `select.value`; the browser follows the mark.
 A select bound with `.value` instead reads right in both, but lit sets it before the options exist on a first render:
 `llm_context_chip.js`'s `renderForm` draws twice then. Assert a kept node with `assert.ok(a === b)`: a failing
 `assert.equal` on two DOM nodes inspects the whole DOM (huge output, can stall the run).
 
+Where a composer line goes is decided twice, in Ruby (`ComposerRoute`, both terminals) and in the web
+(`composer.js#routeComposerLine`). `spec/fixtures/composer_routes.json` holds the cases both answer: rspec
+(`spec/composer_route_spec.rb`) and `npm test` (`spec/web/public/composer.test.js`) run every row. A change to
+either router adds its row there; a row where a UI differs on purpose (or a found divergence) carries a `web` or
+`repl` override and a `note`.
+
 ## While you work: affected specs
 
 ```sh

data/lib/samagotchi/answer_command.rb

@@ -112,6 +112,10 @@ module Samagotchi
       # 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
+      # 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))
 
       if pending && pending[:id].to_s == qid
         return failure(not_dismissable(pending)) if options[:dismiss] && ParentReport.continue?(pending)
@@ -129,7 +133,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])
+      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout], turn: turn)
     end
 
     # The labels to send. A number is an option's place (1-based); an

data/lib/samagotchi/answer_refs.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "log"
 require_relative "ref"
+require_relative "row_refs"
 
 module Samagotchi
   # One ref on the answer: the text it stands for (+match+, what the page
@@ -27,30 +28,20 @@ module Samagotchi
     MAX_MATCH = 500
 
     # A hook's {match:, kind:, target:, label:, actions:}, or a stored
-    # entry (String or Symbol keys, nested ones too). A file ref's relative
-    # path is resolved against +cwd+, so the stored path is absolute; with
-    # no +cwd+ it is refused. An absolute path stays as given.
+    # entry (String or Symbol keys, nested ones too). A file ref is held to
+    # the session's folder as a plugin row's is (RowRefs.inside, plan D7):
+    # +roots+ is RowRefs.roots of it; a relative path is resolved against
+    # it (+relative+; a stored one was stored absolute, so it is dropped),
+    # a path outside it refused, and the path kept under its real
+    # spelling. With no folder (no +roots+), an absolute path stays.
     # @raise [ArgumentError] anything invalid
-    def self.from(value, cwd: nil)
+    def self.from(value, roots: [], relative: true)
       raise ArgumentError, "a ref is a Hash {match:, kind:, target:, label:, actions:}" unless value.is_a?(Hash)
 
       value = value.transform_keys(&:to_sym)
       ref = Ref.new(kind: value[:kind], target: value[:target], label: value[:label], actions: value[:actions] || [])
-      new(match: value[:match], ref: absolute(ref, cwd))
+      new(match: value[:match], ref: RowRefs.inside(ref, roots, relative))
     end
-
-    def self.absolute(ref, cwd)
-      return ref unless ref.kind == Ref::FILE
-
-      path = ref.target[:path]
-      return ref if File.absolute_path?(path)
-      raise ArgumentError, "relative path, no session folder" if cwd.to_s.empty?
-
-      # absolute_path, not expand_path: a leading ~ is a name, never a home.
-      Ref.new(kind: ref.kind, target: ref.target.merge(path: File.absolute_path(path, cwd.to_s)), label: ref.label,
-              actions: ref.actions)
-    end
-    private_class_method :absolute
   end
 
   # The refs after_turn hooks attach to a turn's answer (event[:refs]),
@@ -71,12 +62,13 @@ module Samagotchi
     # Stored refs (+raw+, as read from session.json or a snapshot), each
     # rebuilt and checked again, the caps applied; what isn't valid any
     # more is dropped. Never raises: a reload must show the conversation.
-    # A relative file path is dropped (there is no folder to resolve it).
+    # A relative file path is dropped (it was stored absolute), and with
+    # +cwd+ (the session's folder) a file outside it.
     # @return [Array<Hash>] the refs to send ({match:, kind:, target:, …})
-    def self.for_display(raw)
+    def self.for_display(raw, cwd: nil)
       return [] if raw.nil?
 
-      kept = new([{ role: "model", KEY => raw }], cwd: nil).to_a
+      kept = new([{ role: "model", KEY => raw }], cwd: cwd).to_a
       dropped = raw.is_a?(Array) ? raw.length - kept.length : 1
       Log.debug(:web, "display_refs_dropped", count: dropped) if dropped.positive?
       kept
@@ -92,7 +84,7 @@ module Samagotchi
     def initialize(messages, cwd:)
       last = Array(messages).last
       @target = last if last.is_a?(Hash) && (last[:role] || last["role"]).to_s == "model"
-      @cwd = cwd
+      @roots = RowRefs.roots(cwd)
       @refs = []
       @seen = {}
       @bytes = 2 # the list's []
@@ -149,7 +141,7 @@ module Samagotchi
       unknown = value.keys - KEYS
       return reject(hook, "has unknown keys #{unknown.map(&:to_s).inspect}") unless unknown.empty?
 
-      entry = AnswerRef.from(value, cwd: @cwd).to_h
+      entry = AnswerRef.from(value, roots: @roots).to_h
       return true if @seen.key?(entry)
       return over_cap(hook, "#{MAX_REFS} refs") if @refs.length >= MAX_REFS
 
@@ -163,11 +155,11 @@ module Samagotchi
     end
 
     # A stored entry back in the list, checked again (a relative path is
-    # dropped: it was stored absolute). Duplicates and what is over the
-    # caps go quietly.
+    # dropped: it was stored absolute; so is a file outside the folder).
+    # Duplicates and what is over the caps go quietly.
     # @return [Boolean] kept
     def keep(raw)
-      entry = AnswerRef.from(raw, cwd: nil).to_h
+      entry = AnswerRef.from(raw, roots: @roots, relative: false).to_h
       return false if @seen.key?(entry) || @refs.length >= MAX_REFS
 
       size = JSON.generate(entry).bytesize + (@refs.empty? ? 0 : 1)

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -226,6 +226,7 @@ module Samagotchi
         when :turn_enqueued
           queued = { enqueued_id: event[:enqueued_id], client_id: event[:client_id], prompt: event[:prompt] }
           queued[:images] = event[:images] if event[:images]
+          queued[:delivery] = event[:delivery] if event[:delivery]
           @queued << queued
         when :recap_ready
           # One collected just as a turn started describes the chat before it.

data/lib/samagotchi/bridge.rb

@@ -29,6 +29,7 @@ require_relative "version"
 require_relative "worker_sidecar"
 require_relative "relay_verifier"
 require_relative "relay_watcher"
+require_relative "reply_wait"
 require_relative "tools/task_runtime"
 
 module Samagotchi
@@ -52,8 +53,9 @@ module Samagotchi
     DEFAULT_RING_CAPACITY = 256
     DEFAULT_HEARTBEAT_INTERVAL = 15.0
     # Cancel reasons a client may name (the web sends user, an attached TUI
-    # ctrl_c); anything else is :manual, so client input never mints symbols.
-    CANCEL_REASONS = %w[manual user ctrl_c].freeze
+    # ctrl_c, a session stop session_stopped: SessionManager.stop_session);
+    # anything else is :manual, so client input never mints symbols.
+    CANCEL_REASONS = %w[manual user ctrl_c session_stopped].freeze
     # How long #stop waits for requests it is answering (not open streams).
     REQUEST_GRACE_SECONDS = 1.0
     # How long #stop waits for each killed RelayWatcher thread to end.
@@ -180,6 +182,25 @@ module Samagotchi
       raise e
     end
 
+    # Raised on a connection thread whose request would queue something
+    # (a turn, a command, an exit) after #close_intake: the connection
+    # closes unanswered, as #stop's kill of a request still waiting did.
+    class IntakeClosed < StandardError; end
+
+    # With the event log held (the worker leaving: Worker#leave_idle,
+    # #leave_on_request): no connection is accepted and no request queues
+    # a turn, a command or an exit from here on. #stop, called once the log
+    # is let go, does the rest: a request that waited on the log then ends
+    # at once instead of holding #stop for its REQUEST_GRACE_SECONDS.
+    def close_intake
+      @mutex.synchronize { @stopped = true }
+      begin
+        @server&.close
+      rescue StandardError
+        nil
+      end
+    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
@@ -394,7 +415,7 @@ module Samagotchi
         log_request(method, request[:path], started)
         break if close_after_request?(headers)
       end
-    rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+    rescue Errno::EPIPE, Errno::ECONNRESET, IOError, IntakeClosed
       nil
     rescue StandardError => e
       # The thread doesn't report (report_on_exception = false): log it.
@@ -476,7 +497,11 @@ module Samagotchi
     # task_stop: POST tasks/stop (#handle_task_stop), the web's stop-task button.
     # reparent: the worker reads Session::PARENT_FILE (its rings, each turn's
     # start), so a continue may move it to the chain's new link (ChildMove).
-    FEATURES = %w[restart task_stop reparent].freeze
+    # delivery: POST /turn runs every Delivery value; a queue waits for the
+    # turn's end (Delivery::QUEUE_FEATURE). A worker without it would steer.
+    # turn_ids: the running turn's checkpoint mark, a continue turn and a
+    # Stop's last_turn carry the turn's enqueued_id (ReplyWait.own_turn).
+    FEATURES = ["restart", "task_stop", "reparent", Delivery::QUEUE_FEATURE, ReplyWait::TURN_IDS_FEATURE].freeze
 
     # The routes, by method and what follows /session/:id/: a handler takes
     # the session id and the request body and returns [headers, status, body].
@@ -728,6 +753,7 @@ module Samagotchi
       # A card's action: the UIs leave its line out (the card is the echo).
       command = QueuedCommand.mint(line, client_id: client_id, card: card)
       queued = @engine.synchronize_events do
+        raise IntakeClosed if stopped?
         next false if expired?("command_expired", deadline, sid: session_id, client_id: command.client_id)
 
         queue_command_locked(command)
@@ -777,6 +803,7 @@ module Samagotchi
       return BAD_DEADLINE unless deadline_valid?(deadline)
 
       reason = @engine.synchronize_events do
+        raise IntakeClosed if stopped?
         next :expired if expired?("exit_expired", deadline, sid: session_id, client_id: client_id)
 
         @on_exit_request.call(client_id, **options)
@@ -847,18 +874,25 @@ module Samagotchi
       enqueued_id = SecureRandom.uuid
       # Before it is queued: a drain after this may have taken it (#cut_for_steer).
       epoch = @engine.input_epoch
+      # Whether a queue waits for a running turn: read with the write under
+      # the event log, so no :turn_started or :turn_completed falls between.
+      # To an idle worker the queued file simply runs as the next turn.
+      queued_behind_turn = false
       # Write and announce with the event log held: the worker can't emit
       # this turn's :turn_started (or merge it mid-turn) before
       # :turn_enqueued, and a failed write announces nothing.
       enqueued = @engine.synchronize_events do
+        raise IntakeClosed if stopped?
         next :expired if expired?("turn_expired", deadline, sid: sid, client_id: client_id)
 
+        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|
           next unless ok
 
           enqueued_event = { type: :turn_enqueued, enqueued_id: enqueued_id, client_id: client_id, prompt: prompt.to_s }
           enqueued_event[:images] = images unless images.empty?
+          enqueued_event[:delivery] = Delivery::QUEUE if queued_behind_turn
           @engine.announce(enqueued_event)
           @on_input&.call
         end
@@ -874,7 +908,9 @@ module Samagotchi
       # the running turn's next step.
       cut = nil
       cut = @engine.cut_for_steer(Steer.source_for_client(client_id), epoch: epoch) if images.empty? && Delivery.cut?(delivery)
-      ack = { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id, delivery: delivery }
+      # A queue to an idle worker is a turn now: the ack says next_step.
+      ack_delivery = Delivery.queue?(delivery) && !queued_behind_turn ? Delivery::NEXT_STEP : delivery
+      ack = { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id, delivery: ack_delivery }
       ack[:cut] = cut.to_s if cut
       ack[:cut_after] = @engine.steer_cut_after if cut == :waits
       [{}, 202, ack]

data/lib/samagotchi/bundles/claude-peer/manifest.yml

@@ -0,0 +1,22 @@
+---
+name: claude-peer
+version: 0.1.0
+scope: system
+description: "Pair this session with a Claude Code session you work with: the claude_send tool and /claude send it a part of the work (a plan step, a diff, a finding) to validate or as context, and Claude's answer comes back as the claude-review context; /claude install-skill installs Claude's chi-peer skill, which pairs"
+trust_level: reviewed
+files:
+  skill_claude_peer.md:
+    sha256: sha256:dff0175d0370f43920daf5ecbb81315fdd2c7d8063a33fbefc75c7d0e7312993
+    description: "Send a part of the work to the paired Claude Code session (claude_send): only when the user asks; validate, context or question; Claude's answer comes as the claude-review context"
+plugin:
+  file: plugin.rb
+  sha256: sha256:bf5a95eb125ba4831466e177295bdaba1f625e255b027cea1e59992310d8300e
+scripts:
+  pair: sha256:033f1fc6a644950b57e71865253526a0a487bb4c9fd5a61bb89d031b65f40417
+  chi-peer-SKILL.md: sha256:f35f726b1a86091ff69d289e8dd58794ac6f44879a63630fcc88d69867c56e20
+# Two things need chi 0.63.0, and the bundle works without them on 0.62:
+# ctx.context.list's summary: (the /claude card's last answer; without it
+# the card shows no summary), and a pushed source's first wake: true push
+# waking the session (on 0.62 Claude's first answer arrives as a note
+# without waking; later ones wake).
+requires_chi: ">= 0.62.0"