samagotchi 0.157.0 → 0.159.0

data/docs/memory.md

@@ -3,12 +3,41 @@
 Samagotchi stores memories in two scopes:
 
 - Project scope: `$XDG_CONFIG_HOME/samagotchi/memories/projects/<name>_<hash>/`, one folder per
-  git repository (named and hashed by its root), shared by all its worktrees and
-  subdirectories; outside a repository, one per working directory
+  project (named and hashed by its root): a git repository, shared by all its worktrees and
+  subdirectories, or a folder marked by `chi project init` and its subfolders; outside both, one
+  per working directory
 - System scope: `$XDG_CONFIG_HOME/samagotchi/memories`
 
 `$XDG_CONFIG_HOME` falls back to `~/.config` when unset.
 
+## Projects without git
+
+A folder in no git repository becomes a project with `chi project init [DIR]` (see
+[cli.md](cli.md#commands)): it writes `DIR/.chi/project.yml` (one comment line; the file, not a bare
+`.chi/` dir, is the marker), and DIR and every subfolder share one project memories folder, group their
+sessions (`chi sessions list`, the web's project picker) and take `chi context --project`. Nothing
+chi-specific has to be committed anywhere: a repository never needs the file. It can also be created
+from chi web's project picker (a folder inside a git repository opens that repository's project, and
+the folder is left as is: it is created when missing, nothing is marked).
+
+- **Git wins.** chi looks up a folder's `.git` first; only when there is none does it look for the
+  nearest marker above it, so a marker inside a repository is ignored (`chi project` says so) and a
+  marked folder inside another is a project of its own, as nested repositories are. A dotfiles repository
+  at `~` puts every folder under home in that repository, so markers there never apply.
+- **Not at home.** A marker in `$HOME`, in a folder above it, or in `/` is ignored (`chi project init`
+  refuses them), so a marker in `~` never makes every folder under home one project.
+- **The key.** The marked root is the folder's real path (as git's root is), so a folder chi already ran
+  in at its top keeps its memories after `init`, and a later `git init` in the same folder keeps the same
+  key. Memories saved from a *subfolder* before `init` stay in that subfolder's own folder: move them by
+  hand if you want them in the project's.
+- **Restart what runs there.** A session running in the folder when it is marked keeps the old memories
+  folder and AGENTS.md chain in its prompt until `chi sessions restart ID` (init names them); a running
+  `chi web` groups the folder's older sessions under the project after its restart.
+- **Git-only features stay off in a marked project**: guardrails' outside-the-repo rule, the participant
+  boundaries, a plugin's `ctx.repo_root` (and the bundles using it: nested AGENTS.md, slow-commands,
+  known-names), `chi home doctor`'s project checks and delegate's work-tree check measure from a git
+  checkout only.
+
 Tool behavior:
 
 - `memory_read`: `scope` is optional.
