samagotchi 0.108.0 → 0.110.0

data/docs/plugins.md

@@ -756,7 +756,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.settings` | the bundle's settings, frozen: config.yml's `bundles: <bundle>:` with the session's own `--set` values laid over it ([Per-session settings](#per-session-settings)); the config alone until the session is bound (in `register` and `chi.ctx`) |
 | `ctx.data_dir` | `$XDG_STATE_HOME/samagotchi/plugins/<bundle>/`, created on first use. A session's own state goes in `sessions/<id>.json` or `sessions/<id>/` there: chi removes it when the session is deleted, discarded or pruned |
 | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |
-| `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); the REPL's is the conversation before that turn |
+| `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); the REPL's is the conversation before that turn. An entry may carry `at`, when it happened (docs/sessions.md, Message times) |
 | `ctx.messages_partial?` | whether `ctx.messages` leaves out a running turn (the REPL mid-turn), so a plugin can say what its answer is about |
 | `ctx.prompt_files` | the files whose text is in the session's system prompt now: the AGENTS.md chain (the work tree top down to the cwd) and the appended files (`append_system_prompt:`, `--append-system-prompt`); absolute paths, in prompt order, `[]` before the first build |
 | `ctx.notify(text, level: :info, fallback_for: nil)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command). `fallback_for: :display` marks a line that repeats the answer's display (`event[:present]`), which a UI that renders the display leaves out (`fallback_for: :editor`: a file the viewer could open from a ref in its editor): see [Hooks](hooks.md#what-a-hook-can-do-the-runtime). The keyword needs chi 0.35.0 (it raises on an older chi) |

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`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). 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).
 
+**Message times:** an entry of `messages` may carry `at`, when it happened: a local-offset ISO time with milliseconds (`2026-10-24T14:32:05.120+02:00`). User prompts, lines merged into a turn and steers, reminders, context and task notes, and the model's replies have one (a note's is its `created_at`); tool results, `!cmd` messages and chi's own turn notes don't, nor does anything saved before chi stamped messages (no backfill). It is for the UIs only (the gap dividers, a bubble's time): it never goes to the model, so it changes nothing in the requests or their prompt cache. The one time the model reads is the reminders': due reminders go into a turn as a system message headed `[SYSTEM: REMINDERS DUE 2026-10-24 14:32 local]` (the turn's local time; `ReminderQueue#inject!`), written into the saved content then, so a later request sends the same text.
+
 **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). A session command recognized in a file runs without a turn; its outcome is kept at `input/settled/<enqueued_id>` (`completed`, `failed` for a command error, `canceled` with `cancel_reason` `busy` or `dropped` for one refused mid-turn or dropped as the worker left; `origin: command`) so `chi send --wait` ends instead of waiting for a turn that will not run, its detail saying `the command failed` or `the command was refused (busy)` rather than a turn's words. **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`.
 
 **Removing a queued message:** a message queued for after the running turn (`chi send --queue`, the web's Alt+Enter, `/queue TEXT` in a terminal), or one with images (it waits for the turn's end too), can be taken back while it still waits: the worker's Bridge (`POST /session/:id/turn/dequeue {enqueued_id}`, the `unqueue` feature) deletes its input file and every UI drops it (`:turn_dequeued`). It is a race with the turn's end, decided by the same rename the worker uses to take the file: once a turn took it the answer is `409 already_started` (it runs), and an id the worker no longer knows is `404 unknown_enqueued_id`. A plain message sent without `--queue` is not removable (`409 not_queued`): a running turn's next step may take it at any moment. A wait for its turn (`chi send --queue --wait`, a delegate follow-up's wait) ends at once with `removed` (the tombstone `input/removed/<enqueued_id>` says so), and a `chi -p` run whose queued prompt went ends with exit 1. The `200` carries the removed `prompt`: the web and the attached terminal put it back into the composer to edit (not its images). The images a removed message named stay in the session's `images/`. Not removable: a queued session command (`/queue /model x`: it waits in the worker, not in `input/`), a message in a stopped worker's inbox (the next worker runs it), and the plain REPL's (`--no-shared`) own queue.
