samagotchi 0.147.0 → 0.149.0

data/docs/internals/objectives.md

@@ -0,0 +1,264 @@
+# Session objectives
+
+A session's objectives are a short list the user types: what this session is to achieve. The first version is a
+try-out, so each piece can come out alone. There is no new message kind or store: the list is a note in the
+conversation and the command writes a note file. Terminals show the default note bubble; the web draws it
+([The page](#the-page)). For the user's side, see
+[sessions.md](../sessions.md#objectives) and [cli.md](../cli.md).
+
+## The object and the entry
+
+`Objectives::List` holds `Objectives::Item`s (`id`, `text`, `status` active|done|dropped, optional `done_when`) and the
+number the next id takes. That number only grows, so an id is never reused, not after a drop or a `set`. `done_when`
+is a hint, never enforced.
+
+Each edit is a whole new list in one note entry:
+
+```ruby
+ContextNote.message(note_id:, text: list.text, source: "objectives", header: ContextNote::OBJECTIVES_HEADER,
+                    objectives: list.to_payload)
+```
+
+- `objectives` is one key in `ContextNote::KEYS`, so everything that copies a note field by field keeps it
+  (`ChatLoop#plain`). A note is also what `take_initial_prompt` and `TurnFlow#restore` already handle, which is why
+  this isn't a new kind.
+- The payload is `{"next" => 3, "items" => [{"id", "text", "status", "done_when"}]}`, in string keys before a save and
+  after one (`List#to_payload`). `Objectives.from_payload` reads either style.
+- It is never sent. The wire gets role and content only, and the frame instructs by itself:
+
+  ```
+  [OBJECTIVES, set by the user. What the user wants this session to achieve; replaces any earlier list. Keep work on it. Say when something falls outside it. Don't change it yourself.]
+  O1 [done] Two coffees, open the cart
+  O2 Stops before checkout (done when: no order is placed)
+  [END NOTE]
+  ```
+
+  A dropped item is left out of the text, and a list with nothing left says `(no objectives now)` so that it still
+  replaces the one before it. The frame has no clock, and there are no system prompt lines about it, so a session with
+  no list adds no note and no prompt line. It still carries the tool's bytes ([Moves](#moves)).
+
+A note body isn't escaped when it is saved, and a system-role note reaches the model as it stands, so outside text
+could carry a line that looks exactly like this frame. On the wire, `Steer.wire_text` leads such a line with `(quoted) `
+(`Steer::FORGED_OBJECTIVES`). That covers every entry with a kind, on both loops: a context note, a peer's `send_note`,
+`chi note`, a delegate report, a steer. A participant's message gets the wider `FORGED_OPENINGS`. The real note is
+known by its `objectives` payload key, never by its text. The saved content stays raw, the rewrite is deterministic,
+and text with no such line goes out byte for byte, so the prompt cache holds. The owner's typed prompt has no kind and
+isn't touched. Tool output isn't covered: it goes out as a tool result, not as a system message.
+
+A payload whose `next` isn't an Integer or whose `items` isn't an Array is not a list (`from_payload` answers nil), so
+it can't wipe the fold or restart the ids.
+
+## The current list
+
+`Objectives.build(conversation, pending:)` is a pure fold over the entries, shaped like `WorkingSet.build`: the newest
+list note wins, and a pending payload wins over that, because a file not yet absorbed is newer than anything in the
+conversation. `Objectives.pending_payload(session_dir)` finds the newest objectives file among the notes;
+`Objectives.current` is the two together.
+
+`build` also fills `List#moves`, the latest `Objectives::Move` per id ([Moves](#moves)). Moves are never in the frame or
+the payload, so an edit and a continue carry none: a new link starts with no last move.
+
+## Editing
+
+`/objectives` (`ObjectivesCommand`, registered `anytime`) reads `Objectives.current`. An edit goes out through
+`NoteDelivery.deliver(objectives:)`, which means:
+
+- 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.
+  Each note holds a whole list: without this, two edits that read the same list lost one.
+- `done` refuses a dropped item, and `undo` puts an item back to active.
+- A part with no text of its own refuses the line. An empty done-when is none, and of two done-when groups the last
+  counts. A leading `[done]`, `[dropped]` or `[active]` is stripped, so a text can't pass for a status. Any whitespace
+  collapses, Unicode line separators too, so each item stays one line of the frame.
+- It never writes session.json and runs on any thread: it only adds a file to `notes/`.
+- It is refused in a session a chi REPL owns (`--no-shared`), with the reason `chi note` gives
+  (`NoteDelivery::REPL_REFUSAL`). A show still answers there.
+- A second edit stacks on an unabsorbed first, since the current list reads the pending file.
+- `WorkerInbound#absorb_notes` adds only the newest list in a batch and deletes the others, so edits made during a
+  turn cost one entry. It runs between turns: an idle edit lands at the worker's next pass (the fallback tick, or just
+  before the next turn), and a mid-turn edit waits for the turn's end. A long coordinator turn is the known gap.
+
+The attached TUI and the web composer send the line like any session command (the registry's listing tells them it
+runs mid-turn too). So does `chi send -m "/objectives …"`. A participant's command is refused as any other is.
+
+## Moves
+
+The `objectives` tool (`Tools::ObjectivesTool`, schema last in `TOOL_SCHEMAS`) has one action, `move`: `id`, `note`,
+optional `evidence`. A call with no `action` is a move too. It is information only: nothing is written, and the call in
+history is the record. A handler can't append an entry mid-turn safely, and a system entry would split a call from its
+response, so there is no new entry kind. `Objectives.moves_in` reads the calls back with
+`LLMContextStale.paired_runs`, as `WorkingSet` does: both hosts' forms, a `call_tool` of it as it ran. A run whose output
+counts only if its output is the tool's answer that it recorded that id (`ObjectivesTool.recorded?`): a call with no list,
+a refusal, a denial or an interrupt recorded nothing. A rollback that drops the turn drops its moves.
+
+Mid-turn, `session.messages` doesn't hold the running turn. `/objectives` adds the loop's own conversation
+(`Engine#live_conversation`, a `dup` read on the command's thread), because `Engine#plugin_messages`' running part (the
+Bridge's `TurnAccumulator#current_messages`) leaves tool calls out. A move shows once its result is in.
+
+- **The answer** says it recorded a move, that the list is unchanged and that the user edits it with `/objectives`; so
+  does the schema's description. Other actions get an `Error:` with the same sentence. A small model told to edit the
+  list has nothing to call, and this is the only place it is told so: no stable-prompt line.
+- **No list**: `There are no objectives here…`, not an error, for a delegate (its fold is empty), a session with no list
+  and a kernel without a session (`Tools::Peers#objectives` is nil; `Engine::PeerView#objectives` reads the session).
+- **Refused**: an unknown id, a dropped objective, an empty note. A `done` objective takes a move.
+- **Declared**: on `full` (`all_core`) and on the coordinator kit (its bundle adds it); named in the not-loaded line
+  elsewhere, and so counted in `find_tools`' chi line, and among the deferred tools on a host that loads tools.
+- **Cost**: one extra generation when the move is the step's only call, none when it comes in a batch with another call.
+- **Guardrails**: no rule names it, so it passes with no ask, in `strict` too. `ReviewBoundary` denies it as anything
+  outside its kit. `PairBoundary` denies it as owner-voiced: a move stays in the owner's history and reads as the
+  session's own.
+- **The row**: `recording a move` in the TUI's line with `id=`, `note=`, `evidence=`; the web's row is `objectives O2 note · evidence`
+  (`ToolActivity#tool_title`). No UI of its own.
+
+`serves` on `ask_user_question` waits until moves read well. The model can't edit the list.
+
+## Proposals
+
+`action: propose` (`change` add, reword, done or drop; `id`; `text`; `note`, why) checks the change against the list
+(`Objectives::Proposal#refusal`) and hands it to `Engine#propose_objective`, which keeps it until the turn is over,
+as `#context_choice`'s cards are kept: shown in `run_turn`'s ensure, it is a between-turns card (no `in_turn`), so it
+writes no `pending_card.json`, the stage doesn't say it waits, and it keeps its buttons over a restart (`CardStore` takes
+them only from a card shown in a turn). The same change twice in a turn is one card. A P3 finding stands: a card action
+can't carry a plain reply, so an action here is a real edit.
+
+Apply is `/objectives --card ID done O2`: the proposal's own line (`Proposal#line`) behind a prefix the command reads
+(`ObjectivesCommand::CARD`), so it goes through the one route, with its refusals. On success the card with that id is
+replaced by a one-line notice. Dismiss (`--card ID dismiss`) only folds it. Either is recorded under the lock
+(`objectives_cards.json` in the session's folder), so a repeat, from a stale tab or a second tap, applies nothing: it
+says the proposal was already applied and folds the card again. A reword carries what it was proposed against
+(`--was`, `Objectives.fingerprint`) and is refused when the item has changed since. It keeps the item's done-when unless its text
+brings its own. The page keeps a proposal card's buttons off until the folded card comes or the action fails
+(`cards_place.js actionFailed`). A turn leaves at most `PROPOSALS_PER_TURN` (3) cards; past that the tool says so. A refused edit leaves the card, and its
+`command_ran` shows the refusal. Nothing is recorded as a move (`recorded?` is positive); the call stays in history as
+any call. An add's text can't split on ` | `. The body names the line, for a terminal, which shows no button.
+
+## The page
+
+`Objectives.view` (`List#to_view`) is what the page draws: the items, each with its last move, and `pending`, whether
+the newest list is a file still waiting. The session read (`objectives`, no key with no list) and the live
+`:objectives_updated` carry it. `Engine#announce_objectives` emits when the view differs from the last: after an edit,
+once a list note is in (`add_context_note`), at a turn's end (its moves) and after a rollback between turns. A session
+with no list emits nothing. Between two tabs that is all it takes. A participant gets neither: the event is in
+`ParticipantView::DROPPED`.
+
+Idle, an edit lands at once: the worker's anytime path wakes the loop (`@waker.wake`, one extra pass for any anytime
+command), which absorbs the file. It no longer waits for the fallback tick.
+
+- **The wiring** (`objectives_wiring.js`): the routes the strip and the moves post on, each following a woken worker
+  only while the page still shows that session.
+- **The strip** (`objectives_strip.js`, `#objectivesStrip`; pure parts in `objectives_model.js`, CSS in
+  `objectives.css`). A factory with its own closure (the list; never `store.current`), seeded by `renderSessionView` and reset
+  by `forgetSession`. Its edit list is a `chip_popover.js` shell, so a phone gets the bottom sheet and the focus rules.
+  Every edit is a line on the command route with `card: true`: no echo, and `commandView` hides a good `/objectives`
+  answer that came with that mark, so a tap leaves no bubble, a refusal does. The strip redraws from the event, never
+  optimistically.
+- **The entry** (`objectives_entry.js`, from `turn_html.js noteBubbleTemplate`): `Objectives.entry` puts the note's items
+  and, against the list before it, `changes` (`Objectives.changes`, display only) on the history item and on
+  `context_added`. A first list is pills; a later one a line, `You marked O1 done`. The raw text stays the tooltip.
+- **Moves** (`objectives_moves.js`): a tool row's id is a chip (`moveRowText`), and a row that recorded a move carries
+  `data-move-id`. One observer on `#history` reads those back into a line after each finished `.turn-work`, so a reload,
+  a live end and a hand-off all draw it. The newest line's Not yet is `objectivesStrip.notYet`. A decision card's
+  `Concerns O2` gets the chip there too.
+- **Not yet** is `POST /turn` with a client id of its own (`<tab>:objectives`), so the stream draws its bubble in every
+  tab, this one too: the page's own echo needs the composer. It steers a running turn or starts a turn, as a typed line.
+- **Short version**: the same observer offers `/short` (decision-card) under the newest long answer (`foldable`), only with a list
+  and with the command in the session's listing, and not during a turn: `/short` itself refuses then, since a running
+  turn's "last answer" is interim text. A request that fails, or a worker that leaves with one still out (the bundle's service
+  stops after chi's 3 s wait for a command), ends the card saying so; a worker killed outright leaves its one-line `…` row.
+
+## Continue, rollback, fork
+
+- **Continue**: `Objectives.carry`, in `SessionContinue`'s `before_spawn`, writes a second note file in the new link,
+  after the carry note and any moved context's note, so the list reads as the latest word. It is not in
+  `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.
+- **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.
+
+## The long-answer card
+
+A bundle, not core: [decision-card](../bundles.md#the-decision-card-bundle), removed by uninstalling. It reads the list with
+`ctx.objectives`, the plugin API over `Objectives.current`; `items` and `text` are the bundle's only view of the object.
+
+`:after_turn` reads the answer's length and tail from `event[:answer]`, not from the stored message, which on the native
+loop still holds its thought block, and starts a thread only when both pass, so the turn's end
+is held for no request and the web's answer doesn't wait (no `event[:present]`). The thread reads the list and, with an active
+objective, makes one `ctx.ask_model`. A Transcript drops system entries, so the list goes in `prompt:`. The objective a reply
+names is display only: an id the list doesn't have, or has dropped, is left out.
+
+Stale is a new turn: `:before_turn` takes the running `Ask` and cancels its request, so a one-slot server is free for that
+turn, and `show` holds the same mutex, so a card shows before that start or not at all. The hook runs inside its turn, so the
+card waits for `ctx.turn_running?` to go false: shown earlier, it gets `in_turn: true` and lands in that turn's collapsed block.
+The request doesn't wait: it goes ahead of the turn-end warm-up, so on a one-slot server the warm-up queues behind it and is the
+last thing in the slot, and the next turn keeps its prefilled prompt. A shown card is replaced by a one-line one with
+the same id only at a turn of the owner's (a prompt, no author): a wake has no prompt, and a child's report isn't an answer. A
+worker that restarts forgets a shown card, which then stays as it is: it has no buttons.
+
+A card with no actions writes no `pending_card.json`, so it never reaches `Web::Push::Attention`.
+
+## Check this
+
+`/objectives check O2` and the list's **Check this** (an objective with a move, the one route) run `ObjectivesCheck.run` on the
+anytime command's own thread: one side request (`Engine#ask_objective_check`, on `ask_side_model`) reads the objective's latest
+move against the session's record, and the answer is a verdict with reasons. Information only: no status changes, it is
+never an approval, no coordinator path reads it, and nothing enters the conversation or the next request.
+
+**Why not a `VerifyFresh` child.** The plan said "VerifyFresh-like, fit unchecked". It fits poorly:
+
+- `VerifyFresh.start` starts from a saved unclear verdict and its `VerifyAnchor`, a quote of at most 200 characters that
+  `verify_anchor_source_session` holds against the parent's text. A move has neither, and a faked one would land in `session.verdicts`.
+- A child is an agent on the session's model with the owner's tools: an unknown number of requests, approvals waiting
+  on the child, a place in `session.max_children` and in the session lists, and its spend outside the parent's line.
+  Keeping it read-only and out of the delegate paths (`ChildRing`, `ChildrenStatus`) needs a new session field.
+
+The side request costs exactly one request, shows in the session's side line (kind `objectives`) and comes out with one
+file. What it gives up: **it can't open a file or run anything.** It reads what the session saw, so a claim that nothing in
+the record settles is `unclear`, and a file changed since isn't seen. If that turns out too weak, a read-only child is the
+next step, and the file and view below can stay.
+
+**Independence.** The request (`ObjectivesCheck.request`) has its own system text and no tools. Its record is what people and
+notes said and what tools returned (`.record`, each entry cut at 1,500 characters, the newest 24,000 kept). It never holds the
+agent's prose, the system prompt, the list's notes, a continue's carry note, which holds the agent's last answer
+(`Objectives.outside_note?`, the rule the audit shares), or the objectives tool's calls, since a move isn't evidence for itself.
+Note and evidence are capped at 1,000 characters each. Mid-turn it reads the loop's conversation (`Engine#live_conversation`), the running turn's runs too.
+
+**Its frame.** The claim and the record sit between `<record-RANDOM>` tags made per request, so tool output printing a closing tag
+stays inside; the request says that what's inside is data and its instructions aren't to be followed. No model is needed for
+the frame to hold; a model may still be swayed by text inside it, which is why a verdict is information only.
+
+**Its host.** The model is the session's, or `objectives.check_model`, whose host may be another one. The whole user text goes through
+`Web::ParticipantView::Redact.text`, chi's participant redaction: known key shapes and `token=`-style values become `[redacted]`, and
+the home folder `~`. That is by pattern, so a secret of another shape still goes.
+
+**State.** `objective_checks.jsonl` beside the session: a `running` line, then one with `verdict` (confirmed, refuted, unclear,
+`no_answer`), `reason`, `text`, `model` and `mark`: a digest of the item's line as sent and the move itself (`Move#ref`, its run's
+id and its model entry's time, with its words). The start is under `Objectives.with_lock`, so a double tap or a second tab answers "already
+being checked" and asks nothing. A running line stops counting once its worker's pid is gone, so a kill, a shutdown or a restart frees
+the next check at once, and past `RUNNING_SECONDS` in any case. `Objectives.view` puts the last check on its item (`check`), only while `mark`
+matches: a reword, a status change or a newer move, in the same words too, offers the check again. A running check carries `until`, because no event says
+its worker died: the strip lets the row go at that time (`armExpiry`), and a reconnect's session read clears it sooner. `announce_objectives` carries the start and the end. A continue doesn't carry it.
+
+**Shown as** a card with no actions (`source: objectives`, on the command's thread, so `anytime` and not in a turn's block, and it
+writes no `pending_card.json`, so no push), the list's row, and `check:` under the move in `/objectives`. A model that fails is
+`no_answer`: logged (`objectives_check_failed`), an info card saying so, and the next tap may try again.
+
+**Limits.** Refused during a participant's turn, whose text stays out of a side request; one ending during their turn is still the owner's (`Engine#side_author`). A participant can't reach it: the
+command route is the owner's, and `card` and `objectives_updated` are in `ParticipantView::DROPPED`. A move made in the running
+turn isn't on the page until the turn's end (`announce_objectives`), so its tap waits for that; the typed line works at once.
+
+## System 1 in audit
+
+`ObjectivesAudit`, off unless `objectives.system_one: audit`. See [system-one.md](../system-one.md#objectives-in-audit).
+
+## Not in this version
+
+Stable-prompt lines aren't here, and terminals have no picture: they keep `/objectives`.
+
+Taking it out: old notes stay readable framed bubbles and keep being sent, and the key is ignored. Old `objectives` calls
+stay as history; with a kit no longer declaring the tool, they are ordinary saved calls. The card's bundle uninstalls. The
+page's pieces are the `objectives_*.js` modules and `objectives.css`, wired in a few lines of `app.js`; without them a list note
+falls back to the default bubble once `noteBubbleTemplate`'s first line goes. Check this is `objectives_check.rb`, its line in the command and
+the `check` key; the audit is `objectives_audit.rb` and three calls in `Engine`. Old `objective_checks.jsonl` files and saved runs are then read by nothing.

data/docs/internals/web-frontend.md

@@ -23,7 +23,7 @@ page. A factory dep a new version stops passing is the same hazard the other way
 out of `send_turn.js`, `session_actions.js` and `lists_view.js`); a page loaded before keeps all its old modules
 until a reload, so the risk is a mixed cache, not an open tab. `answer_fold.js`, `details_motion.js`,
 `turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
-`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep) and `worker_features.js` are new modules for that reason.
+`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js` and the `objectives_*.js` modules are new modules for that reason.
 
 ## Two pages, two models
 
@@ -54,6 +54,9 @@ change.
 | **localStorage** (`storage.js` `readStored`/`writeStored`, guarded) | per-browser choices only | the module that owns the choice | read at start (see Storage keys) |
 | **SSE** | see Streams | the server | owner page: events go into the DOM directly; participant page: an event marks the data stale |
 
+The objectives' strip keeps the list in its own closure (`objectives_strip.js`, seeded by `renderSessionView`, reset by
+`forgetSession`, updated by `objectives_updated`): [objectives.md](objectives.md#the-page).
+
 The start page's own choices (the model, the ⚙ panel, the 🧰 list) live in `start_page.js`'s closure, never in
 `store.current`. A fresh chain link's picker reads both.
 

data/docs/plugins.md

@@ -850,10 +850,12 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); the REPL's is the conversation before that turn. An entry may carry `at`, when it happened (docs/sessions.md, Message times) |
 | `ctx.messages_partial?` | whether `ctx.messages` leaves out a running turn (the REPL mid-turn), so a plugin can say what its answer is about |
 | `ctx.prompt_files` | the files whose text is in the session's system prompt now: the AGENTS.md chain (the work tree top down to the cwd) and the appended files (`append_system_prompt:`, `--append-system-prompt`); absolute paths, in prompt order, `[]` before the first build |
+| `ctx.objectives` | the session's [objectives](internals/objectives.md), read now, as a frozen value: `empty?`, `items` (each `id`, `text`, `status` `"active"`, `"done"` or `"dropped"`, `done_when`), `find(id)`, `text` (the lines the model is shown) and `moves` (the latest move per id; mid-turn, a worker's leaves the running turn's out). An edit not yet absorbed counts. Empty when the session has none. Use its methods, not its class. Needs chi newer than 0.148.0 |
 | `ctx.notify(text, level: :info, fallback_for: nil)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command). `fallback_for: :display` marks a line that repeats the answer's display (`event[:present]`), which a UI that renders the display leaves out (`fallback_for: :editor`: a file the viewer could open from a ref in its editor): see [Hooks](hooks.md#what-a-hook-can-do-the-runtime). The keyword needs chi 0.35.0 (it raises on an older chi) |
 | `ctx.card(title:, body: "", actions: [], level: :info, id: nil)` | a card in every UI, returning its id: see [Cards](#cards) |
 | `ctx.ask_user(question:, options:, header: nil, allow_freeform: false, effects: nil)` | a single-select question through the question flow: `{selected:, freeform:, selected_indices:}`, or nil (no one to ask, cancelled, bad options or effects). `effects:` tags the options a parent agent's answer is held to (label => `:spend`, `:permit`, `:permit_wide` or `:deny`; untagged = `:answer`): tag every option that spends or permits, and never let text alone or a dismissal do either ([hooks.md](hooks.md#what-a-hook-can-do-the-runtime)). It needs a chi newer than 0.85.0 |
 | `ctx.cancelled?` | whether the running turn was cancelled (a long tool should stop) |
+| `ctx.turn_running?` | whether a turn runs now. An `:after_turn` hook runs inside its turn, so a card a thread shows before the turn is over belongs to that turn's block, which the web collapses: wait for this to go false. Needs chi newer than 0.148.0 |
 | `ctx.steer(text)` | put text into the running turn: its own user message at the loop's next boundary, shown as `my-bundle> nudged: …`. The model reads it with a header naming your bundle (`[Steer from the my-bundle plugin, mid-task. …]`); the session keeps the raw text. Returns true when queued, false with no turn running (it never starts one; that is `ctx.sessions`' send). Dropped (logged) if the model answers or the turn ends first. Safe from any thread: an anytime command, a hook (false from `:after_turn`), your own |
 | `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason; true when it stopped one now. In a `:before_tool_call` block it also denies that call |
 | `ctx.stop_generation(reason)` | cut the generation that is streaming: the turn goes on and the model is asked again ([hooks.md](hooks.md#watching-the-stream)). Shows nothing: post your own notice. True when it cut one now |
@@ -1377,8 +1379,8 @@ that calls it, or for a real external bundle that does. No method on the chance
    `Samagotchi::Tools::Execute.timeout_seconds`.
 5. `Samagotchi::Tools::TaskRuntime::TASKS_DIR` and `EXIT_CODE_FILENAME`.
 6. `Samagotchi::AtomicFile.write`, `Samagotchi::Log.warn` /
-   `Samagotchi::Log.debug`, `Samagotchi::Config.get` and
-   `Samagotchi::VERSION`.
+   `Samagotchi::Log.debug`, `Samagotchi::Config.get`,
+   `Samagotchi::VERSION` and `Samagotchi::CancellationController` (`new`, `cancel!`: what `cancel:` takes).
 
 `Samagotchi::Testing::Boundary::ALLOWED` is the checked copy of this list,
 and `Boundary::EXCEPTIONS` the per-bundle list of what each shipped bundle

data/docs/releasing.md

@@ -13,7 +13,7 @@ can run the whole release; the user approves the notes before the tag and the
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
 - **Every other shipped bundle** (btw, check-in, guardrails, known-names,
-  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, work-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, work-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, model-notes, decision-card, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`

data/docs/sessions.md

@@ -192,6 +192,48 @@ OSA
 [ -n "$picked" ] && pbpaste | "$chi" note --source clipboard $(print -r -- "$picked" | cut -f1)
 ```
 
+## Objectives
+
+`/objectives set A | B` gives a session a short list of what it is to achieve, and `/objectives` shows it. The list goes
+into the conversation as a note under its own frame (`[OBJECTIVES, set by the user. …]`), which asks the model to keep
+work on it, to say when something falls outside it and not to change it itself. A session with no list behaves as it
+would without the feature; its request only carries the `objectives` tool below (declared on `full`, named in the
+not-loaded line elsewhere). Each item has an id (`O1`, never reused), a status (active, done, dropped) and
+optionally a done-when hint, which nothing enforces.
+
+An edit waits for a moment between turns: it lands within seconds in an idle session, and at the turn's end during one.
+Several edits made during a turn go in as one list. A continue copies the list to the next link, as a second note after
+the carry note; a review link doesn't. `!rollback` keeps it. A chi REPL's session (`--no-shared`) refuses an edit, as it
+refuses a note. See [cli.md](cli.md#session-objectives) for the commands and
+[internals/objectives.md](internals/objectives.md) for the mechanism.
+
+The model can record a **move** with the `objectives` tool: a line on what it did or found for an objective, with
+optional evidence. A move shows as the tool's row in the turn, and `/objectives` shows each objective's latest one under
+it. It is information only: only you change the list or a status, and it never approves anything. A move costs one
+generation when it's the step's only call. On a kit that doesn't declare the tool, `/toolkit add objectives` declares it
+(the model can also reach it with `call_tool`). A participant's turn is denied it.
+
+The model can also **propose** a change with that tool (add, reword, done, drop). You see a card when the turn is over:
+Apply makes the edit, once, Dismiss leaves the list, and ignoring it changes nothing. A turn leaves at most 3. A proposed
+reword is refused when you changed that objective since. The model never changes the list by itself.
+
+**Check this** (`/objectives check O2`, or the button in the web's list, for an objective with a move) asks for an independent read of
+the latest move: one side request, on your request only, on the session's model or `objectives.check_model`. It sees the
+claim, what people and notes said and what tools returned, not the agent's prose, and no file: what the record doesn't
+settle comes back `unclear`. **That is up to 24,000 characters of raw tool output, which with a hosted `check_model` leaves the machine on one tap, even from a local session.** chi's redaction takes out known key shapes and `token=`-style values first, by pattern only, so another secret in a tool's output still goes. The verdict (confirmed, refuted, unclear) and its reasons come as a card and under the
+objective. It is information only: it changes no status, approves nothing, and isn't in the conversation or the model's next request.
+A second tap while one runs asks nothing. Its cost is in the session's side line. Mid-turn it runs beside the turn; on a one-slot
+local server it answers after the running request. A participant can't reach it. See
+[internals/objectives.md](internals/objectives.md#check-this).
+
+**In the web** a session with a list has a strip above the conversation: its objectives and how many are done (a phone
+shows one line, the one being worked on). A tap opens the list, where you add, mark done, drop, undo and tap a text to
+reword it, with no message and no turn. Mid-turn the strip has the change and says it applies after this turn. Each list
+in the conversation shows as pills, or as one line of what you changed. A turn's moves show as chips above its answer;
+Not yet on one (or in the list, for an objective with a move) sends `Not yet on O2 (…).` as a normal message. With the
+[decision-card](bundles.md#the-decision-card-bundle) bundle, the newest long answer offers its Short version in a card,
+which enters no history. A session with no list shows none of this. A participant doesn't see the list.
+
 ## Notes a turn leaves for the model
 
 A turn that ends without an answer leaves one line for the model to read on its next turn, as a tail
@@ -304,8 +346,8 @@ A session can **continue** an earlier one: "the next run of the same routine" (a
 
 `SessionManager.continue_session` makes the next link:
 
-- **What it copies:** the previous link's folder, its model (the name it was typed as, so an alias holds) unless the continue names one (`--model`, the web's `model`), and its own LLM context values. A model given is checked like a new session's (a host config.yml doesn't have refuses the continue, nothing archived). An inherited model whose host can't run it any more (gone from config.yml, `enabled: false`, an alias naming another host) **falls back to the default model** with a warning, `gone:org/model can't run (unknown host 'gone' in model …); started on <default>`, decided before the archive; with no default model configured the continue is refused. The carry note doesn't mention the model. The new link carries no transcript, so a different model, or another provider, starts clean there. Its preview is the previous link's (until its first message is saved), unless it starts with a message. Its title (`/title`) is the previous link's, with or without a first message.
-- **The carry note:** the new link starts with a context note from `session chain` (shown in its transcript as `note from session chain`), queued before its worker spawns, so its first turn sees it: `This session continues 3fa2c1d0 (2026-10-08 09:12), the previous link of its chain. Its recap, as of 2026-10-08 18:02:` and the previous link's recap (`recap.json`; cut at 8000 characters). No recap (fewer user turns than a recap needs, recaps off, none written in time): `… It left no recap.` Never more than the recap: no transcript. An idle new link holding only the note is kept, not discarded as empty.
+- **What it copies:** the previous link's folder, its model (the name it was typed as, so an alias holds) unless the continue names one (`--model`, the web's `model`), and its own LLM context values. A model given is checked like a new session's (a host config.yml doesn't have refuses the continue, nothing archived). An inherited model whose host can't run it any more (gone from config.yml, `enabled: false`, an alias naming another host) **falls back to the default model** with a warning, `gone:org/model can't run (unknown host 'gone' in model …); started on <default>`, decided before the archive; with no default model configured the continue is refused. The carry note doesn't mention the model. The new link carries no transcript beyond the note's last answer, so a different model, or another provider, starts clean there. Its preview is the previous link's (until its first message is saved), unless it starts with a message. Its title (`/title`) is the previous link's, with or without a first message.
+- **The carry note:** the new link starts with a context note from `session chain` (shown in its transcript as `note from session chain`), queued before its worker spawns, so its first turn sees it: `This session continues 3fa2c1d0 (2026-10-08 09:12), the previous link of its chain. Its recap, as of 2026-10-08 18:02:` and the previous link's recap (`recap.json`; cut at 8000 characters). No recap (fewer user turns than a recap needs, recaps off, none written in time): `… It left no recap.` Then `Its last answer:` and the previous link's last answer, read after the recap wait, so its exact shas, paths and next steps survive: a longer one keeps its last 4000 characters, after a `…` (a wrap-up closes on what comes next). There is none when the newest bubble was a step that asked for tools, when a later turn failed or was cut before it answered, and on a review link (a continue doesn't copy the grants, so the next link's participants could differ); `session.carry_last_answer: false` leaves it out of every note. No other transcript. The note never makes a continue fail: it stays within the 16 KiB a note may hold, the answer taking what the head and recap leave, and a session file that can't be read gives no answer. An idle new link holding only the note is kept, not discarded as empty.
 - **Its attached context:** the previous link's movable sources (a command source by default; a pushed one stays) are copied to the new link before its worker starts, with their last text and the removed and muted markers, and a second note (`attached context`, after the carry note) names what moved and what stayed. A push into the archived link is then refused with the new link's id. See [Movable context](context.md#movable-context).
 - **The recap first:** a previous link with a live worker is asked for a recap (the Bridge's `POST /recap`) and given up to 30 s to write it; one with none wrote its recap when its worker left.
 - **The previous link is archived** before the new one starts, by the archive's own rules (see *Archiving a session*): a turn running, a prompt queued or the step-limit question refuse it, a live idle worker is stopped, a plain REPL's session is refused. Its finished delegates are archived with it, as any archive does.

data/docs/system-one.md

@@ -3,7 +3,7 @@
 System 1 is the cheap judgment model chi asks small questions: approvals
 ([guardrails.md](guardrails.md#system-1-experimental)), toolkit suggestions
 ([configuration.md](configuration.md#toolkits)), context candidates
-([context.md](context.md)) and bundles' own ([plugins.md](plugins.md#judgments-chijudgment-and-ctxjudge)). Each use keeps its own mode, gates and log. What they share is
+([context.md](context.md)), the objectives' audit ([below](#objectives-in-audit)) and bundles' own ([plugins.md](plugins.md#judgments-chijudgment-and-ctxjudge)). Each use keeps its own mode, gates and log. What they share is
 one host (`system_one.host`, `.model`, `.timeout_ms`) and one layer that saves every ask, so a later comparison or fine-tune has what
 was sent and what came of it. The runs don't leave the machine; a hosted System 1 host sees each state as it is asked.
 
@@ -20,6 +20,7 @@ one warn and never changes the answer. A use that needs the run's id at once pas
 | `approvals.allow` | `GuardrailWiring#system_one_judge` | gates, acted (the judgment line's decision), labels |
 | `toolkit.suggest` | `ToolkitSuggest.judge` | acted (the log's `did`), no labels |
 | `context.candidate` | `ContextJudge.ask` | labels |
+| `objectives.incoming`, `objectives.outgoing` | `ObjectivesAudit` | none: nothing acts on them |
 | `<bundle>.<name>` | `SystemOne::Judgments` (`ctx.judge`, `ctx.judge_later`) | the bundle's: labels, acted |
 
 Not saved: a toolkit warm-up (it goes straight to the backend), `chi guardrails replay`,
@@ -33,7 +34,7 @@ same `Client` and `Recording`: the API is in [plugins.md](plugins.md#judgments-c
 [configuration.md](configuration.md#bundles-judgments).
 
 Only bundles' judgments have settings of their own (`JudgmentSettings`). Core's take no host, model or mode here, whatever
-`system_one.judgments` says: `Record` and `Similar` are model-blind (`Record#initialize` filters by rule only), so a model swapped
+`system_one.judgments` says: `Record` and `Similar` are model-blind (`Record#initialize` filters by rule, and by repository for a rule in `guardrails.system_one.repo_rules`, never by model), so a model swapped
 for approvals alone would inherit a clean record and could auto-allow. Before any such swap, `Record` and `Similar` have to go by model.
 
 Core's uses keep their own threads (`ToolkitSuggest::Pending`, `ContextJudge`, the approval path) and contention; only the ask-and-save
@@ -41,6 +42,21 @@ seam is common. A bundle's `judge_later` runs on the Engine's `SideJudgments` un
 at shutdown covers it, and a run cut by that one-second limit is lost. Its asks stay out of the session's spend, as all of System 1's do, and no
 cost cap covers them on a hosted host.
 
+## Objectives in audit
+
+`objectives.system_one: audit` asks whether a message may affect an objective: one yes/no (`affects`) per active objective, each ask
+one request and one run. It is off by default, and asks only with a list that has an active objective, a `system_one.host` and saving on
+(`system_one.runs`). **Mode audit only:** there is no `on`. Nothing reads an answer: no card, no wake, no push, nothing in a prompt, and no turn. A
+per-message judge on an objective didn't work as a gate on the pod (AUC about .5 to .66), so these runs are there to look at, with `chi judgments report objectives.incoming`.
+
+- `objectives.incoming`: a person's message of the owner's of 40 characters or more at its turn's start (`TurnOrigin#human?`: not a reminder's or a delegate's prompt), not a `/` or `!` line, and a note going
+  into the conversation (not the list's own, nor a continue's carry note: `Objectives.outside_note?`). A steer isn't asked about.
+- `objectives.outgoing`: a finished answer of the owner's turn of 400 characters or more, not a cancelled or exhausted one.
+- The state: `objective` (its text and done-when, no id or status) and `message` (2000 characters: a message's head, an answer's tail).
+  **That text goes to the System 1 host**, a hosted one too, and into the run. A participant's turn, a review session and a scratch session are never asked about.
+- At most 6 objectives per message. Each direction has one ask running: what comes meanwhile is a run with `asked: false`, `skipped: busy`.
+- The asks run on `SideJudgments`' threads beside the turn, so a turn doesn't wait; on a one-slot server shared with the session's model, a request can still queue behind or ahead of them. They share `/v1/systemone` with approvals: on a slow one-slot host an approval can wait behind up to 2 in-flight asks and time out to the user. A failed ask is a run with its `failure` and one log line (`system_one_failed`), and a `--no-shared` REPL's stderr shows that line as for any System 1 ask.
+
 ## The store
 
 `<state dir>/system_one/runs/<judgment>/YYYY-MM-DD.jsonl` (`SystemOne::RunsStore`): one file per UTC day,

data/lib/samagotchi/answer_tail.rb

@@ -46,7 +46,7 @@ module Samagotchi
       return false if ContextNote.note?(message) || Steer.steer?(message) || TurnNote.empty_answer(message)
       return false unless %w[assistant model].include?((message[:role] || message["role"]).to_s)
 
-      !OutputFormatter.strip_markup((message[:content] || message["content"]).to_s).empty?
+      !OutputFormatter.strip_markup((message[:content] || message["content"]).to_s.scrub).empty?
     end
   end
 end

data/lib/samagotchi/bundles/coordinator/guardrails/merge.yml

@@ -0,0 +1,21 @@
+# The coordinator's merge approval (docs/bundles.md, The coordinator bundle).
+# Here and not in the guardrails bundle: that one is in the core profile, so
+# everyone would get a new ask and --non-interactive merges would start being
+# denied. The skill and the rule upgrade together.
+#
+# Votes in every session on a machine with this bundle, any repo, children and
+# background builds too, and a --non-interactive merge is denied: nobody to ask.
+#
+# Asks on every merge, whatever the branch. Same git-with-global-options prefix
+# as the guardrails bundle's rules; merge-base, merge-tree, merge-file,
+# mergetool and a merge whose first word is --abort, --continue or --quit don't
+# match. git pull and gh pr merge are not covered. Text as data over-asks (a
+# commit message, chi send -m, a heredoc).
+rules:
+  - id: git-merge
+    tool: shell
+    command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+merge(?=[\s;&|)]|$)(?!\s+--(?:abort|continue|quit)\b)'
+    skip_read_only: true
+    verdict: ask
+    scopes: [once, rule]
+    reason: git merge joins a branch into the checked-out one; allowing the rule covers every later merge in this repo

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

@@ -1,18 +1,22 @@
 ---
 name: coordinator
-version: 0.6.1
+version: 0.8.0
 scope: system
-description: "Coordinate parallel work: the coordinator skill (split the work, one worktree and child session per task, check each report, ask before each merge, a handoff memory to resume from), /coordinate <goal>, /coordinate resume, /coordinate end, /coordinate review (experimental: a sprint review session to share) and /children; the coordinator toolkit (lean + delegate, delegate_result, list_sessions) and the coding toolkit for build children (child + be concise)"
+description: "Coordinate parallel work: the coordinator skill (split the work, one worktree and child session per task, check each report, merges under a guardrail approval (the git-merge rule) or a question, a handoff memory to resume from), /coordinate <goal>, /coordinate resume, /coordinate end, /coordinate review (experimental: a sprint review session to share) and /children; the coordinator toolkit (lean + delegate, delegate_result, list_sessions, objectives) and the coding toolkit for build children (child + be concise)"
 trust_level: reviewed
 files:
   skill_coordinator.md:
-    sha256: sha256:5f6b879de274ebc89b7811d3dda3abbecbeb696159e326647a1c7393c3598f57
-    description: "Coordinate parallel work: split it, delegate each task wait:false in its own worktree (cwd:), check each report, ask the user before each merge; resume from a handoff_* memory"
+    sha256: sha256:1cac885facd28757aaa0197b28889246f845834c17101d59b5625d1b2b89679a
+    description: "Coordinate parallel work: split it, delegate each task wait:false in its own worktree (cwd:), check each report, merge under the git-merge approval or ask the user; resume from a handoff_* memory"
 plugin:
   file: plugin.rb
-  sha256: sha256:0cd1e14cfc8afc6c8fd82548f390d20c812f336bdd357edaaa1b8ba1be32e0ef
+  sha256: sha256:84535a86b754f3a12cdb2f2591027ea71bbf9ffb74734b1050899b9a4fde07ac
 # the coordinator toolkit needs chi.toolkit and ctx.use_toolkit (0.66.0); the
 # coding toolkit (chi.toolkit prompt:) and the skill's delegate toolkit: need
 # the next chi.
 requires_chi: ">= 0.107.0"
 # /coordinate review uses ctx.sessions.review (the next chi).
+# No requires_chi_next for guardrails/merge.yml: its keys are long supported, and first-ever too-new rules would make a
+# live older worker deny every call. A chi without `chi guardrails rule` gives a usage error, and the skill then asks.
+# Nor for the objectives tool in the kit and the skill: on an older chi the kit's add names nothing (it declares only what
+# is registered), and a call of it comes back as an unknown tool, no harm.

data/lib/samagotchi/bundles/coordinator/plugin.rb

@@ -3,7 +3,8 @@
 # The coordinator bundle (docs/bundles.md, The coordinator bundle): chi as a
 # coordinator of parallel work. Its skill_coordinator memory holds the steps
 # (split the work, one worktree and a wait: false delegate per task, check
-# each report, ask before each merge); this plugin adds two commands.
+# each report, merge under the git-merge rule's approval or ask); this plugin
+# adds two commands, and guardrails/merge.yml that rule.
 #
 # /children [all] shows this session's children as a card, newest first:
 # state, branch, the last reply and whether it was reported (ChildrenStatus
@@ -41,7 +42,8 @@
 # itself (the core child-boundary guardrail), in every mode: nothing to set up.
 #
 # The coordinator toolkit is lean plus the tools that run children
-# (delegate, delegate_result, list_sessions). /coordinate puts the session
+# (delegate, delegate_result, list_sessions) and objectives (the skill's
+# moves). /coordinate puts the session
 # on it before it asks the model (ctx.use_toolkit), which chi allows only
 # before the session's first model reply and outside a turn: otherwise it
 # says to run /toolkit coordinator, unless the session declares delegate
@@ -83,7 +85,7 @@ class Plugin
   def initialize(_settings = {}); end
 
   TOOLKIT = "coordinator"
-  TOOLKIT_TOOLS = %w[delegate delegate_result list_sessions].freeze
+  TOOLKIT_TOOLS = %w[delegate delegate_result list_sessions objectives].freeze
   CODING_TOOLKIT = "coding"
   CODING_PROMPT = "- Be concise in your responses\n- Show file paths clearly when working with files"