@@ -28,7 +57,7 @@ memories copied to a machine (or a path) where the repository lives elsewhere si
 longer reads. Rename the folder to the new key, or move memories with a bundle zip (see
 [What a bundle owns](#what-a-bundle-owns)).
 
-Inside a git repository, when this project's folder is missing or holds no `*.md` while the projects
+Inside a project (a git repository or a marked folder), when this project's folder is missing or holds no `*.md` while the projects
 dir has a folder of the same basename with another hash, chi says so, naming both folders and the
 `mv` that fixes it (a name match can't prove it's the same project, so nothing is renamed for you):
 
@@ -430,14 +459,14 @@ memory still marked as behind an earlier upgrade keeps its mark either way.
   repo can have a `README.md` without it becoming a memory. A listed file is
   installed whatever its name (`chi bundle build` of your own `security.md`
   lists it). Since chi 0.75.0. Older chi installs every top-level `*.md`
-  whatever `requires_chi` says (it gates hooks, rules and the plugin, not
+  whatever `requires_chi` says (it gates rules and the plugin, not
   memories), so a bundle for older chi too names its readme
   `README.markdown` (or puts docs in a subdirectory).
   `chi bundle upgrade` moves a README an older install made a memory to the
   trash (unless you edited it, like any file a bundle stops shipping).
 - **A symlink is never installed.** A memory that is a symlink is skipped
-  with `notes.md is a symlink (not installed)`, and so is a hook or guardrail
-  rule that is one or lives in a linked dir (`hooks/x.rb is a symlink (not
+  with `notes.md is a symlink (not installed)`, and so is a guardrail rule
+  that is one or lives in a linked dir (`guardrails/x.yml is a symlink (not
   installed)`); a plugin or script that is one fails the install. A tar, zip
   or git repo keeps links, and copying through one would install whatever
   file it points at (`~/.ssh/…`, an API key) as a memory the model reads.
@@ -497,7 +526,7 @@ memory still marked as behind an earlier upgrade keeps its mark either way.
   does an upgrade's removal of a file the new version no longer ships. A
   file you edited still needs `--force`: chi tells by comparing it with what
   the install recorded (the record's checksum, else its base copy; a file with
-  neither counts as edited). A hook, rule, plugin or script you
+  neither counts as edited). A rule, plugin or script (or an older install's hook) you
   edited isn't asked about: it is copied to the same dir (`Copied to the trash
   first: scripts/x (…)`) and the bundle's own copy goes. `chi bundle trash` lists the trash
   (oldest first, with file count, size, and age); `--empty` deletes all
@@ -561,7 +590,12 @@ memory still marked as behind an earlier upgrade keeps its mark either way.
 - **`chi bundle status`** says per file what is `modified` (the uninstall's
   rule above: edited, or with nothing recorded to tell), `missing` or
   `unreadable`, and that a file stays behind and why. Its `issues=` counts files
-  behind, missing or unreadable (and a plugin or hooks that won't load), not edits. A
+  behind, missing or unreadable (and a plugin that won't load, or class-file hooks an older chi installed, which no
+  longer load: `Hooks (N): not loaded`), not edits. `chi bundle status NAME`
+  lists the bundle's guardrail rules and scripts too (`Rules (N):`, `Scripts (N):`),
+  each `[ok]`, `[missing]` or `[modified]`: edited, so the next install or upgrade
+  replaces it, its copy kept in the trash. An edited or missing rule doesn't load
+  and counts in `issues=`, as a missing script does. A
   file an older chi marked, which no retry has looked at, says `may be behind`, and so
   do the counts in `chi bundle list`, `chi self` and `chi update`'s last line.
   `chi bundle status NAME` also has a `Manifest:` line: `[kept]` when chi reads
@@ -569,7 +603,7 @@ memory still marked as behind an earlier upgrade keeps its mark either way.
   what the install recorded, with why (installed by an older chi, the file edited
   or gone) and the command that fixes it (`chi update` keeps it where it can,
   [CLI: Updating](cli.md#updating)).
-- **A dev install** (`chi bundle install --dev PATH`) links the hooks, rules,
+- **A dev install** (`chi bundle install --dev PATH`) links the rules,
   plugin and scripts to `PATH` but still copies the memories at install, so
   an edit to one of them in `PATH` isn't seen until the next install.
 - **The rest of the manifest** (`plugin:`, `requires_chi`, `session_settings:`,

data/docs/plugins.md

@@ -17,7 +17,7 @@ loop, the event shapes, the kit, the pitfalls.
 my-bundle/
   manifest.yml
   plugin.rb
-  identity.md        # optional, like any bundle's memories, hooks/ and guardrails/
+  identity.md        # optional, like any bundle's memories and guardrails/
   README.md          # never a memory (nor CHANGELOG, LICENSE, ...): see memory.md#what-a-bundle-owns
 ```
 
@@ -30,7 +30,7 @@ plugin:
   sha256: sha256:6a1a7022…   # shasum -a 256 plugin.rb
   # required: true           # optional: a guardrail plugin; if it fails to load, every tool call is
                              # denied (see chi.on's on_error: :fail_closed; chi 0.157.0 or newer)
-requires_chi: ">= 0.1.28"    # optional: a gem-style requirement (">= 0.1.28, < 0.2"); the bundle's hooks/ check it too
+requires_chi: ">= 0.1.28"    # optional: a gem-style requirement (">= 0.1.28, < 0.2"); the bundle's rules check it too
                              # every key below has a chi floor: check warns when requires_chi admits a chi that never read it
 # requires_chi_next: true    # shipped bundles only, ignored by chi: rake release:bump raises requires_chi
                              # to the chi being released (docs/releasing.md)
@@ -473,7 +473,8 @@ end
 
 ### `chi.on(event, priority: 100, on_error: :log) { |event, ctx| … }`
 
-This is a bundle hook, the same as a `hooks/*.rb` file. See
+This is a bundle hook: the one way a bundle hooks an event (class-file
+`hooks/*.rb` hooks are retired, [hooks.md](hooks.md#class-file-hooks-are-retired)). See
 [hooks.md](hooks.md#hook-events) for the events; on `:after_turn`,
 `event[:present]` sets how the answer is shown in the web
 ([Presenting the answer](hooks.md#presenting-the-answer-display-only)) and `event[:refs]`
@@ -1546,7 +1547,7 @@ bundle.shutdown
 ```
 
 - **Real seams.** The plugin loads through `Plugin::Loader.register_file` (the real `chi` API and a real `ctx`),
-  the hook files through `Hooks::BundleLoader.load_hook_file`, into registries that already hold chi's own
+  into registries that already hold chi's own
   commands and tools: a name chi has fails the load as it would in chi. `tool_call` runs a real
   `Guardrails::Gate` (context and targets computed for the call; `verdict:` starts from one with a vote in it).
   Only the edges are recorded: the session (`Testing::Host`), the hook helpers (`Testing::Runtime`),
@@ -1600,7 +1601,10 @@ bundle.shutdown
   go on; `bundle.lenient { … }` collects them in `bundle.errors` instead.
 - **Sandbox.** A test runs with temp config, state, data and cache homes (config.yml, memories, `ctx.data_dir`, the
   debug log), `HOME`, `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, no git config of yours, no Keychain and none of your
-  `SAMAGOTCHI_*` settings; `sandbox.config(hash)` writes its config.yml.
+  `SAMAGOTCHI_*` settings; `sandbox.config(hash)` writes its config.yml. A `Testing::Bundle.new` or `Bundle.load` with
+  no `sandbox:` and no current sandbox enters its own, snapshots `ENV` when it is built, and restores that copy at
+  `bundle.shutdown`. Build it before changing `ENV` in a test, not lazily inside a block that sets `ENV` for one example (your own
+  helper, or ClimateControl); or scope the sandbox to the example with the `:bundle` tag or `Sandbox.with { … }`.
 - **RSpec:** `require "samagotchi/testing/rspec"`; example groups tagged `:bundle` (a spec under a bundle's own
   `spec/` is tagged by itself) get `load_bundle(dir)`, `shipped_bundle(name)` and `sandbox`, each example in its
   own sandbox, its bundles shut down after it (chi's shipped bundles keep theirs in `<bundle>/spec/`,
@@ -1634,14 +1638,14 @@ When a session's worker exits (an idle exit, `/exit`, a crash, TERM), or a
 ## Loading, and when it fails
 
 Plugins load when a session starts (`Engine.new`, in a worker or a
-`--non-interactive` one-shot), after the bundle hooks. The steps are:
+`--non-interactive` one-shot), after the config hooks. The steps are:
 
 1. The file must match the sha256 recorded at install (not checked for a bundle installed with `--dev`).
 2. chi must meet `requires_chi`. A bundle whose `requires_chi` this chi doesn't
    meet is refused at install, so this step is reached only by one installed
    with `--force` or by a chi that has since been downgraded.
 3. The file is `module_eval`'d into a new module in the bundle's namespace
-   (`Samagotchi::Bundles::<bundle>`).
+   (`Samagotchi::Bundles::<bundle>`, `Plugin::Loader.namespace_for`).
 4. The class is built, and `register(chi)` runs.
 
 What `register` adds takes effect only when it returns. A plugin that raises
@@ -1663,8 +1667,8 @@ starts again (`chi sessions stop`, or the idle exit).
 
 ## Trust
 
-A plugin is Ruby code that runs inside chi with your permissions, just like
-a bundle's hooks. **Installing a bundle means trusting it**, as you would a
+A plugin is Ruby code that runs inside chi with your permissions.
+**Installing a bundle means trusting it**, as you would a
 gem.
 
 - The sha256 is an integrity check, not proof of who wrote the file. A file

data/docs/releasing.md

@@ -31,10 +31,10 @@ can run the whole release; the user approves the notes before the tag and the
     profile's (next point);
   - a new `ctx.*` / `chi.*` call a plugin may make gets its release's version in `Plugin::Api::SINCE` once
     released (`chi bundle check`'s `requires-chi-floor` reads it); an unreleased one waits there as an `# Unreleased` comment, and
-    `release:check` fails while that comment is left: move each call up with the new version;
+    `release:bump` moves each call it names up with the new version (`release:check` fails while a comment is left);
   - a new manifest key or shape gets its release's version in `Manifest::SINCE` the same way (check's
     `requires-chi-floor` reads it for the manifest too), waits as an `# Unreleased` comment while unreleased,
-    and `release:check` fails while that comment is left;
+    and `release:bump` moves it up with the new version the same way;
   - a new shipped bundle joins a profile (`includes:` in `core` or `dev`; a
     spec checks every bundle is in exactly one), and that profile's version
     goes up: `chi update` then installs only the new bundle for those who
@@ -69,14 +69,14 @@ as the GitHub release body.
 
 | Task | What it does |
 | --- | --- |
-| `rake bundles:sha` | Recomputes the sha256 lines of every shipped bundle manifest (`files:`, `hooks:`, `plugin:`). |
+| `rake bundles:sha` | Recomputes the sha256 lines of every shipped bundle manifest (`files:`, `plugin:`, `scripts:`). |
 | `rake bundles:check` | Sha lines match; every top-level `*.md` of a bundle is listed in its `files:` (an install takes only the listed ones); a bundle changed since the last `v*` tag has a higher version (skipped, with a note, before the first tag). Warns (doesn't fail) when such a bundle's `requires_chi` still admits the tagged chi: mark it `requires_chi_next` if the change uses anything new. Notes a bundle marked `requires_chi_next`, and a profile (`core`, `dev`) whose `requires_chi` is below a member's. The release workflow and `release:check` run it in full. |
 | `rake 'bundles:check[ci]'` | The CI workflow's (every push and PR): the same, except the version check leaves out the system bundle, which is changed and unbumped between releases (`release:bump` moves its version with VERSION). A task argument, not `CI=1`: GitHub sets `CI` in the release workflow too. |
 | `rake bundles:specs` | The shipped bundles' own specs (`lib/samagotchi/bundles/*/spec`) on the bundle test kit alone (no `spec_helper`), as an external bundle's run. CI runs it as its own step. |
 | `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. No commit. |
+| `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: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). |
 
@@ -96,7 +96,8 @@ The agent does each step and stops where the user has to say yes.
    names the bundles whose `requires_chi` it raised (their `requires_chi_next`
    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.
+   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`.
    Fix anything it finds in new commits and run it again.

data/docs/scheduling.md

@@ -0,0 +1,228 @@
+# Schedules (`chi schedule`)
+
+A **schedule** is a prompt with a clock. It lives in one file on this machine, not in a
+worker's memory, so it outlives every session, every restart and every crash:
+`~/.local/state/samagotchi/schedules.json` (next to `sessions/`, written with
+`AtomicFile`, every change a read-modify-write under `schedules.lock`, so cron and
+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.
+
+Each entry carries `id`, an optional `title`, `anchor` (the session it was made
+against, never rewritten: the chain's root and the id you remember), `head` (the
+chain's current link, re-anchored after every firing: the link a chain continue
+made, or the session a `same` turn was queued into), `mode`,
+`prompt`, `recurrence`, `catch_up`, `keep_links`, `max_failures`, `max_skips`,
+`next_due` (UTC ISO), `last_fired`, `last_result`, `failures`, `skips` and
+`enabled`.
+
+<a id="reminder-vs-schedule"></a>## Reminder or schedule?
+
+`register_reminder` and `chi schedule` are separate on purpose; which one you want
+depends on whether the worker has to be running.
+
+| | `register_reminder` | `chi schedule` |
+|---|---|---|
+| Where it lives | the worker's `Engine` (`ReminderStore`), in memory | `<state dir>/schedules.json`, durable |
+| Who fires it | `IdleReminders`, inside a live idle worker | `chi schedule tick`, run by cron/systemd (or the hub when opted in) |
+| Needs a worker | yes — and a reminder *holds* the worker up | no — it wakes one when none runs |
+| Survives a stop, a crash, an archive | only the short asked-restart hand-off (`ReminderCarry`, 2 min) | yes, until cancelled |
+| Longest interval | 1440 minutes | unlimited (`every`, `weekday`, `date`) |
+| What it produces | a turn in the same session | a new chain link, or a queued turn in the same session |
+
+A schedule turn carries `client_id: "system:schedule:<id>"`, so `ClientId.origin`
+says `schedule` and the terminal and the web label it as such rather than as
+something you typed. Like `register_reminder`, the schedule tools are owner-voiced:
+a participant's review or pair turn is denied them ([guardrails.md](guardrails.md)).
+
+## The two modes
+
+- **chain** (the default) runs the prompt as the **next link of the session's chain**:
+  the head is archived, a new link is created with the carry note
+  ([sessions.md, Session chains](sessions.md#session-chains)), and `head` moves to it.
+  This is the "same routine, fresh context" case: a daily coordinator that starts each
+  day with the recap of the last one instead of a 40-link transcript.
+- **same** queues the prompt as a turn **in the session itself**
+  (`SessionManager.deliver_turn`, `Delivery::QUEUE`), waking a worker when none runs.
+  It prunes nothing, and it never archives anything. Like chain mode, it follows
+  `head` through the chain: once the session is continued — by a chain schedule or
+  by a `chi send --continues` — the turn goes to the new link, not to the archived
+  anchor the schedule was made against.
+
+A `scratch` session is refused at `add`: it is deleted when its terminal leaves.
+A prompt is checked at `add` too — non-empty and at most 16 KiB
+(`SessionInbox::NOTE_MAX_BYTES`); a blank one would archive a link and start an
+idle session for nothing.
+
+## Recurrence
+
+One kind per schedule:
+
+| Kind | Written as | How the next due is computed |
+|---|---|---|
+| `every` | `--every 45m` / `2h` / `1d` | interval arithmetic from the firing — `next_due = fired_at + interval` |
+| `weekday` | `--weekday 1 --time 09:00` (1=Mon … 7=Sun) | the next such wall-clock moment in the machine's local zone, strictly after now (today counts if the time is still ahead), stored as UTC |
+| `date` | `--date 2026-11-20` or `--date 2026-11-20T09:00` | one local moment; after it fires the entry is disabled |
+
+**The DST caveat.** `every` is interval math in UTC, so an `every 1d` schedule
+drifts by an hour across a DST fold: fired Monday 09:00, its next due is Tuesday
+09:00 UTC, which is a different hour on the wall clock after the change. For a
+schedule at a *time of day*, use `--weekday` (or `--date`): those build the moment
+with `Time.local` for the candidate date, so `Mon 09:00` stays 09:00 local across
+the fold. If a local moment does not exist (a spring-forward gap), it fires at the
+next valid minute. Schedules use the machine's local clock; there are no named
+time zones.
+
+`catch_up` says what an overdue entry does when the tick arrives after its moment:
+
+- `once` (default): fire once now, then reschedule normally.
+- `none`: fire only when the tick is near the moment. "Missed" — `last_result:
+  "missed"` and the entry moves to its next occurrence — is a **whole cycle**, not
+  a late tick: it happens only when the occurrence *after* the one it missed is
+  already past, which is what the file looks like when the machine was asleep
+  across the interval. A `Mon 09:00` schedule ticked at 09:20 fires; the same
+  entry first seen the following Monday is missed and moves to the Monday after.
+  A `date` one-off has no next occurrence to compare with, so it is never missed:
+  it fires late, once.
+
+## The busy check
+
+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.
+
+**A live worker**: ask it, over the new Bridge route
+`GET /session/:id/activity` (`Worker#activity_snapshot`, the same signals
+`WorkerIdleExit#hold` reads): `{turn_running, input_pending, awaiting_continue,
+open_streams, reminders, tasks_holding}`. It is in `Bridge::FEATURES`, so a worker
+from an older chi has no such route, and any non-200 from it is read as "older":
+the tick says to restart that worker.
+
+- `turn_running`, `input_pending` or `awaiting_continue` ⇒ busy, in both modes.
+- `open_streams` (a terminal attached, or a web tab open on the session) counts
+  **only for chain mode**: a chain firing archives the session and stops its
+  worker, which would cut off the person looking at it. A queued turn into an open
+  session is fine, so `same` mode ignores streams.
+- **An older worker is itself a busy signal for chain mode.** Its 404 must not fall
+  back to the file checks: those cannot see an open tab, so the firing would
+  archive under someone's terminal. The tick skips it with "its worker is too old
+  to ask: `chi sessions restart ID`" — chi's usual rule for an older worker:
+  refuse with a restart, never silently degrade. `same` mode, which only queues a
+  turn, may use the file checks.
+
+A `chi send --wait` or a parent's `delegate` wait is **not** busy: `ReplyWait::Poll`
+reads the session files and `GET /session/:id/state`, never `open_stream`, so a
+coordinator waiting on its own child does not block that child's chain.
+
+Schedules never hold a worker up: unlike reminders, they are not in
+`WorkerIdleExit#hold` (FR14) — the whole point is that the worker may be gone and
+the tick wakes it.
+
+## Skip, not failure
+
+A firing that cannot run now is a **skip**: nothing happens, `skips += 1`,
+`last_result: "skipped"`, and `next_due` goes back to the occurrence this tick tried
+(the tick advances the clock before acting and keeps that moment as `due_was`, so the
+next tick tries it again — a weekly schedule skipped on its Monday is retried at that
+Monday, not a week later). A failure restores it the same way. A `date` entry is the
+exception: advancing it spends it, so it comes back at that same moment.
+Skips
+are the refusals that mean "not this moment": `ArchiveRefused` with `busy`, `queued`
+or `offer`, or `busy_child`/`queued_child`/`offer_child` (a chain's own running
+delegate refuses the archive, since `archivable!` walks the whole descendant tree),
+`SessionContinue::Refused(:continued)` (a human continued it while we were
+resolving) and `:open_children`.
+
+Anything else is a **failure** (`failures += 1`): a gone or archived target,
+`SessionContinue::Refused(:folder_gone)`, `SessionManager::DeleteRefused`,
+`ModelProfile::MissingModel`, `OwnedByTUI`, `Session::NotFound`, and anything a
+spawn throws (`Errno::ENOSPC` included — `run_locked` re-raises it after undoing
+the move, so it is never mistaken for a skip). A `DeleteRefused(:worker_running)`
+hit while pruning stops the pruning for that firing, is logged, and is not a
+schedule failure.
+
+`skips >= max_skips` (default 12) or `failures >= max_failures` (default 3)
+disables the entry and `chi schedule list` says why. **Any successful firing resets
+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.
+
+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
+and recurrence, or the same title — is refused too, naming its id, so a routine that
+tells each of its links to "make sure the Monday audit is scheduled" cannot multiply
+itself. `schedule_task`, `list_schedules` and `cancel_schedule` see only schedules of
+the calling session's chain (`all: true` steps outside it); `chi schedule list` is
+always the machine-wide view. An id, prefix or title that matches more than one entry
+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.
+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.
+
+## Keeping the chain short
+
+`keep_links` (default `schedule.default_keep_links`, `0` keeps all) is how many
+chain links stay behind the head. After a successful chain firing — and after the
+result is recorded under the lock, so a prune that raises midway cannot lose the
+new `head` — the walk goes backwards from `head` and every link older than the
+window is deleted **together with its delegated children** (`descendant_ids`): the
+whole subtree only when every session in it is archived and no worker owns any of
+it, deepest child first and the link last, oldest link first. A subtree with a live
+worker or an unarchived descendant is left whole and retried at the next firing. Pruning a link alone would leave its finished
+delegates archived forever with a dangling `parent_id`: archiving a session archives
+its descendants, and archived sessions are outside the retention sweep
+([sessions.md](sessions.md)), so the delegate pile is the bulk of the archived
+count. The `anchor` is never pruned: it is the chain's root, the id the user and
+the coordinator remember, and `last:<anchor>` must keep resolving.
+
+The oldest kept link still has `continues` naming a link that is gone. The walks
+follow `continues` forward, so nothing breaks; the web's `↩ #N of M` chip counts
+from the surviving root (pruning renumbers the links) and says "earlier links
+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.
+
+## Running the tick
+
+`chi schedule tick` is quiet and safe to run often; it is this machine only
+(`chi --remote studio schedule list` exits 2), so point cron at the chi of this
+machine (cron runs with a thin PATH, so name the binary rather than a shell
+function):
+
+```
+# crontab -e on the machine
+*/5 * * * * /Users/you/.local/share/mise/installs/ruby/global/bin/chi schedule tick >> /Users/you/.local/state/samagotchi/schedule-tick.log 2>&1
+```
+
+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.
+
+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
+fired; retry at the next tick" — with `skips += 1` and `next_due` left at the
+occurrence they tried, so the chain's entries take turns instead of the first one
+added winning every tick. A second chain
+firing in the same pass would continue the link the first one just made and archive
+it before its prompt ever ran: that link has no worker lock yet and the tick's
+listing predates it, so the busy check cannot see it. `same` entries are unaffected:
+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.
+
+See [cli.md](cli.md) for the subcommands and flags, and
+[configuration.md](configuration.md) for the `schedule.*` settings.