@@ -29,7 +31,7 @@ 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, enqueued_id}` (`enqueued_id`: the input the turn runs, so any process can tell which turn is running; a continue turn carries its offer turn's), written as the turn starts, at the loop's first iteration boundary and then at most every 10 s (`updated_at` moves with it). The turn's end saves the real messages without the mark. A worker that died without ending its turn (SIGKILL, a crash of the process) leaves the mark, and loses what came after its last written boundary: at most the last 10 s of steps, plus the step in flight. Each checkpoint write also saves the turn's metrics so far to `analytics.json` (tokens, speeds, timings, its finished tool calls), as the record a killed turn leaves: canceled, `cancellation_reason: worker_stopped`; the turn's own end writes over it. The next worker to start for the session (a `chi send`, `--resume`, `--attach`, the web), or a `--no-shared` REPL resuming it, settles the turn before anything else (`TurnCheckpoint.settle`, log `interrupted_turn_settled`): a note `the previous turn was cancelled (worker-stopped) after Ns` goes at the tail, the status goes idle and the mark goes; `last_turn` stays the previous turn's (a new one saved before the turn a `chi send --wait` woke the worker for would end that wait at once); the dead turn's end is recorded under its `enqueued_id` instead, in `<id>/input/settled/<enqueued_id>` (a `last_turn` record: canceled, `cancel_reason: worker_stopped`), which only a wait for that very turn reads (`chi send --queue --wait`, a `chi send --wait -m` to an idle session or `--new`, `chi send --wait ID --turn`, a continue's wait): it ends `canceled` with `cancel_reason: worker_stopped`, detail "its worker exited mid-turn", instead of timing out. A reply the turn wrote before its worker died is still its answer. The session shows the turn's prompt and steps with that note; the dead turn is not run again, and the model reads on its next turn that it was cut.
+**A worker killed mid-turn:** while a turn runs, its worker keeps it on disk (`TurnCheckpoint`): the session file has the turn so far (the prompt from the turn's start, then the finished tool steps and lines merged into it) and `interrupted_turn: {id, started_at, at, iteration, enqueued_id}` (`enqueued_id`: the input the turn runs, so any process can tell which turn is running; a continue turn carries its offer turn's), written as the turn starts, at the loop's first iteration boundary and then at most every 10 s (`updated_at` moves with it). The turn's end saves the real messages without the mark. A worker that died without ending its turn (SIGKILL, a crash of the process) leaves the mark, and loses what came after its last written boundary: at most the last 10 s of steps, plus the step in flight. Each checkpoint write also saves the turn's metrics so far to `analytics.json` (tokens, speeds, timings, its finished tool calls), as the record a killed turn leaves: canceled, `cancellation_reason: worker_stopped`; the turn's own end writes over it. The next worker to start for the session (a `chi send`, `--resume`, `--attach`, the web), or a `--no-shared` REPL resuming it, settles the turn before anything else (`TurnCheckpoint.settle`, log `interrupted_turn_settled`): a note `the previous turn was cancelled (worker-stopped) after Ns` goes at the tail, the status goes idle and the mark goes; `last_turn` stays the previous turn's (a new one saved before the turn a `chi send --wait` woke the worker for would end that wait at once); the dead turn's end is recorded under its `enqueued_id` instead, in `<id>/input/settled/<enqueued_id>` (a `last_turn` record: canceled, `cancel_reason: worker_stopped`), which only a wait for that very turn reads (`chi send --queue --wait`, a `chi send --wait -m` to an idle session or `--new`, `chi send --wait ID --turn`, a continue's wait): it ends `canceled` with `cancel_reason: worker_stopped`, detail "its worker exited mid-turn", instead of timing out. A wait with no turn id that saw the turn running ends the same way when the settle comes (`chi send --wait ID` with no message on a turn with no id, such as a session's first prompt or a reminder turn; a message merged into the turn as a steer), unless an input still waits or was claimed since: an unmerged message runs as its own turn next, and that turn's end is the answer. A reply the turn wrote before its worker died is still its answer. The session shows the turn's prompt and steps with that note; the dead turn is not run again, and the model reads on its next turn that it was cut.
 
 **Stopping a worker:** `chi sessions stop ID` marks the session stopped (an empty `<id>/stopped` file, not a session.json field, which a worker saving at that moment would write over; a resume removes it), sends its worker TERM and waits (up to 10 s) until the worker has let go of `owner.lock`. A running turn is canceled over the Bridge first, with reason `session_stopped` (the turn's line ends "(session stopped)", its note says `cancelled (session-stopped)`, and a command it was running says "stopped as the session was stopped"; a bare signal to the worker makes it "stopped by a signal to chi"; an older worker takes the reason as `manual`); the TERM stops whatever still runs as a Stop with reason `signal` and saves it (a spawned worker traps TERM, HUP and INT: `WorkerSignals`; a turn not ended within 3 s, 0.5 s after a stop or a second signal, is cut and the session saved as it was), and a stopped worker still saves its kept turn, since the marker, not the saved status, says stopped. Any TERM, HUP or INT does the same to a worker outside a stop: it leaves (log `worker stop reason=signal`) and the next send wakes a new one, so a `chi --resume ID` right after spawns a fresh worker. That is also how to restart a worker still running an older chi, which the attached terminal reports when a command or a question dismiss gets a 404, and the web when an answer, a dismiss, a command or a cancel does (`501 not_supported`; `BridgeClient.stale_worker_message`). A command this chi has that the older worker doesn't (`/llm-context`, the web's `llm ctx` chip, against a 0.39.0 worker) says the same, not `not a session command` (`SessionCommands.builtin_name`); a typo keeps its `400 unknown_command`. The web's `POST /api/sessions/:id/stop` waits the same way, for 2 s (the page's Stop shows the stop at once), or for the body's `wait` up to the same 10 s (`SessionManager::STOP_WAIT`): `chi --remote NAME sessions stop` sends it, so it waits as long as here. A command sent during a turn that waits for its end (`/model X`, `!cmd`; see *Typing during a turn* in [cli.md](cli.md)) and hasn't run when the worker leaves (a stop, a crash) is answered `command_ran {status: "dropped"}`, so no UI keeps showing it waiting.
 

data/docs/sub-agent.md

@@ -72,7 +72,7 @@ Exit codes, both commands:
 | 3 | `waiting_for_owner` | (a participant's wait, `chi --remote NAME send --wait` with their link's token) their review turn waits on the session's owner: a question or an approval it raised, or the owner's step-limit Continue; wait again |
 | 4 | `running` | `--timeout` passed; the turn goes on, wait again |
 | 1 | `refused` | (a participant's wait) their queued review turn was refused before it ran: `cancel_reason` `revoked` (their link was revoked or expired) or `cap_reached` (they spent their cap); no turn ran for it |
-| 1 | `failed`, `canceled`, `limit`, `removed`, `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, except under `guardrails.parent_answers: hard`, where a parent's `/continue yes` is refused as its `chi answer --option Continue` is; `removed`: the `--queue` message waited for was taken back before it ran, no turn ran for 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; `worker_stopped`: the turn waited for (a `--queue` message's, or a message's to an idle session) died with its worker (detail "its worker exited mid-turn"), settled by the next one; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
+| 1 | `failed`, `canceled`, `limit`, `removed`, `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, except under `guardrails.parent_answers: hard`, where a parent's `/continue yes` is refused as its `chi answer --option Continue` is; `removed`: the `--queue` message waited for was taken back before it ran, no turn ran for 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; `worker_stopped`: the turn waited for (a `--queue` message's, a message's to an idle session, the running turn a message merged into or a plain `--wait` saw running) died with its worker (detail "its worker exited mid-turn"), settled by the next one; `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 |
 

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -46,7 +46,7 @@ module Samagotchi
       end
 
       # @return [Hash, nil] a copy of the turn in progress: prompt, origin,
