samagotchi 0.158.0 → 0.160.0

data/docs/memory.md

@@ -2,10 +2,11 @@
 
 Samagotchi stores memories in two scopes:
 
-- Project scope: `$XDG_CONFIG_HOME/samagotchi/memories/projects/<name>_<hash>/`, one folder per
-  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
+- Project scope: `$XDG_CONFIG_HOME/samagotchi/memories/projects/<key>/`, one folder per project: a
+  git repository, shared by all its worktrees and subdirectories (`<name>_<hash>`, named and hashed
+  by its root), or a folder marked by `chi project init` and its subfolders (its id,
+  `<name>-<8 hex>`: see [Projects without git](#projects-without-git)); outside both, one per
+  working directory (`<name>_<hash>`)
 - System scope: `$XDG_CONFIG_HOME/samagotchi/memories`
 
 `$XDG_CONFIG_HOME` falls back to `~/.config` when unset.
@@ -13,8 +14,9 @@ Samagotchi stores memories in two scopes:
 ## 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
+[cli.md](cli.md#commands)): it writes `DIR/.chi/project.yml` (a comment line and the project's
+`id:`; 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
@@ -26,10 +28,34 @@ the folder is left as is: it is created when missing, nothing is marked).
   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.
+- **The key is the id.** A marked project's memories folder and its project context sources
+  (`chi context --project`) are named by the marker's `id:` (`<folder name>-<8 random hex>`), not
+  by its path, so moving or renaming the folder keeps them: a session started there after the move
+  finds them, and one saved before it (its file stores `project_id`) keys its context sources by the
+  id too. A folder chi already ran in at its top keeps its memories after `init`: they move to the
+  id. A later `git init` in the folder makes it a repository, keyed by its path again (git wins): its
+  memories stay in the id folder until you move them, and chi names the id folder at session start
+  (and under a `memory_read` miss) while the repository's own folder holds no memories. 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.
+  A hand-edited id must be letters, digits, `_`, `.` or `-` (up to 64, a letter or digit first);
+  anything else (or a broken file) is ignored and the project keyed by its path (a debug log line
+  says why, `chi project init` reports it).
+- **Older markers adopt an id** when you rerun `chi project init` in the folder: the folders keyed
+  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
+  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
+  `chi project init`.
+- **A copy shares memories.** A copied marked folder (`cp -R`) keeps the id, so the two share one
+  memories folder; at session start in the copy chi says so (a `memory>` load warning: "… share chi
+  project id … (a copied folder?)"; the id folder's `.root` names the folder that started a session
+  with it last, the original keeps it). `chi project init --new-id` in the copy gives it a fresh id,
+  with a copy of the memories and project context sources it had: each folder goes its own way.
+  After a move, the new path just takes `.root` over, with no warning.
 - **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.
@@ -52,13 +78,15 @@ Tool behavior:
 
 ## Moving memories to another machine
 
-A project's folder is keyed by its root's absolute path (`<basename>_<8 hex of MD5(root)>`), so project
+A repository's folder is keyed by its root's absolute path (`<basename>_<8 hex of MD5(root)>`), so project
 memories copied to a machine (or a path) where the repository lives elsewhere sit in a folder chi no
 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)).
