samagotchi 0.160.0 → 0.161.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f4ca470372c140d0bcdc30583312ee1139b05b878a8e0f4688f9401a7af3700
-  data.tar.gz: dfd3b0bf49a29758ea645bdf4ac6614c9a93610f013e7517d75d8eefe4b3e3ab
+  metadata.gz: d3a8c4d1d4d37965fda091bc5c48281cdf352d6f3e496d5e5073f72777fe5994
+  data.tar.gz: 74a26cfde1a9028c44763b99cdc60ce044028598ddd2955b244338076ef8fd86
 SHA512:
-  metadata.gz: 18bd973f0dfffd58845df4341e41a2f3d32292a4d158e866cf76d907b64d9aac4539bacfc0a9cbc4a81a05b5a3bcc81cf8fec8413f52deb0a95c7141a6235082
-  data.tar.gz: 2c2aaf26b58566064737487ae20dfc7037a752f20e426c80375ca0068e14f31e85ac2bc5927522c500dd4622c17f7696e0e93aadf3697cb79cf6b7d08e00669d
+  metadata.gz: 1de962941edd2efc63a07e566954a8e6cd212891c4858db791667341e0eca601b0e920a4661198760317f5133ee26e3411d9cad570a63a87e861527ab8e21a7e
+  data.tar.gz: 0fb530ff96ccbfe79f2dc04b4cba6d59fc1b0ee6a921cf593907d9159b60eec1bed10c3360f1777417f30333c9afd36090d2b3abf7f58b9e4e4cf1b27e558946

data/CHANGELOG.md

@@ -8,6 +8,90 @@ 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
@@ -5922,7 +6006,8 @@ 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.160.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

data/docs/architecture.md