-      #   continue, ordered parts (generation / thinking / text / tool /
+      #   continue, at (its wall time), ordered parts (generation / thinking / text / tool /
       #   input / steer / reminder / notice), pending_question and the last event_seq folded
       #   in. A finished tool part keeps the live row's action and duration_ms
       #   too, a running one the time it has run so far (elapsed_ms), so a
@@ -275,6 +275,8 @@ module Samagotchi
           @turn = { prompt: event[:prompt], origin: event[:origin], continue: !!event[:continue],
                     parts: [], pending_question: nil }
           @turn[:resumed] = true if event[:resumed]
+          # Its wall time (MessageTime): a joining page's gap divider.
+          @turn[:at] = event[:at] if event[:at]
           @tool_started_at = {}
           @working_set = nil
           @turn[:images] = event[:images] if event[:images]

data/lib/samagotchi/bridge.rb

@@ -26,6 +26,7 @@ require_relative "turn_origin"
 require_relative "participants"
 require_relative "image_store"
 require_relative "log"
+require_relative "proxy_trace"
 require_relative "version"
 require_relative "worker_sidecar"
 require_relative "relay_verifier"
@@ -120,6 +121,8 @@ module Samagotchi
       @connection_threads = []
       @stopped = false
       @mutex = Monitor.new
+      @proxied_log_mutex = Mutex.new
+      @proxied_logged_at = nil
       @open_streams = 0
       # Open streams by the client_id a stream named (`?client_id=`); web
       # tabs, through the `chi web` proxy, name none.
@@ -438,6 +441,10 @@ module Samagotchi
           break
         elsif browser_request?(headers)
           write_json(io, 403, nil, { error: "cross_origin", detail: "the bridge answers chi's own clients only" })
+        elsif proxied_request?(headers)
+          note_proxied_refused(request[:path])
+          write_json(io, 403, nil, { error: "proxied", detail: "the bridge answers chi's own clients on this machine, " \
+                                                               "never a request through a proxy" })
         elsif route.nil?
           write_json(io, 404, { "Allow" => "GET, POST" },
                      { error: "not_found", path: request[:path] })
@@ -524,6 +531,24 @@ module Samagotchi
     # no Sec-Fetch-Site. A browser page always sends one of them (another
     # website's text/plain POST needs no preflight), and a DNS-rebound page
     # also has a foreign Host. Headers are the raw ones, lowercased.
+    # A request through a proxy (an auth proxy forwarding every port, as a
+    # work pod's does) carries a trace chi's own clients never send
+    # (ProxyTrace: X-Forwarded-*, Forwarded, X-Real-IP, X-Auth-Request-*…,
+    # underscore twins too): refused, whoever signed in to the proxy. chi
+    # web's stream proxy forwards Last-Event-ID only (ProxyStreamBody).
+    def proxied_request?(headers) = headers.keys.any? { |name| ProxyTrace.header?(name) }
+
+    PROXIED_LOG_INTERVAL = 60.0
+
+    # At most once a minute: a scan through a forward would fill the log.
+    def note_proxied_refused(path)
+      now = monotonic_now
+      due = @proxied_log_mutex.synchronize do
+        (@proxied_logged_at.nil? || now - @proxied_logged_at >= PROXIED_LOG_INTERVAL).tap { |fresh| @proxied_logged_at = now if fresh }
+      end
+      Log.warn(:bridge, "proxied_refused", path: path) if due
+    end
+
     def browser_request?(headers)
       return true if headers.key?("origin")
       return true if headers.key?("sec-fetch-site") && headers["sec-fetch-site"].downcase != "none"

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

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

data/lib/samagotchi/config.rb

@@ -316,6 +316,10 @@ module Samagotchi
       Entry.new(key: "web.participants.expires", yaml_path: %w[web participants expires], type: :string, default: "7d", expose: %i[env config], lifecycle: :next_matching_turn_display_poll_write),
       Entry.new(key: "web.participants.cap",     yaml_path: %w[web participants cap],     type: :float,  default: 2.0,  expose: %i[env config], lifecycle: :next_matching_turn_display_poll_write),
       Entry.new(key: "web.participants.queue",   yaml_path: %w[web participants queue],   type: :integer, default: 3,   expose: %i[env config], lifecycle: :next_matching_turn_display_poll_write),
+      # chi web behind an auth proxy (Web::PublicUrl, docs/configuration.md "Behind an auth proxy").
+      Entry.new(key: "web.public_url",           yaml_path: %w[web public_url],           type: :string, default: nil,  expose: %i[env config], lifecycle: :web_start),
+      Entry.new(key: "web.proxy.identity_header", yaml_path: %w[web proxy identity_header], type: :string, default: nil, expose: %i[env config], lifecycle: :web_start),
+      Entry.new(key: "web.proxy.owner",          yaml_path: %w[web proxy owner],          type: :string, default: nil,  expose: %i[env config], lifecycle: :web_start),
 
       Entry.new(key: "no_interrupt",             yaml_path: %w[no_interrupt],             type: :bool,   default: false,            expose: %i[env config cli], lifecycle: :next_cli_run),
       Entry.new(key: "no_default_input",         yaml_path: %w[no_default_input],         type: :bool,   default: false,            expose: %i[env config cli], lifecycle: :next_cli_run),

data/lib/samagotchi/context_note.rb

@@ -2,6 +2,7 @@
 
 require "time"
 require_relative "paths"
+require_relative "message_time"
 
 module Samagotchi
   # A context note: background text pushed into a session from outside (the
@@ -13,7 +14,8 @@ module Samagotchi
     # The message keys a note carries besides role and content; everything
     # that copies messages field by field must keep them.
     # context_source: the attached context source a note is about
-    # (ContextAbsorber), so the UIs can tie it to its chip.
+    # (ContextAbsorber), so the UIs can tie it to its chip. A note's wall
+    # time (MessageTime::KEY) is every entry's, kept beside these.
     KEYS = %i[kind note_id source from_session from_cwd context_source].freeze
     HEADER = "CONTEXT NOTE"
     # A finished background task's note (TaskFinishNote): a header of its own.
@@ -27,14 +29,16 @@ module Samagotchi
     # Takes SessionInbox.read_note's keys. +turn_start+ / +turn_id+: the
     # note starts a turn chi runs for it (a context wake), as a wake turn's
     # delegate report does (Steer.turn_prompt?). +header+: the frame's
-    # (HEADERS), not kept as a key: the content carries it.
+    # (HEADERS), not kept as a key: the content carries it. Its wall time
+    # (MessageTime::KEY) is +created_at+'s, else now.
     # @return [Hash] the conversation message
     def message(note_id:, text:, source:, created_at: nil, from_session: nil, from_cwd: nil, context_source: nil,
                 turn_start: nil, turn_id: nil, header: HEADER, **)
       { role: "system", kind: KIND, note_id: note_id, source: source, from_session: from_session,
         from_cwd: from_cwd, context_source: context_source, turn_start: (true if turn_start == true), turn_id: turn_id,
         content: frame(text, source: source, created_at: created_at, from_session: from_session,
-                             from_cwd: from_cwd, header: header) }.compact
+                             from_cwd: from_cwd, header: header),
+        MessageTime::KEY => MessageTime.iso_of(created_at) || MessageTime.iso(MessageTime.now) }.compact
     end
 
     def frame(text, source:, created_at: nil, from_session: nil, from_cwd: nil, header: HEADER)