+[What a bundle owns](#what-a-bundle-owns)). A marked project with an id needs neither: copy its id
+folder along with the marked folder.
 
 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
+dir has a folder of the same basename with another hash (`<basename>_<hash>`, or a marked project's id folder
+`<basename>-<8 hex>`; links, an adopted project's old names, are skipped), 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):
 
 - at session start, a `memory>` load warning (a `:guardrail_warning` with label `memory`; the attached
@@ -591,7 +619,11 @@ memory still marked as behind an earlier upgrade keeps its mark either way.
   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 that won't load, or class-file hooks an older chi installed, which no
-  longer load: `Hooks (N): not loaded`), not edits. A
+  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

data/docs/scheduling.md

@@ -0,0 +1,241 @@
+# 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.
+
+The file is versioned: each entry member is required or declares the format
+version and default that introduced it. Rewrites preserve unknown keys and
+entries missing required members; those entries are warned about and ignored by
+`list` and `tick`, never erased. A write never lowers the file's version.
+
+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>"` in both modes (a chain
+link's first turn through `Session#first_turn_client_id`, which `Schedules#fire_chain`
+passes to `SessionContinue.run`), so `ClientId.origin` says `schedule` and the terminal
+and the web label it as such rather than as something you typed. For the same reason a
+schedule's prompt is never a session command: a `/word` prompt reaches the model as
+text, and one that starts with `!` is refused by `chi schedule add` and `schedule_task`
+([guardrails.md, Who may run a session command](guardrails.md#who-may-run-a-session-command)).
+An entry stored with one before that fails when it fires (toward its `max_failures`),
+before anything is started or delivered. A chi web
+(or cron tick) still running an older chi starts chain links without the origin, so
+restart it after updating. 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.

data/docs/sessions.md

@@ -115,7 +115,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 
 ## Session file
 
-`Session::FIELDS` is the table of `<uuid>.json`, in the order `Session#save` writes it (`Session.new`, `.from_h` and `#to_h` all go by it; 41 keys). Each key is one `SessionField` row (`session_field.rb`): its default for a file without it, how a value is cast when read and what the file gets, the codec being its type's own (`Toolkit.from_file`, `SessionReview.of`, `PromptNote.list`, `#to_file`…); the typed fields' writers cast through their row, and `#to_h` reads each field's instance variable, not its reader. A key a file lacks reads as the default below, a key present as `null` as `null` (then cast: `test_run` false, `toolkit_origin` chosen); `review`, `first_turn_id`, `verdicts` and `verify_fresh` are written only when set (`OPTIONAL_FIELDS`). A key this chi doesn't know is kept and written back as it was (see the rule above). `thinking`, `reasoning_history` and `llm_context` follow one Unread rule (`SessionField.level`): a value this chi can't read (a newer chi's level, a hand edit) reads as none and is kept and written back as it was, until the session sets its own; `llm_context` keeps the parts it can't read under the ones it can. So does `toolkit_origin`: an unknown one (a String) reads as `chosen` and is written back as it was, until the session sets its own. Where the file and the session's dir are, and which ids name a session, is `SessionPaths` (`session_paths.rb`, a leaf that `Session` extends: `Session.session_dir` is `SessionPaths.session_dir`). The bytes a save writes for each field and on each path that makes or rewrites a file are pinned in `spec/session_file_goldens_spec.rb`, with what a fork, a continue, a delegate child and a respawn keep of their source (`carry_matrix.json`). "Who writes it": the Engine runs in the session's worker (or a `--non-interactive` run); the rest are named.
+`Session::FIELDS` is the table of `<uuid>.json`, in the order `Session#save` writes it (`Session.new`, `.from_h` and `#to_h` all go by it; 43 keys). Each key is one `SessionField` row (`session_field.rb`): its default for a file without it, how a value is cast when read and what the file gets, the codec being its type's own (`Toolkit.from_file`, `SessionReview.of`, `PromptNote.list`, `#to_file`…); the typed fields' writers cast through their row, and `#to_h` reads each field's instance variable, not its reader. A key a file lacks reads as the default below, a key present as `null` as `null` (then cast: `test_run` false, `toolkit_origin` chosen); `review`, `first_turn_id`, `first_turn_client_id`, `verdicts` and `verify_fresh` are written only when set (`OPTIONAL_FIELDS`). A key this chi doesn't know is kept and written back as it was (see the rule above). `thinking`, `reasoning_history` and `llm_context` follow one Unread rule (`SessionField.level`): a value this chi can't read (a newer chi's level, a hand edit) reads as none and is kept and written back as it was, until the session sets its own; `llm_context` keeps the parts it can't read under the ones it can. So does `toolkit_origin`: an unknown one (a String) reads as `chosen` and is written back as it was, until the session sets its own. Where the file and the session's dir are, and which ids name a session, is `SessionPaths` (`session_paths.rb`, a leaf that `Session` extends: `Session.session_dir` is `SessionPaths.session_dir`). The bytes a save writes for each field and on each path that makes or rewrites a file are pinned in `spec/session_file_goldens_spec.rb`, with what a fork, a continue, a delegate child and a respawn keep of their source (`carry_matrix.json`). "Who writes it": the Engine runs in the session's worker (or a `--non-interactive` run); the rest are named.
 
 | Key | Meaning | Written by |
 |-----|---------|------------|
@@ -136,6 +136,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 | `pending_question` | The question the worker waits on (`PendingQuestion`), `null` with none. | `QuestionDesk` |
 | `used_memory_names` | The memories the session read. | the Engine |
 | `project_root` | The project the session started in, stored because a worktree may be deleted later; `null` outside a repository or a marked folder (looked up again on read). | creation |
+| `project_id` | A marked project's id (its `.chi/project.yml`'s `id:`), saved beside `project_root`: the session's project context sources are keyed by it, so they follow a moved folder. Absent for any other project. | creation |
 | `preloaded_memory_names`, `muted_memory_names` | `--memory` and `--mute`, written before the worker starts so a respawn builds the same prompt. | creation |
 | `prompt_notes` | The model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)). | the Engine, at each prompt build |
 | `parent_id` | The session that delegated this one or forked it (`ctx.sessions.fork`); `null` otherwise. See [Delegating](#delegating). | `SessionManager.spawn_session`; `ChildMove` writes a `parent.json` beside it instead of this file |
@@ -156,6 +157,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 | `working_set_pins` | The working-set items the user pinned (`/working-set pin`); kept by a respawn, a continue and a fork. | the Engine's command |
 | `review` | A review session's subjects and source (`SessionReview`), see [Review sessions](#review-sessions). | `ReviewStart` |
 | `first_turn_id` | The id the creating prompt's turn gets, so a wait can name it (`chi send --new --wait`, `--wait --turn T ID`); `null` for a session created idle. | `SessionManager.spawn_session` |
+| `first_turn_client_id` | Who sent the creating prompt when no person did (`delegate:<parent8>` for a delegate's task, `system:schedule:<id>` for a chain schedule's link): that first turn's origin, so its line is no command of the owner's (docs/guardrails.md, Who may run a session command) and `last_turn` names the sender. Written only when set; not carried by a fork, a continue or a delegate. An older chi keeps it but runs the first prompt as a person's. | `SessionManager.spawn_session` (its `client_id:`) |
 | `verify_fresh` | A Verify fresh child's requester, rules and claim (`VerifyFreshOrigin`). | `VerifyFresh.start`, once |
 
 ## Context notes
@@ -358,7 +360,31 @@ A session can **continue** an earlier one: "the next run of the same routine" (a
 - **Web:** `POST /api/sessions` takes `continues: "<id, prefix or last:id>"`, with `idle: true` (a new link waiting for its first message, previewed by the previous link's, or `preview`) or a `prompt`, and `model` (or `model_name`) for the new link's model, but not `dir`, `llm_context`, `thinking`, `settings`, `toolkit`, `tools`, `no_tools` or `parent_answers` (400 `invalid_continues`: the previous link's are taken). 201 is the new session's summary, `continues` set, with `moved`: the ids of the delegates that moved to it (`[]` for none), and `model_warning`: the default-model fallback's warning, then any about the model id, joined by `; ` (`null` for none), and `opener`: the previous link's first typed message, in full, when that link continues one itself (`null` otherwise: a chain's first link's first message is its task), and `moved_context`: `{moved: [names], stayed: [{name, why}]}`, the attached context it took (`why` `pushed` or `not movable`); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a given model whose host config.yml doesn't have (or a fallback with no default model); 409 `continued` with `next_id` (the link that continues it already, which the page opens instead), `open_children` with `ids` (open delegates that can't move), `folder_gone`, `busy`, `scratch` or `owned_by_tui`. Every session summary carries `continues`.
 - **The page:** the info bar's `continue →` continues the open session (`continues: <id>, idle: true`; it reads `continuing…` through the recap wait) and opens the new link with an opener in the composer, not sent (a draft written in this session stays instead; one carried over from another session or the start page gives way to the opener, and the toast's **Restore draft** brings it back): the previous link's own first typed message when that link continues one (the 201's `opener`; a `!shell` line isn't taken), else `Continue where we left off.`. So whatever you sent on the last link comes back on the next one, and editing it once changes it for every later link; the previous link is archived, a toast says so (`Continued 3fa2c1d0 in 4b7e9a01; 3fa2c1d0 is archived; 1 open delegate moved`), and a moved delegate's card folds under the new link. When the previous link's model's host is gone the link starts on the default model and the toast carries the server's `model_warning` too, and then stays until closed. A fresh link (one with no turn yet, however it was made: `continue →`, `chi send --new --continues`, a reload) shows the model picker in its composer with the link's model, until its first turn starts (a failed or canceled first turn ends it too); a pick runs `/model <name>` in the link (a command bubble; the info bar follows) and changes neither the start page's remembered model nor its Recent list, and a Send right after it waits for the `/model` to be taken. A link a one-turn `chi --non-interactive` run has, or one continued already, shows none. A link continued already has no `continue →`: its `→` link goes to the next link (a stale page's continue answered 409 `continued` opens `next_id`). A continue refused for open delegates that can't move shows a toast that names each one (its preview and what the server says to do: `older chi worker 0.46.1; restart it`, `in use by a one-turn chi --non-interactive run or an older chi's terminal; let it finish`), each a link to its page; any other refusal shows the server's words. The info bar of a link carries `← 2026-10-08` (the previous link's day) and, on an earlier link, `2026-10-10 →`, each a link with its id, its full start (`2026-10-10 14:32`) and its preview in the tooltip; a neighbour that started on the open link's own day shows its time instead (`← 09:12`, `14:32 →`). A link made by `continue →` inherits the previous link's preview (and its title, if it has one) when it is created, so its card keeps its chain's title whatever opener it is sent, and its top bar and browser tab show its card's title. A link with a recap of its own reads its auto title, else its recap's first sentence, instead (a link without one reads its chain's name, and a first link's recap names its chain). A link whose title is the opener and nothing else (a `chi send --new --continues` link whose first message is `Continue where we left off.`) shows its chain's first link's title instead, on its card, in the popover and in its info bar's title line, display only (its messages and data keep the opener; its own title when the first link is gone). The lists fold a chain into the card of its latest listed link, whatever the earlier links' archived state (typing in an archived link brings it back, folded there still), their delegates with them: the card's `↩ #N` chip (`#N of M` when later links aren't listed; its tooltip `Session chain: link N of M`) opens a popover of the other links, newest first (`#N`, its date, with its time (`2026-10-17 14:32`) when another link of the chain started the same day, its own title when it differs from the card's (a link inherits its chain's, so mostly it doesn't), else its recap's first sentence, else its preview, `archived`), a click opens one; the chip shows a live dot or `waiting` for a link that has a worker or waits on the user, and a waiting link puts its chain's card first. All sessions folds nothing while a search is typed or the `archived` toggle is on: every link is a card of its own then, its chip `#N of M`, with its own delegates folded in, so a search finds an earlier link and its delegates.
 - **CLI:** `chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT]` (see *Starting a session*).
-- **Which link:** an id, a unique prefix, or `last:<id or prefix>`, the latest link of the chain that session is in. It walks the links that still exist: a deleted link in the middle (`chi sessions delete`, the retention sweep of an unarchived one) ends the walk before it, so `last:` of an earlier link then names that earlier link, and continuing it starts a second line beside the links after the gap; name a link after the gap instead. A trigger names the chain this way: `chi send` to an archived link would bring it back (a human's input), not continue the chain.
+- **Which link:** an id, a unique prefix, or `last:<id or prefix>`, the latest link of the chain that session is in. It walks the links that still exist: a deleted link in the middle (`chi sessions delete`, the retention sweep of an unarchived one) ends the walk before it, so `last:` of an earlier link then names that earlier link, and continuing it starts a second line beside the links after the gap; name a link after the gap instead. A trigger names the chain this way: `chi send` to an archived link would bring it back (a human's input), not continue the chain. A chain pruned by a schedule keeps its `anchor`: the kept window's oldest link still names a link that is gone, so the walk simply stops there; the page's chip counts from the surviving root (pruning renumbers the links) and its popover says `earlier links pruned` where the walk stops, rather than linking to a deleted session.
+
+## Schedules
+
+A **schedule** is a prompt with a clock, kept in `<state dir>/schedules.json` and
+fired by a tick that needs no worker — cron, systemd, `chi schedule tick`, or chi
+web's hub when `schedule.auto_tick: true`. `chi schedule add --session ID
+--weekday 1 --time 09:00 -m "…"` makes one; `chi schedule list|show|tick|run-now|enable|disable|cancel`
+read and run it. Each firing is either the **next link of the session's chain**
+(the default: the head is archived, a new link takes its place, and the links
+behind `keep_links` are deleted with their delegates — archived links are outside
+the retention sweep, so this is what bounds them) or a **turn in the session
+itself** (`--mode same`, queued like a typed prompt). A target that is busy is
+**skipped**, not failed: `next_due` stays, `skips` grows, and after
+`max_skips` (12) consecutive skips or `max_failures` (3) consecutive failures the
+schedule is disabled and `list` says why; any firing that succeeds resets both.
+
+The difference from `register_reminder` is where the clock lives. A reminder is
+in-memory state of a live worker: it holds that worker up (`/exit` asks about it),
+maxes out at 1440 minutes, and survives only the short asked-restart hand-off. A
+schedule is a file: it outlives every worker, wake, crash and archive, has no
+interval limit, and never holds a worker up — a tick wakes one when none is
+running. A schedule turn carries `client_id: "system:schedule:<id>`, so both UIs
+label it `schedule`. Full details, the busy check and the DST caveat:
+[Scheduling](scheduling.md).
 
 ## Review sessions
 

data/lib/samagotchi/bridge.rb

@@ -9,6 +9,7 @@ require "openssl"
 require "time"
 require_relative "atomic_file"
 require_relative "bridge_secret"
+require_relative "command_intake"
 require_relative "degrade"
 require_relative "delivery"
 require_relative "session_inbox"
@@ -116,11 +117,14 @@ module Samagotchi
     #   without the worker exiting, for POST /holds/stop; returns the
     #   HoldStop::Stopped the 200's +stopped+ carries; without one that route
     #   answers 501
+    # @param on_activity [#call, nil] what the worker is busy with right now
+    #   (Worker#activity_snapshot: the same signals WorkerIdleExit#hold reads)
+    #   for GET /activity; without one that route answers 501
     def initialize(engine:, state_dir:, session_id:, bind: DEFAULT_BIND,
                    port: 0, ring_capacity: DEFAULT_RING_CAPACITY,
                    heartbeat_interval: DEFAULT_HEARTBEAT_INTERVAL, input_format: nil, on_input: nil,
                    on_command: nil, on_exit_request: nil, exit_discards: nil, exit_stopped: nil,
-                   on_holds: nil, on_holds_stop: nil)
+                   on_holds: nil, on_holds_stop: nil, on_activity: nil)
       @engine = engine
       @on_input = on_input
       @on_command = on_command
@@ -129,6 +133,7 @@ module Samagotchi
       @exit_stopped = exit_stopped
       @on_holds = on_holds
       @on_holds_stop = on_holds_stop
+      @on_activity = on_activity
       @input_format = input_format
       @state_dir = state_dir
       @session_id = session_id
@@ -687,9 +692,12 @@ module Samagotchi
     # pair_turns: a participant's turn in a working session runs as a pair
     # turn (Guardrails::PairBoundary); a worker without it runs it as a
     # review turn, and chi web says so (Delivery::PAIR_FEATURE).
+    # activity: GET /activity answers with Worker#activity_snapshot, so
+    # `chi schedule tick` can ask a live worker what it is busy with.
     FEATURES = ["restart", "task_stop", "reparent", Delivery::QUEUE_FEATURE, ReplyWait::TURN_IDS_FEATURE,
                 VerifyAnchor::FEATURE, ReviseAnchor::FEATURE,
-                SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE, TurnDrawings::FEATURE].freeze
+                SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE, TurnDrawings::FEATURE,
+                WorkerLink::ACTIVITY_FEATURE].freeze
 
     # The routes, by method and what follows /session/:id/: a handler takes
     # the session id and the request body and returns [headers, status, body].
@@ -706,6 +714,7 @@ module Samagotchi
       %w[POST exit] => :handle_exit_request,
       %w[GET holds] => :handle_holds,
       %w[POST holds/stop] => :handle_holds_stop,
+      %w[GET activity] => :handle_activity,
       %w[POST recap] => :handle_recap,
       %w[POST relay] => :handle_relay,
       %w[POST relay/status] => :handle_relay_status,
@@ -1101,6 +1110,22 @@ module Samagotchi
       [{}, 200, { status: "stopped", session_id: @session_id, stopped: stopped.to_h }]
     end
 
+    # GET /session/:id/activity: what this worker is busy with right now — the
+    # same signals WorkerIdleExit#hold reads (a turn running, input queued, a
+    # continue offer waiting, clients holding the stream, reminders, watched
+    # tasks). A `chi schedule tick` runs out of process: it cannot read a
+    # worker's memory, and the session files cannot see an open tab, so it
+    # asks. Read-only and small: no task list, no transcript.
+    # 200 {session_id, turn_running:, input_pending:, awaiting_continue:,
+    #   open_streams:, reminders:, tasks_holding:}; 501 activity_unavailable
+    # when this worker has no such step.
+    # Returns [headers, status, body].
+    def handle_activity(_session_id, _body = nil)
+      return [{}, 501, { error: "activity_unavailable" }] unless @on_activity
+
+      [{}, 200, { session_id: @session_id, **@on_activity.call }]
+    end
+
     # Queue a turn for this session through its file IPC (the worker polls
     # its input dir). Returns [headers, status, body]. Only this bridge's own
     # session: another id, in the path or the body, is refused as on every
@@ -1171,9 +1196,17 @@ module Samagotchi
       # A session command sent as a message (chi send -m "/model x", chi -p,
       # a UI whose command list lags) runs as the command, as typed in a
       # TUI; an unknown /word stays a prompt. Not with images: those are
-      # for the model.
+      # for the model. Only from a sender that may send commands
+      # (CommandIntake.allowed?: a person, chi answer): a delegate's, a
+      # schedule's or a plugin's /word line is a prompt, its shell line
+      # refused (403, nothing queued).
       if images.empty? && @on_command && command_registry.command?(prompt.to_s)
-        return queue_command_request(sid, prompt.to_s.strip, client_id: client_id, deadline: deadline, author: author)
+        if CommandIntake.allowed?(client_id)
+          return queue_command_request(sid, prompt.to_s.strip, client_id: client_id, deadline: deadline, author: author)
+        elsif CommandIntake.shell_line?(prompt)
+          Log.warn(:bridge, "shell_line_refused", client_id: client_id)
+          return [{}, 403, { error: CommandIntake::REFUSED_ERROR, detail: CommandIntake::REFUSED }]
+        end
       end
 
       enqueued_id = SecureRandom.uuid

data/lib/samagotchi/broadcast/scope_card.rb

@@ -46,7 +46,8 @@ module Samagotchi
         session = Session.load(recipient.id, state_dir: state_dir)
         prompts = user_texts(session.messages)
         branch = GitHead.branch(session.working_directory)
-        sources = ContextSources.attached(session.id, project_root: session.project_root, state_dir: state_dir)
+        sources = ContextSources.attached(session.id, project_root: session.project_root, project_id: session.project_id,
+                                                      state_dir: state_dir)
                                 .map { |attached| [attached.name, attached.source.hint] }
         ScopeCard.new(id: session.id, project: recipient.project && File.basename(recipient.project),
                       folder: folder(session.working_directory, recipient.project), branch: branch,

data/lib/samagotchi/bundle_command.rb

@@ -30,7 +30,8 @@ module Samagotchi
 
         status [<bundle>]
           Show provenance and each file's status for bundles. issues= counts what
-          needs you: a file that stays behind, is missing or can't be read, not one you edited.
+          needs you: a file that stays behind, is missing or can't be read, or a rule that won't load;
+          not a memory or script you edited.
 
         diff <bundle> [file]
           Show diffs between base/current/incoming for a bundle.
@@ -265,6 +266,7 @@ module Samagotchi
     # @return [Array(MemoryBundle::PreparedSource, String), nil]
     def prepare_or_fail(expanded_source, word)
       prepared = Samagotchi::MemoryBundle::PreparedSource.prepare(expanded_source)
+      Samagotchi::MemoryBundle::Manifest::HooksRetired.refuse_source_files(prepared.dir)
       named = [prepared, Samagotchi::MemoryBundle::Manifest.read(dir: prepared.dir).name]
     rescue Samagotchi::MemoryBundle::SourceNormalizer::UnknownSourceError,
            Samagotchi::MemoryBundle::Manifest::ValidationError => e
@@ -525,6 +527,8 @@ module Samagotchi
           @stdout.puts "  Hooks (#{st.retired_hooks.size}): not loaded: #{Samagotchi::MemoryBundle::Manifest::HooksRetired::WORDS}"
           st.retired_hooks.each { |file, state| @stdout.puts "    #{file} [#{state}]" }
         end
+        print_assets("Rules", st.rules, " (edited after install: not loaded; reinstall the bundle)")
+        print_assets("Scripts", st.scripts, " (edited after install: the next install replaces it, a copy kept in the trash)")
         if (plugin = st.plugin)
           note = plugin[:state] == "modified" ? " (edited after install: not loaded; reinstall the bundle)" : ""
           @stdout.puts "  Plugin: #{plugin[:file]} [#{plugin[:state]}]#{note}"
@@ -548,6 +552,8 @@ module Samagotchi
           plugin = st.plugin
           mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
           mods += 1 unless st.retired_hooks.empty?
+          # A rule that is missing or edited doesn't load; a script runs edited.
+          mods += st.rules.values.count { |state| state != "ok" } + st.scripts.values.count("missing")
           mods += 1 if st.scope_error
           plugin_info = plugin ? " plugin=#{plugin[:file]}" : ""
           includes = st.provenance.includes
@@ -558,6 +564,15 @@ module Samagotchi
       0
     end
 
+    # A bundle's rules or scripts (MemoryBundle::Status.asset_states), one
+    # line each, +modified+ said after an edited one.
+    def print_assets(heading, states, modified)
+      return if states.empty?
+
+      @stdout.puts "  #{heading} (#{states.size}):"
+      states.each { |file, state| @stdout.puts "    #{file} [#{state}]#{modified if state == "modified"}" }
+    end
+
     # "Manifest: [kept]", or "[from the install record]", and what its case
     # says (MemoryBundle::ManifestStanding).
     def manifest_line(record)
@@ -602,6 +617,8 @@ module Samagotchi
           diff_memory(prov, target_dir, file_arg)
         elsif plugin_file && [plugin_file, "plugin/#{plugin_file}"].include?(file_arg)
           diff_plugin(prov, record, plugin_path)
+        elsif (asset = asset_states(prov, record).find { |a| a.label == file_arg })
+          diff_asset(asset)
         else
           @stdout.puts "=== #{file_arg} ==="
           @stdout.puts "(not found in bundle)"
@@ -616,10 +633,31 @@ module Samagotchi
           diff_plugin(prov, record, plugin_path)
           @stdout.puts ""
         end
+        asset_states(prov, record).select(&:edited?).each do |a|
+          diff_asset(a)
+          @stdout.puts ""
+        end
       end
       0
     end
 
+    # The recorded rules and scripts (no source: an edited one is
+    # MemoryBundle::AssetState#edited?), for diff.
+    def asset_states(prov, record)
+      state = Samagotchi::MemoryBundle::AssetState
+      { rule: [prov.guardrails_dir, record.guardrails], script: [prov.scripts_dir, record.scripts] }.flat_map do |kind, (dir, recorded)|
+        recorded.keys.sort.map { |name| state.of(File.join(dir, name), kind_of_file: kind, recorded: recorded[name], name: name) }
+      end
+    end
+
+    # A rule or script keeps no base text: its recorded and current sha256.
+    def diff_asset(asset)
+      @stdout.puts "=== #{asset.label} ==="
+      current = File.file?(asset.path) ? Samagotchi::MemoryBundle::Provenance.file_sha(asset.path) : "(missing)"
+      edited = asset.edited? ? " (edited after install: the next install replaces it, a copy kept in the trash)" : ""
+      @stdout.puts "--- recorded sha256=#{Samagotchi::MemoryBundle::Provenance.recorded_sha(asset.recorded)} current sha256=#{current}#{edited}"
+    end
+
     # The base and the file; a marked one also the bundle's text it stays
     # behind (its source-less FileState says which).
     def diff_memory(prov, target_dir, key)

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.158.0
+version: 0.160.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:750822b3488b302c6e32638e6224f270d8e06b50ea85cd6e0bb5a6ff12eed1d8
   config_modification_protocol.md: sha256:44cf7bdac8e526805bff36b76b54fefecd41db30ca525c2ed661d78fe9155dd8
-  memory_guide.md: sha256:91e8fd248a155afad6b825097d9ee0a0215ba0b79092c8ab25501c0fc19dedfc
+  memory_guide.md: sha256:bdd34f34063df1b4ae74f7cda7c31080986d155e535ee4526d673c70edac8292
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd