@possumtech/rummy 2.0.1 → 2.2.0

package/SPEC.md

@@ -1,9 +1,33 @@
 # RUMMY: Architecture Specification
 
 The authoritative reference for Rummy's design. The instructions
-plugin (`instructions.md` + phase-specific `instructions_10N.md` +
-tool docs) defines model-facing behavior. This document defines
-everything else.
+plugin (`instructions-system.md` + `instructions-user.md` + tool
+docs) and the persona plugin (`persona/default.md`) define model-
+facing behavior. This document defines everything else.
+
+---
+
+## Glossary {#glossary}
+
+Canonical meanings. When a doc, comment, test name, or commit message
+uses one of these words, it should mean exactly what's written here.
+
+| Term | Meaning |
+|---|---|
+| **run** | The alias-keyed lifetime of one project-agent invocation. Begins on `set run://{alias}` with a prompt; ends at terminal status (200/204/422/499/500). One run per alias; aliases are unique per project. |
+| **loop** | One `ask` or `act` invocation and all its continuation turns until terminal `<update>`, abandonment, or abort. A run can contain multiple loops if a fresh prompt arrives on an existing run. |
+| **turn** | One round-trip with the LLM: one assembled prompt sent, one response parsed. A loop is a sequence of turns. |
+| **mode** | `ask` (read-only — no proposals, no `<sh>`, no edits) or `act` (full tool surface). Per loop, set at the entry point. |
+| **phase** | The RECORD→DISPATCH split within a single turn (see [dispatch_path](#dispatch_path)). AGENTS.md "Phase 1 / Phase 2 / ..." entries refer to project-development milestones; that's a separate use of the word. The model-facing workflow lives in `persona/default.md` as the 7D ladder — Draft → Decompose → Discover → Distill → Define → Determine → Deliver — a persona convention, not a status-keyed engine state. |
+| **proposal** | A tool-call entry at status 202 awaiting client resolution (accept/reject). Side-effecting actions (`<sh>`, `<env>`, file `<set>`, file `<rm>`/`<mv>`/`<cp>`, `<ask_user>`) emit proposals. YOLO mode auto-accepts. |
+| **verdict** | The end-of-turn ruling from `hooks.turn.verdict.filter` — a generic filter chain. Returns `{continue, status, reason}`. The error plugin is the canonical subscriber today; future plugins (cycle-detection, budget-overflow termination) can join the chain to vote without touching error.js or AgentLoop. Decides whether the loop continues to another turn or terminates. |
+| **strike** | A turn whose verdict counts toward `MAX_STRIKES`. A strike fires when `turnErrors > 0` (any `error.log` entry that turn) or when cycle detection trips silently. The streak counter resets on a clean turn (no errors, no cycle); reaches `MAX_STRIKES` → loop abandons at 499. |
+| **resolution** | Client's accept/reject of a proposal via `run/resolve` RPC. |
+| **dispatch** | The DISPATCH phase of a turn — actually executing recorded action entries. |
+
+**Hierarchy:** project ⊃ run ⊃ loop ⊃ turn. A turn is the smallest
+unit of model interaction. A strike is a per-turn property that
+accumulates across turns within a loop.
 
 ---
 
@@ -99,11 +123,12 @@ hooks-and-filters system. Plugins subscribe to events (fire-and-forget
 side effects) and filters (transformation chains that thread a value
 through subscribers in priority order).
 
-**Every `<tag>` the model sees is a plugin.** `<knowns>` → known
-plugin. `<unknowns>` → unknown plugin. `<performed>` → performed
-plugin. `<previous>` → previous plugin. `<prompt>` → prompt plugin.
-No monolithic assembler decides what goes where. Each plugin filters
-for its own data from the shared row set, renders its section, returns.
+**Every `<tag>` the model sees is a plugin.** `<summary>` /
+`<visible>` → known plugin. `<unknowns>` → unknown plugin. `<log>`
+→ log plugin. `<instructions>` → instructions plugin. `<prompt>` →
+prompt plugin. `<budget>` → budget plugin. No monolithic assembler
+decides what goes where. Each plugin filters for its own data from
+the shared row set, renders its section, returns.
 
 **Plugins compose, they don't coordinate.** A plugin subscribes to a
 filter at a priority, receives the accumulator value, appends its
@@ -227,7 +252,7 @@ Every entry plays one of four roles:
 
 | Role | Category | Section | Description |
 |------|----------|---------|-------------|
-| **Data** | `data` | `<context>` | Entries the model works with — persistent state and captured payload |
+| **Data** | `data` | `<summary>` + `<visible>` | Entries the model works with — persistent state and captured payload. Summary line in `<summary>` for visible+summarized tiers; full body in `<visible>` only when promoted. |
 | **Logging** | `logging` | `<log>` | Records of what happened — tool results, lifecycle signals |
 | **Unknowns** | `unknown` | `<unknowns>` | Open questions the model is tracking |
 | **Prompt** | `prompt` | `<prompt>` | The task driving the loop |
@@ -262,10 +287,11 @@ across two namespaces as a direct consequence:
   scheme=`log`, category=`logging`. Renders in `<log>`.
 - **Payload channels** live in `{action}://turn_N/{slug}_N` —
   scheme=`{action}` (registered as `category: "data"`). Render in
-  `<context>`.
+  `<summary>` (always, while tracked) and `<visible>` (when
+  promoted).
 
 This keeps `<log>` a terse audit trail (what happened, exit code,
-paths) while `<context>` carries the actual streamed bytes the model
+paths) while `<visible>` carries the actual streamed bytes the model
 reads. Conflating the two — e.g., writing channels under `log://...` —
 mislabels payload as audit and pollutes the logging section with
 multi-line command output. See [streaming_entries](#streaming_entries).
@@ -364,11 +390,18 @@ the current loop; pending loops survive. Projects > runs > loops > turns.
 
 The `file_constraints` table is project-level configuration — it
 defines which files a project cares about. This is backbone, not tool
-dispatch. Constraints have three visibilities:
-
-- `active` — matching files are promoted into the run's context
-- `readonly` — promoted but not editable by the model
-- `ignore` — demoted (excluded from context)
+dispatch. Constraint type governs **membership** and **write
+permission**, not in-context visibility. In-context visibility
+(`visible` / `summarized` / `archived`) is per-entry and model-
+controlled — files default to `archived` on ingestion; the model
+promotes via `<get>` / `<set visibility=…>`.
+
+- `add` — file is part of the project; ingested as an entry; model
+  may write. Default for `setConstraint`.
+- `readonly` — same ingestion; `<set>` is vetoed at the proposal-
+  accept gate.
+- `ignore` — excluded from scans entirely. The file remains on disk
+  for `<sh>` / `<env>` invocation but is not present as an entry.
 
 **Boundary:** Setting a constraint (`File.setConstraint`) is a
 project-config write. Promoting/demoting the matching entries is tool
@@ -434,6 +467,32 @@ policy filtering, abort cascade). Plugin-tier convenience verbs
 don't invoke the handler chain. Plugin code that wants full handler
 semantics calls `hooks.tools.dispatch` directly.
 
+**Two-phase turn execution.** Model output flows through
+`TurnExecutor.execute` in strict order:
+
+1. **RECORD** — every parsed command is materialized as a
+   `log://turn_N/action/slug` audit entry via `#record()`. Each
+   tool's parser shape surfaces exactly one of `path` / `command` /
+   `question` as its addressable target; absent fields are treated
+   as empty so the validation gate catches bad shapes rather than
+   letting `undefined` propagate. Targets longer than 512 chars or
+   containing control characters are rejected as likely reasoning
+   bleed (the model's chain-of-thought leaking into a tool path).
+   Plugins can validate or transform via the `entry.recording`
+   filter before the row is committed.
+2. **DISPATCH** — recorded entries fire sequentially via
+   `hooks.tools.dispatch`. Each tool runs to completion before the
+   next starts. A failed entry sets `abortAfter`; subsequent
+   entries record as `outcome="aborted"`. Crashes inside dispatch
+   route through `hooks.error.log` at status 500 and trigger the
+   same abort cascade. After each entry, `proposal.prepare` lets
+   plugins materialize pending 202 proposals (e.g. `set`'s
+   search/replace revisions) from the just-recorded entry.
+
+Narration outside tags is fine when the turn also emitted at least
+one command — "OK", "Let me check:", reasoning prefixes are natural
+and don't trigger the no-actionable-tags error path.
+
 **Tool dispatch:** Commands are dispatched sequentially in the order
 the model emitted them. Each tool either succeeds (200), fails (400+),
 or proposes (202). On failure, all remaining tools are aborted. On
@@ -451,9 +510,9 @@ to a continuation (the model's claim of doneness is false); the update
 plugin resolves the update entry to 409 and surfaces it to the next
 turn as a continuation. Multiple `<update>` tags → last signal wins.
 
-**Post-dispatch budget check:** After all tools dispatch, the budget
-plugin re-materializes context and checks the ceiling
-(`hooks.budget.postDispatch`). If context exceeds the ceiling, Turn
+**Post-dispatch budget check:** After all tools dispatch, TurnExecutor
+emits `turn.dispatched`; the budget plugin subscribes, re-materializes
+context, and checks the ceiling. If context exceeds the ceiling, Turn
 Demotion fires — all `visible` `run_views` rows for the current turn
 have their `visibility` flipped to `summarized`, and an `error://` entry at status 413 is
 written. Status is NOT touched (see [schemes_status_visibility](#schemes_status_visibility)). The tools already ran;
@@ -508,6 +567,68 @@ export default class Rm {
 
 A plugin can be multiple types. Known is a tool AND an assembly plugin.
 
+### Failure Reporting {#failure_reporting}
+
+**The action entry IS its outcome.** Every action plugin's handler
+finalizes the action's own log entry (`log://turn_N/{action}/{slug}`)
+with body, state, and outcome. Success and failure are two values of
+the same shape — only the field values change. The model sees both
+through the same channel, rendered under the action's scheme.
+
+```
+<get path="src/x.js" status="200">…file body…</get>          # success
+<get path="src/x.js" state="failed" outcome="not_found">     # failure
+  src/x.js not found
+</get>
+```
+
+State + outcome label the verdict; body is the result — file content
+on success, failure message on failure. No separate error entry is
+written for action-level failures; the model finds the failure exactly
+where it would find the success: at the action's own log path.
+
+**Strike attribution.** `error.js#verdict` looks up the post-handler
+state of every recorded entry on each turn. Any `state="failed"`
+result counts as a strike. Plugin authors write their action entry
+once with the right state; the strike machinery follows. They never
+call `error.log.emit` for action-level failures.
+
+**`error.log.emit` is for actionless failures** — failures that have
+no corresponding action entry to attach to:
+
+- Dispatch crash — the framework caught an exception thrown from inside
+  a handler before the handler had a chance to write its own entry.
+- Parser-level failures — malformed XML warnings, no-actionable-tags
+  responses, fired before any action entry could be recorded.
+- Runtime watchdog firings — `ContextExceededError`, RPC timeout,
+  stream timeout — not bound to a specific action.
+- Budget overflow — pre-dispatch rejection.
+
+`error.log.emit` writes a `log://turn_N/error/<slug>` entry and
+increments `state.turnErrors`, which also feeds strike accumulation.
+Both channels (action-entry state=failed and `error.log.emit`)
+contribute to the strike streak; either path advances it.
+
+**Recording-filter rejection.** Plugins on the `entry.recording` filter
+chain (e.g. `policy`) can return an entry with `state="failed"`. The
+framework writes that entry to the store before returning from
+`#record`, and dispatch skips it. The model sees the rejection at the
+action's own log path, exactly like any other action-level failure.
+
+Cycle detection is **silent** — it does not call `error.log.emit`.
+The strike accumulates internally via `state.turnErrors++`; on
+`MAX_STRIKES` the run abandons at 499 with a telemetry-side reason.
+The model sees no special signal, because telling the model "you're
+looping" invites superficial evasion (vary an attribute to bust the
+fingerprint) without addressing the underlying confusion.
+
+**Plugin author contract.** Your handler does one job: finalize the
+action's own log entry with the right body/state/outcome. That's the
+whole API for failure reporting. You do not call `error.log.emit`.
+If your handler throws, the framework catches and routes through
+`error.log.emit` at status 500 — that's the only situation where the
+framework writes on your behalf.
+
 ### Mode Enforcement {#mode_enforcement}
 
 Two mechanisms, operating at different layers:
@@ -520,9 +641,11 @@ Two mechanisms, operating at different layers:
 2. **Per-invocation filtering** — the `policy` plugin subscribes to
    `entry.recording` and inspects individual emissions for ask-mode
    violations that the tool-list alone can't catch (file-scheme `<set>`
-   edits, file `<rm>`, file-destination `<mv>`/`<cp>`). Rejects with
-   status 403 and emits `error://`. The tool remains advertised; the
-   specific invocation is blocked.
+   edits, file `<rm>`, file-destination `<mv>`/`<cp>`). Rejects by
+   marking the action entry `state="failed"`, `outcome="permission"`
+   with a body describing the rejection. Per the failure-reporting
+   contract — see [failure_reporting](#failure_reporting). The tool
+   remains advertised; the specific invocation is blocked.
 
 ### YOLO Mode {#yolo_mode}
 
@@ -569,44 +692,43 @@ plumbing for the attribute and the rummy-context payload enrichment
 on `proposal.pending`. Feature logic stays in
 `src/plugins/yolo/yolo.js`.
 
-### Repo Overview {#repo_overview}
+### Project Manifest {#project_manifest}
 
-The `rummy.repo` plugin maintains a single `repo://overview` entry per
-run, regenerated on every scan, that gives the model a navigable map
-of the project. It is the entry-point for code-aware runs — files
-themselves default to `archived` so a 5000-file repo doesn't dump
-hundreds of thousands of tokens into context before any work happens.
+The `rummy.repo` plugin writes a single `log://turn_0/repo/manifest` entry
+once per run — a flat snapshot of every project file with its token
+cost. It gives the model orientation at run start without burning
+prefix-cache on a turn-keyed regeneration. Files themselves default
+to `archived` so a 5000-file repo doesn't dump hundreds of thousands
+of tokens into context before any work happens.
 
 **Entry contract.**
 
-- Path: `repo://overview` (scheme `repo`, category `data`,
-  `model_visible: 1`)
-- Visibility: `visible` (the navigation map is always in context)
-- Body: a markdown structure containing the project root, file count,
-  root-level files, top-level directories with file counts,
-  active/readonly constraints, and a navigation legend showing the
-  promote/demote idioms.
-- Visible projection: full body.
-- Summarized projection: first ~12 lines + a truncation marker, so a
-  model can demote it once it has the layout memorized.
+- Path: `log://turn_0/repo/manifest` (log scheme; turn-0 marks "before
+  any model turn"). One entry per run, written once.
+- Visibility: `visible` at write; demotable like any log entry.
+- Body: a flat list of `* <relative-path> - <N> tokens` lines, one
+  per file, sorted by path. No headers, no directory aggregation, no
+  constraints, no navigation legend — those are the model's business
+  to derive from the list itself or from tooldocs.
+
+**Stale by design.** The manifest is a turn-0 snapshot; it does not
+update mid-run. Authoritative current state lives in the per-file
+entries (mtime/hash-driven, change-only writes). The model can
+`<get path="**" preview/>` for a fresh listing if it suspects
+staleness.
 
 **File default visibility flip.**
 
 `FileScanner` registers each tracked file at `archived` by default
 (was `summarized`). Files with `constraint=active` still register at
-`visible`. The model uses `repo://overview` to discover paths, then
+`visible`. The model uses the manifest to discover paths, then
 promotes individual files via `<get path=...>` (visible, full body)
 or whole subtrees via `<set path=".../**" visibility="summarized"/>`
 (skim mode, symbols only).
 
-**Bounded cost.** The overview body is constant-ish in size regardless
-of repo size: root files capped, directory counts aggregated, no per-
-file symbol enumeration. The token cost in context stays roughly
-flat from a 30-file project to a 50,000-file monorepo.
-
 **Disabled when noRepo.** Setting `noRepo: true` on a run skips the
-scan entirely; no `repo://overview` is created and no file entries
-are registered. Behaviour identical to pre-plugin runs.
+scan entirely; no manifest is created and no file entries are
+registered. Behaviour identical to pre-plugin runs.
 
 ### Streaming Entries {#streaming_entries}
 
@@ -633,12 +755,14 @@ log://turn_N/{action}/{slug}    scheme=log       category=logging   status=202
 
 {action}://turn_N/{slug}_1      scheme={action}  category=data      status=102 → 200/500
                                 body: primary stream (stdout for shell)
-                                summary="{command}" visibility=summarized
-                                (renders in <context>)
+                                tags="{command}" visibility=summarized
+                                (line in <summary>; full body in
+                                 <visible> when promoted)
 
 {action}://turn_N/{slug}_2      scheme={action}  category=data      status=102 → 200/500
                                 body: alt stream (stderr for shell)
-                                (renders in <context>, often empty)
+                                (line in <summary>; full body in
+                                 <visible> when promoted, often empty)
 ```
 
 `{action}` is the producer plugin's name (`sh`, `env`, future: `search`,
@@ -653,6 +777,16 @@ channels. Non-process producers (search, fetch) map their streams onto
 the same numeric space: `_1` for the primary data stream, `_2` for
 anomalies/errors, `_3`+ for auxiliary streams.
 
+**Search prefetch.** The `search` producer (provided by `rummy.web`
+when wired) may prefetch its result URLs as separate `<https>` data
+entries before the model emits any `<get>`. The model sees those
+pages as already-summarized data without having explicitly loaded
+them. Auditors reading dumps should be aware: the absence of a
+corresponding `log://turn_N/get/` for a URL does **not** mean the
+URL wasn't loaded — it may have arrived via search prefetch. The
+prefetch policy is the search plugin's implementation detail; the
+data entries themselves obey the streaming-producer shape above.
+
 **Status 102 ("Processing") marks an entry in mid-stream:** body is
 partial, will change; tokens grow as chunks arrive. Agents reading a
 102 entry use `<get>` with `line`/`limit` (including negative `line`
@@ -681,62 +815,121 @@ Two messages per turn. System = stable truth. User = active task.
 
 ```
 [system message]
-    instructions text
-        (instructions.md base template + tool docs injected via
-         instructions.toolDocs filter; optional persona appended)
-    <context>
-        all category=data entries (knowns, files, http/https),
-        wrapped by known.js on assembly.system at priority 100
-    </context>
-[user message]
+    instructions-system.md text (with [%TOOLS%] / [%TOOLDOCS%]
+    expansions) + persona body. Resolved by the instructions
+    plugin's hooks.instructions.resolveSystemPrompt — single-owner,
+    cache-stable across all turns within a run. The assembly.system
+    filter chain exists but currently has no subscribers; the
+    system message is the resolved system prompt verbatim.
+[user message]                     (sandwich ordering — see below)
+    <prompt tokenUsage="N" tokensFree="M">user prompt</prompt>
+        (prompt.js, assembly.user priority 30 — front, cacheable
+         across the run within a loop)
+    <summary>
+        one entry per category=data entry whose visibility is visible
+        or summarized. Each entry renders under its scheme tag with
+        its summarized projection as the tag body — the compact-but-
+        informative view produced by the plugin's summarized() hook
+        (truncated knowns, code symbols for files, page abstracts
+        for URLs). Identity-keyed, slow-mutating: only grows when a
+        new entry lands. Archived entries — including prompts —
+        are filtered out uniformly. There is no instruction-side
+        guard against archiving the active prompt — if the model
+        archives it, the next turn renders without a <prompt> tag
+        and visibly fails (paradigm purity over silent rescue;
+        action-gate is the principled future fix per
+        src/plugins/prompt/README.md).
+        (known.js, assembly.user priority 50)
+    </summary>
+    <visible>
+        each category=data entry whose visibility is visible, rendered
+        under its scheme tag with its visible projection as the tag
+        body (full body per the plugin's visible() hook). Working-set:
+        append on promote, remove on demote. A visible entry exists in
+        BOTH blocks — summary projection up top, full body below.
+        (known.js, assembly.user priority 75)
+    </visible>
     <log>
-        action history — log:// entries + pre-latest prompts
+        action history — all logging-category entries (log:// audit
+        records, error://, update://) plus pre-latest prompt://
+        entries (the active prompt is extracted to <prompt>).
         (log.js, assembly.user priority 100)
     </log>
     <unknowns>
-        (open questions at category=unknown, unknown.js priority 200)
+        open questions at category=unknown, rendered under <unknown>
+        children with their bodies as questions. (unknown.js,
+        assembly.user priority 150)
     </unknowns>
     <instructions>
-        current phase directive — one of instructions_104.md …
-        instructions_108.md, selected by the latest <update status="1XY">
-        emission (instructions.js, assembly.user priority 250)
+        instructions-user.md text. Per-turn imperative reminders.
+        Same bytes every turn — no phase keying, no status-driven
+        selection. (instructions.js, assembly.user priority 165)
     </instructions>
-    <prompt mode="ask|act" tokenUsage="N" tokensFree="M">user prompt</prompt>
+    <budget tokenUsage="N" tokensFree="M">…breakdown table…</budget>
+        (budget.js, assembly.user priority 175 — last, recency for
+         the live accounting at the action site)
 ```
 
 **System** = stable world state the model operates within (identity,
-tools, tool docs, reference context). Stable across turns within a
-run, which keeps prompt caching intact. **User** = active work (what
-the model is doing right now): history, open questions, current
-phase, and current prompt. The phase-specific `<instructions>` block
-lives in the user message precisely *because* it changes between
-turns — putting it in system would invalidate the cache on every
-phase transition.
+tools, tool docs, persona). Stable across turns within a run, which
+keeps prompt caching intact. **User** = active work: the project's
+data surface, history, open questions, current task, and live
+accounting. The user message changes turn-to-turn so it sits outside
+the prefix-cacheable region; both `<instructions>` and the codebase
+blocks (`<summary>` / `<visible>`) live here because they mutate at
+turn cadence — putting mutable state in system would invalidate the
+cache on every promote.
+
+**Sandwich ordering.** User-message blocks are arranged
+`<prompt>` (30, front) → `<summary>` (50) → `<visible>` (75) →
+`<log>` (100) → `<unknowns>` (150) → `<instructions>` (165) →
+`<budget>` (175, last). The prompt sits at the front (cacheable
+across turns of a loop, since it doesn't change within a loop); the
+instructions and budget sit at the tail so the rules and live
+accounting have recency at the action site. An earlier front-loaded
+ordering (instructions first for max cache) regressed terminal-
+`<update>` discipline in e2e — the model lost the rule when it sat
+3K tokens upstream of the action. Recency at the action site beats
+cache savings when the action depends on remembering a rule.
+
+**Why two blocks instead of one `<context>`.** Promote/demote is the
+dominant intra-loop operation. A single-block render would
+invalidate the entire data surface on every promote. With the split,
+`<summary>` mutates only when a new entry lands (slow); `<visible>`
+mutates on every promote/demote (fast). Ordering slow-above-fast
+preserves the prefix cache for `<summary>` across the common case.
+Cognitively: `<summary>` is "what I know exists" (identity);
+`<visible>` is "what I'm reading right now" (working memory).
 
 The `<prompt>` tag is present on every turn — first turn and
-continuations alike. The model always sees its task. The active prompt
-is extracted from its chronological position and placed last for maximum
-recency. The `<prompt>` element carries `tokenUsage` / `tokensFree`
-attributes so the model can do budget arithmetic in-line with the cause.
+continuations alike. The model always sees its task. The
+`tokenUsage` / `tokensFree` attributes also appear on `<budget>` so
+the model can do budget arithmetic at both ends of the user message.
 
-### Loops, Previous, and Performed {#loops_previous_performed}
+### Loops and Cross-Loop Continuity {#loops_previous_performed}
 
 A **loop** is one `ask` or `act` invocation and all its continuation
-turns until `<update status="200">`, fail, or abort.
-
-**Previous** = all completed loops on this run. The user prompt, model
-responses, tool results, agent warnings — the full chronicle in order.
-Lives in the system message as established history. Omitted on the
-first turn of the first loop.
-
-**Performed** = the active loop's work so far. Model responses, tool
-results, agent warnings — in order. Does NOT include the user prompt
-(one per loop, extracted to `<prompt>`). Lives in the user
-message as immediate context. Empty on the first turn of a loop.
+turns until `<update status="200">`, fail, or abort. A run may
+contain many loops; pending loops queue FIFO via the loops table.
+
+Cross-loop continuity is carried by the entry store itself:
+
+- **Knowns, files, unknowns** persist across loop boundaries with
+  whatever visibility the model left them at. They render in
+  `<summary>` / `<visible>` per visibility, regardless of which
+  loop wrote them.
+- **Log entries** (action audit, errors, updates) accumulate at
+  `log://turn_N/...` for every turn of every loop; `log.js`
+  renders all logging-category entries plus pre-latest prompts in
+  `<log>` in chronological order.
+- **The active prompt** is extracted from its chronological
+  position and rendered as `<prompt>` at priority 30 (front);
+  prior prompts render in `<log>` like any other logging entry.
 
 When a new prompt arrives on an existing run, the prior loop's
-`<performed>` content plus its prompt move to `<previous>`. When a loop
-continues (next turn), new results append to `<performed>`.
+`prompt://N` entry stays in the store; on the next assembly it
+falls out of `<prompt>` (replaced by the new prompt) and into
+`<log>` — visibility-driven re-rendering of the same entry rows.
 
 ### Key Entries {#key_entries}
 
@@ -758,23 +951,33 @@ Each turn:
 
 1. Write `instructions://system` (empty body, attributes = { persona, toolSet })
 2. Emit `turn.started` — plugins write prompt/instructions entries
-3. Resolve the instructions system prompt (`hooks.instructions.resolveSystemPrompt`)
+3. Resolve the instructions system prompt
+   (`hooks.instructions.resolveSystemPrompt` — single-owner; see
+   AGENTS.md "Architectural exceptions"). Returns
+   `instructions-system.md` with `[%TOOLS%]` / `[%TOOLDOCS%]`
+   expanded, persona body appended.
 4. Query `v_model_context` VIEW → visible entries (joined from
    `run_views` + `entries` + `schemes`)
 5. Project each entry through its scheme's `visible`/`summarized` projection
 6. Insert projected rows into `turn_context`
-7. Invoke `assembly.system` filter chain (instructions text as base):
-   - Known plugin (priority 100) → `<knowns>` section
-   - Previous plugin (priority 200) → `<previous>` section
+7. Invoke `assembly.system` filter chain — currently no
+   subscribers, so the system message is the resolved system
+   prompt verbatim.
 8. Invoke `assembly.user` filter chain (empty string as base):
-   - Performed plugin (priority 100) → `<performed>` section
-   - Unknown plugin (priority 200) → `<unknowns>` section
-   - Prompt plugin (priority 300) → `<prompt>` element (carries
-     `tokenUsage` / `tokensFree` attrs when `contextSize` is set)
+   - Prompt plugin (priority 30) → `<prompt>` element (carries
+     `tokenUsage` / `tokensFree` attrs)
+   - Known plugin (priority 50) → `<summary>` section
+   - Known plugin (priority 75) → `<visible>` section
+   - Log plugin (priority 100) → `<log>` section
+   - Unknown plugin (priority 150) → `<unknowns>` section
+   - Instructions plugin (priority 165) → `<instructions>` section
+     (renders `instructions-user.md`)
+   - Budget plugin (priority 175) → `<budget>` element (carries
+     `tokenUsage` / `tokensFree` and per-scheme breakdown)
 9. Store as `system://N` and `user://N` audit entries (telemetry plugin)
 
 The VIEW determines visibility from `visibility` and `status`:
-- `visibility = 'visible'` → full body visible in `<knowns>` / `<performed>`.
+- `visibility = 'visible'` → full body visible in `<visible>` (data) or `<log>` (logging).
 - `visibility = 'summarized'` → summarized projection visible (typically path +
   summary attr). Promote with `<get>` to expand.
 - `visibility = 'archived'` → invisible. Discoverable via pattern search
@@ -794,6 +997,29 @@ Model controls visibility via `<set>` attributes:
 attaches a description (≤ 80 chars) that persists across visibility
 changes.
 
+### Filesystem Freshness {#filesystem_freshness}
+
+After any mutation of a file or scheme entry, the next turn's
+assembled context reflects the post-mutation body AND visibility,
+without the model needing a fresh `<get>` to recover its own
+changes. The model's view of the entry store is always a faithful
+projection of current state — there is no read-after-write skew.
+
+The invariant has two parts:
+
+1. **Body freshness** — a write that changes the entry body shows
+   the new body on the next assembly's `<visible>` (when visible)
+   or under `<get>` (when summarized/archived).
+2. **Visibility freshness** — a write that explicitly sets
+   `visibility=...` honors the requested level on the next
+   assembly. Edit-path side effects (e.g., a SEARCH/REPLACE accept
+   silently downgrading visibility) violate the invariant; the
+   model would answer the next turn from memory of pre-edit state
+   while the new body sits invisible.
+
+Enforcement: `test/integration/file_freshness.test.js` exercises
+write-through for both file and scheme entries.
+
 ### Token Accounting {#token_accounting}
 
 Tokens are a property of the materialized packet, not of stored entries.
@@ -868,33 +1094,55 @@ an entry is being written.
 ### Budget Enforcement {#budget_enforcement}
 
 The model owns its context. The system enforces a hard ceiling and
-surfaces the numbers — it does not automatically manage entries.
+surfaces the numbers. Auto-demotion is reserved for the 413 budget
+grinder, which only fires in response to actual overflow — never
+helpfully or speculatively.
 
 **Ceiling.** `ceiling = floor(contextSize × RUMMY_BUDGET_CEILING)`
 (default `RUMMY_BUDGET_CEILING = 0.9`, i.e. 10% headroom). All budget
 decisions compare `assembledTokens` against `ceiling`, never against
 `contextSize` directly.
 
-**Pre-LLM enforce** (`hooks.budget.enforce`, in TurnExecutor before
-the LLM call). Measures the assembled messages (using
-`turns.context_tokens` from the prior turn when available,
-`countTokens(messages)` as a first-turn estimate).
-
-- `assembledTokens ≤ ceiling` → return 200, proceed to LLM.
-- `assembledTokens > ceiling` on the first turn of a loop → **Prompt
-  Demotion**: demote the incoming `prompt://N` entry to `visibility =
-  demoted`, re-materialize, re-check. If the retry fits, proceed.
-- `assembledTokens > ceiling` on a non-first turn, or still over after
-  Prompt Demotion → return 413. AgentLoop exits the loop with 413.
-
-**Post-dispatch Turn Demotion** (`hooks.budget.postDispatch`, after
-all tool dispatches complete). Re-materializes end-of-turn context
-and re-checks. If still over the ceiling, flips every `run_views` row
-for this turn from `visibility = visible` to `visibility = summarized`
-(status preserved — see [schemes_status_visibility](#schemes_status_visibility))
-and emits a 413 error via `hooks.error.log.emit` with the descriptive
-body (what was demoted, the 50% rule for the next turn). The model
-sees the `error://` entry next turn and adjusts.
+**Pre-LLM grinder** (`hooks.turn.beforeDispatch.filter`, in
+TurnExecutor before the LLM call; budget is the canonical
+subscriber). A four-step ladder. Each step demotes a strictly smaller
+scope and rechecks. The first step that fits the ceiling proceeds to
+the LLM; if step 4 fires, AgentLoop exits the loop with 413.
+
+1. **Check budget.** Measure `assembledTokens` (using
+   `turns.context_tokens` from the prior turn when available, the
+   materialized packet estimate as a first-turn fallback). If
+   `assembledTokens ≤ ceiling`, proceed to the LLM.
+2. **Soft 413 — previous-turn demotion.** Flip every `run_views`
+   row where `turn = current_turn - 1 AND visibility = visible` to
+   `summarized` (status preserved — see
+   [schemes_status_visibility](#schemes_status_visibility)). All
+   schemes participate; no exemption for knowns / unknowns /
+   files. Re-materialize, re-check.
+3. **Soft 413 — current-prompt demotion.** Flip the incoming
+   `prompt://N` entry to `summarized`. Re-materialize, re-check.
+   Step 3 exists because the prompt is stamped at `current_turn`,
+   not the previous turn — step 2's filter never sees it. Without
+   step 3, an oversized first-turn prompt has no path to fit.
+4. **Hard 413.** Emit a 413 `error://` entry via
+   `hooks.error.log.emit` with the descriptive body (what was
+   demoted across steps 2-3, the ceiling, the residual overflow).
+   AgentLoop exits the loop with 413.
+
+Steps 2 and 3 also emit 413 `error://` entries when they fire
+(distinct from step 4 in that the run keeps going). The model reads
+those next turn and learns what got auto-demoted. Status of the
+turn that proceeded after a soft 413 is unaffected.
+
+**Trunks and forks are treated identically.** A forked run inherits
+the parent's `run_views` rows verbatim — each entry keeps its
+original `turn`. There is no fork-event restamping. The grinder's
+`current_turn - 1` rule applies the same way in both cases. For
+the rule to point at meaningful inherited content on a fork's first
+dispatch, the child run inherits the parent's `next_turn` so turn
+numbering is absolute across the lineage; sibling forks share the
+same prior history at lower turn numbers and only diverge at
+fork-time.
 
 **LLM-reported context exceeded.** If the LLM rejects the request
 with a "context too long" error (detected via the regex in
@@ -978,9 +1226,9 @@ on `get` also sets a project-level file constraint (operator privilege).
 
 | Method | Params |
 |--------|--------|
-| `startRun` | `{ model, temperature?, persona?, contextLimit? }` |
-| `ask` | `{ prompt, model, run?, temperature?, persona?, contextLimit?, noRepo?, noInteraction?, noWeb?, fork? }` |
-| `act` | `{ prompt, model, run?, temperature?, persona?, contextLimit?, noRepo?, noInteraction?, noWeb?, fork? }` |
+| `startRun` | `{ model, temperature?, persona?, contextLimit?, yolo? }` |
+| `ask` | `{ prompt, model, run?, temperature?, persona?, contextLimit?, noRepo?, noInteraction?, noWeb?, noProposals?, yolo?, fork? }` |
+| `act` | `{ prompt, model, run?, temperature?, persona?, contextLimit?, noRepo?, noInteraction?, noWeb?, noProposals?, yolo?, fork? }` |
 | `run/resolve` | `{ run, resolution: { path, action, output? } }` |
 | `run/abort` | `{ run }` |
 | `run/rename` | `{ run, name }` |
@@ -992,6 +1240,10 @@ on `get` also sets a project-level file constraint (operator privilege).
 be added explicitly by the client).
 `noInteraction` removes `ask_user` from the tool list.
 `noWeb` removes `search` from the tool list.
+`noProposals` removes `ask_user` / `env` / `sh` from the tool list
+(no proposals at all).
+`yolo` opts the run into server-side proposal auto-accept and
+in-process sh/env execution — see [yolo_mode](#yolo_mode).
 
 #### Streaming (see [streaming_entries](#streaming_entries))
 
@@ -1021,17 +1273,20 @@ connected clients). `stream/cancel` also handles stale 102 cleanup.
 
 #### Skills & Personas
 
-| Method | Params |
-|--------|--------|
-| `skill/add` | `{ run, name }` |
-| `skill/remove` | `{ run, name }` |
-| `getSkills` | `{ run }` |
-| `listSkills` | — |
-| `persona/set` | `{ run, name?, text? }` |
-| `listPersonas` | — |
-
-Skills loaded from `RUMMY_HOME/skills/{name}.md`. Personas from
-`RUMMY_HOME/personas/{name}.md`.
+Both attach to a run via the entry grammar.
+
+- **Skills** — model emits `<skill path="[path-or-url]"/>`.
+  Handler walks local file/folder/`.zip` (via `yauzl-promise`) or
+  fetches a URL. Single `.md` registers as `skill://<name>`
+  (summarized); folder/zip registers root `index.md` summarized,
+  rest archived; `foo/index.md` collapses to `skill://<name>/foo`.
+  Re-emit overwrites. Authors link with absolute `skill://...` URIs.
+- **Personas** — `ask` / `act` / `startRun` accept `persona` as a
+  run attribute. The persona plugin renders the persona body inside
+  the system prompt (below tooldocs) on first turn; if no `persona`
+  is passed, `AgentLoop.ensureRun` defaults to
+  `src/plugins/persona/default.md`. 1:1 run:persona, immutable for
+  the run's lifetime.
 
 ### Notifications {#notifications}
 
@@ -1075,6 +1330,16 @@ is raw JSON; parse client-side. Mid-turn emissions have `telemetry:
 null`; the final emission of each turn includes the full telemetry
 block (token usage, context distribution, cost).
 
+**Telemetry completeness guarantee.** Every `run/state` emission
+computes a real budget from real numbers — never undefined, never
+synthesized. When no fresh turn result is available
+(abort/max-turns/crash paths fire before any turn executed, or after
+a turn that produced no tokens), `AgentLoop.#emitRunState` reads the
+last turn's `context_tokens` from the DB. Absent means no turn ran
+yet; zero is the truth, not a fallback. The shape and the math are
+the same on every code path so the client's renderer never needs to
+discriminate by emission cause.
+
 `stream/cancelled` payload: `{ run, path, reason }`. Server has
 already transitioned the entries to 499 (`Client Closed Request`);
 client should stop sending `stream` chunks for that path.
@@ -1089,6 +1354,30 @@ client should stop sending `stream` chunks for that path.
 | accept | neither | `running` — healer decides |
 | error | any | `running` — error state, model retries |
 
+**RPC ack vs run terminal status.** `resolve` and `inject` return the
+*current* run status (typically 102 mid-run), not 200. The client's
+dispatch handler must distinguish the synchronous RPC ack from the
+asynchronous `run/state` notification that carries real terminal
+state at end-of-turn — otherwise an HTTP-style 200 ack on a
+successful resolve would prematurely close the document.
+
+**Proposal hook chain.** Resolution flows through three filter/event
+hooks plugins can subscribe to:
+
+- `proposal.accepting` (filter) — first plugin to return
+  `{ allow: false, outcome, body }` vetoes acceptance. The entry
+  resolves to `state="failed"` with the plugin-supplied outcome and
+  body. Used by `policy` for read-only enforcement and similar
+  guards. First veto wins; later filters don't run.
+- `proposal.content` (filter) — when acceptance proceeds, plugins
+  override the resolved body. Default is `output ?? ""`. The `set`
+  plugin uses this to prefer the proposed body it already staged
+  on the audit entry over whatever literal body the client passed
+  through `resolve`.
+- `proposal.accepted` / `proposal.rejected` (events) — fired after
+  the resolution is committed; plugins side-effect on either
+  outcome.
+
 ---
 
 ## Plugin System {#plugin_system}
@@ -1165,28 +1454,126 @@ one unified mechanism.
 
 ### Pattern Distribution
 
-Hedbergian pattern matching (globs, body filters, preview) is taught
+Hedbergian pattern matching (globs, body filters, manifest) is taught
 across multiple tools, not concentrated in one. `get` shows content
-filtering. `cp` shows glob batch operations. `rm` shows preview safety.
+filtering. `cp` shows glob batch operations. `rm` shows manifest safety.
 Each tool reinforces the pattern vocabulary from a different angle.
 A model that sees `path="known://*"` in get, `path="known://plan_*"` in
-cp, and `path="known://temp_*" preview` in rm learns that patterns
+cp, and `path="known://temp_*" manifest` in rm learns that patterns
 are universal — not a feature of any single tool.
 
 ---
 
-## Hedberg Editing Syntax {#hedberg}
+## Edit Syntax
+
+The model expresses entry writes through `<set path="..."><body></set>`.
+The body shape determines the operation. All shaped operations use a
+bash-heredoc-flavored marker family.
 
-The model picks its preferred edit format. The parser understands all of them:
+### Marker Grammar
 
-1. Git merge conflict: `<<<<<<< SEARCH ... ======= ... >>>>>>> REPLACE`
-2. Replace-only: `======= ... >>>>>>> REPLACE`
-3. Unified diff: `@@ -1,3 +1,3 @@` with `-`/`+` lines
-4. Sed syntax: `s/old/new/flags`
-5. Claude XML: `<old_text>old</old_text><new_text>new</new_text>`
-6. JSON body: `{"search": "old", "replace": "new"}` or `{search="old", replace="new"}`
-7. XML attributes: `<set search="old" replace="new"/>`
-8. Full replacement: anything else becomes the new content
+    <<IDENT
+    body content
+    IDENT
+
+Where `IDENT` matches `[A-Z][A-Za-z0-9_]*`. The leading keyword of
+`IDENT` selects the operation; any trailing alphanumeric suffix is
+opaque to operation routing and exists to disambiguate nested markers
+or avoid collisions when the body literally contains the bare keyword
+(same convention as bash heredoc `<<EOF1` vs `<<EOF`).
+
+The opener `<<IDENT` must be preceded by start-of-body, whitespace,
+or `>` (so `vec<<SEARCH` mid-token does not false-trigger). The
+closer is bare `IDENT` with whitespace boundaries on both sides.
+
+Newline-tolerant: the multi-line shape above and the single-line
+`<<IDENT body IDENT` form parse identically.
+
+### Distinct from Packet Rendering
+
+The engine renders entry bodies in context using a different marker
+shape: `<<:::path...:::path` (see `plugins/helpers.js`). Edit syntax
+is the bare `<<IDENT` form; packet rendering keeps the `:::` sentinel.
+The two grammars are visibly distinct so model emissions and engine
+renderings can never be confused. A `<set>` body echoing the packet
+shape is NOT treated as edit syntax — it falls through to plain-body
+REPLACE with the markers preserved as literal content.
+
+### Operations
+
+| IDENT prefix | Effect |
+|---|---|
+| `NEW` | Create the entry. Behaves identically to `REPLACE` on existing entries — named separately to align with model intent. |
+| `PREPEND` | Prepend body content to the existing entry. Creates the entry if it doesn't exist. |
+| `APPEND` | Append body content to the existing entry. Creates the entry if it doesn't exist. |
+| `REPLACE` | Replace the entire entry body with the marker content. Standalone (not preceded by `SEARCH`). |
+| `DELETE` | Remove a literal-matching region from the existing entry body. The marker content is the region to remove. |
+| `SEARCH` | Match a literal region in the existing entry body. Must be immediately followed by a `REPLACE` block; the pair is an in-place edit. |
+
+### SEARCH / REPLACE Pairs
+
+Surgical in-place edits. `SEARCH` must be immediately followed by
+`REPLACE` (no intervening operation):
+
+    <set path="src/main.go"><<SEARCH
+    old line
+    SEARCH
+    <<REPLACE
+    new line
+    REPLACE</set>
+
+Multiple pairs in one `<set>` body apply in order against the
+progressively-edited body.
+
+### Suffix for Body Collisions
+
+When the body content literally contains a marker keyword (`SEARCH`
+in prose, `<<` in code), the model appends a digit or alphanumeric
+suffix to the IDENT so the inner literal does not prematurely close
+the outer marker:
+
+    <set path="docs/grammar.md"><<DOC1
+    The opener is <<SEARCH and the closer is bare SEARCH alone on
+    a line. Use <<SEARCH1 ... SEARCH1 if your body contains literal
+    SEARCH or <<SEARCH tokens.
+    DOC1</set>
+
+### Errors
+
+| Condition | Outcome |
+|---|---|
+| `SEARCH` content not found in current body | conflict (soft) |
+| `DELETE` content not found in current body | conflict (soft) |
+| Lone `SEARCH` (no following `REPLACE`) | parse error |
+| Unclosed marker (opener with no matching `IDENT` closer) | parse error |
+| Non-keyword `IDENT` (e.g. `<<EOF`, `<<DOC`) | routes to REPLACE — inner content becomes the new body |
+| `<set>` body with no `<<IDENT` markers at all | full-body REPLACE (tolerated; not demonstrated to models) |
+
+### Pattern Matching
+
+The literal-match semantics used by `SEARCH` and `DELETE` are
+delegated to the Hedberg pattern library — see [hedberg](#hedberg).
+Matching is fuzzy on whitespace and indentation; an exact-byte match
+is not required.
+
+---
+
+## Hedberg Pattern Library {#hedberg}
+
+The pattern library exposed to every plugin through `core.hooks.hedberg`.
+Used internally by the Edit Syntax (above) for `SEARCH` / `DELETE`
+matching and by `<get>` / `<rm>` for path globs.
+
+| Function | Purpose |
+|---|---|
+| `match(pattern, string)` | Full-string match — paths, equality. |
+| `search(pattern, string)` | Substring search — content filtering. |
+| `replace(text, search, replace, options)` | Patch application; fuzzy on whitespace and indentation. |
+| `generatePatch(path, oldBody, newBody)` | Unified-diff rendering for telemetry. |
+
+Pattern types: glob (picomatch-backed, with `**` cross-slash and
+`!()` negation), regex (`/pattern/flags`), xpath, jsonpath. Detection
+is by syntactic shape — see `src/lib/hedberg/patterns.js`.
 
 ---
 
@@ -1205,11 +1592,14 @@ Termination protocol:
   (the claim of doneness is refuted by the failures)
 - `<update status="102">` → run continues
 - Multiple `<update>` → last one wins
-- No `<update>` + investigation tools → stall counter (RUMMY_MAX_STALLS)
 - No `<update>` + action-only tools → healer infers terminal from body
 - No `<update>` + plain text → healer infers terminal from body
-- Repeated commands → cycle detection (RUMMY_MIN_CYCLES, RUMMY_MAX_CYCLE_PERIOD)
-- Repeated update text without non-update work → stall (RUMMY_MAX_UPDATE_REPEATS)
+- Repeated turn fingerprints (commands, attributes, or empty turns) →
+  cycle detection (`RUMMY_MIN_CYCLES`, `RUMMY_MAX_CYCLE_PERIOD`); after
+  detection, strikes accumulate up to `RUMMY_MAX_STRIKES` then close 499.
+- Hard ceiling: `RUMMY_MAX_LOOP_TURNS` caps turns within a single loop,
+  regardless of any other guard. There is no per-run cap; a run may
+  comprise many loops.
 
 Format normalization:
 - Gemma `\`\`\`tool_code` fences → stripped before parsing
@@ -1218,6 +1608,77 @@ Format normalization:
 - Mistral `[TOOL_CALLS]` → normalized to XML
 - Sed alternate delimiters (`s|old|new|`) → parsed like `s/old/new/`
 
+### XML Parser {#xml_parser}
+
+`src/agent/XmlParser.js` is the syntax layer between raw model output
+and the dispatch pipeline. Models routinely emit malformed XML —
+unclosed tags, missing slashes, mismatched closes, unterminated
+attribute values, embedded code-fences, training-format tool calls.
+The parser's contract is: never throw, never silently drop a tool
+call, surface every recovery as a warning so error.log can route it.
+
+**Pre-flight repair pipeline** (order is load-bearing):
+
+1. `#normalizeToolCalls` — translate native training formats (gemma
+   `\`\`\`tool_code\n<xml>\n\`\`\``, Qwen `<|tool_call>call:NAME{...}`,
+   OpenAI `{"name":"...","arguments":{...}}`, Anthropic
+   `<tool_use><name>...</name><input>{...}</input></tool_use>`,
+   Mistral `[TOOL_CALLS] [{...}]`, harmony role/channel pseudo-tags
+   `<|channel>` / `<channel|>`). Catch-all malformed `<|tool_call>`
+   tokens become `<error>` blocks (in prose — never with literal
+   `<get>`/`<set>`/etc. tags, which would re-enter the parser as
+   phantom tool calls).
+2. `#neutralizeCodeSpans` — entity-encode tag brackets inside
+   backtick spans (`` `<get/>` `` → `` `&lt;get/&gt;` ``). Models
+   quote instructions; quoted tool names must not parse.
+3. `#correctMismatchedCloses` — at outer tool depth (stack=1),
+   rewrite `</WRONG>` to `</RIGHT>`. htmlparser2 silently drops
+   unmatched closes, which would make the explicit recovery path
+   unreachable and absorb every sibling command as body text.
+   Conservative: only outermost depth; nested mismatches inside
+   tool bodies are left alone (bodies are opaque, see below).
+4. `#balanceAttrQuotes` — close `ATTR="..."` values that never
+   quote-close before the next tag. Without this repair,
+   htmlparser2 consumes the rest of input as one giant attribute
+   value and silently drops every subsequent tool call. Triggers
+   only when the value contains no quote, no `>`, and is followed
+   by another tag opening or close.
+
+**Body opacity.** Tool bodies are opaque text, not nested XML. The
+model writing a plan with `<get/>` examples in it, SEARCH/REPLACE
+markers in `<set>`, or XML samples in `<known>` all need to survive
+intact. Nested tag opens push onto a per-tool stack; matching closes
+pop. Orphan closes that don't match the stack but match a known tool
+name are treated as recovery (likely typo); unknown orphan closes
+are kept as body text.
+
+**Empty-body recovery.** A new tool tag opens while the current tool
+has no body content yet — the model meant the current tag to
+self-close but typed it paired, or emitted a mismatched close that
+htmlparser2 dropped. Close current, open new, emit recovery warning.
+
+**Per-tool attr-vs-body resolution** (`resolveCommand`). Tools accept
+attributes on the open tag *and* body text inside the tag. If the
+canonical attribute is missing, the body silently fills it. The
+shape per tool:
+- `set` — body parsed via `parseMarkerBody` (see "Edit Syntax"
+  above): `<<:::IDENT...:::IDENT` markers route to `operations`
+  list; bodies without markers are plain-body REPLACE.
+- `update` — body fills `body`, status defaults to 102 if absent.
+- `get` / `rm` — attr `path` or body fills target. Spread `a` so
+  `line` / `limit` / `visibility` / future attrs reach the handler.
+- `search` — attr `path` or body fills target; `results` numeric.
+- `mv` / `cp` — attr `path` (source); attr `to` or body fills dest.
+  Spread `a` so `visibility` reaches the handler for batch
+  visibility changes.
+- `sh` / `env` — attr `command` or body fills the command.
+- `ask_user` — attr `question`; attr `options` or body for options.
+
+**Tool-call cap.** `RUMMY_MAX_COMMANDS` caps the number of tool
+calls per turn. When hit, remaining commands drop with a warning;
+the model sees one structured error so it can adjust on the next
+turn rather than rediscovering silent truncation.
+
 ---
 
 ## Testing
@@ -1364,7 +1825,7 @@ Full reference is `.env.example` — these are the load-bearing vars.
 | Var | Default | Purpose |
 |-----|---------|---------|
 | `PORT` | 3044 | WebSocket port |
-| `RUMMY_HOME` | `~/.rummy` | Skills, personas, local config |
+| `RUMMY_HOME` | `~/.rummy` | Local config root. Used by telemetry; available for future per-user state. |
 | `RUMMY_DB_PATH` | `rummy.db` | SQLite path |
 | `RUMMY_MMAP_MB` | 0 | SQLite mmap hint (MB; 0 disables) |
 | `RUMMY_DEBUG` | false | Verbose logging |
@@ -1381,17 +1842,18 @@ Full reference is `.env.example` — these are the load-bearing vars.
 
 | Var | Default | Purpose |
 |-----|---------|---------|
-| `RUMMY_MAX_TURNS` | 15 | Hard loop iteration cap |
+| `RUMMY_MAX_LOOP_TURNS` | 99 | Per-loop turn cap (no per-run cap) |
 | `RUMMY_MAX_COMMANDS` | 99 | Max parsed tool calls per turn |
-| `RUMMY_MAX_STALLS` | 3 | Turns without `<update>` before force-complete |
-| `RUMMY_MAX_UPDATE_REPEATS` | 3 | Same-text repeat threshold without progress |
+| `RUMMY_MAX_STRIKES` | 3 | Strikes (errors or detected cycles) before close at 499 |
 | `RUMMY_MIN_CYCLES` | 3 | Consecutive repetitions to trigger cycle detection |
 | `RUMMY_MAX_CYCLE_PERIOD` | 4 | Max cycle period checked by healer |
 | `RUMMY_RETENTION_DAYS` | 31 | Days of completed/aborted runs kept |
-| `RUMMY_THINK` | 1 | Enable `<think>` tag reasoning |
-| `RUMMY_TEMPERATURE` | 0.5 | Default LLM temperature |
+| `RUMMY_THINK` | 0 | Reasoning request flag forwarded to LLM provider |
+| `RUMMY_TEMPERATURE` | 0.1 | Default LLM temperature |
 | `RUMMY_RPC_TIMEOUT` | 30000 | RPC timeout (ms) |
 | `RUMMY_FETCH_TIMEOUT` | 300000 | LLM HTTP timeout (ms) |
+| `RUMMY_LLM_DEADLINE` | 600000 | LLM transient-retry deadline (ms). Used as the budget for `warmup` and `rate_limit` categories in `src/llm/retry.js#retryClassified`; gateway/server categories have shorter hardcoded deadlines (30s / 60s). |
+| `RUMMY_LLM_MAX_BACKOFF` | 30000 | Max single backoff between retry attempts (ms) for warmup/rate_limit categories. |
 
 **LLM providers** (plugin-scoped; a provider with no config is inert):
 
@@ -1422,9 +1884,11 @@ local `node_modules` then global).
 
 | Var | Purpose |
 |-----|---------|
-| `RUMMY_SEARCH` | `brave` \| `searxng` |
-| `BRAVE_API_KEY` | Brave Search API key |
-| `RUMMY_SEARXNG_URL` | SearXNG instance URL |
+| `RUMMY_WEB_SEARXNG_URL` | SearXNG instance URL (SearXNG federates Brave / DuckDuckGo / Wikipedia / etc. upstream and normalizes the responses) |
+| `RUMMY_WEB_FETCH_TIMEOUT` | Playwright `page.goto` timeout (ms) |
+| `RUMMY_WEB_PLAYWRIGHT_WS` | Optional CDP endpoint for shared chromium |
+| `RUMMY_WEB_NO_SANDBOX` | `1` to drop chromium's user-namespace sandbox |
+| `RUMMY_WEB_CHROMIUM_HEAP_MB` | Cap chromium's V8 heap (MB) |
 
 **Testing:**