data/lib/samagotchi/engine.rb

@@ -78,6 +78,7 @@ require_relative "thinking"
 require_relative "reasoning_history"
 require_relative "answer_display"
 require_relative "answer_refs"
+require_relative "message_time"
 require_relative "edit_preview"
 require_relative "question_desk"
 require_relative "question_asked"
@@ -585,9 +586,12 @@ module Samagotchi
 
     # Emit a :recap_ready event (additive slot) carrying the generated recap
     # and the generation id an observer uses to reject an invalidated recap.
-    # +covered+ counts the session messages it summarizes.
-    def emit_recap(recap:, generation:, covered: nil)
-      @session_observer.notify(type: :recap_ready, recap: recap, generation: generation, covered: covered)
+    # +covered+ counts the session messages it summarizes; +created_at+ is
+    # the saved recap's (UTC ISO; the UIs show its local time).
+    def emit_recap(recap:, generation:, covered: nil, created_at: nil)
+      event = { type: :recap_ready, recap: recap, generation: generation, covered: covered }
+      event[:created_at] = created_at if created_at
+      @session_observer.notify(event)
     end
 
     # Count one side request (a recap, a plugin's ctx.ask_model: IdleClient's
@@ -1997,8 +2001,10 @@ module Samagotchi
     # +resume_from+: where its reasoning starts, the run it resumes
     # (run_turn's resume_from:); nil for every other turn, and for a
     # Continue that starts cold (after a model change).
+    # +wall+: the wall time it started (MessageTime.now, once): the
+    # :turn_started event's at and its user message's (and reminders') stamp.
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id, :limit, :resumed, :resume_from) do
+                      :settings, :id, :limit, :resumed, :resume_from, :wall) do
       def resumed? = resumed ? true : false
 
       # The turn's boundary events carry the origin only when it names a
@@ -2009,6 +2015,9 @@ module Samagotchi
 
       # Seconds since the turn started (the cancel note says how long it ran).
       def elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+
+      # The wall time's stamp text (MessageTime::KEY).
+      def at = MessageTime.iso(wall)
     end
     private_constant :Turn
 
@@ -2141,7 +2150,7 @@ module Samagotchi
 
       Turn.new(session: session, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
                controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
-               id: id || SecureRandom.uuid)
+               id: id || SecureRandom.uuid, wall: MessageTime.now)
     end
     private :begin_turn
 
@@ -2155,7 +2164,7 @@ module Samagotchi
       image_refs, image_error = turn_image_refs(session, images)
       # Emit turn_started event
       bind_metrics(session)
-      turn_started = { type: :turn_started, session_id: session.id, prompt: turn.prompt, turn_id: turn.id }
+      turn_started = { type: :turn_started, session_id: session.id, prompt: turn.prompt, turn_id: turn.id, at: turn.at }
       turn_started[:continue] = true if turn.continue
       turn_started[:resumed] = true if turn.resumed?
       turn_started[:images] = image_refs unless image_refs.empty?
@@ -2316,16 +2325,18 @@ module Samagotchi
       # system prompt invalidates cache for the entire prefix.
       # Not into a participant's turn: the owner's reminders are the owner's,
       # and would be used up there under the review boundary.
-      due_reminders = turn.origin.participant? ? [] : @reminder_queue.inject!(turn.messages)
+      due_reminders = turn.origin.participant? ? [] : @reminder_queue.inject!(turn.messages, now: turn.wall)
       if due_reminders.any?
         emit_event(turn.on_event, {
           type: :reminder_injected,
-          reminders: due_reminders
+          reminders: due_reminders,
+          at: turn.at
         })
       end
 
       unless turn.continue
-        user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author) }
+        user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author),
+                         MessageTime::KEY => turn.at }
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
         session.last_prompt = turn.prompt

data/lib/samagotchi/idle_recap.rb

@@ -504,7 +504,7 @@ module Samagotchi
                 model: served || job[:model], created_at: Time.now.utc.iso8601 }
       @mutex.synchronize { @state = saved }
       save(saved)
-      @engine.emit_recap(recap: text, generation: job[:generation], covered: job[:covered])
+      @engine.emit_recap(recap: text, generation: job[:generation], covered: job[:covered], created_at: saved[:created_at])
     rescue StandardError
       @in_flight = nil
     end

data/lib/samagotchi/idle_reminders.rb

@@ -8,7 +8,7 @@ module Samagotchi
   #
   # Two delivery paths cooperate:
   #   1. Every turn injects what is due (ReminderQueue#inject!, from
-  #      Engine#run_turn) as [SYSTEM: REMINDERS DUE] and marks it fired.
+  #      Engine#run_turn) as [SYSTEM: REMINDERS DUE <local time>] and marks it fired.
   #   2. Synthetic turns: when this job's tick finds due reminders while
   #      idle, it fires @auto_turn_callback, which queues their names
   #      (Engine#note_due_reminders) for the worker's or the REPL's

