samagotchi 0.159.0 → 0.161.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab720ab347312f152fc99a03ca8cd423a640de2c9b4221ccc70803396a2d8c09
-  data.tar.gz: 313bbe5c7cce008df50c73de233557824723566db8449a8e3a04ff01e85343f9
+  metadata.gz: d3a8c4d1d4d37965fda091bc5c48281cdf352d6f3e496d5e5073f72777fe5994
+  data.tar.gz: 74a26cfde1a9028c44763b99cdc60ce044028598ddd2955b244338076ef8fd86
 SHA512:
-  metadata.gz: 4c02cc469245adaa130c74b1e10978c11b51e85f7ff8c2fe9c27d0de68682d0452f07d9dec7f9100c032dac9cf7357bff81fc70586c9c6cb1e99ab0327c68d56
-  data.tar.gz: 7ffaacdca84dc1396e5f6edd1160b54e063daa38b71d9aa7c36d7619495d26271606efd277024f344e18043ed2112f3343ea127560438bea0f5480b98df617f3
+  metadata.gz: 1de962941edd2efc63a07e566954a8e6cd212891c4858db791667341e0eca601b0e920a4661198760317f5133ee26e3411d9cad570a63a87e861527ab8e21a7e
+  data.tar.gz: 0fb530ff96ccbfe79f2dc04b4cba6d59fc1b0ee6a921cf593907d9159b60eec1bed10c3360f1777417f30333c9afd36090d2b3abf7f58b9e4e4cf1b27e558946

data/CHANGELOG.md

@@ -8,6 +8,128 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.161.0] - 2026-11-10
+
+### Added
+
+- `chi bundle upgrade NAME` and `chi bundle uninstall NAME`, when the bundle's plugin changed (or an upgrade brought
+  one in) and a session running it can be restarted, end with one line naming those sessions and
+  `chi sessions restart ID` for each (nothing on a dry run, with no restartable worker, or when the plugin is
+  unchanged — only the plugin stays in a worker's memory; its rules reload by stamp and its scripts run from disk).
+
+### Changed
+
+- Worker restart hints now follow one compatibility rule: the current and previous minor release are supported.
+- `chi bundle install` and `chi bundle upgrade` refuse a memory, plugin or script whose bytes disagree with the
+  sha256 its manifest declares, before writing anything (`Checksum mismatch for FILE: ...; chi bundle install
+  --force installs it anyway`, exit 1). `--force` installs it anyway, as it already does for an edited memory (its
+  copy going to the trash first) and for a bundle whose `requires_chi` this chi doesn't meet; a dev install, a
+  non-strict run, `chi update` and a bundle profile keep the warning-only behaviour.
+- Core guardrail checks judge a plugin tool by what its `targets:` say it acts on, not by its name: paths it
+  declares it writes (`writes: true`) are checked like `write` and `edit`. See docs/plugins.md (Guardrails).
+- `chi context push` says what a wake push did: `· chi woken` (an idle-exited session started), `· chi is stopped:
+  it sees this at its next start` (a stopped session is never started) or `· chi is starting`; chi web's push
+  answer carries it as `wake`. A delegate's report, or a push, now wakes a session whose file still said stopped
+  without a `chi sessions stop` behind it: only the stop marker means stopped.
+
+### Fixed
+
+- A session being started is no longer pulled from under its worker: a session resumed while the retention sweep runs
+  is not deleted, two starts at once (chi web and a `chi send`, a delegate's report) start one worker, and a second
+  continue of a chain can't archive the link the first one just started. A deleted session no longer comes back
+  when a worker that still had it saves.
+- A `chi sessions stop` that lands while a session's worker is leaving (an idle exit, `/exit`, a signal) is no longer
+  undone by a new worker started for input or delegate reports that were waiting: the session stays stopped and
+  they wait for its next start, as a stop during a restart already did.
+- Session deletion and retention now also end participant grants and purge System 1 runs and context-candidate records.
+- An interrupted continue now repairs its archived previous link when no successor was saved, so the session stays listed.
+- A note sent to a session that was continued (`chi note`, `send_note`, `chi broadcast`, chi web) reaches the new link
+  (`chi note` prints `OLD → NEW (continued)`), and notes waiting when it was continued move with it; a note that
+  still lands in the old link as it is continued is taken by the new link's worker, and a continue that fails gives
+  the notes back. An `/objectives` edit stays in its own session.
+- `chi bundle uninstall NAME` of a bundle whose install was interrupted before its record (only the
+  `pending.json` journal left) retags the index line of a kept shared file in the journal's own target folder, not the
+  current folder's: run from another project, it no longer edits that project's `index.md` for a file living elsewhere.
+- A schedule counts a firing only after its turn completes: failed, canceled or unanswered turns now count toward
+  `max_failures` with the reason visible in `chi schedule list` and `show`.
+- A schedule firing left without a turn after a process interruption is recorded as a failure instead of staying
+  stuck; its uncertain occurrence is not replayed.
+- `chi schedule run-now` reserves an entry under the tick lock before firing, preventing an overlapping tick from
+  starting the same work.
+- Retention protects an enabled schedule's stored anchor and head as well as its resolved target; cancel the
+  schedule with `chi schedule cancel ID` before deleting any of them.
+- Schedule add, list and `schedule_task` warn when the ticker is stale and auto-tick is off; acquired ticks record
+  their timestamp.
+- chi web's schedule tick runs outside the session scan loop, and overlapping hub scans do not start a second
+  tick while one is in flight.
+- The web chain chip waits until its session is in the loaded list before saying earlier links were pruned.
+- A `chi send`, delegate or schedule delivery whose Bridge answered an error after it had queued the prompt no
+  longer runs it twice: the client makes the enqueued id, the input-file fallback reuses it, and the worker runs
+  each id once (also after a restart, a turn that already ran or was cut off by the worker's death).
+- The continue's carry note of unabsorbed pushed context keeps the sources after one trimmed to the per-source 4 KiB
+  cap: a source that fits the room left is carried whole even when that room is under the cap, the note ends only at a
+  source it has no room for, and "[additional pushed text omitted]" is added whenever text is left out.
+- The memory-orphan hint says how the other folder is keyed: a `chi project init` folder is named by its project id
+  instead of "another path's hash", and a project keyed by an id is named by its folder, not by that id (so a marked
+  folder whose memories stayed in its id folder after `git init` is described correctly).
+- A browser tab or terminal that connects to a worker with no cursor, after its event ring has wrapped, is re-synced
+  from the session instead of replaying from the middle of a turn.
+- Stop (the web button, Ctrl-C in the terminal) names the turn it was pressed for, so one pressed as that turn ends no
+  longer cancels the queued turn that starts next.
+- `chi bundle install` and `upgrade` check that the plugin and scripts the manifest names are in the bundle before
+  they write anything, so a bundle that lacks one is refused with your memories, plugin and record as they were.
+- A bundle install or upgrade that is killed or fails after it copied memories (a `pending.json` journal in
+  `.bundles/NAME/`) no longer leaves them as your own files or local edits: a retry owns them, `chi bundle status`
+  shows no edit, the next upgrade fast-forwards them and uninstall removes them.
+- A `delegate` follow-up the child's worker refuses says why, in the same sentence `chi send` prints for a delivery
+  that did not go in (`DeliverResult#refusal_text`): "Error: session abc12345 refused: this session's worker predates
+  queueing ... and send again" rather than the bare error code.
+- A fork and a continue keep the session's `--memory` and `--mute` lists; a non-delegate child does not inherit the
+  reserved `system/delegated` memory.
+- A review fork carries its source's `--mute` list, but not its `--memory` preloads.
+
+Update with `chi update`, then restart chi web and running sessions (`chi sessions restart`): workers from
+0.160.0 keep working (N-1), but the new starting marker, session inbox and stop-during-leave rule apply only to
+workers started by 0.161.0.
+
+## [0.160.0] - 2026-11-09
+
+### Added
+
+- A folder made a chi project with `chi project init` keeps its memories when you move or rename it (an `id:` in
+  .chi/project.yml); rerun `chi project init` in an older project to adopt one, `--new-id` to split a copied folder.
+
+### Changed
+
+- `schedules.json` keeps what a newer chi wrote (its format version, unknown fields, entries this chi can't read) when
+  an older chi rewrites it.
+- The `SessionManager.run_session_loop` forwarder for older boot strings is gone: a chi web or terminal still
+  running 0.158.0 or older must be restarted after updating, because a worker it spawns names that entry.
+
+### Fixed
+
+- A message that starts with `!` runs as a shell command only when a person sends it (a web tab, a chi TUI, `chi send`):
+  from a delegating parent, a schedule or a plugin it is refused and nothing runs, and a `/command` line from them is
+  plain text for the model. `chi answer`'s lines (a parent agent's `/continue yes`, `/parent-answers`) still run as
+  commands, with the same trust as `chi send`.
+- A delegate's task and a chain schedule's firing now start their session as their sender's turn, not yours: its
+  `last_turn` origin reads `delegate` or `schedule`, the turn counts as automatic in the session's metrics, and the
+  objectives audit skips it as it skips a delegate's follow-up; it no longer counts as your input either (it doesn't
+  unarchive the session or reset its wakes). Restart `chi web` (and any worker) after updating: one
+  still running the older chi starts chain links whose first message runs as yours.
+- `delegate`, `schedule_task` and `chi schedule add` refuse a task or prompt that starts with `!`, saying why, so the
+  model can write it as an instruction. A schedule stored with one before this fails when it fires (counted toward
+  its `max_failures`; nothing is started or delivered).
+- A command you allow "for this session" is allowed again only in the same worktree or folder, with the same `env:`
+  (kept as a digest); the same text run in another checkout asks again. Session approvals stored before this ask one
+  more time.
+- `chi bundle upgrade` and `chi update` report a replaced guardrail rule as Updated, like other bundle assets.
+- Bundle install, upgrade and dry runs now name the guardrail, plugin and script files a new version drops.
+- `chi bundle upgrade --dry-run` names edited files it would copy to the trash, including marked memories.
+- `chi bundle uninstall` names a plugin it removes even when the bundle has no memories or hooks.
+- `chi bundle status` labels retired hooks as present or missing; they are not loaded.
+- `chi update` plan rows name memory files a shipped bundle adds.
+
 ## [0.159.0] - 2026-11-09
 
 Update with `chi update`.
@@ -5884,7 +6006,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.159.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.161.0...HEAD
+[0.161.0]: https://github.com/dm1try/samagotchi/compare/v0.160.0...v0.161.0
+[0.160.0]: https://github.com/dm1try/samagotchi/compare/v0.159.0...v0.160.0
 [0.159.0]: https://github.com/dm1try/samagotchi/compare/v0.158.0...v0.159.0
 [0.158.0]: https://github.com/dm1try/samagotchi/compare/v0.157.0...v0.158.0
 [0.157.0]: https://github.com/dm1try/samagotchi/compare/v0.156.0...v0.157.0

data/docs/architecture.md

@@ -105,7 +105,7 @@ terminal renders the events it gets over the Bridge.
 | Adapters | `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | Raw-prompt servers, the OpenAI chat API, Anthropic's Messages API, and the HTTP they share. |
 | Tools | `lib/samagotchi/tools/*` | Execute, read, edit, write, memory, task_*, web_fetch, delegate/delegate_result, ask_user_question, reminders, send_note, list_sessions, context_read, objectives, forget_outputs, find_tools/call_tool (the tool index), plus runtime/output-guardrails. |
 | Bundles | `lib/samagotchi/memory_bundle/*`, `BundleCommand` | `chi bundle`: install/upgrade (3-way, with a text merge of edited memories), build, uninstall; the install record under `.bundles/<name>/` that the guardrail and plugin loaders read ([internals/bundles.md](internals/bundles.md)). |
-| Background | `Samagotchi::Worker`, `Samagotchi::SessionManager` | `SessionManager` (`session_manager.rb`, its parts in `session_manager/`: spawn · worker_command · listing · delivery · lifecycle · removal · emptiness) forks/spawns one worker process per session. The worker process's main (owner lock, detach, signals, project env, what it does as it leaves) is `WorkerBoot` (`worker_boot.rb`), which the boot string loads directly; SessionManager's `run_session_loop` forwarder stays for older spawners' strings. Its `Worker` builds the `Engine` and `Bridge` (no terminal rendering) and runs queued turns. The spawned process (own process group) forks the worker, which `setsid`s and is reparented to init once its starter exits (it waits until the worker holds `owner.lock`, so the spawner's `Process.detach` waiter tells a starting worker): nothing that walks the spawner's process tree reaches it (`SAMAGOTCHI_WORKER_DETACH=1`, `detach_from_spawner`). The lock's pid is the worker's; `spawn`'s `child_pid` is its starter's. |
+| Background | `Samagotchi::Worker`, `Samagotchi::SessionManager` | `SessionManager` (`session_manager.rb`, its parts in `session_manager/`: spawn · worker_command · listing · delivery · lifecycle · removal · emptiness) forks/spawns one worker process per session. The worker process's main (owner lock, detach, signals, project env, what it does as it leaves) is `WorkerBoot` (`worker_boot.rb`), which the boot string loads directly. Its `Worker` builds the `Engine` and `Bridge` (no terminal rendering) and runs queued turns. The spawned process (own process group) forks the worker, which `setsid`s and is reparented to init once its starter exits (it waits until the worker holds `owner.lock`, so the spawner's `Process.detach` waiter tells a starting worker): nothing that walks the spawner's process tree reaches it (`SAMAGOTCHI_WORKER_DETACH=1`, `detach_from_spawner`). The lock's pid is the worker's; `spawn`'s `child_pid` is its starter's. |
 | Web | `Samagotchi::Web::App`, `Samagotchi::Web::Server`, `Samagotchi::Web::SessionHub` | Rack+WEBrick on one port, `127.0.0.1:4567` (index.html + `/api/*` + SSE); with `web.host: lan` also on this machine's LAN address, behind an access token (`Web::Lan`, `Web::Token`). The hub is chi web's projection of the session list, pushed to every tab over `GET /api/events`. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File `sessions/<uuid>.json` + sidecar `input/`/`output/`; retention 14d/500, `updated_at desc`, lazy sweep. |
 
@@ -162,9 +162,8 @@ Unchanged: `ContextProviders`' `{ruby}` (`RbConfig.ruby`: the home's ruby inside
 project env below, so a `mise env` that sets GEM_HOME reaches it), `chi bundle
 try/test/check` (`-I LIB_DIR`), hooks (in-process). The worker's boot string, `run_session_loop(id, state_dir:)` and
 `SAMAGOTCHI_BOOT_FALLBACK` stay the cross-version contract (`spec/worker_contract_spec.rb`): the home only adds the
-prelude in front. The string names `WorkerBoot.run_session_loop`, the worker's main; the SessionManager forwarder
-remains one more release for boot strings written by older spawners. An older chi that wakes a session doesn't read
-home.json and starts its worker as before.
+prelude in front. The string names `WorkerBoot.run_session_loop`, the worker's main. An older chi that wakes a
+session doesn't read home.json and starts its worker as before.
 
 **The tools a worker runs** follow the project, not the boot, and only they do: a spawned worker
 (`WORKER_PROCESS_ENV`; never an in-process loop) calls `ProjectEnv.compute` in `WorkerBoot.run_session_loop`, after the owner
@@ -194,10 +193,14 @@ log's last 4 MB). Rows: [configuration.md](configuration.md#checking-it-chi-home
 
 ## Session retention & ordering
 
-- **Files:** `~/.local/state/samagotchi/sessions/<uuid>.json` + `<uuid>/input|output|owner.lock|bridge.json` (XDG-aware), and the `<uuid>/stopped` and `<uuid>/archived` marker files. Durable schedules belong to the machine, not a session: `~/.local/state/samagotchi/schedules.json` and its `schedules.lock`, next to `sessions/` ([Scheduling](scheduling.md)).
+- **Files:** `~/.local/state/samagotchi/sessions/<uuid>.json` + `<uuid>/input|output|owner.lock|bridge.json` (XDG-aware), and the `<uuid>/stopped`, `<uuid>/starting` and `<uuid>/archived` marker files. Durable schedules belong to the machine, not a session: `~/.local/state/samagotchi/schedules.json` and its `schedules.lock`, next to `sessions/` ([Scheduling](scheduling.md)).
 - **Single owner:** the process running a session's Engine (its worker, or a `--non-interactive` one-shot) holds a flock on `owner.lock` (`OwnerLock`); a second owner backs off, and the web answers 409 for a session a one-shot owns.
-- **Status:** `status` is turn state (`idle`/`running`); liveness is the lock. A stop is the `<uuid>/stopped` marker (`Session.mark_stopped`; a resume removes it), which `Session.load` and `.summary_from_file` read as status `stopped`, so no other process rewrites a worker's session file.
-- **Retention:** 14 days / 500 cap (env `SAMAGOTCHI_SESSION_RETENTION_DAYS`/`MAX_COUNT`, optional `KEEP_STATUS`), live-owner guard, only when `*.json` present; lazy sweep at most once per `session.sweep_interval_hours` (default 24) from the session hub's full-probe tick (and on `GET /api/sessions`, which the page no longer calls), manual via `bin/chi sessions prune --dry-run`.
+- **Status:** `status` is turn state (`idle`/`running`); liveness is the lock. A stop is the `<uuid>/stopped` marker (`Session.mark_stopped`; a resume removes it), which `Session.load` and `.summary_from_file` read as status `stopped`, so no other process rewrites a worker's session file. A resume writes nothing else: the worker, holding the lock, turns a status from before it idle (`Worker#settle_stale_status`: `stopped` with no marker, `error`, a `running` no turn is behind; not a new session's `running` whose first prompt waits), and saves at start whatever the status, which stamps `updated_at` as the resume's save did (a session woken with no turn stays young for the sweep). N-1: a newer spawner starting an older worker (a checkout's chi spawning the installed one) loses that reset; a restart covers it.
+- **Starting:** every spawn marks the session starting (`<uuid>/starting`, `{pid, at}`, `StartingMarker`) until its worker holds the lock: `spawn_worker_for_session` writes it with its own pid before `Process.spawn` and the starter's after (the starter lives until the worker holds the lock, at most `WORKER_START_GRACE`; a spawn that raises or whose starter is gone leaves none), `spawn_session` before the new file is saved, and `Worker#start` removes it. It holds for 60 s at most, and only while the pid it names runs. A resume claims it (`StartingMarker.claim`, a link(2): of resumes racing from any processes one wins), then reads the owner again. A stop marker cancels the hold-off (`start_pending?` = starting and not stop-marked) for a start marked before the stop only: of two sends after a stop, the claim lets one spawn. The stop marker carries its own `at` (`{"at"}`, on the starting marker's clock; `Session.stopped_at`), an older chi's empty one its mtime. The sweep, archive (`:starting`) and delete (refused as an owned session) honour it. N-1: an older spawner writes none for a resume (the owner checks stay); an older worker never leaves one it was given (every worker clears it at start); a leftover one is stale by age or pid (a claim's temp files a kill left, `starting.*`, count as skeleton); a 0.160 spawner or chi web still holds off on a fresh marker under a stop (it reads `starting?` before the stop), until the start ends or 60 s. `SessionManager` keeps only its starters' pids, for chi web's restart to adopt (`live_spawn_pids`), and decides nothing from them.
+- **Deleting:** `delete_session`, the retention sweep and a failed continue's cleanup use `remove_files` for the session JSON, sidecar dir, plugin state, attached context, participant grants, System 1 runs and context-candidate records. The JSON and dir go through `remove_session_files`, holding the owner lock (kind `deleting`, which `stop_session` never signals; not waited for: a worker that took it since the check keeps the session) and reading the starting marker again under it (a resume that claimed the start just before keeps the session; one after it sees the lock held). N-1: an older chi's stop reading the owner then would TERM the deleter (chi web, the CLI) in that moment; an older reader shows the kind as unknown. `Session#save` of a session read from its file (or saved once) skips a file that is gone (log `save_skipped_deleted`) rather than recreate it; only a new session's first save creates one.
+- **Worker presence:** whether a worker is up, coming or held off is read once per decision as a `WorkerPresence` (`worker_presence.rb`, a `Data.define`), the deciders' one reader of those facts (display and list rows still read `session_owner` / `WorkerLink` themselves): the owner lock's holder, the stop marker (`stop_marked?`: the only "stopped" a decider reads, never the session file's status), the `starting` marker (`StartingMarker`, `starting?`, `start_pending?`: every spawn writes it, see Starting), the archive marker, the session file's existence, and the `WorkerLink` outcome when asked (never the file itself: a scratch session's flag is read by `WakePolicy`, last). The deciders read it: `resume_session` (tui, owned, `resume_held_off?`), the session inbox's `WakePolicy` (a ring, a push's wake, a note, a fresh verdict, `wake_for_report`, `deliver_turn`'s two liveness checks, `WorkerBoot`'s leave: below), `Local#wake`/`#worker`, `AttachLauncher`, `Schedules#busy_reason`, archive, delete and the retention sweep. Each keeps its own subset of the facts and their order.
+- **Session inbox:** a delivery into a session (`SessionInbox.deliver(kind, id) { |at| write }`, `session_inbox_delivery.rb`) runs one path: resolve the link (`SessionInbox::Head.resolve`: send, push and a fresh verdict are pinned to the id named; a note goes to the chain's newest link; a ring's file stays with the parent `parent.json` names and its wake goes one hop, to the link whose `ChildReports` reads that file; only an archived id is walked, with one `Session.list`), refuse before any write (a gone session; a one-turn run's or a scratch session for send and a note), write with the kind's own writer (formats unchanged), read `WorkerPresence` once, and apply the kind's `WakePolicy` row. `decide` reads in one order for every kind: gone, one-turn run (`:owned`), owned (`:live`), the stop marker (`:stopped`: the only "stopped", the file's status never decides; send un-stops), archived (send alone starts one), starting (`:starting`, never a second spawn), the kind never starts (`:none`: a note, a fresh verdict) or wasn't asked to (`:off`), scratch (the session file is read only here), else `:start` through `SessionManager.start_for_inbox` (`resume_session`, its claim on the starting marker; it answers `:woken` only when it spawned the worker, `:starting` when another start won the claim, `:live` when a worker took the lock since). N-1 gap: a session file that says `stopped` with no stop marker (stopped before the marker existed, or a resume whose spawn failed after it cleared the marker) is woken, and an older worker, which has no `Worker#settle_stale_status`, exits on its first pass; the wake still reads `:woken`, and each later ring or push spawns another such worker (bounded by the rings and pushes). Restarting chi on the new version (`chi web`, the workers) closes it. `SessionInbox.wake` is the wake half alone (`wake_for_report`, a failed continue's rings). On it: `ChildRing.ring` (its start on a thread), `Local#context_push`'s wake (its outcome is `ContextPush#wake`, the push line's ending), `NoteDelivery.deliver` (every note writer a person or another session drives: `chi note`, `send_note`, `chi broadcast`, chi web's notes route; `NoteDelivery::Result#id` is the link that has it, `#asked` the one named; `/objectives` passes `pin: true`: its list is its own session's) and `VerifyFresh.forward` (`:fresh_verdict`: the child's parent, pinned, no worker). Send keeps its Bridge/file flow in `SessionManager.deliver_turn` (pinned to the id it names: an archived link gets the message and comes back); its two liveness checks (before the post, after a file's write) read the `:send` row and leave the refusals to `resume_session`'s wording. One row is not a delivery: `:leave`, `WorkerBoot.run_session_loop`'s successor as a worker leaves (input left after a signal, an idle exit's or `/exit`'s input or rings, a restart), read on a fresh presence once the lock is free: a stop that landed as it left starts none for any way out (`resume_session` would clear the stop; logged `respawn_dropped`, `restart_dropped` for a restart, whose reminders go with it), the input and rings stay for the next start. The notes a spawn writes into the session it starts stay direct `SessionInbox.write_note` calls, pinned by construction: spawn_session's chain note, `ContextMove`'s notes, `Objectives.carry`, `ChildMove`'s note to a moved child. A continue moves the previous link's waiting notes to the new link last in its `before_spawn` (`NoteMove.move`), a failed one gives them back before the link goes (`NoteMove.give_back`), and the new link's worker adopts what the archived links before it get after their continue (`NoteMove.adoption`, from `WorkerInbound#absorb_notes` and `Worker#start`: back along the chain through up to 8 archived links, from each only notes from the creation of the link that continued it, never an objectives list). `write_note` refuses a session with no file and no folder (`Session::NotFound`), so a late writer can't bring back a deleted link's folder.
+- **Retention:** 14 days / 500 cap (env `SAMAGOTCHI_SESSION_RETENTION_DAYS`/`MAX_COUNT`, optional `KEEP_STATUS`), live-owner and starting guard (looked at again right before a session's files go), only when `*.json` present; lazy sweep at most once per `session.sweep_interval_hours` (default 24) from the session hub's full-probe tick (and on `GET /api/sessions`, which the page no longer calls), manual via `bin/chi sessions prune --dry-run`.
 - **Ordering:** `Session.list(sort:,order:,limit:,offset:)` and `GET /api/sessions?sort=&order=&limit=&offset=` default `updated_at desc`; Web UI sort/filter/pagination.
 - **Test hygiene:** `test_run` flag when `SAMAGOTCHI_ENV=test`/`RACK_ENV=test`/`CI`, targetable via `prune --test-only` / `clean`.
 
@@ -471,7 +474,7 @@ model: [internals/remote-sessions.md](internals/remote-sessions.md).
 | `DELETE /api/sessions/:id/context/:name?own=1` | owner | | 200 `{status: detached}`: the session's own only | 409 `project_source` (chi context rm's words); 404 |
 | `POST /api/sessions/:id/stop` | owner | `wait?` (seconds, capped at `SessionManager::STOP_WAIT`, 10: `chi --remote NAME sessions stop` sends it) | 200 `{status: stopped, session_id, released}`: `released`, whether the worker let go within the wait (without one `STOP_WAIT_SECONDS`, 2 s: the page's Stop) | 409 `owned_by_tui` |
 | `DELETE /api/sessions/:id?force=` | owner | `force=true` stops a live worker first (the page sends it) | as before | 409 `worker_running` without it |
-| `GET /api/sessions/:id?brief=1` | participant (theirs: title, status, participants) | | 200 `{brief, session: {id, status (the file's), title, display_title, project_root, working_directory, model_name, model_typed, parent_answers, owner}, pending_question}` (the file's; no messages): `Remote#show` | 404 |
+| `GET /api/sessions/:id?brief=1` | participant (theirs: title, status, participants) | | 200 `{brief, session: {id, status (the file's), title, display_title, project_root, project_id, working_directory, model_name, model_typed, parent_answers, owner}, pending_question}` (the file's; no messages): `Remote#show` | 404 |
 | `POST /api/sessions/:id/turn` (its 202) | owner | | the ack with `via`: `bridge` or `file` (the input file: a remote `chi send --wait` follows that turn) | |
 | `GET /api/sessions/:id/context?full=1`, `…/context/:name?full=1` | owner | | each row with `source` (`Source#to_h`, its command too; the page's rows never carry one), `snapshot` (`Snapshot#to_h`, no text) and `shadowed`, shadowed project sources included | |
 | `POST /api/sessions/:id/wake` | owner | `wait` (seconds, default and most 10: `WAKE_MAX_WAIT`) | 200 `{session_id, woke, worker: {epoch, started_at, version, features}, model_name, default_model, parent_strategy, installed}`: the live worker as is (`woke: false`), else resumed and its Bridge waited for (`Local#wake`); `default_model` and `installed` are this machine's | 409 `owned_by_tui`, `scratch` (`Session::SCRATCH_REFUSED`); 504 `worker_timeout` (`LaunchMode::BRIDGE_LATE`); 400 `invalid_wait`; 404 |
@@ -655,7 +658,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Dialects | `llm/dialect.rb` (`LLM::Dialect`) | What an `api: anthropic` provider's `/v1/messages` does differently (`dialect: fireworks`) ([internals/anthropic.md](internals/anthropic.md)). |
 | Logging | `log.rb` (`Log`), `log_subscriber.rb` (`LogSubscriber`), `log_path.rb` (`LogPath`), `log_line.rb` | The debug log: tagged records, a session's event trail, where the file goes ([configuration.md](configuration.md#debug-log-file)). |
 | Stores | `reminder_store.rb` (`ReminderStore`), `recap_store.rb` (`RecapStore`) | A session's reminders, and its idle recap (`recap.json`). |
-| Schedules | `schedules.rb` (`Schedules`, its `Entry`, `Tick`, `Index`), `schedule_command.rb` (`ScheduleCommand`) | Durable schedules that outlive every worker: `<state dir>/schedules.json` and its `schedules.lock`, the tick's busy check (a live worker asked over the Bridge's `GET /activity`, the files when there is none), the chain prune. `chi schedule` is this machine only. See [Scheduling](scheduling.md). |
+| Schedules | `schedules.rb` (`Schedules`, its `Entry`, `Tick`, `Index`), `schedule_command.rb` (`ScheduleCommand`) | Durable schedules that outlive every worker: versioned `<state dir>/schedules.json` and its `schedules.lock`; rewrites preserve unknown keys and entries missing required members. The tick's busy check (a live worker asked over the Bridge's `GET /activity`, the files when there is none), the chain prune. `chi schedule` is this machine only. See [Scheduling](scheduling.md). |
 | Reply waits | `reply_wait.rb` (`ReplyWait`, `GONE_AFTER`: the one dead-worker rule), `reply_wait/poll.rb` (`ReplyWait::Poll`, one look per poll), `reply_wait/target.rb` (`ReplyWait::Target`: which turn a wait binds, cursor, baseline, `owner_grace`; `first_message`, `message`, `wait_only`, `answer`, `participant`, `from_cursor`), `reply_wait/liveness.rb` (`ReplyWait::Liveness`: one owner and link read per look; `#owner?` for gone, `#worker_owned?` for an open question) | `chi send --wait`, `chi answer`, a participant's wait, the delegate tools and delegate reports wait through `ReplyWait.call(id, **target.to_h, …)` ([sub-agent.md](sub-agent.md)). |
 | Session rows | `session_row.rb` (`SessionRow`) | A session as the lists see it: scalar facts only, built by `SessionManager.session_rows` (one owner, link, recap and analytics read each), `#to_summary_h` the summaries route's body and `.from_summary_h` a remote's rows read back, `#cli_line` the one `chi sessions list` line, `.running_or_starting?` the delegates' and Verify fresh's "running" (a 15 s grace for a worker on its way). A leaf: never session_manager or web. |
 | Setup and update | `bootstrap_command.rb`, `bootstrap/`, `update_command.rb`, `gem_update.rb` | `chi bootstrap` (first config.yml, system bundle, core profile) and `chi update` (the gem, shipped bundles, the macOS helper). |

data/docs/cli.md

@@ -36,8 +36,8 @@
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `big memories` the memories over `memory.entry_warn_tokens` ([Memory](memory.md#a-memorys-size)), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--to VERSION] [--json] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, and check the bundles from elsewhere, in one table (see [Updating](#updating))
 - `chi home`, `chi home set [--ruby PATH]`, `chi home doctor` — the chi home: the one Ruby (and its gem path) every chi launch boots, whoever launches it. `chi home` shows it (its Ruby, the newest chi in it, gem home and path, `mise`, when and by which chi it was set, and the chi you ran when that is another one; exit 1 with the problem when it can't boot chi), `set` records this chi's Ruby and gem path (or `--ruby PATH`'s own; it must have samagotchi), `doctor` checks it and what should follow it, one row each with `ok`, `warn` or `fail` and what to run (exit 1 on a `fail`; see [Checking it](configuration.md#checking-it-chi-home-doctor)). At a terminal, a chi on another Ruby than the home's says so in one dim line a day. This machine only (see [The chi home](configuration.md#the-chi-home))
-- `chi project`, `chi project init [DIR]` — this folder's project, and making a folder in no git repository one. `chi project` prints how its project was found (`kind` `git`, `marker` or `none`), its `root` (what memories are keyed on), its `top` (where the AGENTS.md chain starts) and its project `memories` folder, with a `note` for a marker a repository makes ignored, or a `$HOME` that is a git repository. `init` writes `DIR/.chi/project.yml` (DIR defaults to this folder and is created when missing), so DIR and every subfolder share one memories folder, group their sessions and take `chi context --project`; it writes nothing in a git repository (the repository already is the project, exit 0), says so for a folder already marked, refuses `$HOME`, a folder above it and `/` (exit 1), and marks a folder inside another marked project as its own, nested one. It prints the root and the memories folder (with the memories already there: a folder chi ran in at its top keeps them), the running sessions in DIR to restart (`chi sessions restart ID`: their prompt keeps the old project) and, when DIR has saved sessions, that a running chi web groups them after its restart. This machine only. See [Projects without git](memory.md#projects-without-git)
-- `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Plugins](plugins.md) and [Bundle hooks](hooks.md#bundle-hooks)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `upgrade <name>` upgrades an installed bundle by name from the source it came from (its folder, archive or git URL), `upgrade <source>` from a new one; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Bundles](bundles.md#the-btw-bundle), [the mcp bundle](bundles.md#the-mcp-bundle) [the loop-guard bundle](bundles.md#the-loop-guard-bundle), [the check-in bundle](bundles.md#the-check-in-bundle) and [the skills bundle](bundles.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). `install`/`upgrade` `--force` overwrites existing entries and also installs a bundle whose `requires_chi` this chi doesn't meet; without it such a bundle is refused (exit 1), nothing written. A plain `install` of a bundle that is already installed from the same source rewrites its rules, plugin, scripts and record: the summary lists a file that already holds the bundle's bytes as `Up to date: …`, one you wrote as `Skipped: …`, and ends with `NAME was already installed from SOURCE: its rules, plugin and scripts now match it and its record was rewritten` (plus, when a memory was kept, `your own copies of its memories were kept (chi bundle upgrade NAME merges the bundle's changes into them)`). A source with class-file hooks (`hooks/*.rb` or a manifest `hooks:` entry) is refused, `--dry-run` too; an older install's hooks are removed by the next install or upgrade (`Removed (chi no longer loads class-file bundle hooks): …`, an edited one copied to the trash first; see [Class-file hooks are retired](hooks.md#class-file-hooks-are-retired)). `status NAME` lists the bundle's guardrail rules and scripts beside its plugin, each `[ok]`, `[missing]` or `[modified]` (edited: the next install replaces it, its copy kept in the trash; an edited rule doesn't load, so it counts in `issues=`), and `diff NAME` names an edited rule or script with its recorded and current sha256 (chi keeps no base text for them). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
+- `chi project`, `chi project init [--new-id] [DIR]` — this folder's project, and making a folder in no git repository one. `chi project` prints how its project was found (`kind` `git`, `marker` or `none`), its `root`, its `top` (where the AGENTS.md chain starts), a marked project's `id` (what its memories and project context are keyed on; else the root's path is) and its project `memories` folder, with a `note` for a marker a repository makes ignored, or a `$HOME` that is a git repository. `init` writes `DIR/.chi/project.yml` with a new `id:` (DIR defaults to this folder and is created when missing), so DIR and every subfolder share one memories folder (kept when DIR moves or is renamed), group their sessions and take `chi context --project`; it writes nothing in a git repository (the repository already is the project, exit 0), says so (with the id) for a folder already marked, refuses `$HOME`, a folder above it and `/` (exit 1), and marks a folder inside another marked project as its own, nested one. On a folder marked without an id (an older chi's marker) it adopts one: the folders keyed by its path move to the id, each leaving a link by its old name, and it says what moved and names memories an earlier path left (refused, exit 1, while a session of the project runs). `--new-id` gives a marked folder a fresh id with a copy of its memories and project context (a copied folder going its own way; refused elsewhere, exit 1). It prints the root, the id and the memories folder (with the memories already there: a folder chi ran in at its top keeps them, moved to the id), the running sessions in DIR to restart (`chi sessions restart ID`: their prompt keeps the old project) and, when DIR has saved sessions, that a running chi web groups them after its restart. This machine only. See [Projects without git](memory.md#projects-without-git)
+- `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Plugins](plugins.md) and [Bundle hooks](hooks.md#bundle-hooks)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `upgrade <name>` upgrades an installed bundle by name from the source it came from (its folder, archive or git URL), `upgrade <source>` from a new one; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Bundles](bundles.md#the-btw-bundle), [the mcp bundle](bundles.md#the-mcp-bundle) [the loop-guard bundle](bundles.md#the-loop-guard-bundle), [the check-in bundle](bundles.md#the-check-in-bundle) and [the skills bundle](bundles.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). `install`/`upgrade` `--force` overwrites existing entries and also installs a bundle whose `requires_chi` this chi doesn't meet and a memory, plugin or script whose bytes disagree with its manifest `sha256`; without it such a bundle or file is refused (exit 1), nothing written. A plain `install` of a bundle that is already installed from the same source rewrites its rules, plugin, scripts and record: the summary lists a file that already holds the bundle's bytes as `Up to date: …`, one you wrote as `Skipped: …`, and ends with `NAME was already installed from SOURCE: its rules, plugin and scripts now match it and its record was rewritten` (plus, when a memory was kept, `your own copies of its memories were kept (chi bundle upgrade NAME merges the bundle's changes into them)`). A source with class-file hooks (`hooks/*.rb` or a manifest `hooks:` entry) is refused, `--dry-run` too; an older install's hooks are removed by the next install or upgrade (`Removed (chi no longer loads class-file bundle hooks): …`, an edited one copied to the trash first; see [Class-file hooks are retired](hooks.md#class-file-hooks-are-retired)). `status NAME` lists the bundle's guardrail rules and scripts beside its plugin, each `[ok]`, `[missing]` or `[modified]` (edited: the next install replaces it, its copy kept in the trash; an edited rule doesn't load, so it counts in `issues=`), and `diff NAME` names an edited rule or script with its recorded and current sha256 (chi keeps no base text for them). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
 - `chi guardrails replay [--dry-run] [--threshold T] [--model M]` — seed System 1's record from the approvals this machine's sessions already answered: each ask is judged by the configured model and written to `guardrails/judgments.jsonl` with the answer the user gave, then a per-rule table prints (asks, allowed, denied, would-be auto-allows, false allows, asks with no judgment). A parent agent's answer is not the user's: only its deny is replayed, and only where the parent could have allowed. `--dry-run` judges without writing, `--threshold` overrides `guardrails.system_one.threshold` for the table, `--model` the configured model for this run. Exit 2 when `guardrails.system_one.mode` is off or no `host` is set; a usage error exits 2 (see [System 1](guardrails.md#system-1-experimental))
 - `chi guardrails rule <id>` — print exactly `asks` when that rule is loaded, not disabled and votes `ask` in this `guardrails.mode` for every model; any other line says why not (no such rule, disabled, another mode, it denies, for some models only, rules that failed to load, `guardrails.enabled: false`). Exit 0 either way, 2 for a usage error. It reads config.yml and the installed bundles as a worker does (`GuardrailWiring#rules`) and takes the rule's id, never a command; the [coordinator skill](bundles.md#the-coordinator-bundle) reads it before it merges without asking
@@ -512,9 +512,9 @@ invalid option (exit 1).
 | `--parent-answers LEVEL` | A new session's own `guardrails.parent_answers` (`hard`, `standard` or `soft`): what a parent agent may answer on its questions. It may only tighten config.yml's: the stricter of the two applies, and a looser one is saved as given with a warning (`--parent-answers soft is looser than config.yml's guardrails.parent_answers: standard; standard applies`). Saved in the session; a respawned worker, a fork and a continue keep it, a `delegate` child takes its parent's. Ignored with `--attach`/`--resume` (one line, as `--toolkit`); refused with `chi web`. Only you loosen it: `/parent-answers` in the terminal or the web. See [Guardrails](guardrails.md#answers-from-a-parent-agent). |
 | `--set KEY=VALUE` | A setting for a new session (repeatable; a later one of the same key wins). A core key a session may set (`recap.enabled`, `recap.sentences`) is typed by the key and goes first, over the CLI, env and config.yml: `--set recap.enabled=false` turns the idle recap off for this session; a value it doesn't take (`recap.enabled=maybe`) or a key no session sets (`guardrails.mode`) is an error, exit 2 (see [Per-session settings](configuration.md#per-session-settings)). Any other name is a bundle's `BUNDLE.KEY`, laid over config.yml's `bundles: <bundle>:` in what the bundle's plugin reads (`ctx.settings`): `--set cost-cap.cap=3`. The value is typed simply: an integer (`3`, `-1`) or a decimal (`2.5`, `.5`, `1e1`) is a number, `true`, `yes` and `on` are true, `false`, `no` and `off` are false (any case, as in config.yml), anything else stays the text as given (`010`, `0x10`, `3:30`, `y`, `null`), and so does every value of a key the manifest types `string`. For cost-cap, `0`, a negative number or `off` is no cap. Only a key the installed bundle's manifest lists in `session_settings:` is taken, with a value of the type it gives the key: a bundle that isn't installed (or whose plugin doesn't load), a key it doesn't list (a record installed before the bundle listed it says to run `chi update` or `chi bundle upgrade NAME`), a value of another type (`--set cost-cap.cap=five`), or another shape (`--set foo`, `--set a.b.c=1`) is an error naming what it takes, exit 2, nothing started. Saved in the session; a respawned worker, a fork and a continue keep it, a delegate child doesn't. Ignored with `--attach`/`--resume` (one line, as `--toolkit`); refused with `chi web`. See [Per-session settings](plugins.md#per-session-settings). |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
-| `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
+| `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Stored on the session; a fork and a continue keep the list too. A fork leaves out reserved `system/delegated` so it does not become a delegate. |
 | `--append-system-prompt FILE` | Put `FILE`'s text into the system prompt, after AGENTS.md and before the memory indexes (repeatable; relative to the shell's directory). Added after the config.yml `append_system_prompt:` list. A missing or unreadable file is an error, exit 1. Saved in the session, so a respawned worker, a fork and a continue keep it; ignored with `--attach`/`--resume` (one line, as `--memory`). See [Appended prompt files](configuration.md#appended-prompt-files). |
-| `--mute NAME` | Hide a memory from this session (repeatable; a comma list too): its index line is not in the prompt, `memory_read` refuses it, the identity auto-load skips it, and it is dropped from the preloads (config baseline or `--memory`). A name matches in both scopes (`gh-helper`, `project/gh-helper` and `gh-helper.md` all hide `gh-helper`). Nothing on disk changes. See [Muting a memory](#muting-a-memory). |
+| `--mute NAME` | Hide a memory from this session (repeatable; a comma list too): its index line is not in the prompt, `memory_read` refuses it, the identity auto-load skips it, and it is dropped from the preloads (config baseline or `--memory`). A name matches in both scopes (`gh-helper`, `project/gh-helper` and `gh-helper.md` all hide `gh-helper`). A fork and a continue keep the list. Nothing on disk changes. See [Muting a memory](#muting-a-memory). |
 | `--llm-context LAYERS` | This session's own LLM context strategy: `none`, or layers such as `stale` or `stale,forget` (comma, space or `\|` separated). Saved in the session, before the model's `llm_context_strategy`. With `--resume` it is set on the resumed session; on an attached or resumed worker it runs as `/llm-context` before the first prompt (after `--model`'s `/model`). A value that isn't one is an error before anything starts. See "LLM context: a session's own strategy" in configuration.md. |
 | `--llm-context-apply RULE` | This session's own apply rule: `payoff`, `next_request` or `turn_end`. |
 | `--llm-context-budget TOKENS` | This session's own context budget: `64000`, `64k` (4k to 10M), or `off` (wins over the model's budget). |
@@ -804,7 +804,9 @@ file and index line stay as they are; only this session doesn't see it.
   `muted_memory_names` in the session's JSON), written before the worker
   starts. A worker respawned by `--resume`, `--attach` or `chi send` builds
   the same prompt, and a `--resume ID --non-interactive` one-shot keeps the
-  lists too (merged with the flags it is given).
+  lists too (merged with the flags it is given). A fork and a continue keep
+  the lists too; a fork drops the reserved `system/delegated` memory, and a
+  continuation of a delegate child drops it because the new link is not a delegate.
 - A mute wins: `--mute user_preferences` drops that config baseline entry for
   one session, and `--memory x --mute x` is a mute (one warning line).
 - Names are checked before the launch, warnings only: `Warning: --memory 'x'

data/docs/context.md

@@ -252,7 +252,16 @@ you're away from the terminal. All of these must hold:
 - the session's worker is up and idle: no turn running, nothing queued, no
   question or continue offer waiting, not just started. A changed push from a
   session-scoped source can start an idle-exited worker; it never restarts an
-  explicitly stopped session;
+  explicitly stopped session (the push waits for its next start). Only the
+  stop marker (`chi sessions stop`) counts as stopped. `chi context push`
+  ends its line with what that wake did: `· chi woken`, `· chi is stopped: it
+  sees this at its next start` or `· chi is starting` (nothing when the
+  worker is up, or the push asked no wake; chi web's push answer carries it
+  as `wake`). `· chi woken` means this push started the worker; one another
+  start had begun says `· chi is starting`. A worker from an older chi woken
+  for a session whose file still says stopped with no `chi sessions stop`
+  behind it exits at once: the line still says woken; restarting chi on the
+  new version covers it;
 - under `session.max_wakes` turns in a row with no message from you (the
   budget delegate reports and finished background tasks use too; a turn that
   failed, or was stopped before the model call, pauses wakes until you write);

data/docs/guardrails.md

@@ -92,10 +92,13 @@ Allowing beyond "once" is stored in `$XDG_STATE_HOME/samagotchi/guardrails/appro
 
 | Scope | Allows |
 |---|---|
-| session | this exact call in this session: the tool + command, or for a file tool its paths, so its label names them (`Allow edits to config.yml for the session`) and a later edit of that file needs no ask |
+| session | this exact call in this session: the tool + command, or for a file tool its paths, so its label names them (`Allow edits to config.yml for the session`) and a later edit of that file needs no ask. A command's holds only where it was given: the same worktree or folder (`repo_root`, never the repository's other checkouts) and the same `env:` (a sha256 of it is stored as `env`, never the values) |
 | repo | this exact call in this repo (the cwd outside a repo), any session |
 | rule | anything this rule asks about in this repo |
 
+A session entry of a command from before chi kept its place (no `repo_root`) no longer matches: the call asks once
+more. `/guardrails` shows a session entry with its folder (`session 3fa2c1d0 in /work/app`, `with its env:`).
+
 "This repo" is the git repository, not the folder: an approval given in one
 worktree holds in the main checkout and every other worktree of it (it is
 stored with the repository's common git dir as `repo`, and the worktree as
@@ -294,9 +297,26 @@ by editing the session file, or by running `chi --attach` on a PTY with the
 markers cleared. chi's instructions for parents ([chi as a
 sub-agent](sub-agent.md)) tell them to use `chi answer` only.
 
+## Who may run a session command
+
+A message that is a session command (`/model x`, `!cmd`, `!rollback`) runs as the command only when a person sends
+it: a web tab, an attached chi TUI, `chi send` (yours, or one a model runs from `execute`: the trust model above), a
+message with no sender named, and `chi answer`'s lines (`cli:answer`: a parent agent's `/continue yes` and
+`/parent-answers`), which may send any session command, with the same trust as `chi send`.
+`!cmd` runs its shell line with no rule or ask (it is yours), so from anyone else it is refused: a delegating parent's
+task or follow-up, a schedule's firing (both modes), a plugin's message, a context or task wake. Chi web's Bridge answers
+`403 command_not_permitted` with one message, an input file's line shows as the command's error, and nothing runs.
+Their `/word` line is plain text: the model reads it. `delegate`, `schedule_task` and `chi schedule add` refuse a task
+or prompt that starts with `!` with the same message, so the model can rewrite it. A participant's command is refused
+as before ([their review boundary](#a-participants-review-boundary)). The rule is `CommandIntake`
+(`lib/samagotchi/command_intake.rb`), asked by `Bridge#handle_post_turn` and `WorkerInbound#queue_as_command`;
+`POST /command` (a UI's or a card's explicit command line) is not a message and is not covered.
+
 ## Protected paths
 
-Built in, for `write`, `edit` and `memory_write` (symlinks resolved; see
+Built in, for a call whose [targets](plugins.md#guardrails) say it writes
+its paths: `write`, `edit`, `memory_write`, and a plugin tool's `targets:`
+with `writes: true` (symlinks resolved; see
 [How paths resolve](#how-paths-resolve)):
 
 - deny: the approval store's dir, installed bundles (`memories/.bundles/`),
@@ -316,7 +336,9 @@ bundle: a child asks before it changes anything outside its folder, the work
 tree top of the folder it was started in (a worktree from `delegate cwd:`,
 else the parent's checkout). Rule `child-boundary`, source `core`; it asks when
 
-- `write` or `edit` names a path outside it (tmp dirs and memory files don't count);
+- a call whose [targets](plugins.md#guardrails) say it writes its paths —
+  `write`, `edit`, and a plugin tool's `targets:` with `writes: true` —
+  names a path outside it (tmp dirs and memory files don't count);
 - `execute` or `task_create` runs mutating git in another dir (`git -C`, `cd`,
   `GIT_DIR`: what `git: outside_repo` matches), or a command that isn't
   read-only starts outside it (its `cwd:`) or names a path in the repository's
@@ -326,7 +348,12 @@ else the parent's checkout). Rule `child-boundary`, source `core`; it asks when
   even from its own worktree: a `git config` write (not `--get`, `--list`,
   `--worktree`), `update-ref`, `worktree add|remove|move|prune`, `stash
   drop|clear|pop`, creating or deleting a tag, and deleting, forcing or
-  overwriting a branch other than its own.
+  overwriting a branch other than its own;
+- any call whose `targets:` carry a `command:` (a plugin tool's) is checked
+  for git that changes what every checkout shares, and for a `cwd:` outside
+  the child's folder. Its command's text may not be shell, so the reads a
+  shell call gets (its `git -C`/`cd` dirs, its redirects, its read-only test)
+  are left out.
 
 Read-only commands (`git -C ../app log`, `cat ../app/x`) and paths elsewhere
 (`/usr/bin`, `~/.gem`) never ask, nor does a read-only command that writes only
@@ -1508,6 +1535,7 @@ the text a rule sees, and a function or alias shadowing a reader in the same
 command isn't seen at all. `outside_repo` covers the file tools and git
 only: `sed -i`, `cp` or `cat > file` into another folder from the shell aren't
 asked about, and neither is git run through `sh -c`, a script, an alias, `make`
-or a folder in a variable. `!cmd` lines typed by you are not checked. The only
+or a folder in a variable. `!cmd` lines typed by you are not checked (see
+[Who may run a session command](#who-may-run-a-session-command)). The only
 real defence against an adversarial model is isolation (a sandbox, a git
 identity without push rights).

data/docs/internals/attached-context.md

@@ -51,8 +51,10 @@ comment is the file map and [../context.md](../context.md#storage) lists it for
   `Candidate`, `Left`, `Moved`/`Stayed`.
 - **Locations.** A `Location` is a folder of sources: a project's (`projects/<project_key>/`, shared by the
   project's workers) or a session's (`sessions/<id>/`, which also holds `subscriptions.json`, the `muted/` and
-  `declined/` markers, `candidates/`, `left.json`). `ContextSources.attached(session_id, project_root:)` is what a
-  session sees: its own, then the project's it doesn't shadow. Names are `NAME_RE`; `subscriptions` and `left` are
+  `declined/` markers, `candidates/`, `left.json`). `ContextSources.attached(session_id, project_root:, project_id:)`
+  is what a session sees: its own, then the project's it doesn't shadow. The project key is
+  `MemoryPaths.key_for(root:, id:)`, the memories folder's key: a marked project's id (`Session#project_id`, saved at
+  creation), else the root's path key; every caller holding a session passes both. Names are `NAME_RE`; `subscriptions` and `left` are
   reserved (`RESERVED_NAMES`) because their files share the folder.
 - **Writes are file replaces** (`AtomicFile`). `Location#locked(name)` takes `<name>.lock`, the lock a fetch holds
   for its whole command; `record_text` and `record_error` run under it, and `remove` leaves the lock file so a fetch

data/docs/internals/bridge.md

@@ -195,8 +195,11 @@ ring holds the event. `serve!` orders a join so that nothing is missed or double
 
 A **`reset`** frame (the same content, numbered with its own seq) is written when a cursor cannot be replayed: it is
 from another epoch, ahead of the engine (a restarted worker), behind the ring's window (a cursor at `oldest - 1` has
-seen everything before the window and replays), or the queue overflowed since the last drain. A cold connect replays
-the whole window. Replay state is in memory per worker; there is no durable resume.
+seen everything before the window and replays), or the queue overflowed since the last drain. A cold connect (no
+cursor) is behind the window too once the ring has evicted an event (`RingBuffer#dropped?`: a replay would start mid-turn), so
+it gets the `reset`; on a ring that never evicted (its first seq can be above 1: events before the Bridge started) it
+replays the whole window. The clients re-sync on a `reset` and
+reconnect with the snapshot's own id, which is inside the window (the web `resync`, the TUI's `follow`). Replay state is in memory per worker; there is no durable resume.
 
 Each frame is `id: <seq>-<epoch>` (`EventId`: the seq first so a reader that takes it as a number still gets the
 seq), `event: <type>`, `data: <json>`. A `: ping` goes out after `heartbeat_interval` (15 s) of silence. A watcher
@@ -235,6 +238,13 @@ The Bridge exposes:
   sends its requests there (`worker_changed`); it gives up after ~12 s, or at once when the session
   was stopped.
 
+  **Adding an event type.** Assign every emitted type a lifetime in `Events::CLASSIFICATION`
+  (`row`, `state`, `transient` or `internal`); keep stream frames and synthetic replay types in
+  `Events::STREAM_FRAMES` and `Events::SYNTHETIC`. `spec/events_drift_spec.rb` checks event coverage
+  and names the live web/TUI handlers; for rows it also checks the reload owner (`TurnAccumulator`
+  or `CardStore`) and TUI join replay. Follow any documented exception there when a row reloads
+  through session messages or a fallback path instead.
+
   The wire chunk (the contract; the engine's own event keeps the provider's `payload` and the raw `content`):
 
   ```
@@ -286,9 +296,18 @@ The Bridge exposes:
   doesn't: the client uses `generation_started`'s). Unknown provider fields never cross; a field is added here
   when a client needs it, never as a catch-all bag. Details: [internals/context-telemetry.md](context-telemetry.md).
 - `POST /session/:id/turn` — fire-and-forget turn creation; returns `202` with an `enqueued_id`
-  (delivery is at-least-once via the worker's file-IPC input path — it never calls `run_turn`
-  across the HTTP boundary). Only the bridge's own session: another id, in the path or the body's
-  `session_id`, is `404 unknown_session`. Inspect results through the read surface, not the turn response.
+  (body: `{session_id, prompt, enqueued_id?}`; the optional id is a client-made UUID, generated by
+  the Bridge when absent or invalid). `BridgeClient#post_turn` supplies one when its caller does not,
+  including the attached TUI. The turn still goes through the worker's file-IPC input path — the
+  Bridge never calls `run_turn` across the HTTP boundary. Repeating an id already accepted by this
+  worker with the same prompt returns the original `202` acknowledgement, including its delivery and
+  cut outcome, and does not enqueue another turn; a different prompt with that id is refused with
+  `409 enqueued_id_conflict`. An input file with an already accepted id is consumed without running.
+  The worker keeps a bounded recent history of accepted ids.
+  For N-1 compatibility, an older worker ignores the optional field and generates its own id; an older
+  client sends none, so this Bridge generates one. Only the bridge's own session: another id, in the
+  path or the body's `session_id`, is `404 unknown_session`. Inspect results through the read surface,
+  not the turn response.
   An optional `deadline` (epoch seconds; `BridgeClient` sends 5/6 of its read timeout ahead) makes
   a request read after it (a worker frozen by sleep or SIGSTOP) answer `408 deadline_passed` and
   not run: a client that timed out has said the message was not sent. `/answer`,
@@ -300,7 +319,10 @@ The Bridge exposes:
   timeout is `504 worker_timeout`; a Bridge 404 for a route an older worker lacks is
   `501 not_supported` with the restart hint; a Bridge `404 unknown_session`, no bridge or a
   refused connection is `503 not_live`.
-- `POST /session/:id/cancel` — cancel the running turn; `202`, or `409` when none runs.
+- `POST /session/:id/cancel` — cancel the running turn; `202`, or `409 not_running` when none runs. The optional
+  `turn_id` names the turn the Stop means (the web page and the TUI send the one they show): `TurnState#cancel!` compares
+  it to the running turn's id under its lock, and another turn running is `409 turn_mismatch`, nothing cancelled, so a
+  Stop pressed as a turn ends can't cancel the queued next one. No `turn_id` (an older client) cancels whichever runs.
 - `POST /session/:id/recap` — `/recap` in an attached TUI: `200 {enabled, saved, request,
   min_user_turns}` (`{enabled: false, session_off}` without recaps; `session_off` when the session's own
   `/recap off` turned it off); a new recap is asked for at once and

data/docs/internals/bundles.md

@@ -31,7 +31,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 
 | Piece | Role |
 |---|---|
-| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check/try` (`install --dev`: the Installer's `dev:`, links and `Provenance::DEV_SHA`); runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it). `upgrade` resolves its argument by `upgrade_source`: a git URL or an existing path, then a shipped name, then the bare name of an installed bundle — whose record's source it then uses (a git URL with its `#ref`, a dir or an archive that is still there), printed as `Upgrading NAME from SOURCE`; a dev record is refused with `Installer.dev_install_line`, a recorded source that is relative, empty or gone says so and asks for the path or URL of a copy (`Installer.source_gone_line`, the words `ManifestStanding` uses too) |
+| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check/try` (`install --dev`: the Installer's `dev:`, links and `Provenance::DEV_SHA`); runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it). `upgrade` resolves its argument by `upgrade_source`: a git URL or an existing path, then a shipped name, then the bare name of an installed bundle — whose record's source it then uses (a git URL with its `#ref`, a dir or an archive that is still there), printed as `Upgrading NAME from SOURCE`; a dev record is refused with `Installer.dev_install_line`, a recorded source that is relative, empty or gone says so and asks for the path or URL of a copy (`Installer.source_gone_line`, the words `ManifestStanding` uses too). After an upgrade or uninstall that changed the bundle's plugin (or brought one in), one line names the sessions still running its old code (`LiveVersions.workers`, the ones whose worker takes a restart) and `chi sessions restart ID` for each: only the plugin stays in memory, since a bundle's rules reload by their stamp and its scripts run from the replaced files. |
 | `BundleCommand::Check` (bundle_command/check.rb) | `chi bundle check [PATH] [--fix] [--set K=V]`: a bundle being written, checked as an install takes it (docs/cli.md lists the codes); parses the manifest from `Shas.parseable` (a placeholder sha is a `sha` finding, not a YAML error), reads the user's installed bundles only for `clash`, and installs and loads through `Testing::Install` in a `Testing::Sandbox` with `force: true`, the log's echoes swallowed |
 | `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: `Command` (its flags, help and checks) drives the rest and `Render` prints the trace; a filtered-config `Sandbox` (its folders a `SandboxLayout`, the layout `Testing::Sandbox` uses too) installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards (`Bridge::CardStore.saved`, as the web does) and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output (a turn a `--timeout` interrupt cut keeps its calls like a Ctrl-C, the one cut short answered as interrupted, so its rows come from the saved calls too; `Run::Result#timed_out` becomes `timed_out`). `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers (`ChildEnv`, the scrub a session's worker spawn uses too). Every dropped key is sent as nil, so the child really lacks it: a spawn env is merged onto the spawner's, so a key only deleted from the Hash is still inherited (`ChildEnv.spawn_env`). The child runs in its own process group: a `--timeout` sends it INT, then `ProcessGroup.stop` (the groups its processes started too); after any exit the group is signalled only while a straggler is still in it, never a reaped group. `Sandbox#stop_leftovers` (before the trace, and in `cleanup`) stops what left the child's tree, found by the sandbox's own records: a delegate's worker by its session's `owner.lock`, a task by its running `task.json` whose pid still leads its group. |
 | `BundleCommand::ApiCalls` (bundle_command/api_calls.rb) | what a plugin's source calls of the API, by Prism: `#findings` (a call or keyword the API's classes lack, `check`'s `api`), `#keywords` (the floor check's `call(keyword:)`). Its only list is `MEMBERS`, which object a member gives (`ctx.sessions` → `Plugin::Sessions`); a new such object joins it |
@@ -131,8 +131,12 @@ has the bundle's own manifest at the recorded version (`Provenance#adopt_manifes
 
 ## Installer#run, in order
 
-The order matters: warnings print in it, and a plugin/script the manifest names but the bundle lacks raises
-`InstallError` after the memories are already copied.
+The order matters: warnings print in it. Before the first write, `AssetInstaller#check_named_files` raises `InstallError`
+for a plugin or script the manifest names but the bundle lacks (or ships as a link): nothing is written then. With
+`refuse_mismatch: true` (only `BundleCommand#installer_for` passes it), `Installer#refuse_memory_mismatches` and
+`AssetInstaller#check_named_checksums` raise the same way for a memory, plugin or script whose bytes disagree with the
+sha its manifest declares -- `--force` skips the check, a dev install follows its own tree, and a non-strict run has no
+shas to trust; `chi update`, `SystemBundle` and a profile pass nothing and keep the post-write warning.
 
 1. `load_source`: normalize (or take the `PreparedSource` `BundleCommand` passed as `prepared:`), read `manifest.yml` (strict: a missing/invalid one raises; non-strict: a warning). Then `refuse_too_new`: a bundle whose `requires_chi` this chi doesn't meet raises `InstallError` unless `force` — nothing is written, dry run included (docs/plugins.md, "Loading, and when it fails").
 2. `resolve_target`: scope = CLI > manifest > `system`; then `check_source` against the existing record
@@ -155,7 +159,8 @@ The order matters: warnings print in it, and a plugin/script the manifest names
    rules. A file that is a symlink or resolves outside the bundle dir (`AssetInstaller#linked?`) is skipped with a
    warning (a rule) or raises `InstallError` (the plugin, a script).
 5. An upgrade's `prune_dropped_files`: each dropped file's `FileState` (`shipped: false`) and its `UPGRADE` / `FORCE` row: unchanged (`#edited?` false) → trash; edited → kept (`kept_pruned`); owned by another bundle → kept.
-6. `verify_memory_checksums` (strict except a dev install, whose own tree may have stale shas; `chi bundle check` flags them: a memory whose action takes the bundle's text, `Action#takes_source?`: installed, forced, an upgrade's or a re-install's fast-forward, or merged into a local edit; it checks the source file the write or merge takes its bytes from, so a dry run checks what it would bring in; a `Remerge` merge checks its incoming file too), `warn_missing_needs`.
+6. `verify_memory_checksums` (strict except a dev install, whose own tree may have stale shas; the warning only, since a
+   run that refuses a mismatch (`refuse_mismatch: true`) never reaches it with one unless `--force`; `chi bundle check` flags them: a memory whose action takes the bundle's text, `Action#takes_source?`: installed, forced, an upgrade's or a re-install's fast-forward, or merged into a local edit; it checks the source file the write or merge takes its bytes from, so a dry run checks what it would bring in; a `Remerge` merge checks its incoming file too), `warn_missing_needs`.
 7. `write_provenance` (manifest, not a dry run): each owned file's base comes from its action's `next_base`
    (`Installer#next_base`): the file on disk, which has the bundle's bytes; the incoming file for a merge, since the merged
    file holds the user's edit and taking it would make current == base, so the next upgrade would fast-forward over the
@@ -171,7 +176,21 @@ The order matters: warnings print in it, and a plugin/script the manifest names
 A file system error in steps 3 to 5 (`Installer#replace_files`; a `.trash` it can't write, an edited file it can't read) is an
 `InstallError` in `Trash.failure_message`'s words, as it is an `UninstallError` in `Uninstaller#run`. Each save comes before
 its removal, so no edit is lost, and the record isn't written, so a retry is the same upgrade. Not atomic: files the
-failed run already placed stay.
+failed run already placed stay, and the intent journal says they are the bundle's.
+
+**The intent journal.** After `check_named_files` and before the first write, a real run with a manifest writes
+`.bundles/<name>/pending.json` (`Provenance#write_pending`, atomically like the record): `{"version": "2.0.0",
+"scope": "project", "target_dir": "/path/to/project-memories", "files": {"a.md": ["<sha256>"]}}`: the target
+`version` is the latest run's target version, while `files` holds the union of incoming shas recorded by interrupted
+runs for that scope/target directory. A retry of another version in the same target adds its incoming shas; a journal
+for another scope directory is ignored. `Provenance#write` removes it with the record write; an uninstall's `rm_rf`
+sweeps it. `FileState.of` reads it:
+a file whose disk sha is one of its shas is that bundle's text at the pending version, owned and its own base (an entry
+made up when the record has none), so a killed fresh install's copy isn't `:user_same` (kept as the user's for good) and
+a killed upgrade's fast-forward isn't `:edited` (a conflict at the next version). Install, upgrade, uninstall and
+`chi bundle status` all go through it. A file matching none of its shas follows the usual rules; a merged file isn't
+journaled (its bytes are no bundle text). Not covered: a journal left by a run that failed before writing a file whose
+text the user already had is read the same way.
 
 Which files a plan asks `Merger::Upgrade` about is the caller's, and the lists differ, each less the files the bundle
 doesn't own: the Installer's `MemoryFiles.select`; `ShippedUpdate.forecast`' every shipped `*.md`, so `chi update`'s plan

data/docs/internals/engine.md

@@ -538,7 +538,13 @@ Where a participant's author (`"p:<id>"`; `Steer.participant_author?`) goes (the
 - **`Session#last_turn.author`** and the analytics record's `author` (`SessionMetrics`); a Continue keeps the offer
   turn's author (`ContinueOffer#run_continue_turn`).
 - **Never a command**: a participant's `/word` or `!line` is refused (`Bridge#handle_post_turn` 403,
-  `WorkerInbound#queue_as_command` drops it).
+  `WorkerInbound#queue_as_command` drops it). The same two intakes ask `CommandIntake.allowed?` for every other
+  sender: only a person's (`ClientId.human?`, not `review:`) and `cli:answer`'s line is a command; from a delegate, a
+  schedule, a plugin or a wake a `/word` line is a prompt and a `!` line is refused (the Bridge's 403
+  `command_not_permitted`; an input file's or a first prompt's is queued and `Worker#run_command_line` answers it with
+  the error `command_ran`). A session's first prompt carries its sender too: `WorkerInbound#initial_origin` reads
+  `Session#first_turn_client_id` (a delegate child without it: `ClientId.delegate` of its parent) and `first_turn_id`,
+  for `#initial_command?` and `Worker#run_initial_prompt`.
 - **Delivery**: a participant's input always waits for a turn of its own (`SessionInbox.waits_for_turn_end?`), so
   the drain never merges it; their turns count against chi web's `pending_limit` (429 `too_many_turns`).
   `Worker#run_prompt` checks their link and cap (`participant_refusal`) before the turn and after it.

data/docs/internals/objectives.md

@@ -61,7 +61,10 @@ the payload, so an edit and a continue carry none: a new link starts with no las
 ## Editing
 
 `/objectives` (`ObjectivesCommand`, registered `anytime`) reads `Objectives.current`. An edit goes out through
-`NoteDelivery.deliver(objectives:)`, which means:
+`NoteDelivery.deliver(objectives:, pin: true)`, which means:
+
+- It stays in its own session, even one that was continued: the list is built from this conversation, so it never
+  follows the chain to the newest link (as other notes do) and overwrites that link's list.
 
 - One edit's read and write are one step (`Objectives.with_lock`, a file lock in the session's folder, across threads
   and processes), and the worker's absorb holds it from its claim to the files' delete, so no edit reads between them.
@@ -176,7 +179,10 @@ command), which absorbs the file. It no longer waits for the fallback tick.
   `SessionChain.note_text` (capped; the last answer gets what the recap leaves). It reads the previous link fresh,
   with its unabsorbed newest file. A failure is only logged (`continue_objectives_failed`), because it runs inside the
   continue's rollback. A review link's list stays behind, as its last answer does: the next link's participants could
-  differ.
+  differ. The previous link's other waiting notes move after it (`NoteMove.move`, the step after: moved first, the
+  carry would miss a pending edit, and the stale list would be the batch's newest); its objectives notes never move,
+  and the new link's worker never adopts one from it (`NoteMove.adoption`), so a list from the archived link can't
+  overwrite the carried one.
 - **Rollback**: a note survives `TurnFlow#restore`, and an unabsorbed edit is on disk, untouched.
 - **Fork, delegate**: a plugin fork copies what it is passed. A delegate starts with an empty fold, so the tool answers
   that there are none.