@@ -193,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`.
 

data/docs/cli.md

@@ -37,7 +37,7 @@
 - `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 [--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; 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 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

@@ -314,7 +314,9 @@ as before ([their review boundary](#a-participants-review-boundary)). The rule i
 
 ## 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/`),
@@ -334,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
@@ -344,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

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
@@ -293,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`,
@@ -307,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/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.

data/docs/internals/remote-sessions.md

@@ -134,7 +134,8 @@ the session commands*. Keep that table in step with `SessionAccessRoutes`.
   `parent_continue_refused`, `no_vision`, exit 1) or `BadRequest` (the other `invalid_*`, `missing_fields`, `bad_images`,
   exit 2, the usage-error path). That is for the routes `raise_refusal` reads (create, uploads, …). `POST …/turn` is
   mapped in `Remote#deliver_turn`: any 4xx but 404 and `owned_by_tui` becomes a refused `DeliverResult` with the
-  server's `ack`, which `SendCommand` prints as `<id>  refused: <detail>` (`refused_word`, `REMOTE_REFUSALS`), exit 1.
+  server's `ack`, which `SendCommand` prints as `<id>  <refused|failed>: <detail>` (`DeliverResult#refusal_text`,
+  whose refused codes are `DeliverResult::REMOTE_REFUSALS`), exit 1.
   A per-method mapping covers the rest (`Remote#deliver_turn`, `#note`, `#context_push`, `#context_remove`,
   `#bridge_reply` for answer/dismiss: chi web's 503 `not_live` or 404 `not_found` → nil, i.e. no worker; 504 → the
   Bridge's 408; 501 → its 404). `#context_push` maps 409 to `:not_push` and 410 `context_continued` (a continued

data/docs/memory.md

@@ -44,8 +44,10 @@ the folder is left as is: it is created when missing, nothing is marked).
   by its path (memories, project context sources, the skills bundle's kept versions) move to the id,
   each leaving a link by its old name (an older chi, keying by path, finds the same folder), then the
   id is written. It refuses while a session of the project runs (stop it first, so nothing writes to
-  the old folder mid-move), and names memories an earlier path left (the same folder name with
-  another hash: a folder moved before it had an id), merging nothing. A link stays behind: a new
+  the old folder mid-move), and names memories an earlier key left (the same folder name with
+  another path's hash: moved before it had an id, or a `chi project init` id folder,
+  `<basename>-<8 hex>`, left behind when `git init` turns that marked folder into a repository),
+  merging nothing. A link stays behind: a new
   folder (or git repository) made later at the old path reaches the moved project's memories
   through it; delete the link to stop that. chi web's project picker marks a new folder with an id
   but never moves folders: a folder it marks that already has path-keyed memories gets no id until

data/docs/plugins.md

@@ -264,7 +264,7 @@ run by `call_tool` as the tool itself ([the chi group](#chitool_sourcecall-acts_
   it raises, the default is shown. Both are saved with the call's result, so
   a web page reloaded later shows the same row: the web server doesn't run
   plugins.
-- `targets`: `->(args) { { paths: [...], command: "…", cwd: "…", acts_as: "…", args: {…}, label: "…" } }`,
+- `targets`: `->(args) { { paths: [...], writes: true, command: "…", cwd: "…", acts_as: "…", args: {…}, label: "…" } }`,
   each key optional, says what a call acts on, for [guardrails](#guardrails).
 - `refs`: `->(args) { [{ kind:, target:, label:, actions: [] }, …] }`, what the call's row traces to in the web
   (display only, the model never sees them). See [Refs on a tool's row](#refs-on-a-tools-row).
@@ -335,8 +335,15 @@ is what `targets:` says:
 - `paths:`: files the call reads or writes, absolute or relative to `cwd:`
   (else the session's directory). `path:` globs, `outside_repo` (measured
   from the session's repo, whatever the call's `cwd:`) and the protected
-  paths (chi's config, …) match them.
-- `command:`: a shell command the call runs; `command:` rules match it.
+  paths (chi's config, …) match them. A call that writes them adds
+  `writes: true` (what `write` and `edit` carry): the protected paths and a
+  delegate child's boundary then judge its paths as they do a write's. Say
+  it when the call writes, never when it only reads (a read's paths are
+  `path:` rule material, not a write); a tool without it is judged as
+  today.
+- `command:`: a shell command the call runs; `command:` rules match it, and
+  a delegate child's boundary checks where it runs and whether it changes
+  what every checkout shares (as for `execute`).
 - `cwd:`: where it runs, for the repo root and relative paths.
 - `acts_as:`: the tool a call stands for, when the tool runs other tools
   (chi's `call_tool`, which calls a tool a [source](#chitool_sourcecall-acts_as-label-wait-prefix) published). Rules keyed by that tool's name match the
@@ -1689,7 +1696,9 @@ gem.
 
 - `chi bundle install <dir>`: copies the plugin to
   `<memories>/.bundles/<name>/plugin/`. It records the plugin's sha256 and
-  `requires_chi`, and warns about a wrong declared sha256. A bundle whose
+  `requires_chi`, and refuses a plugin or script whose bytes disagree with its
+  declared sha256 (`--force` installs it anyway, with the `Checksum mismatch`
+  warning; an automatic `chi update` of a shipped bundle only warns). A bundle whose
   `requires_chi` this chi doesn't meet is **refused**: `Install failed: NAME
   can't be installed: it requires chi >= X (this is chi Y)`, exit 1, nothing
   written. `--force` installs it anyway, with the warnings that its plugin,

data/docs/releasing.md

@@ -76,7 +76,7 @@ as the GitHub release body.
 | `rake lint` / `rake lint:fix` | RuboCop over the repo (must report no offenses; CI runs it) / its safe autocorrect (`rubocop -a`). |
 | `rake gem:validate`, `gem:build`, `gem:install`, `gem:clean` | Check the gemspec; build the gem into `pkg/`; build and install it locally; remove the built gems. |
 | `rake release:draft_changelog` | A draft Unreleased section from the commit subjects since the last tag, grouped. Stdout only. |
-| `rake release:bump[X.Y.Z]` | VERSION, the system manifest, Gemfile.lock, CHANGELOG, and `requires_chi: ">= X.Y.Z"` for each bundle marked `requires_chi_next` (the marker dropped), then a profile left below a member's `requires_chi` raised to it, with a patch bump of its version (none when it moved since the last tag) and named in the CHANGELOG's "Update with `chi update`" line, and each entry an `# Unreleased` comment in `Plugin::Api::SINCE` or `Manifest::SINCE` names moved into the table at X.Y.Z (the comment dropped). No commit. |
+| `rake release:bump[X.Y.Z]` | VERSION, the system manifest, Gemfile.lock, CHANGELOG, a compatibility corpus at `spec/compat/X.Y.Z/` written through the current state writers, and `requires_chi: ">= X.Y.Z"` for each bundle marked `requires_chi_next` (the marker dropped), then a profile left below a member's `requires_chi` raised to it, with a patch bump of its version (none when it moved since the last tag) and named in the CHANGELOG's "Update with `chi update`" line, and each entry an `# Unreleased` comment in `Plugin::Api::SINCE` or `Manifest::SINCE` names moved into the table at X.Y.Z (the comment dropped). No commit; commit the corpus with the release. |
 | `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, no `requires_chi_next` left, no `# Unreleased` comment left in `Plugin::Api::SINCE` or `Manifest::SINCE`, `bundles:check`, `rake lint` (RuboCop) + `npm run lint` (the web frontend's ESLint), rspec (both roots: `spec` and the bundles' own `spec/`) + `rake bundles:specs` + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
 | `rake release:notes[X.Y.Z]` | Prints the CHANGELOG section (default: the current VERSION). |
 
@@ -97,9 +97,12 @@ The agent does each step and stops where the user has to say yes.
    markers are gone) and the profiles it raised with them (a patch bump of
    each one's version, none for a profile already bumped since the last tag),
    which it names in the CHANGELOG's "Update with `chi update`" line, and the
-   SINCE entries it moved out of their `# Unreleased` comments.
-5. **Check.** Commit first (the check wants a clean tree), then run it:
-   `git commit -am "Release X.Y.Z"` and `bundle exec rake release:check`.
+   SINCE entries it moved out of their `# Unreleased` comments. It also records
+   the release's session, bridge, cards, schedules and bundle state under
+   `spec/compat/X.Y.Z/`; commit those samples with the release so the next
+   release's reader spec checks them as N-1 data.
+5. **Check.** Add all release files, including the new compatibility corpus, then run it:
+   `git add -A && git commit -m "Release X.Y.Z"` and `bundle exec rake release:check`.
    Fix anything it finds in new commits and run it again.
 6. **Push main.** `git push origin main`; wait for CI to go green.
 7. **Tag and push the tag.**

data/docs/scheduling.md

@@ -7,6 +7,7 @@ worker's memory, so it outlives every session, every restart and every crash:
 chi web's hub can never lose an update to each other). A **tick** — cron, systemd,
 launchd, `chi schedule tick`, or chi web's hub when `schedule.auto_tick` is on —
 walks the entries whose `next_due` has passed and runs the ones that are not busy.
+The top-level `last_tick_at` records the last acquired, non-dry-run tick.
 
 The file is versioned: each entry member is required or declares the format
 version and default that introduced it. Rewrites preserve unknown keys and
@@ -104,7 +105,10 @@ A cron tick cannot read a worker's memory, so the tick has two paths.
 
 **No live worker** (the usual case for a weekly schedule): the files say what can
 be known — the saved status is not `running` (and not inside the starting grace),
-`input/` is empty, no step-limit question is open. Nothing else can be busy.
+`input/` is empty, no step-limit question is open, and, for chain mode, no worker
+is being started for it (the `<id>/starting` marker every spawn writes: another
+ticker's firing that just continued the chain; its archive refuses it too, a
+skip). Nothing else can be busy.
 
 **A live worker**: ask it, over the new Bridge route
 `GET /session/:id/activity` (`Worker#activity_snapshot`, the same signals
@@ -162,6 +166,16 @@ both counters**, so twelve skips spread over months do not kill a healthy weekly
 schedule. `list` prints the skip budget as a time window — 12 skips at a 5 minute
 tick is about an hour of patience, which is what the count really measures.
 
+An accepted delivery is **pending**, not fired: `schedules.json` records its
+session and turn id, and the next tick follows that turn's own outcome, even if a
+later turn has replaced `last_turn`. A completed turn is a success; a failed or
+canceled turn counts toward `max_failures`, with its reason in `chi schedule list`
+and `show`. A question does not time out with the 40-second firing step: the turn
+stays pending until its hard limit, derived from the schedule interval (at least
+10 minutes and at most 6 hours). If no outcome is known by then, it counts as a
+failure with reason `no outcome`. Failed, canceled and expired turns are not
+re-fired; `next_due` remains at the next occurrence.
+
 A chain holds at most `schedule.max_per_session` enabled schedules (default 10) and
 the machine `schedule.max_total` (default 50); `schedule_task` and `chi schedule add`
 refuse past them, naming the key. A schedule the chain already has — the same prompt
@@ -175,7 +189,13 @@ is refused with exit 2, naming the matches.
 The tick's lock covers the file only, never the action: the clock advances before
 the work starts — for `every` and `weekday` to the next occurrence, for a `date`
 one-off to none — so a tick killed mid-continue cannot fire the same entry twice.
-`firing_since` is what `chi schedule show` prints; the advanced clock is the guard.
+If a later tick finds a firing older than 40 seconds without an accepted turn, it
+counts an `interrupted` failure. This 40-second limit covers only the firing
+step, not an accepted turn or its pending question. The action may already have
+taken effect before the process died, so that occurrence is not replayed; a
+`date` one-off stays disabled with the failure visible, and recurring schedules
+keep their advanced clock. An accepted turn is tracked separately until its own
+outcome is known or its hard limit is reached.
 And a `chi schedule add` from a terminal never waits on an archive or a recap wait. Chain mode targets `last:<head>`, so `SessionContinue.run`'s
 own retry loop follows a continue a human made between our resolve and its lock
 instead of racing it.
@@ -204,6 +224,11 @@ pruned" instead of linking to a deleted session.
 If a link to prune still has a worker (`DeleteRefused(:worker_running)`), pruning
 stops there for this firing and is retried at the next one.
 
+Retention keeps the stored `anchor` and `head`, as well as the resolved target,
+of every enabled schedule. Deleting a protected session is refused—even with
+`chi sessions delete --force`—until the schedule is cancelled with
+`chi schedule cancel ID`; a disabled schedule does not protect its sessions.
+
 ## Running the tick
 
 `chi schedule tick` is quiet and safe to run often; it is this machine only
@@ -220,7 +245,9 @@ Run it from systemd or launchd instead if you prefer a timer: the command is the
 same, `chi schedule tick`, and the lock makes overlapping runs harmless — the
 second one exits 0 with "no schedules due (another tick holds the lock)".
 `--dry-run` prints what would fire and changes nothing; `--format json` is the seam
-for scripts and for a future web UI.
+for scripts and for a future web UI. `chi schedule run-now` reserves the entry
+under the same lock before starting its action, so it cannot race a tick into a
+duplicate firing.
 
 A tick fires **one entry per chain**: of the due entries of one chain, the one due
 earliest (`next_due`, then id) fires and the rest are skipped — "the chain just
@@ -234,8 +261,13 @@ they queue a turn, they do not archive.
 
 `schedule.auto_tick: true` makes chi web's hub tick on
 `schedule.tick_interval_minutes` (default 5) as well, sharing the same lock, so
-cron and the hub can coexist without firing twice. It is off by default: cron or
-systemd is the documented driver.
+cron and the hub can coexist without firing twice. The hub runs its tick outside
+the session scan loop and allows only one hub tick at a time, so a firing waiting
+on a worker does not stall session updates. It is off by default: cron or systemd
+is the documented driver. When it is off and no tick has run within twice
+the configured interval, `chi schedule add`, `chi schedule list` and `schedule_task`
+warn to turn `schedule.auto_tick` on or run `chi schedule tick` from cron; `--dry-run`
+and lock-held attempts do not refresh `last_tick_at`.
 
 See [cli.md](cli.md) for the subcommands and flags, and
 [configuration.md](configuration.md) for the `schedule.*` settings.