data/lib/samagotchi/kernel_loop.rb

@@ -33,6 +33,7 @@ require_relative "llm_context_forget"
 require_relative "working_set"
 require_relative "llm_context_notice"
 require_relative "answer_display"
+require_relative "message_time"
 require_relative "llm/model_result"
 require_relative "llm/turn_settings"
 require_relative "llm/stream_drops"
@@ -360,7 +361,8 @@ module Samagotchi
         return after_malformed(turn, generation, reason)
       end
 
-      turn.conversation << { role: "model", content: request.prefill + generation.response.to_s }
+      turn.conversation << { role: "model", content: request.prefill + generation.response.to_s,
+                             MessageTime::KEY => MessageTime.iso(MessageTime.now) }
       # Profile-specific parse (incl. Qwen unterminated-block recovery); the
       # returned fragment (non-nil only for Qwen) is fed back on the next
       # iteration if the model opened a tool-call block it did not close.
@@ -867,7 +869,8 @@ module Samagotchi
       # cannot leak) so a follow-up steering message continues with the model's
       # half-finished work in context instead of losing it.
       unless partial.empty?
-        message = { role: "model", content: "#{partial}\n[interrupted]", interrupted: true }
+        message = { role: "model", content: "#{partial}\n[interrupted]", interrupted: true,
+                    MessageTime::KEY => MessageTime.iso(MessageTime.now) }
         # The thinking this generation streamed goes with it (the chat loop's
         # with_thinking key, which MessageParts reads and the prompt doesn't):
         # without it, reloading the cut step shows the empty answer it isn't.
@@ -1088,16 +1091,18 @@ module Samagotchi
 
     # +keep_thought_from+: model messages from this index on keep their
     # thought blocks (a resumed run's); nil strips every one.
+    # A model message is rebuilt from an allow-list: `display`,
+    # `display_refs` and its wall time (MessageTime::KEY) ride along so the
+    # stored conversation keeps them; the prompt formatter never reads them
+    # (AnswerDisplay, AnswerRefs, MessageTime).
     def sanitize_history(messages, keep_thought_from: nil)
       messages.each_with_index.map do |m, index|
         if m[:role] == "model" && keep_thought_from && index >= keep_thought_from
-          { role: m[:role], content: m[:content].to_s, display: m[:display], display_refs: m[:display_refs] }.compact
+          { role: m[:role], content: m[:content].to_s, display: m[:display], display_refs: m[:display_refs],
+            MessageTime::KEY => m[MessageTime::KEY] }.compact
         elsif m[:role] == "model"
-          # `display` and `display_refs` ride along so the stored
-          # conversation keeps them; the prompt formatter never reads them
-          # (AnswerDisplay, AnswerRefs).
           { role: m[:role], content: strip_thought_blocks(m[:content].to_s), display: m[:display],
-            display_refs: m[:display_refs] }.compact
+            display_refs: m[:display_refs], MessageTime::KEY => m[MessageTime::KEY] }.compact
         else
           m.dup
         end

data/lib/samagotchi/llm/chat_loop.rb

@@ -30,6 +30,7 @@ require_relative "../empty_answer_retry"
 require_relative "../steer"
 require_relative "../reasoning_history"
 require_relative "../turn_note"
+require_relative "../message_time"
 require_relative "../thinking"
 
 module Samagotchi
@@ -432,7 +433,8 @@ module Samagotchi
       # note's marker (TurnNote.empty, never sent), and an answer's display
       # and display_refs (AnswerDisplay, AnswerRefs; never sent), a
       # find_tools result's loaded names and a tool change's TOOL_CHANGE
-      # (sent only to a wire that loads tools).
+      # (sent only to a wire that loads tools), and an entry's wall time
+      # (MessageTime::KEY, display-only, never sent).
       def plain(conversation)
         conversation.map do |entry|
           content = entry[:content].is_a?(Array) ? entry[:content] : entry[:content].to_s
@@ -454,6 +456,7 @@ module Samagotchi
           Steer::AUTHOR_KEYS.each { |key| message[key] = entry[key] if entry[key] }
           message[ToolResponse::LOADED] = entry[ToolResponse::LOADED] if entry[ToolResponse::LOADED].is_a?(Array)
           message[TOOL_CHANGE] = entry[TOOL_CHANGE] if entry[TOOL_CHANGE].is_a?(Hash)
+          message[MessageTime::KEY] = entry[MessageTime::KEY] if entry[MessageTime::KEY]
           message
         end
       end
@@ -704,7 +707,10 @@ module Samagotchi
         # (reasoning_history). A wire that sends its blocks back keeps them
         # as +anthropic_content+ (ChatResponse#provider_content: string
         # keys, as received, so a resumed session sends the same bytes).
+        # Every reply built from a response comes through here, so it is
+        # also where a reply gets its wall time (MessageTime::KEY).
         def with_thinking(message, response)
+          MessageTime.stamp(message, MessageTime.now)
           reasoning = response.reasoning.to_s
           message = message.merge(thinking: reasoning) unless reasoning.strip.empty?
           blocks = response.provider_content
@@ -1038,7 +1044,8 @@ module Samagotchi
           emit(type: :generation_cancelled, iteration: iteration, reason: reason, stopped_by: @cancel_controller&.stopped_by)
           visible = @loop.strip_model_thought(partial.to_s).strip
           unless visible.empty?
-            message = { role: "model", content: "#{visible}\n[interrupted]", interrupted: true }
+            message = { role: "model", content: "#{visible}\n[interrupted]", interrupted: true,
+                        MessageTime::KEY => MessageTime.iso(MessageTime.now) }
             thought = thinking.to_s
             message[:thinking] = thought unless thought.strip.empty?
             @conversation << message

data/lib/samagotchi/message_time.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Samagotchi
+  # When a history entry happened: its wall-clock stamp (KEY), and the
+  # dividers the UIs print when a quiet gap passes between two entries.
+  #
+  # The stamp is display-only: no wire format reads it, so the bytes the
+  # model gets (and its prompt cache) are the same with or without it. A
+  # time the model should read is baked into the message's content when the
+  # message is made (ReminderQueue's header), never rendered at wire time.
+  #
+  # Everything here is a pure function of the times passed in; the one wall
+  # clock is #now (a seam the specs pin to a fixed time).
+  module MessageTime
+    # The history entry key: a local-offset ISO 8601 time with milliseconds.
+    KEY = :at
+    # The quiet time after which the UIs mark a gap.
+    GAP_SECONDS = 600
+
+    DEFAULT_SOURCE = -> { Time.now }
+    private_constant :DEFAULT_SOURCE
+
+    class << self
+      # The wall clock: a callable returning a Time (nil: Time.now).
+      attr_writer :source
+
+      # @return [Time] now, by the wall clock seam
+      def now = (@source || DEFAULT_SOURCE).call
+
+      # Back to Time.now.
+      def reset! = @source = nil
+    end
+
+    module_function
+
+    # @param time [Time]
+    # @return [String] the stamp's text
+    def iso(time) = time.iso8601(3)
+
+    # The stamp of an ISO text from elsewhere (a note's created_at), or nil
+    # when it doesn't parse.
+    def iso_of(text)
+      text && iso(Time.iso8601(text.to_s))
+    rescue ArgumentError
+      nil
+    end
+
+    # +message+ with KEY set to +time+'s stamp, unless it has one already
+    # (a Symbol- or String-keyed message). Changes +message+ and returns it.
+    def stamp(message, time)
+      return message if message.key?(KEY) || message.key?(KEY.to_s)
+
+      message[KEY] = time.is_a?(String) ? time : iso(time)
+      message
+    end
+
+    # @return [String, nil] the stamp of +message+ (Symbol or String keys)
+    def of(message)
+      return nil unless message.is_a?(Hash)
+
+      message[KEY] || message[KEY.to_s]
+    end
+
+    # @return [String, nil] "14:32", local time
+    def clock(iso) = local(iso)&.strftime("%H:%M")
+
+    # @return [String, nil] "Sat 24 Oct 09:10", local time
+    def day_clock(iso) = local(iso)&.strftime("%a %-d %b %H:%M")
+
+    # The divider between activity that ended at +prev_iso+ and activity
+    # starting at +cur_iso+: nil below GAP_SECONDS (or when either time is
+    # unknown), else "── 14:32 · 47 min later ──", the date added when the
+    # local day changed.
+    def gap_line(prev_iso, cur_iso)
+      prev = local(prev_iso)
+      cur = local(cur_iso)
+      return nil unless prev && cur
+
+      seconds = cur - prev
+      return nil if seconds < GAP_SECONDS
+
+      time = prev.to_date == cur.to_date ? cur.strftime("%H:%M") : cur.strftime("%a %-d %b %H:%M")
+      "── #{time} · #{ago(seconds)} later ──"
+    end
+
+    # @return [String] "47 min", "3 h", "2 d" (whole units, rounded down;
+    #   the web's relativeTime scale)
+    def ago(seconds)
+      seconds = seconds.to_f
+      return "#{[(seconds / 60).floor, 0].max} min" if seconds < 3600
+      return "#{(seconds / 3600).floor} h" if seconds < 86_400
+
+      "#{(seconds / 86_400).floor} d"
+    end
+
+    def local(iso)
+      iso && Time.iso8601(iso.to_s).localtime
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/samagotchi/proxy_trace.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The request headers a proxy in front of chi adds and chi's own clients
+  # never send: chi web takes a request with one as proxied
+  # (Web::ProxyGate), a Bridge refuses it (Bridge#browser_request?). Names
+  # are compared lower-cased with "_" read as "-", so an underscore twin
+  # (X_Forwarded_For) counts too. See docs/configuration.md "Behind an auth
+  # proxy".
+  module ProxyTrace
+    # Any name starting with one of these: X-Forwarded-For/-Host/-Proto/
+    # -Email/-User…, oauth2-proxy's X-Auth-Request-*, Cloudflare's Cf-*,
+    # Tailscale Serve's Tailscale-User-*, Authentik's X-Authentik-*, Google
+    # IAP's X-Goog-*, Azure App Service's X-MS-Client-Principal*, AWS ALB's
+    # X-Amzn-Oidc-*, Envoy's X-Envoy-*.
+    PREFIXES = %w[x-forwarded- x-auth-request- cf- tailscale- x-authentik- remote- x-goog- x-ms-client-principal
+                  x-amzn-oidc- x-envoy- x-original-forwarded-].freeze
+    # And these whole names.
+    NAMES = %w[forwarded x-real-ip via true-client-ip x-client-ip x-original-url x-original-uri].freeze
+
+    # The identity headers known setups send (docs/configuration.md's
+    # table): chi web's hint when the proxy sends one of them but not the
+    # one configured.
+    IDENTITY_HEADERS = %w[X-Forwarded-Email X-Auth-Request-Email Cf-Access-Authenticated-User-Email Tailscale-User-Login
+                          Remote-Email X-Authentik-Email X-Goog-Authenticated-User-Email X-MS-Client-Principal-Name
+                          X-Amzn-Oidc-Identity X-Forwarded-User X-Auth-Request-User Remote-User].freeze
+
+    module_function
+
+    # @param name [String] a header's name as sent (any case, - or _)
+    def header?(name)
+      key = normalize(name)
+      NAMES.include?(key) || PREFIXES.any? { |prefix| key.start_with?(prefix) }
+    end
+
+    def normalize(name) = name.to_s.downcase.tr("_", "-")
+
+    # The header name of a Rack env key (HTTP_X_FORWARDED_FOR →
+    # x-forwarded-for), nil for a key that isn't a header's.
+    def env_name(key)
+      key = key.to_s
+      key.start_with?("HTTP_") ? key.delete_prefix("HTTP_").downcase.tr("_", "-") : nil
+    end
+  end
+end

data/lib/samagotchi/reminder_queue.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require_relative "message_time"
 
 module Samagotchi
   # The session's due reminders, on their way into a turn.
@@ -11,9 +12,16 @@ module Samagotchi
   # turn while they are pending. A turn injects whatever is due then
   # (#inject!), which marks it fired and clears the pending names.
   class ReminderQueue
+    # The reminders message's first line at +time+ (a Time in the zone to
+    # show: Time.now's is the local one).
+    def self.header(time) = "[SYSTEM: REMINDERS DUE #{time.strftime("%Y-%m-%d %H:%M")} local]"
+
     # @param store [ReminderStore, nil]
-    def initialize(store:)
+    # @param now [#call] the wall clock (a Time) for the injected message's
+    #   stamp, when #inject! is given none
+    def initialize(store:, now: -> { MessageTime.now })
       @store = store
+      @now = now
       @lock = Monitor.new
       @pending = []
     end
@@ -55,14 +63,23 @@ module Samagotchi
     # A tail message, not the head system prompt: changing the head would
     # make the model server re-evaluate the whole conversation's prefix
     # (its KV cache) every interval; a tail costs only the new suffix.
+    # The header names the local time the reminders came due at, for the
+    # model ("[SYSTEM: REMINDERS DUE 2026-10-24 14:32 local]"): baked into
+    # the content here, never rendered at wire time, so a replay sends the
+    # same bytes (the prompt cache) whatever the time zone or DST. The
+    # message also carries that time as its stamp (MessageTime::KEY,
+    # display-only).
     # @param messages [Array<Hash>] the turn's messages (appended to)
+    # @param now [Time, nil] the turn's wall time (nil: the clock's)
     # @return [Array<Hash>] the reminders injected (maybe none)
-    def inject!(messages)
+    def inject!(messages, now: nil)
       reminders = due
       return [] if reminders.empty?
 
+      time = now || @now.call
       lines = reminders.map { |r| "  #{r[:name]}: #{r[:description]} (interval: #{r[:interval_minutes]}m)" }.join("\n")
-      messages << { role: "system", content: "[SYSTEM: REMINDERS DUE]\n#{lines}\n[END REMINDERS]" }
+      messages << { role: "system", content: "#{self.class.header(time)}\n#{lines}\n[END REMINDERS]",
+                    MessageTime::KEY => MessageTime.iso(time) }
       @store.mark_fired_batch(reminders.map { |r| r[:name] })
       # Without this a turn's injection leaves a stale name, and the next
       # reminder turn would run with nothing due.